image.1

speech signal process tools

.\" Copyright (c) 1988, 1989 Entropic Speech, Inc.  All rights reserved.
.\" @(#)image.1	1.16	4/1/97	ESI
.TH IMAGE 1\-ESPS 4/1/97
.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"
image \- plot data from ESPS file as a color, gray-scale, or halftone image
.SH "SYNOPSIS"
.B image
[
.BR \- { ef } " \fIrange\fP"
] . . . [
.BI \-l " range"
] [
.BR \-o
] [
.BR \- { prs } " \fIrange\fP"
] [
.BI \-t " text"
]
.br
[
.BI \-x " debug_level"
] [
.BI \-A " algorithm"
] [
.BI \-B " scale"
] [
.BI \-C " colormap"
] [
.BI \-D
] [
.BI \-F " function"
]
.br
[
.BI \-G " range"
] [
.BR \-L { prs }
] [
.BR \-M " magnification"
] [
.BI \-P " param"
] [
.BI \-S " width\fR[\fP" : "height\fR]\fP"
] [
.BI \-T " device"
] [
.BI \-V " text"
] [
.BI \-W " X_geometry"
]
.I file
.SH "DESCRIPTION"
.PP
\fIImage\fP interprets data from a specific ESPS FEA field as
comprising the rows (or columns) of an image, and it displays the
resulting image.  A typical use for \fIimage\fP to display data from
an ESPS spectrum (FEA_SPEC) file as a spectrogram (see \fIplotsgram\fP
(1\-\s-1ESPS\s+1), which is a script that calls \fIimage\fP).  
.PP
In general, data values are obtained from the input records, scaled to
represent gray-scale values, and displayed as a two-dimensional image
with one axis representing time or record number and one axis
representing frequency or relative position within a record.  On
single-plane systems, the gray scale is simulated by a half-tone
technique: the density of dots near a point is proportional to the
value being represented.  Alternatively, on some devices, a true
gray-scale image may be obtained, consisting of dots of various
intermediate intensities, and a colormap may be specified for use on
color systems.  A range of records within the file may be selected
with the
.BR \-p ,
.BR \-r ,
or
.B \-s
option,
and a range of elements within the record may be selected with the
.B \-f
option.
By default, the image is displayed on the user's graphics display;
hard copy may also be obtained, or the image may be saved to a file.
.SH "OPTIONS"
.PP
The following options are supported.  Values in brackets are defaults. 
.TP
.BI \-e " range"
The option letters
.B \-e
and
.B \-f
are synonymous, and
.I range
may have any of the forms shown below with
.B \-f.
The preferred letter is now
.B \-f
(mnemonic for ``field name''), but
.B \-e
(mnemonic for ``element number'') is supported for backward compatibility.
.TP
.BI \-f " grange"
.LP
\fB\-f "\fIfield-name\fB\^[\^\fIgrange\fB\^]\^"\fR
.TP
.BI \-f " field-name" " \fR[re_spec_val]"
This option specifies a set of elements within each record.
.IP
The argument may be a general range specification acceptable to
.IR grange_switch (3\-ESPSu).
This specifies a set of integers that indicate the positions of the
elements within a record.
The tag, if present is counted as element zero.
The other elements are counted starting with one,
whether tags are present or not.
To find the element number of an element in an ESPS file, use
.IR fea_element (1\-ESPS).
The following are allowable forms for
.I grange.
.RS
.TP
.I element
A single integer specifies a single record element.
.TP
.IB first : last
A pair of elements specifies an inclusive range of elements.
.TP
.IB first :+ incr
The form with the plus sign is equivalent to
.IB first : last
with
.IR last " = " first " + " incr.
.TP
.IB range , " . . . " , " range"
A comma-separated list of range specifications of the first three
forms allows for noncontiguous sets of elements.
The ranges should be given in increasing order and without overlaps.
.RE
.IP
If the specified range contains points not in the file, the
range is reduced as necessary.
.IP
If the input file is an ESPS feature (FEA) file, a field within a
record may be specified by name.
In that case, the bracketed
.I grange
refers to positions within the field, counting the first as position
zero.
A field name without a bracketed
.I grange
refers to the entire field.
In that case the double quotes can be omitted as well,
as their only purpose is to prevent the shell
from giving the usual special interpretation to the brackets.
.IP
The command line may contain several
.B \-f
options with field names.
The
.B \-f
option without a field name may be used at most once
and may not be used in the same command with the form containing a
field name.
.IP
If the input file is an ESPS spectrum (FEA_SPEC) file
and this option is not specified,
the spectrum values are converted to logarithmically scaled power (in dB)
and plotted against frequency instead of position withing the record.
.IP
The first form of this option (with no field name)
was devised to permit specifying elements of ESPS files of arbitrary types,
including non_FEA types.
With the replacement of non-FEA file types by FEA subtypes,
this form has become obsolescent;
the forms involving a field name are preferred for use with FEA files.
The first form is not supported with input files
that contain fields with complex data types.
The forms involving a field name are supported with real fields
even though other fields in the file may be complex.
.TP
.BI \-l " low" : "high" " \fR[(determined from data)]"
.TP
.BI \-l " low" :+ "incr"
The first form gives the data values corresponding to the limits of
the grayscale.
Values of
.I low
or less correspond to a blank region of the image, and values of
.I high
or more correspond to a completely filled-in region.
If 
.IR high " = " low " + " incr,
the second form (with the plus sign) specifies the same range as the
first.
.TP
.BI \-o
The default orientation of the image has the origin in the lower left corner
with the horizontal axis representing time or record number
and the vertical axis representing frequency or relative position within
the record.
If this option is specified, the origin is moved to the upper left corner,
and the roles of the axes are reversed.
.TP
.BR \- { prs "} \fIfirst\fP" : "\fIlast\fR [(first in file):(last in file)]"
.TP
.BR \- { prs "} \fIfirst\fP" :+ "\fIincr\fP"
In the first form, a pair of unsigned integers specifies the range of
records from which element values are to be plotted.
If
.B \-r
is used, the limits refer to the record number,
counting the first record in the file as number one.
If
.B \-p
is used, the file must be tagged, and the limits refer to the values of the
tags.
If
.B \-s
is used, the limits are times in seconds.
It must then be possible to associate times with records.
There are two possibilities.
The first is that the file is tagged,
and the header contains the generic header item "src_sf",
which gives the sampling frequency of the reference file.
(In tagged FES_SPEC files without "src_sf",
the header item "sf" is used instead.)
Then the time associated with a record is
.RI ( tag
\- 1) divided by the sampling frequency.
The second possibility is
that the file contains the generic header item "record_freq".
In that case the time associated with record number
.I r
is given by
.I start_time
+
.RI ( r "\-1)/" record_freq,
where
.I start_time
is given by the generic header item "start_time"
or 0 if the item is not present.
.IP
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 records not in the file, the
range is reduced as necessary.
.TP
.BI \-t " text" "\fR [(none)]"
Title to be printed at the bottom of the page.
.TP
.BI \-x " debug level" "\fR [0]"
Print diagnostic messages as program runs (for debugging purposes
only).
Higher levels give more messages.
The default level of zero suppresses all debugging messages.
.TP
.BI \-A " algorithm" " \fR[(device-dependent)]\fP"
Gray-scale algorithm.
The following arguments give black-and-white dot halftone renderings:
.IP
.I "od1 od2 od3 od4 fs fs2"
.IP
On Masscomp, X Windows, and Sun multiplane color systems,
the following arguments
give multilevel gray-scale renderings by manipulating the color map:
.IP
.I "16lvl 16od1 16od1_2 16od1_3."
.IP
In the first set,
.I od1\-od4
are just ordered-dither algorithms with various threshold matrices.
Better results may usually be obtained with
.I fs,
which is a Floyd-Steinberg algorithm.
Algorithm
.I fs2
first squares the scaled values between 0 and 1
that represent the gray levels: then it applies
.I fs.
The squaring operation enhances the contrast
in the darker areas of the image, and
.I fs2
is recommended for use with spectrograms.
.IP
The algorithms of the second group use 16 entries in the color map
to obtain 16 different gray levels.  The first one,
.I 16lvl,
is a simple-minded algorithm
that just rounds each gray level to the nearest of the 16 levels.
It produces contouring and is not recommended.
The other three use dithering between adjacent gray levels
to simulate a much greater number of gray levels than 16.
Algorithm
.I 16od1_2
is a variant of
.I 16od1
just as
.I fs2
is a variant of
.I fs
\- it uses a squaring operation to enhance contrast in the darker areas.
Algorithm
.I 16od1_3
is similar, but cubes instead of squaring.
For spectrograms,
.I 16od1_2
or
.I 16od1_3
is recommended.
On the multiplane color systems mentioned above, the default is
.I 16od1_2
for FEA_SPEC input files and
.I 16od1
for other file types.
On other output devices, the default is
.I fs2
for FEA_SPEC input files and
.I fs
for other file types.
.TP
.BI \-B " scale" " \fR[0]\fP"
Include a border containing titles and axis labels.
Unless this option is invoked,
only the unadorned gray-scale image is displayed,
and the
.B \-t
and
.B \-V
options have no effect.
The argument is a scale factor that controls the sizes and spacing
of tick marks and characters in axis labels and titles.
The default value of 0 causes a reasonable scale to be selected for
the particular output device.
.TP
.BI \-C " file-name"
.LP
.BI \-C " file-name" "\^[\^" grange "\^]\^"
.IP
Read a file containing triples of intensities (red, green, blue)
and load the color map used by
.I image.
This option is effective only on color systems
running X Windows or Sun's SunView window system,
and only when the ``gray-scale'' algorithm (see
.BR \-A )
actually uses multiple color-map entries.
The file should be an Ascii file containing lines
that begin with three integers (base 10) in the range 0\-255.
The numbers should be delimited by whitespace;
anything that follows on the same line is ignored.
Colormap files used with
.I waves+
have this format and can be read by
.I image.
The filename may optionally be followed by a bracketed range specification
of the type accepted by
.IR grange_switch (3-ESPSu).
This specifies a sequence of line numbers in the file;
for example
.BR \-C " cmap" [ 25:85 ]
selects the colormap entries from lines 25 through 85 of the file
.I cmap.
The line numbering begins with 0 for the first line.
Omitting the bracketed range specification
selects all lines in the file.
If this option is not specified, and if there is no
.I colormap
entry in the parameter file,
the program uses a default scale of grays starting with
{255, 255, 255} (white) and decreasing in equal steps to
{0, 0, 0} (black).
At present all the algorithms that set the color map at all
use a 16-entry color map.
However, it is not necessary for the file
or the selected sequence of lines to contain exactly 16 entries;
if there are too many or too few,
a sequence of 16 triples is derived by linear interpolation.
.TP
.B \-D
Disable linear interpolation.
Normally
.I image
interpolates between data points to make the intensity (or color)
vary continuously from point to point in the image.
When
.B \-D
is specified, the data points each appear in a rectangle with a sharp boundary
and a uniform intensity or color representing the actual data value.
.TP
.BI \-F " function" "\fR[(log for FEA_SPEC files, NONE for other types)]\fP"
Apply a function to the data before the gray-scale algorithm is applied.
The possible arguments are
.IP
.I "NONE log exp sq sqrt."
.IP
The default is
.I NONE
for FEA files.
.IP
For FEA_SPEC files,
.I log
converts the spectral values to dB,
whatever the actual FEA_SPEC-file subtype;
this is the default for FEA_SPEC files.
.I NONE
converts to actual power, and
.I sqrt
gives the square root of the power.
Though available,
.I sq
and
.I exp
are unlikely to be useful with FEA_SPEC files.
.IP
The
.B \-F
option interacts with the
.B \-l
option in that the limits given with
.B \-l
apply to the values that result from applying the function.
Thus if, for instance,
.B \-FNONE
is used with a FEA_SPEC file, then the arguments of
.B \-l
are interpreted as actual power rather than dB.
.TP
.BI \-G " low" : "high" " \fR[(none)]"
Normalize gains to enhance features in low-level spectrum records.
This option causes the mapping of data values to gray levels to be
adjusted individually in each time slice.
For example,
.B \-G\-20:\-1
means
that anything more than 20 dB below the maximium value in the time slice