\section{Graphics Post-Processors}

\subsection{mplot}

\label{sec:mplot}

\tt mplot \rm is one of the graphics post-processors used in
connection with OASES and other compatible  acoustic propagation
models. 
It produces
publication quality line-style graphics using the \tt MINDIS \rm
graphics library.

Alternatively, \tt plotmtv \rm may be chosen as the default line plot
package by setting an environment variable:

\begin{verbatim}
setenv PLP_PACKGE MTV
\end{verbatim}

It should be noted that some of the \tt mplot \rm options described
below may not be fully supported by \tt plotmtv. \rm


\subsubsection{Input files}

\tt mplot \rm requires two input files, with extensions \tt plp \rm
and \tt plt \rm.

The file with extension \tt plp \rm contains plot parameters such as axis 
lengths, titles, labels etc, whereas the other file, with extension
\tt plt \rm, 
contains the actual data values to be plotted. Both files are formatted ASCII
files, and it is therefore possible to change the layout of the plots by
editing the \tt plp \rm file. 

A typical \tt plp \rm file is:

\small
\begin{verbatim}
     1024                                 MODULO
_FIPP__STLDAV,CPX,IYA	
_DEPTH AVERAGED LOSS	
_SAFARI-FIP case 3.	
_       2                                 NUMBER OF LABELS 
_Freq:   30.0 Hz$
_SD:     50.0 m$
_      20.000000                          XLEN	
_      12.000000                          YLEN	
_       0                                 GRID TYPE	
_    0.000000                             XLEFT	
_     5.00000                             XRIGHT	
_     1.00000                             XINC	
_     1.00000                             XDIV	
_Range (km)$	
_LIN		
_     80.0000                             YDOWN	
_     20.0000                             YUP
_     10.0000                             YINC
_     1.00000                             YDIV
_Normal stress (dB//1Pa)$
_LIN				
_        1                                NC
_      112                                N	
_        0.044957                         XMIN	
_    0.449567-001                         DX	
_    0.000000                             YMIN
_        0.000000                         DY
_FIP___PLTEND			
\end{verbatim}
\normalsize


The underscore denotes a space which is necessary for \tt mplot \rm to correctly read
the file. The \tt plp \rm file will always start with a block size MODULO, with which
the corresponding data file was written. This parameter is a leftover from
the versions using binary data files, but for the present version of
\tt mplot \rm
this parameter is dummy. The file ends with the \tt PLTEND \rm flag 
signalling the end-of-file.

Between these two records the blocks of actual plot parameters are specified, 
in the present case for a single plot only. Any number of blocks could, 
however, be included, each generating one plot.

The plot parameter block starts with a record specifying a 12-character plot
identification (FIPP  STLDAV) followed by a series of 3-character options
separated by commas. The files generated by the acoustic propagation
models
 will in general
not have any options specified, but these are important tools for generating
final plots. The following options are currently available:

\begin{itemize}
\item[DUP] A {\bf DUPLEX} character generator will be used in stead of the
	default {\bf SIMPLEX}.
\item[CPX] The {\bf COMPLEX} character generator is selected. 
\item[ITA] The {\bf ITALIC} character generator is used.
\item[IXA] Integer format will be used for plotting the $x$-axis tick mark numbers	instead of the default decimal format.
\item[IYA] Integer format will be used for plotting the $y$-axis tick mark numbers	instead of the default decimal format.
\item[DSD] If the plot contains more than one curve (NC$>1$), then the first 
	curve will be plotted with a solid line, the second with a dashed and
	the third with a dotted. If more than three curves are plotted, this
	sequence will be repeated. 
\item[COL] This option will plot individual curves in different colour, using
	the repeatable sequence: red - green - blue - cyan - magenta -
yellow.
Also affects the shading option \tt SHD \rm.
\item[MRK] A marker will be plotted for each 10th data point on the curves. In
	the case of more curves, different markers will be used for each. 
\item[TCT] This option is used in connection with the stacked time series
	plots in order to truncate the amplitude of each trace at an amplitude
	corresponding to half the distance between traces. 
\item[SHD] Produces shaded wiggles on timeseries plots. If specified
alone both positive and negative wiggles will be shaded. If specified
together with options \tt POS \rm or \tt NEG \rm only the positive or
negative wiggles will be shaded, respectively. If specified together
with \tt COL \rm the shading is color coded depending on the
amplitude. Currently the shading will only appear on the hardcopy
devices.
\item[POS] Shading only applied to positive wiggles.
\item[NEG] Shading only applied to negative wiggles.
\item[NWR] Disables plotting of the option at the upper right corner
of the plot. Used when generating final figures for documents.
\item[NOP] This option will read both the parameters from the \tt plp \rm file and 
	the data from the \tt plt \rm file but no plot is produced. It is therefore
	used for time saving when only selected plots are required. 
\end{itemize}

The next record specifies the main title of the plot, followed by a record
containing the title specified in the data file for the propagation
models. 
This title will be plotted just above the plot frame.

There is then a sub-block containing the labels to be plotted in the upper right
corner of the plot frame. The number of labels ($\geq 0$) is given first, 
followed by the label texts, each of which should be on separate lines and 
terminated by a \$.

The parameters XLEN and YLEN specify the length in cm of the $x$- and $y$-axis,
respectively. The parameter labelled \tt GRID TYPE \rm indicates whether a
grid should be plotted. A value of 1 will produce a dotted grid.

The next 6 records contain the parameters for the $x$-axis of the
plot. \tt XLEFT \rm
and \tt XRIGHT \rm are the data values at the left and right borders of the plot frame,
respectively, whereas \tt XINC \rm is the distance in the same units between the
tick marks. \tt XDIV \rm is a multiplication factor which will be applied to both the
axis parameters and the data values. After \tt XDIV \rm the $x$-axis label is specified,
terminated by a \$, and finally \tt LIN \rm indicates that the $x$-axis should be linear.
Another possibility is a logarithmic axis, which has not yet been implemented 
however. The parameters for the $y$-axis are given in the same way in the next 6
records. 

The parameter \tt NC \rm specifies the number of curves to be plotted. For each curve
a sub-block of 5 records has to be specified. The first parameter \tt
N \rm indicates
the number of points in the curve. If \tt N \rm is negative, no curve will be plotted; 
instead a marker will be plotted at the position of each data point. The 
parameter \tt XMIN \rm  is the $x$-coordinate (range) of the first data point, whereas 
\tt DX \rm is the equidistant spacing. If \tt DX \rm had been
specified as 0, then the 
\tt N \rm $x$-coordinates of the data points would be read from the
\tt plt \rm file. In that
case \tt XMIN \rm would be interpreted as an $x$-offset to be applied to the curve. The
same rules apply to \tt YMIN \rm  and \tt DY \rm. In the above example the $y$-values  will therefore be read from the PLT file, and no $y$-offset will be
applied. The offsets are mainly used for the stacked time series plots
If both \tt DX \rm  and \tt DY \rm are specified
as 0, then \tt mplot \rm will first read all \tt N \rm  $x$-values and
then all $y$-values. 

\subsubsection{Executing mplot}

To execute \tt mplot \rm, prepare the input files,
e.g. \tt input.plp \rm  and \tt input.plt \rm   as described above. 
Then execute the script
\begin{itemize}
\item[$\>$] \tt mplot input \rm
\end{itemize}

\subsection{cplot}
\label{sec:cplot}

\tt cplot \rm is the standard script for producing contour plots
generated by SAFARI, OASES or SNAP.
However, \tt cplot \rm is available for more general
use, provided the data to be contoured and the plot lay-out parameters
are  file-structured as
described below. 

The plot lay-out parameters are transferred to \tt cplot \rm in a file
with extension \tt .cdr \rm, whereas the actual contour data are
transferred in a file
with extension \tt .bdr \rm. 
The data file is allowed to be in both ASCII or binary 
format, but in computational environments with different types of
hardware platforms, it
is most convenient to use ASCII format.

The \tt cdr \rm file can be edited for changing the layout of the 
contour plot. As
a typical example, the \tt cdr \rm  file used to create the contour plot in 
Fig. 14b of the {\em SAFARI User's Guide}  is as follows:

\small
\begin{verbatim}
CONDR,FIP,FMT,CPX,UNI,TEK 	
SAFARI-FIP case 5.  
saffip5.bdr          
Range (m)         	
          0.0000    RMIN
        299.8535    RMAX
          0.0000    XLEFT	
        300.0000    XRIGHT	
         15.0000    XSCALE	
         50.0000    XINC	
Depth (m)         	
         50.0000    YUP	
        125.0000    YDOWN	
          6.2500    YSCALE	
         25.0000    YINC	
        141.0000    DATA POINTS ALONG X AXIS	
         51.0000    DATA POINTS ALONG Y AXIS	
          1.0000    DIVX 	
          1.0000    DIVY 	
          0.0000    FLAGRC 	
         50.0000    RDUP 	
        125.0000    RDLO 	
         50.0000    SOURCE DEPTH (M)
        141.0000    GRID POINTS ALONG X AXIS 
         51.0000    GRID POINTS ALONG Y AXIS 
       1000.0000    FREQUENCY (HZ)	
          0.0000    DUMMY 
          5.0000    CAY 	
          5.0000    NRNG 	
         21.0000    ZMIN 	
         54.0000    ZMAX 	
          3.0000    ZINC 	
          2.0000    X ORIGIN OF PLOT IN INCHES
          0.0000    DUMMY 	
          2.0000    Y ORIGIN OF PLOT IN INCHES
          0.0000    NSM   	
          0.1000    HGTPT 	
          0.1400    HGTC 	
         -3.0000    LABPT 	
          1.0000    NDIV 	
          5.0000    NARC 	
         -1.0000    LABC 	
         -1.0000    LWGT 	
BOTTOM  1
  0.0 100.0
300.0 100.0
300.0 120.0
  0.0 120.0
BOTTOM  3
  0.0 120.0
300.0 120.0
300.0 125.0
  0.0 125.0
\end{verbatim}
\normalsize

The first record specifies one 5-character option (CONDR) followed by a series
of 3-letter options. The CONDR option indicates that the actual contour plot
is of the depth-range type and \tt cplot \rm will interpret the parameters 
accordingly. {\em This option should therefore never be changed}. The first
3-letter option (FIP) is purely for identification and has no further effect.
The FMT option  indicates that the \tt bdr \rm  data file is ASCII
formatted 
(BIN for
binary format). These first 3 options should always be present in the specified
order, but the options following are optional and can be given in any
order.  The
implemented options are as follows:
\begin{itemize}
\item[DUP] The {\bf DUPLEX} character generator will be used for MINDIS plots
	 instead of the default {\bf SIMPLEX}.
\item[CPX] The {\bf COMPLEX} character generator is selected for
MINDIS plots.
\item[ITA] The {\bf ITALIC} character generator will be used by MINDIS.
\item[MIN] The MINDIS plot package will be used to produce line contour plots.
\item[MTV] The PLOTMTV plot package will be used to generate a colour or 
greytone contour plot. MINDIS is the default plot package.
\item[UNI] The UNIRAS plot package will be used to generate a colour or 
greytone contour plot. MINDIS is the default plot package.
\item[X11] The raster plot will be produced on the X-windows display
defined by the current setting of the \tt DISPLAY \rm environmental variable. 
        (UNIRAS only).
\item[TEK] The raster plot will be produced on the Tektronix 4691 ink jet
	plotter (UNIRAS only).
\item[LAS] The raster plot will be produced on the default laser 
	printer (UNIRAS only).
\item[CLA] A Colour-Postscript file is created which may be printed on
	a colour laser printer (UNIRAS only).  
\item[PSP] A Grey-tone Postscript file in portrait mode is created for
later printing or inclusion in LaTeX documents.
\item[PSL] A Grey-tone Postscript file in landscape mode is created for
later printing or inclusion in LaTeX documents.
\item[COL] If the options MTV or UNI has been selected, 
	a colour raster plot using an inbuilt colour scale will be generated. 
	By default greytone scale is applied (UNIRAS and PLOTMTV).
\item[REV] Reverses the default colour or grey-tone scales (UNIRAS only).
\item[ROT] UNIRAS plots will be rotated 90 degrees. On most
graphics devices the default is landscape mode. 
\item[NCL] By default the raster plots will have the contour lines
separating the levels plotted as well. This option disables this feature.
\item[NCS] By default a colour scale will be produced to the right of
the contour map. This option disables this feature.
\end{itemize}

If you are using \tt cplot \rm through X-Windows, UNIRAS or PLOTMTV plots may
alternatively be 
generated interactively after the
default MINDIS plot is produced. 
The default graphics package may be changed by setting environmental 
parameters. Thus, to change the default to PLOTMTV color in X-windows, use the following definitions in your \tt .login \rm file:

\begin{verbatim}
 setenv CON_BWCOL COL
 setenv CON_PACKGE MTV
 setenv CON_DEVICE X11
\end{verbatim}

PLOTMTV is available in public domain, and is easily installed, as described
inSection~\ref{sec:plotmtv}.  
 
After the option record there is a record containing the title of the plot and
a record containing the name of the file containing the data, i.e. the
\tt bdr \rm
file. Except for 2 records containing the $x$-axis and $y$-axis
labels,  the rest 
of the records contain numerical parameters, all supplied with a descriptive
label. In general only a few of these parameters should be changed. 
The most important ones are described below.

The lengths of the $x$- and $y$-axes are controlled by the parameters
XSCALE  and 
YSCALE, respectively. \tt cplot \rm requires these parameters to be
specified  in
coordinate units per cm. ZMIN and ZMAX specify the limits of the contouring
interval, whereas ZINC is the associated increment. If UNIRAS is selected, 
areas with small data values will be filled with magenta colour or black 
in the greytone mode. The colour scale then moves through different red tones
into blue (white in the greytone mode). If the default MINDIS package is
selected, only contour lines with identifying numbers are plotted. 


Another important parameter is NSM, which controls the amount of smoothing
applied to the calculated contours. This parameter can be set to any value 
between 0 and 10, with 0 corresponding to no smoothing. It is obvious that this
parameter should be used with extreme care.

At the end of the file, any number of blocks -- identified by the
keyword \tt BOTTOM \rm -- can be specified, creating a shaded polygon
in one of 4 grey-tones as specified by the number
following the keyword \tt BOTTOM \rm (1 is light grey and 4 black). 
Each line following states the
$x$- and $y$-coordinates of the corners of the polygon.

The top of the corresponding \tt bdr \rm file looks as follows:

\small
\begin{verbatim}
    141.00    51.00  0.0E+00   1.0000  0.0E+00  0.0E+00
   0.0E+00  0.0E+00  0.0E+00  0.0E+00  0.0E+00  0.0E+00
   0.0E+00  0.0E+00  0.0E+00  0.0E+00  0.0E+00  0.0E+00
   0.0E+00  0.0E+00  0.0E+00  0.0E+00  0.0E+00  0.0E+00
   0.0E+00  0.0E+00  0.0E+00  0.0E+00  
    25.866   22.212   20.700   20.726   21.781   23.280    
    24.908   26.937   29.723   33.102   36.234   38.500    
    40.540   43.220   45.981   47.238   48.749   52.225    
    55.318   56.159   59.268   64.670   65.453   67.815    
    75.660   77.704   79.630   90.666   109.52   91.888    
    89.072   87.422   83.239   85.975   85.229   81.266    
    84.744   85.196   81.190   84.615   86.690   82.392    
      :        :        :        :        :        :
      :        :        :        :        :        :
\end{verbatim}
\normalsize

The \tt bdr \rm file must have a header with 28 real numbers. Only the
first 4 numbers are of significance. The first is the number of
columns
(or $x$-values) in the data matrix, with the second similarly giving
the
number of rows (or $y$-values). These numbers must be identical to the
corresponding number of data points specified in the \tt cdr \rm file.
The third and fourth numbers must be specified as 0.0 and 1.0, 
respectively.
After the header the data to be contoured follow row by row in free
format. Alternatively, the data may be specified column-wise, 
provided the parameter FLAGRC is set to 1.0 in the \tt cdr \rm file. 


\subsubsection{Executing cplot}

To execute \tt cplot \rm, prepare the input files,
e.g. \tt input.cdr \rm  and \tt input.bdr \rm   as described above. 
Then execute the \tt cplot \rm script
\begin{itemize}
\item[$\>$] \tt cplot input \rm
\end{itemize}
