mcd.1

speech signal process tools

.\" Copyright (c) 1986-1990 Entropic Speech, Inc.
.\" Copyright (c) 1991 Entropic Research Laboratory, Inc.; All rights reserved
.\" @(#)mcd.1	3.4 8/2/91 ESI/ERL
.ds ]W (c) 1991 Entropic Research Laboratory, Inc.
.TH MCD 1\-ESPS 8/2/91
.SH "NAME"
mcd \- Sun filter for plot data in Unix GPS format and interactive plot/play program when used with plotsd
.SH "SYNOPSIS"
.B mcd
[
.BI \-r " region"
] [
.B \-u
] [
.BI \-x " level"
] [
.BI \-R
] [
.BI \-i " icon file"
] [ 
.BI \-P
] [
.BI \-p " play options"
] [
.I file.gps
]
.SH "DESCRIPTION"
.PP
.I Mcd
reads plot data in Unix Graphic Primitive String (GPS) format and displays
the plot in a Sun window.  The program emulates a subset of the functions
of the Masscomp program of the same name.
.I Mcd
is intended to be invoked in a
.IR shelltool (1), 
or
.IR cmdtool (1)
window and creates a new window for the plot.   The initial size of the 
window is 24 by 80 characters (using the standard Sun font), but it
may be adjusted by the user to any size (width or height) by using the 
\fIresize\fR function on the
from the \fIsuntools\fR menu obtained by pressing the right mouse button
while pointing to the title bar of the plot window.
   All of the other standard 
\fIsuntools\fR menu items are available through that menu, including
moving, closing (reducing the window to an icon), and quiting.
.PP
.I Mcd
includes the function of the ESPS Masscomp \fIrange\fR program.   
This feature supports the selection of a
range from the plot, zooming in, zooming out, and calling the ESPS play
program on sections of the plot.  See the \fB\-R\fR and the \fB\-P\fR
options below.
Normally
these features are only used by the ESPS script that implements 
\fIplotsd(1\-ESPS)\fR.
.PP
.I Mcd
uses the SunView window system calls, and remains active after drawing
the plot.  This is so that the plot can be resized, refreshed, or moved.
To exit use the \fIquit\fR function on the main frame menu (click the
right mouse button on the frame title bar at the top of the window).  If
you want to regain control of the shell window without removing the plot
window, then be sure to run \fImcd\fR as a subprocess by putting a
\fB&\fR after the command.
.PP
Output from the programs
.IR mlplot (1\-ESPS)
and
.IR genplot (1\-ESPS)
can be displayed with
.I mcd;
files written by the Masscomp
.IR plot (1G)
program and the graphics editor
.IR ged (1G)
are also acceptable input.
The ESPS programs
.IR plotsd (1\-ESPS),
.IR plotspec (1\-ESPS),
.IR mlplot (1\-ESPS),
and
.IR genplot (1\-ESPS)
use
.I mcd
internally to implement their
.B \-Tmcd
option.
.PP
If
.I file.gps
is `\-' or is omitted, standard input is used.
.SH OPTIONS
.TP
.BI \-r " region"
Scale the plot so that graphing region number
.I region
just fits in the window.
Valid values are 1\-25.
.TP
.B \-u
Scale the plot so that the entire graphing universe
just fits in the window.
.PP
The
.B \-r
and
.B \-u
options are mutually exclusive.
The default behavior, in case neither is selected,
is to scale the plot so that the actual plot just fits in the window.
.TP
.BI \-R
Cause \fImcd\fR to go into \fIselect/range\fR mode, after drawing the plot.  
This mode is used with some plot programs (\fIplotsd\fR(1\-ESPS)) and is
called directly by the ESPS plot program.  
When used this way, \fImcd\fR
allows the user to select a range from a sampled data plot that is currently 
displayed and to enter that range into the
ESPS Common file.  
It can also be used with \fIplotsd\fR and \fIplay\fR as an interactive
plot/play program.
After \fIplotsd\fR is used to display a sampled data plot in a window,
\fImcd\fR displays instructions at the top of the display.   
The program is now in what we will call \fIselect mode\fR.
At this point, the left mouse button will select the starting point of
the range, the middle button will call the \fIplay\fR program on the
entire displayed plot (if the \fB\-P\fR option is used), 
and the right buttton will zoom out the plot
(replot the entire sampled data file). 
After the starting point of the range is selected (with the left button)
the current range
will be displayed at the top of the screen as the mouse is moved
across the graph.  The program is now in \fIrange mode\fR.
In this mode pressing the left button will zoom in on the selected
range (replot the sampled data file using the selected range).  The
middle button will save the selected range into the Common file.
The right button will abort the current range and allow you to
reselect the starting point again (that is it returns to \fIselect mode\fR). 
.TP
.BI \-P
If the \fB\-P\fR option is used, then \fImcd\fR will call the
\fIplay\fR program, instead of just saving the selected range
when the middle button is pressed in \fIrange mode\fR.  This causes the
selected range to by played (assuming of course, that your system has
playback capability and the ESPS \fIplay\fR program has been correctly
configured).  When \fIplay\fR returns, if the mouse has not been moved,
pressing the middle button again will save the range into Common.
If the mouse has moved, then the program simply remains in
\fIrange mode\fR.
.PP
The ESPS Common file is updated whenever the plot is redrawn (zoom
in or out), or when a segment is played.   This could be useful when
running \fIplotsd/mcd\fR in one window and another ESPS program that
uses Common in another window.
The top line of the display always tells what the mouse buttons will do
in each mode.
To exit at anytime, use the \fIquit\fR function on the SunView frame
menu.
.TP
.BI \-p " play options"
This character string is passed to the \fIplay\fR program on its command
line, each time \fIplay\fR is called.   Enclose the etire argument in
quotes.
.TP
.BI \-x " level"
Print debugging messages to standard error\-more messages at higher levels.
The default is 0 (no messages).
.PP 
In most cases, these options are used by other ESPS programs and not
used directly by user's.   See the \fIplotsd\fR(1\-ESPS) script for an
example of the usage of this program.
.SH "ESPS PARAMETERS"
No ESPS parameter file is read.
.SH ESPS COMMON
The following items are read from the ESPS Common file:
.IP
.I "beginplot - integer"
.IP
This is the x-coordinate position at the origin of the graph.
.sp
.I "endplot - integer"
.IP
This is the x-coordinate position at the end point of the graph.
.PP
The following items are written into the ESPS 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.
.PP
The ESPS Common file is updated everytime \fIplay\fR or \fIplotsd\fR is
called by \fIrange\fR.
.PP
ESPS Common processing may be disabled by setting the environment variable
USE_ESPS_COMMON to "off" (though it would be pointless to do so when using
this program).  The default ESPS Common file is
.espscom in the user's home directory.  This may be overidden by setting
the environment variable ESPSCOM to the desired path.  User feedback of
Common processing is determined by the environment variable ESPS_VERBOSE,
with 0 causing no feedback and increasing levels causing increasingly
detailed feedback.  If ESPS_VERBOSE is not defined, a default value of 3 is
assumed.
.SH "ESPS HEADERS"
.PP
No ESPS file headers are read or written.
.SH "ESPS PARAMETERS"
.PP
No parameter file is read.
.SH "SEE ALSO"
.PP
plotsd(1\-ESPS), plotspec(1\-ESPS), mlplot(1\-ESPS), plotspec(1\-ESPS)
.SH "FUTURE CHANGES"
.PP
Implement more of the GPS primitives and expand to a more general
GPStool.
.SH "DIAGNOSTICS"
.PP
.nf
usage: mcd [\-r region][\-u][-R][-P][-p][\-x level] [file.gps]
mcd: unexpected end of file.
mcd: can't open \fIfilename\fP: \fIreason\fP
.SH "BUGS"
.PP
Only a minimal set of the GPS primitives is implemented.
.SH "AUTHOR"
Rodney Johnson and Alan Parker.