plotpit.1

speech signal process tools

.TH PLOTPIT 1-SPS 9/29/86
\"@(#)plotpit.1	1.2 9/29/86 EPI
.ds ]W "\fI\s+4\ze\h'0.05'e\s-4\v'-0.4m'\fP\(*p\v'0.4m'\ Entropic Processing, Inc.
.SH NAME
plotpit - plot pitch pulse positions and sampled data
.SH SYNOPSIS
.B plotpit
[
.BI \-s " sdfile"
] [
.B \-e
] [
.BI \-x " debug_level"
] [
.BI \-p " range"
] [
.BI \-y " range"
] [
.BI \-Y " range"
] [
.BI \-m " maxpnts"
] [
.BI \-t " text"
]*
.I pitfile
.SH DESCRIPTION
.PP
.I Plotpit
plots a portion of a sampled data file together with lines marking pitch
pulse positions in that file.  Actually, 
.I plotpit
generates commands that are suitable for
.IR plotas (1)
or
.IR stou (1).
By default, the sampled data file to be
plotted is determined from the field
.I variable.refer
in the header of
.I pitfile, 
but an alternate sampled data file may be specified with the 
.B \-s
option.
.PP
If the \fB\-p\fP option is omitted, then the \fIrange\fP is computed
from the parameter and common files, otherwise the the entire file is
used as the default range.  A range from the common file is not used
unless the 
.I filename
in the common file matches the source SD file name from the pitch file
header (or the name given with 
.B \-s).  
.PP
.I Plotpit
finds the maximum and  minimum values in the specified range 
and computes appropriate scales for the 
.I x\-
and 
.IR y\- axes.
These automatic values can be overriden by the 
.B \-y
or
.B \-Y 
options.  
.PP
When 
.IR stou "(1) and"
.IR mcd (1)
are used to plot on the Masscomp screen (see EXAMPLES, below), the plots
will take a long time if every point is plotted.  For this reason, 
.I plotpit
plots a maximum of approximately 3000 points across the range 
specified by the user (intermediate points are skipped).  This behavior
can be changed by means of the 
.B \-m 
option.   
.PP
.I Plotpit
will run faster if the 
.B \-Y
option is used, especially in the case of large files.  
.SH OPTIONS
.PP
The following options are supported:
.TP
.BI \-s " sdfile"
Specifies the name of the SD file to plot with pitch marks from
.I pitfile.  
If this option is not used, 
.I plotpit
tries to determine the SD file from the 
.I variable.refer
field in the header of 
.I pitfile.  
.TP
.B \-e
Calls for plotting preemphasized data instead of the true data.
The filter coefficients are sought in the
.IR hd.pit \-> prefilter
field of the pitch-file header, in lieu of the old SDS
.I hd_pre
field, which does not exist under SPS.
The option is not currently useful (April, 1986) \- see ``Bugs'' below.
.TP
.BI \-x " debug_level\fR [0]\fP"
Sets the debugging level.  If it is nonzero, the names of the two input
files are written to the standard error output.  
.TP
.BI \-p " first:last"
.TP
.BI \-p " first:+incr
Determines the range of points to be plotted.  In the first form, a
pair of unsigned integers gives the first and last points of the range.  
If 
.I first
is omitted, 1 is used.  If 
.I last 
is omitted, the last point in the file is used.  The second form is
equivalent to the first with 
.I "last = first + incr".
.TP
.BI \-y " low:high"
Specifies approximate lower and upper limits for the 
.IR y- axis.
The values are adjusted by 
.I plotpit
in an attempt to make an esthetically pleasing plot.  
.TP
.BI \-Y " low:high"
Specifies exact lower and upper limits for the 
.IR y- axis.
.TP
.BI \-m " maxpnts\fR [3000]\fP"
Specifies that 
.I plotpit
plot up to an approximate maximum of 
.I maxpnts 
points.  If the total number of points in the 
.I range
exceeds 
.I maxpnts,
points are skipped evenly throughout.  
.TP
.BI \-t " text"
A line of text to be printed below the plot.  
Up to ten
.B \-t
options may be specified; they are printed as text lines in order below the
plot.
.SH EXAMPLES
.TP
.BI "plotpit " <options> " | stou | mcd"
plots on the Masscomp display.
.TP
.BI "plotpit " <options> " | plotas | tpen | ipr -Ltektronix"
plots on the Imagen
.TP
.BI "plotpit " <options> " | stou | tek | ipr -Ltektronix"
also plots on the Imagen, but a scaling factor may need to be 
specified for tek. 
.TP
.BI "plotpit " <options> " | plotas | tpen"
plots on a Tektronix terminal
.TP
.BI "plotpit " <options> " | stou | tek"
also plots on a Tektronix terminal. 	
.SH "SPS COMMON"
The following items are read from the SPS Common file.  The values for
start and nan are not used if a range is specified on the command line or
if the referenced sample data file is not the same file identified in the
Common file by the "filename" symbol. 
.IP
.I "start - integer"
.IP
This is the starting point in the sampled data file to begin
plotting. 
.sp
.I "nan - integer"
.IP
This is the number of points (starting at 
.IR start ) 
to plot.
.sp
.I "filename - string"
.IP
This is the name of the file to be displayed if \fIfile\fP is omitted
from the command line.
.PP
The following items are written into the SPS Common file:
.IP
.I "start - integer"
.IP
The left point in the range selected.
.sp
.I "nan - integer"
.IP
The number of points in the selected range.
.sp
.I "beginplot - integer"
.IP
The origin of the graph (x-coordinate).
.sp
.I "endplot - integer"
.IP
The end point of the graph (x-coordinate).
.sp
.I "prog - string"
.IP
This is the name of the program (\fIplotpit\fP in this case).
.sp
.I "filename - string"
.IP
This is the name of the file for which the SPS common values 
apply.  
.PP
.SH "SPS HEADERS"
.PP
.I Plotpit
reads the 
.I common.type 
field from the SD and PIT file headers.  It reads the following
additional values from PIT file header: 
.I variable.refer,
.I hd.pit\->start,
.I hd.pit\->nan,
.I hd.pit\->prefilter.  
.SH DIAGNOSTICS
.PP
.I Plotpit
complains if there is no such pitch file or no such sampled data file,
or if either file is not the right type.
It also complains if there are too many
.B \-t
options, or if it cannot allocate sufficient dynamic memory to hold the 
data.  Finally, it complains (not always correctly \- see ``Bugs'' below)
if it thinks the specified range of data points is in error.
.SH BUGS
.PP
If the pitch file specified is in a different directory, and no explicit
directory name was given when the pitch file was generated,
.I plotpit
may not be able to find the right directory.
.PP
The preemphasis called for by the
.B \-e
option is not exact if the preemphasis filter has a denominator of
non-zero order and the data do not start at the beginning of the file.
There are not currently any SPS programs that write preemphasis filter
coefficients in the pitch-file header; the option will remain untested
and unusable until there are.
.PP
A few points previous to the first specified may be plotted and may fall
outside the frame drawn around the plot; likewise a few at the end of the
range may be missed.  If the starting point of the range is less than 3,
.I plotpit
will fail.
.SH EXPECTED CHANGES
.PP
Many more options may be added.
.SH SEE ALSO
.IR plotsd (1\-SPS), 
.IR plotsdm (1\-SPS), 
.IR plotsdi (1\-SPS), 
.IR mlplot (1\-SPS), 
.IR genplot (1\-SPS), 
.IR stou "(1),\ " 
.IR plotas "(1),\ "
.IR mcd "(1),\ "
.IR tek "(1).\  "
.SH AUTHOR
.nf
Joseph T. Buck, Entropic Processing, Inc.
Option \fB\-e\fP added by Bernard G. Fraenkel.
Converted for new SPS format by Rod Johnson.
Modified for SPS Common, -m, and -Y by John Shore
Manual page revised by John Shore
.fi