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

#if @HELP_YPROJECT

    YPROJECT

    Purpose: Overplots the Y projection of an XYZ plot.

    Syntax:  YPROJECT(win, yloc, color)

             y = YPROJECT(win)

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

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

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

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

             y = YPROJECT(win) returns the Y 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);yproject()

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

             Same as above except the Y projection is plotted in purple
             at y = 0.5.

    Remarks:
             YPROJECT overplots the X projection of an XYZ series. The
             projection is an XYZ series with constant Y values equal to
             YLOC. By default, YLOC is set to the maximum Y 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
             Zproject
#endif


/* Y projection of XYZ plot */
yproject(win = refwindow(w0), yloc = getyt(win), color = -1)
{
        local y;

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

        /* build x-z constant y */
        y = xyz(xvals(win), ones(length(win), 1) * yloc, zvals(win));

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