%  example.tex 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.
%  
\clearpage
\SectionIndex{Initial windows}
\markright{\headtitle}

\begin{figure}
\centerline{\psfig{figure=../psfig/help.ps}}
\centerline{\psfig{figure=../psfig/main.ps}}
\caption{Initial windows}
\label{fig:InitialScreen}
\end{figure}


Figure~\ref{fig:InitialScreen} shows the initial windows.
At the top is a help window that is changed based on your actions.
This window can be independently resized. Below this is
the main window. At the top is a menubar that documents
and controls the use of this window.
Below this is
space for entering \Index{\DPP{}}
language statements. These are entered in the highlighted area
(click in the region to make it the selected point for input). Commands
once entered are scrolled into the grey area. This area also contains
the language statements that are generated automatically when a
network is created graphically. 

Below this is a similar area for entering menu data base commands
from the keyboard. The last three options selected either with the keyboard
or the mouse are scrolled into the grey area. Below this is two or three
levels of the menu data base.
Push buttons that have text in 
bold face select a command when button is pushed with the left mouse
button.
If a push button has normal type it selects another menu.
You can `peel off' any line of
\index{peel off menu}
\index{menu create}
the menu tree by holding the \verb'ctrl' key down and clicking mouse button
one on a pushbutton. If this is a menu button you will get the first line
of this menu in a new window. If this is a command button you will
get a copy of the line containing this button in a new window. (These
windows can be removed by holding the \verb'ctrl'
\index{menu delete}
\index{menu remove}
\index{delete menu}
and \verb'shift' keys down while
typing \verb'delete' with the cursor over the window to be deleted.)

All of the shortcut mouse and key options (like holding the
control key down and pressing the left mouse button to peel off menus)
are listed in the pull down menus
at the top of most windows.
There is a simple coding scheme
for these.
Mouse shortcuts (if available) are in square brackets `[ ]'.
Keyboard shortcuts are in round brackets `( )'.
Keyboard shortcuts are denoted as a single character like `(p)' for 
lower case `p' or a word that designates the key like `(space)' for the
space bar. A key can be modified with the shift or control keys.
`(shift-space)' means hold the shift key down and press the space bar.
For the most part you can enter shortcut keys whenever the window is selected
and the cursor positioned within it. However there are some `dead spots'
in some windows. If you find that shortcut keys are having no effect
move the cursor around.



\clearpage
\SectionIndex {Spectral analysis example}
\markright{\headtitle}

To select the example described in this section choose \verb'examples' from
the second line in the menu. Select \verb'fft' from the third menu line and
finally select \verb'execute' from the third menu line. (The main window
never has more than three menu lines. Menus you peel off can keep
\index{peel off menu}
\index{execute example}
\index{example execute}
growing up to the length of the screen.)

\begin{figure}
\centerline{\psfig{figure=../psfig/FFT_Net_no.ps}}
\caption{Network from spectral analysis example}
\label{fig:SpectFftNet}
\end{figure}

\begin{figure}
\centerline{\psfig{figure=../psfig/ex1_fft.ps}}
\caption{FFT plot from spectral analysis example}
\label{fig:SpectFftPlot}
\end{figure}


First a graphical display of the DSP network will appear followed
by three windows that contain the network input and output
signals.
The network display and FFT output plot are
shown in figures~\ref{fig:SpectFftNet} and
\ref{fig:SpectFftPlot}. All the plots in this example are of complex data. 
The real part is shown in black and the imaginary part in red
(or gray when printed). This is not clear in the printed
plots because there is one point per pixel on the default axis.
You can see more detail by touching the right
arrow key and dragging the mouse between two positions. This will expand
the X axis of the entire plot to cover the distance between the X positions
you selected. You can see all the options for changing the plot scale
by touching the \verb'F3' function key or using the mouse to pull down
the \verb'X or Y Detail' menu. Figure~\ref{fig:SpectFftPlotExp} shows
and \Index{expanded plot} of the data in figure~\ref{fig:SpectFftPlot}. You
\index{plot expansion}
can easily see the real and imaginary components. Whenever the plot
is expanded to the point where the individual X coordinates are sufficiently
separated a dashed line is drawn at each sample plotted.
You can see more detail
in a plot without changing the scale by making the plot window
\index{plot resizing}
larger.


\begin{figure}
\centerline{\psfig{figure=../psfig/ex1_fft_exp.ps}}
\caption{Expanded spectral plot}
\label{fig:SpectFftPlotExp}
\end{figure}


For a frequency domain plot such as
\index{plot of power}
\index{plot of decibel power}
figure~\ref{fig:SpectFftPlot}, you are often more interested in the
power or decibel power.
\index{plot of power}
\index{plot of decibel power}
These are both available at one keystroke.
Position the cursor in the plot you wish to view in a different way
and type \verb'ctrl-p' to see a plot of the power like
figure~\ref{fig:PowerSpectFftPlot} or \verb'ctrl-b' to see a
decibel plot like figure~\ref{fig:DecibelSpectFftPlot}.

\begin{figure}
\centerline{\psfig{figure=../psfig/ex1_fft_p.ps}}
\caption{Power spectral plot}
\label{fig:PowerSpectFftPlot}
\end{figure}

\begin{figure}
\centerline{\psfig{figure=../psfig/ex1_fft_d.ps}}
\caption{Decibel spectral plot}
\label{fig:DecibelSpectFftPlot}
\end{figure}


\begin{figure}
\centerline{\psfig{figure=../psfig/ex1_desc.ps}}
\caption{Program for spectral analysis example}
\label{fig:SpectDesc}
\end{figure}

If you now select the \verb'desc' option in the menu for
the \verb'fft' example a window will appear with
\index{example description}
a description and 
program. Figure~\ref{fig:SpectDesc} shows
this enlarged
to include the entire program. (To delete help windows like this
position the cursor in the window, hold the \verb"ctrl" and \verb"shift"
\index{help window delete}
\index{delete help window}
\index{remove help window}
keys down and type \verb"delete".)

It is not necessary to know the \Index{\DPP{}} language to define
DSP networks. They can be built by pointing to the DSP
nodes you want to connect. However this language provides a concise and
readable record of your work. It is the format used for
saving objects and networks between sessions.
\index{object saving}
\index{session saving}
It may be helpful
to refer
to both the program in figure~\ref{fig:SpectDesc} and the
network display in figure~\ref{fig:SpectFftNet} in understanding this
example.


\begin{figure}
\centerline{\psfig{figure=../psfig/ex1_menu.ps}}
\caption{Menu for FFT\_Sig object}
\label{fig:SpectFftSigMenu}
\end{figure}


\begin{figure}
\centerline{\psfig{figure=../psfig/ex1_men_help.ps}}
\caption{Description of FFT\_Sig object}
\label{fig:SpectFftSigDesc}
\end{figure}



The nodes in the network display have two names. The top one is the
class name and the lower one is the object name. The first node is
\index{node class name}
\index{node name}
\index{class name}
\index{object name}
a \verb'CxCos' or complex cosine signal called \verb'FFT_Sig'. We can refer
to the program listing to see the frequency, phase and amplitude of
this signal. We can also get this information by holding the \verb'ctrl'
key down and clicking the left mouse button with the cursor in this node.
The menu that comes up when you do this and the description that will
appear in the help window when you select \verb'desc' from this menu
are in figures~\ref{fig:SpectFftSigMenu} and~\ref{fig:SpectFftSigDesc}.
We see from
this figure that the frequency is $0.02655$ radians per sample.
From the program we see that this corresponds to a frequency of
$2 \times \pi \times .08$ radians per sample
or $.08$ hz with a 1 hz sample rate.
A default sample rate of 1 hz. is assumed.
\index{sample rate default}
\index{default sample rate}
You can set the
sample rate for any node in the network and the timing will be
adjusted for all affected displays. Select the \verb'exec'
option from the menu for \verb'FFT_Sig' and then the \verb'SetSampleRate'
\index{sample rate}
\index{SetSampleRate}
option to change the sample rate of the network. If you check
the spectral plot in figure~\ref{fig:SpectFftPlot} you will
see there is a peak at $.08$ hz. If you now change the sample rate
to 4 hz the scale on the frequency plot will be adjusted so the
peak is at .32 hz.


Returning to the display of the entire network in
figure~\ref{fig:SpectFftNet} we see that \verb'FFT_Sig' is connected
to a small box with the number `2' in it. This represents an output buffer
\index{node channel number of}
that drives the inputs of two nodes. One of these is node \verb'FFT_Sum'.
The `2' in the left hand part of this node stands for two input channels.
Each node can have a variable number of input channels, output
channels and nodes driven by each output channel. These are represented
by numbers at the left of the node at the right of the node and in the
buffer box to the right of the node. The output from \verb'FFT_Sum' goes
to a complex FFT (\verb'CxFFT') called \verb'FFT_FFT' and a plotting node
called \verb'FFT_Plot'. This latter node generated the spectral plot we
just discussed. The other output from \verb'FFT_Sig' goes to another plotting
node called \verb'FFT_PltSignal'. Notice that the plots for both the spectral
output and the linear time series are the same class \verb'Plot'. This class
\index{Plot}
\index{Plot data types}
of node knows the type of data it is receiving and generates
the correctly formatted plot. You need not select different nodes
or enter parameters redundantly to get the correct plot. The other
input to \verb'FFT_Sum' comes from a \Index{Gaussian noise}
generator \verb'FFT_Noise'.
The output from this node is also plotted.
