\"  pplots.roff from ObjectProDSP 0.2
\"  Copyright (C) 1994 1995, Mountain Math Software. All rights reserved.
\"  
\"  This file is part of ObjectProDSP, a tool for Digital Signal
\"  Processing design, development and implementation. It is free
\"  software provided you use and distribute it under the terms of
\"  version 2 of the GNU General Public License as published
\"  by the Free Software Foundation. You may NOT distribute it or
\"  works derived from it or code that it generates under ANY
\"  OTHER terms.  In particular NONE of the ObjectProDSP system is
\"  licensed for use under the GNU General Public LIBRARY License.
\"  Mountain Math Software plans to offer a commercial version of
\"  ObjectProDSP for a fee. That version will allow redistribution
\"  of generated code under standard commercial terms.
\"  
\"  This program is distributed in the hope that it will be useful,
\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
\"  GNU General Public License for more details.
\"  
\"  You should have received a copy of version 2 of the GNU General
\"  Public License along with this program. See file COPYING. If not
\"  or if you wish information on commercial versions and licensing
\"  write Mountain Math Software, P. O. Box 2124, Saratoga, CA 95070,
\"  USA, or send us e-mail at: support@mtnmath.com.
\"  
\"  You may also obtain the GNU General Public License by writing the
\"  Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
\"  USA.  However if you received a copy of this program without the
\"  file COPYING or without a copyright notice attached to all text
\"  files, libraries and executables please inform Mountain Math Software.
\"  
\"  ObjectProDSP is a trademark of Mountain Math Software.
\"  
.H 1 "Plots"

Plots in ObjectProDSP are windows on data streams. You can move
the window though the data with the `page-up' and `page-down' commands
and the scroll bar at the bottom of each plot.

Real data may be plotted as a linear time series. Complex data may be plotted
as a linear time series or as an `eye' or X-Y plot, i. e. where the real value
determines the X coordinate and the imaginary value determines the y
coordinate. The linear plot node configures itself based on the type of
input data it receives. If its input is complex it will plot the real
and imaginary components in different colors.

Data streams have an element size parameter that determines
the number of scalar values in each sample. This includes but
is not limited to
1 for real and 2 for complex data. All
element size components will be displayed on the same plot using
with different colors for each component.

To access the plot nodes select `objects' and `plot'.

.H 2 "Plotting FFT (blocked) output"

If the input to a plot node is from an FFT 
one frame from the FFT will be displayed in each plot. The X axis
will be labeled in frequency
based on the sample rate of the data stream and the FFT parameters.
(A default sample rate
of 1 hz for the first input channel is assumed if no rate is set.)

A block size parameter associated with each data stream determines
the number of samples displayed in a plot. If the block size
is 1 then the a strictly linear time series is assumed. The block size
parameter is generated by the FFT node and read by the
plot node. 

.H 2 "Output after a network has been edited"

If you execute a network, edit it and then execute it for additional
iterations there may be discontinuities in the output at the point of
the edit. If your editing adds new plotting nodes these will have
a different time base then the plot nodes that were present
before the edit. When you edit a network all the buffers are cleared
and the nodes are reset. If you want output from an edited network
with a consistent time base write the state out and then read it
back in with options in the `state' menu. You must use the
`read over state' option if you want to replace a network that
has already been defined. Alternatively you can exit ObjectProDSP
and then reexecute it. The state will be saved and read back in
when you restart (unless you use the `-c' option or not using
the default state file name).

.H 2 "Invalid numeric values"

If the numbers sent to the plotting routine in the user interface
process are not valid IEEE floating point values they will be converted
to 0. A warning is displayed the first times this happen. A count
of these is kept and can be displayed from `state' and `plot err'
in the menu data base. This should not happen unless you a debugging
a node that generates such values. There is only limited protection
against this. Such values can cause the system to crash with a
floating point exception.


.H 2 "Saving and reading plots"

A plot can be saved as a file and a plot window image from
the `View' pull down menu.
This image window is saved with the X-windows utility `xwd'.
It can be translated to a postscript file with the utility
`xpr'. The postscript file can be included in printed documents.

A plot saved in a file can be read by ObjectProDSP
and includes all the data in the original plot, not just the data displayed
in the window. To read a plot file saved in this way select `setup' and
`read plot' in the menu data base.


