/*****************************************************************************
*                                                                            *
*   ZPROJECT.SPL  Copyright (C) 2020 DSP Development Corporation             *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:       Randy Race                                                 *
*                                                                            *
*   Synopsis:     Overplots the Z projection of XYZ data                     *
*                                                                            *
*   Revisions:    20 Feb 2020   RRR  Creation                                *
*                                                                            *
*****************************************************************************/

#if @HELP_ZPROJECT

    ZPROJECT

    Purpose: Overplots the Z projection of an XYZ plot.

    Syntax:  ZPROJECT(win, zloc, color)

             z = ZPROJECT(win)

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

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

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

    Returns: Nothing, the Z projection is overplotted onto the XYZ series.

             z = ZPROJECT(win) returns the Z projection as an 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);zproject()

             Creates a sinusoidal XYZ series. The Z projection is overplotted
             as an XYZ series with constant Z values at the smallest Z
             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);zproject(w0, 0.5, purple)

             Same as above except the Z projection is plotted in purple
             at z = 0.5.

    Remarks:
             ZPROJECT overplots the Z projection of an XYZ series. The
             projection is an XYZ series with constant Z values equal to
             ZLOC. By default, ZLOC is set to the minimum Z plotting range
             of the source XYZ plot.

             See XYZPROJECT to overplot the X, Y and Z projections of an
             XYZ series.

    See Also:
             Overplot
             Xproject
             XYZ
             XYZproject
             Yproject
#endif


/* Z projection of XYZ plot */
zproject(win = refwindow(w0), zloc = getzb(win), color = -1)
{
        local z;

        if (isscalar(win))
        {
                color = zloc;
                zloc  = win;
                win   = refwindow(w0);
        }

        /* build z-y constant z */
        z = xyz(xvals(win), yvals(win), ones(length(win), 1) * zloc);

        if (outargc > 0)
        {
                return(z);
        }
        else
        {
                /* overplot */
                overplotwin(win, z, color);
        }
}