/*****************************************************************************
*                                                                            *
*   XYZPROJECT.SPL  Copyright (C) 2020 DSP Development Corporation           *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:       Randy Race                                                 *
*                                                                            *
*   Synopsis:     Overplots the X, Y and Z projections of XYZ data           *
*                                                                            *
*   Revisions:    20 Feb 2020   RRR  Creation                                *
*                                                                            *
*****************************************************************************/

#if @HELP_XYZPROJECT

    XYZPROJECT

    Purpose: Overplots the X, Y and Z projections of an XYZ plot.

    Syntax:  XYZPROJECT(win, xloc, yloc, zlox, zloc, xcolor, ycolor, zcolor)

             (x, y, z) = XYZPROJECT(win)

                win - Optional. A window that contains an XYZ series.
                      Defaults to the current window.

               xloc - Optional. A real, the fixed X location of the X
                      projection. Defaults to the maximum X plotting range
                      of the XYZ series.

               yloc - Optional. A real, the fixed Y location of the Y
                      projection. Defaults to the maximum Y plotting range
                      of the XYZ series.

               zloc - Optional. A real, the fixed Z location of the Z
                      projection. Defaults to the minimum Z plotting range
                      of the XYZ series.

             xcolor - Optional. An integer, the X projection overplot color.
                      Defaults to -1, automatic.

             ycolor - Optional. An integer, the Y projection overplot color.
                      Defaults to -1, automatic.

             zcolor - Optional. An integer, the Z projection overplot color.
                      Defaults to -1, automatic.

    Returns: Nothing, the X, Y and Z projections are overplotted onto the
             source XYZ series.

             (x, y, z) = XYZPROJECT(win) returns the X, Y and Z projections
             as three XYZ series.

    Example:
             W1: gsin(1000, 1/1000, 1)
             W2: gsin(1000, 1/1000, 2)
             W3: gsin(1000, 1/1000, 3)
             W4: xyz(w1, w2, w3);xyzproject()

             Creates a sinusoidal XYZ series. The X, Y and Z projections
             are overplotted as constant value X, Y and Z XYZ series where
             the constant values are set to the limits of the XYZ plotting
             range.

    Example:
             W1: gsin(1000, 1/1000, 1)
             W2: gsin(1000, 1/1000, 2)
             W3: gsin(1000, 1/1000, 3)
             W4: xyz(w1, w2, w3);xyzproject(w0, -1.0, 0.0, 0.5, purple, red, blue)

             Same as above except the X projection is plotted in purple
             at x = -1.0, the Y projection is plotted in red at y = 0.0
             and the Z projection is plotted in blue at z = 0.5.

    Remarks:
             XYZPROJECT overplots the X, Y and Z projections of an XYZ series.
             The projections are constant value XYZ series with constant values
             equal to XLOC, YLOC and ZLOC. By default, XLOC is set to the
             maximum X plotting range, YLOC is set to the maximum Y plotting
             range and ZLOC is set to the minimum Z plotting range of the
             source XYZ plot.

             See XPROJECT, YPROJECT and ZPROJECT to overplot individual
             projections.

    See Also:
             Overplot
             Xproject
             XYZ
             Yproject
             Zproject
#endif


/* X, Y and Z projections of XYZ plot */
xyzproject(win = refwindow(w0), xloc = getxr(win), yloc = getyt(win), zloc = getzb(win), xcolor = -1, ycolor = -1, zcolor = -1)
{
        local x, y, z;

        if (outargc > 0)
        {
                /* return projections */
                x = xproject(win);
                y = yproject(win);
                z = zproject(win);

                return(x, y, z);
        }
        else
        {
                /* overplot projections */
                xproject(win, xloc, xcolor);
                yproject(win, yloc, ycolor);
                zproject(win, zloc, zcolor);
        }
}