image.1

speech signal process tools

is rendered as white,
and anything less than 1 dB below the maximium in the time slice
is rendered as black.
These limits can be chosen to improve the appearance of a spectrogram.
Lowering the lower limit will bring out more faint detail
but will also permit more intrusion of gray
into the spaces between formants.
Lowering the upper limit will broaden the high-level formant tracks
but wil also introduce more gray.
.IP
In the absence of
.BR \-G ,
the lower and upper limits on data values,
corresponding to white and black,
are globally determined, either explicitly with
.B \-l
or by default from the global maximum data value.
When
.B \-G
is used,
there are additional adjustments to keep the limits determined by
.B \-G
from overstepping the bounds given by the global limits.
.TP
.BR \-L { prs }
.IP
Label the
.IR x -axis
in terms of
.RB `` p oints''
.RI ( i.e.
tag values),
.BR r ecord
numbers, or
.BR s econds.w
If this option is not specified,
and if the parameter file does not specify a value for
.I label_units,
the axis is labeled in the units
in which the range was specified with the
.BI \-p ,
.BI \-r ,
or
.B \-s
option.
If none of those three were used, the final default is
.BR \-Lr .
If
.B \-Lp
is used, the file must be tagged.
If
.B \-Ls
is used, it must be possible to associate times with records
as described for the
.B \-s
option.
.TP
.BI \-M " magnification" " \fR[1]\fP"
This option if effective for laser-printer output via
.BR \-Timagen ,
.BR \-Tpostscript ,
or
.BR \-Thp
The option causes each pixel of the image to be rendered as an
.IR m \(mu m
block of device resolution cells, where
.I m
is the magnification;
thus a magnification greater than 1 causes output at a coarser resolution
than the finest the device is capable of.
The default magnification of 1 gives full-resolution images.
When the lower resolution is acceptable, a magnification greater than 1
can greatly speed up the printing of images by reducing the number of
bits that must be sent to the printer.
Acceptable magnifications are 1, 2, and 4 for an Imagen;
any positive integer for Postscript;
and 1, 2, 3, and 4 for an HP printer.
.TP
.BI \-P " param" " \fR[param]\fP"
The name of the parameter file.
.TP
.BI \-S " width" : "height" "\fR[(device-dependent)]
.TP
.BI \-S " width"
The size in pixels of the image.
The second form implies a square image.
For a graphics display, the default size depends on the size of the screen
or window.
.TP
.BI \-T " device" " \fR[x11 \fIor\fR mcd]"
Output device.
The default value
calls for displaying the image on the user's graphics terminal.
A value of
.B x11
calls for use of the X Window System (Version 11),
which is usually the default on systems where it is available.
Otherwise the default is
.BR mcd ,
which calls for use of a system's native graphics system, if any.
A value of
.B imagen
causes output on
.I stdout
suitable for an Imagen laser printer.
The output may be piped directly to
.IR ipr (1).
A value of
.B postscript
causes PostScript output on
.I stdout,
and
.B hp
causes output on
.I stdout
suitable for a Hewlett-Packard printer.
A value of
.B ras
causes output on
.I stdout
in Sun raster-file format;
this may be viewed on the Sun by piping into the program
.IR showras (ESPS-1).
A value of
.B type
causes a crude Ascii typewriter plot to be sent to
.I stdout.
.TP
.BI \-V " text" "\fR [(none)]"
Title to be printed along the left edge of the page (running upward).
.TP
.BI \-W " X_geometry"
For versions of this program that use X-window graphics,
this option is used to specify the location and size of the
plot. 
The standard X windows syntax is used: "=<width>x<height>{+-}<xoffset>{+-}<yoffset>, where items enclosed in "<>" are integers and items enclosed in "{}"
are a set from which one is allowed.
If this option is not specified, internally generated defaults
are used, as is the case for non X-window based systems.
.SH "ESPS PARAMETERS"
.PP
The parameter file is not required to be present, as there are default
values for all parameters.
If the file exists, the following parameters may be read
if they are not determined by command-line options.
.TP
.I elements \- integer array
The element positions selected in each record.
This parameter is not read if the command-line option
.B \-f
(or
.BR \-e )
is specified.
If the set of element positions is specified neither with the
option nor in the parameter file,
the default is as described for the option.
.TP
.I minlevel \- real
Data value corresponding to the lower limit of the grayscale.
This parameter is not read if the
.B \-l
option is specified.
If the command-line option is not specified
and the paramter is not present in the parameter file,
the default used is the lowest data value to be represented.
.TP
.I maxlevel \- real
Data value corresponding to the upper limit of the grayscale.
This parameter is not read if the
.B \-l
option is specified.
If the option is not specified and the paramter is not present,
the default used is the greatest data value to be represented.
.TP
.I orientation \- string
The orientation of the image.
This parameter is not read if the
.B \-o
option is specified.
Two values are recognized:  "default" and "rotated".
The string "default" refers to the default orientation as described for the
.B \-o
option,
and assigning this value is equivalent to omitting the parameter entirely.
The string "rotated" refers to the orientation obtained when the
.B \-o
option is specified.
.TP
.I startrec \- integer
The record number of the first record to be processed.
This parameter is not read if the
.BR \-p ,
.BR \-r ,
or
.BR \-s
option is specified.
The default value is 1 in case these options are not specified and the
parameter is omitted from the parameter file.
.TP
.I nrecs \- integer
The number of record to be processed.
This parameter is not read if the
.BR \-p ,
.BR \-r ,
or
.BR \-s
option is specified.
The default is to continue processing until the end of the file
in case these options are not specified and the
parameter is omitted from the parameter file.
.TP
.I x_text \- string
Text to b printed at the bottom of the page.
This parameter is not read if the
.B \-t
option is specified.
If no text is specified either with the option or in the parameter file,
none is printed.
.TP
.I algorithm \- string
Gray-scale algorithm.
The possible values are arguments for
.B \-A
listed under Options.
This parameter is not read if the
.B \-A
option is specified.
The default is "fs" (Floyd-Steinberg) in case no algorithm is specified
with either the command-line option or this parameter.
.TP
.I b_scale \- integer
Scale factor that determines the sizes and spacing of tick marks, axis
labels, titles, and other features that occupy the border around the
actual image.
This parameter is not read if the
.B \-B
option is specified.
If the option is not specified and the parameter is not present,
the plot consists of the image alone, and the border is omitted.
A value of 0 for the option calls for a default appropriate to
the output device.
.TP
.I colormap_file \- string
The name of a file to be read for colormap entries.
As in the argument to the
.B \-C
option, the file name may be followed by a bracked
.I grange
specification indicating a list of line numbers.
This parameter is not read if the
.B \-C
option is specified.
If no colormap file is specified
with either the command-line option or in the parameter file,
the default is an internally computed scale of grays
ranging between white and black.
.TP
.I function \- string
A function to be applied to the data before the gray-scale algortihm is
applied.
The possible values are the arguments to
.B \-F
listed under Options.
This parameter is not read if the
.B \-F
option is specified.
In case no function is specified with either the command-line option or in
the parameter file, the default is "log" (convert to dB) for FEA_SPEC files
and "NONE" for other types.
.TP
.I gain_low_lim \- real
.TP
.I gain_high_lim \- real
Limits used in normalizing gains as described for the
.B \-G
option.
This parameter is not read if the
.B \-G
option is specified.
If the option is not specified and these parameters are not in the
parameter file, no gain normalization is done.
If the option is not specified and either of these parameters is present,
the other must be present also.
.TP
.I label_units \- char
Allowed values are 'p', 'r', and 's', indicating whether to label the
.IR x -axis
in terms of ``points''
.RI ( i.e.
tag values), record numbers, or seconds.
This parameter is not read if the
.B \-L
option is specified.
The default when the option is not specified
and the parameter is not present
is as described for the
.B \-L
option.
.TP
.I magnification \- integer
Magnification factor to control the resolution
of "imagen", "postscript", and "hp" laser-printer images.
This parameter is not read if the
.B \-M
option is specified.
The default is 1 when the option is not specified
and the parameter is not present.
.TP
.I width \- integer
.TP
.I height \- integer
The dimensions in pixels of the image.
These parameters are not read if the
.B \-S
option is specified.
The default dimensions,
used when the option is not specified and the parameter is not present,
depend on the output device.
.TP
.I device \- string
The name of the output device.
This parameter is not read if the
.B \-T
option is specified.
The default,
used when the option is not specified and the parameter is omitted,
is "x11" or "mcd", depending on what is available on a particular system.
Other possible values are as described under
.B \-T
in the Options section.
.TP
.I y_text \- string
Text to be printed up the left side of the page.
This parameter is not read if the
.B \-V
option is specified.
If no text is specified either with the option or in the parameter file,
none is printed.
.SH "ESPS COMMON"
.PP
The ESPS common file is not accessed.
.SH "ESPS HEADERS"
.PP
.SH "EXAMPLES"
.PP
On a black-and-white display, try the following on a sampled-data file
.I speech.sd
containing a half-second or second of speech.
.PP
.nf
filter \-Ppreemp_params speech.sd \- \\
    | fft \-o6 \-l32 \-S10 \-p1:2000000000 \- \- \\
    | image \-t"Time (seconds)" \-V"Freq. (Hz)" \-s: \-Afs2 \-B0 \-G\-20:0 \-
.fi
.PP
On a multiplane color display, try changing "\-Afs2" to "\-A16od1_2"
or "\-A16od1_3".
.PP
The file preemp_params may contain the following.
.PP
.nf
# parameter file for preemphasis with filter(1-ESPS) program
float	filter_num = {1.0, -1.0}: "Preemphasis filter numerator";
float	filter_den = {1.0}: "Preemphasis filter denominator";
int	filter_nsiz = 2: "Number of numerator coefficients";
int	filter_dsiz = 0: "Number of denominator coefficients";
.fi
.SH "SEE ALSO"
.PP
.SH "DIAGNOSTICS"
.PP
.nf
image: unknown option \-<\fIletter\fP>
Usage: image [\-{ef} range] . . . [\-l range][\-o][\-{prs} range][\-t text]
 [\-x debug_level][\-A algorithm[\-B scale][\-C colormap][\-F function][\-G range]
 [\-L{prs}][\-M mag][\-P param][\-S width[:height]][\-T device][\-V text] file
image: too many file names specified.
image: no input file name specified.
image: only one of \-p, \-r, and \-s may be used at one time
image: named fields allowed only with FEA files
image: if any \-f option argument has a field name, all must.
image: unrecognized function name.
image: header item "spec_type" undefined or not CODED
image: unknown spectral type
image: header item \"num_freqs\" undefined or not LONG
image: use \-f option unless file is FEA file.
image: axis label units must be given as p, r, or s.
image: \-p option or axis labeling in points requires tagged file
image: \-s option or axis labeling in seconds
       requires nonzero sampling or record frequency.
image: initial tag not positive
image: initial tag not less than final tag
image: initial record number not positive
image: initial record number not less than final record number
image: starting time before start of file
image: starting time not less than ending time
image: starting record number not positive
image: span of records in file doesn't overlap given range
image: unrecognized value for "orientation" parameter
image: magnification must be positive.
image: header item "freq_format" undefined or not CODED
image: header item "sf" undefined or not FLOAT
image: freq format ARB_VAR not yet supported.
image: unrecognized freq format <\fIcode number\fP>.
image: just one of "gain_low_lim" and "gain_high_lim" defined
image: field "<\fIname\fP>" not defined in feature file header
image: first record doesn't precede end of range
image: last record doesn't follow beginning of range
image: can't open colormap file <\fIfile name\fP>.
image: no line <\fInumber\fP> in colormap file.
SPS assertion failed: <\fImessage\fP>
.br
    with any of the following messages.
can't allocate space for field name list
can't allocate space for element array from symbol table
can't get "elements" parameter--may be too long
can't allocate space for array of element numbers
can't allocate space for input FEA_SPEC record
can't allocate space for input data vector
can't reallocate space for vector of element numbers
can't allocate space for buffer to make temp file
can't allocate space for 3 rows of interpolated values
can't reallocate space for 3 rows of interpolated values
can't allocate space for colormap
can't reallocate space for colormap
can't allocate space for subset of colormap
can't allocate space to interpolate colormap
.fi
.SH "BUGS"
.PP
.SH WARNINGS
.PP
.SH "FUTURE CHANGES"
.PP
Support for fields with complex data types in FEA files.
New device types will be added.
.SH "AUTHOR"
Rodney Johnson.