,mlplot.1

speech signal process tools

.\" %W%  %G%
.TH MLPLOT 1-ESPS %G%
.ds ]W "\fI\s+4\ze\h'0.05'e\s-4\v'-0.4m'\fP\(*p\v'0.4m'\ Entropic Speech, Inc.
.SH "NAME"
mlplot - plot long sampled data files in multiline format
.SH "SYNOPSIS"
.B mlplot
[
.BI \-a " range"
] [
.BR \-m { cpv }
] [
.BI \-p " range"
] [
.BI \-l
] [
.BI \-s " int"
] [
.BI \-t " int"
]
.br
[
.BI \-x " scale"
] [
.B \-z
] [
.BI \-P " file.esps"
] [
.BI \-X " text"
] [
.BI \-Y " text"
] [
.BI \-d " device"
]
.br
[
.BI \-o " outdir"
] [
.BI \-n
] [
.BI \-D " debug level"
] [
.I file1.sd file2.sd ... filen.sd
]
.SH "DESCRIPTION"
.PP
.I Mlplot
reads
.I n
ESPS sampled data files
.I file1.sd
to
.I filen.sd
and produces an
.IR xy-plot
of sample value
.I vs.
sample number.
If
.I file1.sd
is ``\-'', the standard input is read along with any other file names
specified.
The standard input is also read if no files names are specified and the
.B \-P
option is not given.
If no input file names are specified, but an ESPS
file containing tags is given with the
.B \-P
option, then the first source file named in its header
is used as an input Sampled Data file.
.PP
Output is a stream of plotter commands written to the standard
output.
The default output is in Graphics Primitive String (GPS)
format suitable for displaying plots on a MASSCOMP graphics terminal.
The output format can be changed by specifying a different device
name with the \fB\-d\fP option.
The output format is suitable for an
Imagen ``Image Station'' laser printer in Tektronix-4014 emulation mode
if ``imagen'' is the device name specified using the \fB\-d\fP option.
.PP
The abscissas are scaled so that the spacing between plotted points
is an exact integer number of device resolution units in the
horizontal direction.
If the required number of points will not fit
in the available width of the page, the plot is continued on a second
``line'':  a second set of axes lined up below the first.
If more
continuation lines are needed than will fit on one page, the plot is
continued on additional pages.
.PP
If the graph is to be displayed on a MASSCOMP graphics terminal, then
a page corresponds to a \fIregion\fP in MASSCOMP universe coordinates
and up to 25 regions can be displayed simultaneously on the screen.
If the \fB\-o\fP option is specified, then a directory is created
with the name given by \fIoutdir\fP and a file is created for each
page (region) generated.
Note, the \fB\-o\fP option only applies if
the device name specified is ``gps'' (the default) and the output is
\fIalso\fP sent to stdout for viewing the whole graph in the
\fIuniverse\fP (this can be restricted by the \fB\-n\fP option). 
.SH "ESPS PARAMETERS"
.PP
This program does not access the parameter file.
.SH "ESPS HEADERS"
The following items of the input sampled-data file header are
accessed:  
.I common.type,
.I common.ndrec,
.I common.ndouble,
.I common.nfloat,
.I common.nlong,
.I common.nshort,
.I common.nchar,
and
.I common.tag.
If the
.B \-P
option is specified, the following items of the file
header are accessed:  
.IR variable.source [0]
and
.I common.tag. 
.SH "OPTIONS"
The following options are suported.
Values in brackets are defaults. 
.TP
.BI \-a " upper" ":" "lower"
.TP
.BI \-a " limit"
Amplitude range.
Specifies sample values for the upper and lower
.IR y- axis
limits.
The second form is equivalent to
.BI \-a " \-limit" ":" "limit."
If the option is omitted, or if both limits are omitted,
.RB ( \-a: )
then a default range for each file is computed from the data.
If one limit is omitted,
a default limit for each file is computed from the data.
.TP
.BI \-d " device [gps]"
The output device types currently supported are ``gps''
(the default), ``imagen'' and ``tek''.
.TP
.BI \-D " debug level"
Print diagnostic messages as program runs (for debugging purposes
only).
.TP
.BR \-m { pvc "} [c]"
``Mode.''  Selects one of 3 styles.
.RS
.TP
.B c
Connected.
Successive data points are connected by straight lines.
.TP
.B p
Point.
Individual data points are plotted without connecting lines.
.TP
.B v
Vertical line.
Each point is connected to the 
.IR x- "axis (" y "=0)"
by a vertical line.
.RE
.TP
.BI \-p " first" : "last" "\fR [(first in file):(last in file)]"
.TP
.BI \-p " first" :+ "incr"
In the first form, a pair of unsigned integers specifies the range of
samples to be plotted.
Either 
.I first
or
.I last
may be omitted; then the default value is used.
If 
.IR last " = " first " + " incr,
the second form (with the plus sign) specifies the same range as the
first.
If the specified range contains points not in the file, the
range is reduced as necessary.
.TP
.BI \-l
If this option is specified, then the sample values are plotted
starting with the range given by the
.BI \-p
option.
Otherwise, the plots are plotted by an offset determined by
the number of horizontal resolution units.
.TP
.BI \-n
Suppress output to stdout when writing into a directory with the
\fB\-o\fP option.
.TP
.BI \-o " outdir"
Create a directory named \fIoutdir\fP and write output pages
(regions) into files named \fIpage1, page2, page3,\fP etc.
This
option is only valid if the output device is gps. 
.TP
.BI \-s " int" "\fR [1]"
Samples in the input file are numbered starting with the given integer,
rather than 1, for the first sample.
This option may be specified
.I m
times, where
.I m
is less than or equal to the number of files to be plotted.
Only the first
.I m
files will be affected by this option.
.TP
.BI \-t " int" "\fR [100]"
Number of samples per labeled tic mark on the
.IR x- axis.
.TP
.BI \-x " scale" "\fR [4]"
Number of resolution units along the
.IR x- axis
between plotted samples.
Must be an integer.
.TP
.B \-z
Do not draw the
.IR x- "axis (" y "=0)."
.TP
.BI \-P " file" "\fR [(no tagged file)]"
Mark tag locations given in the named file.
This option only applies to the first input file specifed or,
if none are given,
to the first source file of the file specified with this option.
Any additional files are plotted without any
tag markings.
.TP
.BI \-X " text" "\fR [(none)]"
Title to be printed at the bottom of each page.
.TP
.BI \-Y " text" "\fR [(none)]"
Title to be printed along the left edge of each page (running upward).
.SH "EXAMPLES"
.PP
%
.B mlplot
.BI \-d " imagen " \-p " 4555:9000 " \-l " flute.sd jesdec.sd | "
.BI ipr " " \-Ltektronix
.br
# begin plot at sample 4555 and send output to be printed
.br
# on an Imagen laser printer.

%
.B mlplot
.BI  \-d " imagen " \-x " 1 " \-t " 300 file1.sd file2.sd | "
.BI ipr " " \-Ltektronix
.nf
# Print two sampled data files on an Imagen laser printer
# with 1 pixel per point resolution and tic marks every 300 samples.
.fi

%
.B mlplot
.BI  \-d " gps " \-o " FLUTE " \-n " flute.sd "
.br
.nf
# create a directory called FLUTE to which to send the output, and
# suppress output to stdout (\fB\-n\fP option).
The files generated will
# correspond to pages generated by the first example above.
# To view the second page on a MASSCOMP Graphics terminal,
# type the following:

.fi
%
.BI mcd " FLUTE/page2"
.br
# or
.br
%
.BI ged " FLUTE/page2"
.br
.nf

# The latter command allows you to zoom into various parts of the
graph; see the DATA PRESENTATION APPLICATION PROGRAMMING MANUAL for
more information concerning \fIged\fP.
.fi
.SH "FILES"
.PP
None.
.SH "SEE ALSO"
.PP
.I "plotsd genplot"
.SH "DIAGNOSTICS"
.PP
.nf
mlplot: unknown option \-\fIletter\fP
Usage: mlplot [\-a range][\-m{cpv}][\-p range][\-t int][\-x scale][\-z][P file.esps][\-X text]
	[\-Y text][\-s int][\-l][\-o outdir][\-n][\-d device][file1.sd ...]
mlplot: can't allocate memory for \fIn\fP points
mlplot: can't open \fIfilename\fP: \fIreason\fP
mlplot: \fIfilename\fP is not an ESPS file
mlplot: \fIfilename\fP is not a sampled-data file.
mlplot: \fIfilename\fP is not tagged.
mlplot: empty amplitude range specified.
.SH "FUTURE CHANGES"
Options to allow more control over format.
More intelligent choice
of axis subdivisions.
Selection
of default \fIy\fP-axis limits according to header information.
.SH "BUGS"
Default for the
.B \-t
option should depend on the 
.IR x- scale
.RB ( \-x " option)."
.br
.SH "AUTHOR"
Rodney W. Johnson and Ajaipal S. Virdy, Entropic Processing, Inc.