annotate man/man1/genwav.1 @ 0:5242703e91d3 tip

Initial checkin for AIM92 aimR8.2 (last updated May 1997).

.TH GENWAV 1 "11 May 1995"
.LP
.SH NAME
.LP
genwav \- display the wave in filename.
.LP
.SH SYNOPSIS
.LP
genwav [ option=value | -option ] [ filename ]
.LP
.SH DESCRIPTION
.LP 

Genwav sets up and Xwindow and displays a segment of the input wave
in the window. The size of the window and the size of the wave are
determined by options, as are a number of other input/output
functions. These options have no direct bearing on the auditory
processing performed by AIM. For convenience, these Non-Auditory
options are associated with the instruction genwav (the one
non-auditory instruction), and they are listed at the top of the
options tables prior to the auditory options.

.LP
There are three classes of Non-Auditory options: 
.LP
I)   DISPLAY OPTIONS that determine the format of the auditory representations 
of sound on the screen, or on paper when printed.
.LP  
II)  OUTPUT OPTIONS that determine the format and content of files used
to store the auditory representations of sounds.
.LP 
III) INPUT OPTIONS that determine how the wave in the input file should
be interpreted.
.LP
The output options are presented before the input options so that the
input options will be adjacent to the filterbank options in the
options tables produced by genbmm and subsequent instructions.

.SS 
I. DISPLAY OPTIONS
.LP

The AIM modules produce output in the form of a set of functions, one
for each channel of the auditory filterbank.  For example, the output
of genbmm is a set of functions that simulate basilar membrane motion
produced in response to the input wave.  By default, the AIM software
puts an Xwindow up on the computer screen and displays the output in
the window. This section describes the options that control these
displays.

.LP
The display options are: title, display, x0-win, y0-win, width_win,
height_win, display, view, top, bottom, overlap, headroom,
magnification, pensize, hiddenline.
.LP
A. The Display Window Title, Position, and Size
.RS 3

.LP
title	Title of output display.
.RS 5
	Character string. Default: input file name.
.RE
.LP
The title of the output being displayed.  If no title is given, the
display bears the name of the file of the input wave.

.LP
display	Display output on screen
.RS 5
	Switch.  Default: on.
.RE
.LP

Normally this switch is on and a bitmap of the output is displayed in
a graphical window on the computer screen.  The switch is provided
because the time taken to create the displays is considerable, and it
is useful to turn it dsiplay off using AIM as a preprocessor for
speech recognition.

.LP
x0_win	Left edge of window
.RS 5
	Unit: pixels.  Default: centre.
.RE
.LP
The left edge of the window into which the display will be drawn,
relative to the left edge of the screen (i.e. the x-coordinate of the
window within the screen).  A value of centre will cause centring in
the horizontal dimension (provided the window manager does not
override).
.LP
y0-win    Lower edge of window
.RS 5
	Unit: pixels.  Default: centre.
.RE
.LP
The lower edge of the window into which the display will be drawn,
relative to the lower edge of the screen (i.e. the y-coordinate of the
window within the screen).  A value of centre will cause centring in
the vertical dimension (provided the window manager does not
override).
.LP
Taken as a pair x0_win and y0-win determine the origin of the window,
relative to the screen origin which is assumed to be the lower left
corner of the screen.
.LP
width_win Window width
.RS 5
	Unit: pixels.  Default: 640.
.RE
.LP
The width of the window into which the display will be drawn.
.LP
height_win Window height
.RS 6
	Unit: pixels.  Default: 480.
.RE
.LP
The height of the window into which the display will be drawn.
.RE


.LP
B. Display Controls
.RS 3
.LP
top	The largest postive value visible in the display
.LP
	Scalar. Default value: 1024 (for genwav) 
.LP
Each of the functions in the multi-channel output of a module is
displayed in a transparent window. Provided the channel density is not
too low, the functions are related and the set of functions produces a
display that looks like a complex landscape. Top determines the
largest positive value that will appear in the transparent windows of
the individual functions, so top must be as large as the largest value
in the full set of functions. Increasing top has the effect of moving
the viewer farther up above the landscape.
.LP
bottom	The largest negative value visible in the
.RS 5 
	display 
.RE
.RS 5
	Scalar. Default value: -1024 (for genwav) 
.RE
.LP
Bottom determines the largest negative value that will appear in the
transparent windows of the individual functions, so bottom must be as
large in the negative direction as the largest negative value in the
full set of functions. Increasing bottom in the negative direction has
the effect of depeening the valleys in the landscape.
.LP
overlap   The overlap of transparent windows of the 
.RS 5
	individual functions
.RE
.RS 5
	Scalar: percentage. Default value: 50%
.RE
.LP 
The fact that the output functions are related means that they
fit up under each other in the display in a way that concentrates the
lines on the landscape and improves the display.
.LP
headroom  Display with headroom for the uppermost channel 
.RS 5
	Scalar: percentage. Default value: 0%
.RE
.LP
Because of the overlap of the transparent windows, part of the
uppermost transparent window is hidden by the upper edge of the
display window. This can cause truncation of the waves in the upper
channels.  To avoid truncation, headroom enables the user to specify
that the highest channel ought to be centred below the upper edge of
the window.  The value specified is taken to be the percentage of the
window between the zero line of the upper channel and the upper edge
of the window.
.LP
magnification Display magnification
.RS 9
	Scalar.  Default: 1.0.
.RE
.LP
The degree to which the amplitude of the functions in the display
should be magnified before being displayed.  This parameter is merely
for adjusting the visual contrast of the display.  The magnification
option is a multiplier, so a value of 1 implies drawing to scale,
while a value of 10 implies ten times (10x) the size of values in the
module output and 0.1 implies one tenth of the output size.
Magnification is related to, but separate from, the gain options which
affect the values of the output functions and the values stored in any
output files. Magnification is an alternative means of controlling the
size of the functions in the display -- alternative to top and bottom.
.LP
pensize	The size of the lines in the displays and the 
.RS 5
	dots on the spiral
.RE
.RS 5
	Unit: pixels.  Default: 1. 
.RE
.LP
This option allows the user to specify the thickness of the lines in
the display and the size of the dots on spiral auditory images.  It
also affects the lines and dots in postscript plots.  It is provided
primarily for use with printers which have much more resolution than
computer screens.  On laser printers a value of 3-5 gives reasonable
line thickness.  On the screen, a linewidth greater than 1 produces
slow drawing, and a gagged, blurred display.
.LP
hiddenline  Draw with overlapping parts of functions 
.RS 5 
	  hidden 
.RE
.RS 5
	  Switch.  Default: on.
.RE
.LP
This switch specifies whether or not a 'hidden line' algorithm should
be used when drawing the display.  It also affects printed displays.
In almost all cases, hiddenline results in more attractive displays of
waveforms, and it often makes complex displays easier to understand,
so the default is 'on'.  Note: hiddenline almost doubles the drawing
time so it is sometimes useful to switch it off on slower machines.
.LP

.SS 
II. OUTPUT OPTIONS
.RS 3
.LP
The output options are listed and described before the input options
so that the input options will be adjacent to the filterbank options
in the listings produced by genbmm and subsequent modules.  The output
options are downchannel, erase_ctn, animate_ctn, bitmap_ctn,
postscript, output, and header.
.LP
downchannel Average adjacent channels of multichannel 
.RS 7
	representations 
.RE
.RS 7
	Units: Number of averagings. 
.RE
.RS 7
     Default value: 0.
.RE
.LP

There is interaction between channels in the transmission-line
filterbank of the physiological version of AIM, and in the neural
encoding of the functional version of AIM.  The minimum channel
density for these processes to operate properly is four channels per
ERB and 2 channels per ERB, respectively.  For broadband signals like
speech this means that the minimum number of channels is on the order
of 128 and 64, respectively.  This channel density can produce
cluttered displays, and more importantly, it is far too many channels
for current speech recognition systems which typically use 12-24
channels.  This is not just a computer power problem; the recognition
systems actually perform less well with extra channels.  Accordingly,
the option 'downchannel' provides the option of reducing the channel
density at output, so that AIM can operate with the appropriate
channel density and still provide output that is compatible with
displays and speech recognition systems.

.LP
Downchannel averages pairs of adjacent channels and the option value
specifies how many times it should execute the averaging process. Each
averaging reduces the number of channels by a factor of 2, so for
proper transmission-line filtering and an output file with 16
channels, set channels_afb=128 and downchannel=3 (three successive
halvings of the number of channels).


.LP
A. Animated Cartoons
.LP
.RS 3
Four of the AIM instructions produce output in the form of sequences
of spectral frames (gensgm, gencgm, genasa and genepn).  Bitmap
versions of the displays of the frames can be stored by AIM and
replayed by review and xreview.  When the sequence of frames is played
rapidly, it appears as an animated cartoon that shows the dynamic
behaviour of the spectrum of the sound.
.LP
Similarly, the AIM instructions for auditory images (gensai and
genspl) produce sequences of landscape frames, and bitmap versions of
the landscape displays can also be stored by AIM and replayed by
review and xreview.  Indeed, it was the desire to produce auditory
image cartoons that led to the development of much of the AIM software
package. The animated cartoons or auditory images show the dynamic
behaviour of features in the images, like the motion of formants in
diphthongs and the motion of notes in a melody.
.LP
This section describes the options that control the construction and
storage of sequences of bitmaps; there is a separate manual entries for
the xreview routine that replays the bitmaps ( 'manaim xreview').


.LP
erase_ctn   Erase the current frame before presenting  
.RS 7 
	the next frame
.RE
.RS 7
	Switch. Default value: on.
.RE
.LP

Normally, when presenting a sequence of frames as an animated cartoon,
one wants to erase the current frame before presenting the next. When
the frames are spectra, however, the set of frames can together form a
meaningful display; for example, the set of rising spectra produced at
the onset of a sound produces a contour map of the onset. The option
erase_ctn enables the user to observe the full set of spectra
simultaneously. (See aimdemo_gtf_spectra or aimdemo_tlf_spectra ).

.LP
animate_ctn Store frames in memory and replay all of 
.RS 7
	them as a cartoon
.RE
.RS 7
	Switch. Default value: off.
.RE
.LP
When this option is on, AIM stores the bitmaps of the frames it
produces in the memory of the machine and replays them rapidly when
the instruction is complete. Type RETURN to animate the cartoon again;
type 'q RETURN' to exit the instruction.  (This option was important
when machines were slower and before the availability of review and
xreview. It is now largely obsolete.)
.LP
bitmap_ctn  Store bitmaps of frames in a file for  
.RS 7 
	replay as a cartoon 
.RE
.RS 7
	Switch. Default value: off.
.RE
.LP
When this option is on, bitmaps of the frames produced for the input
in file_name will be stored in file_name.ctn.  The sequence of frames can later be replayed using either 
.LP
> review file_name  or
.LP
> xreview file_name	
.LP
Both of these programs enable the user to vary the rate of animation,
the section of the sequence to be view, etc. The xreview version has a
window interface with useful information and is the preferred version
in most cases.
.RE

.RS 3
B. Output Files for Printing and Postprocessing

.LP
Postscript  Produce printer-ready output
.RS 7
	Switch.  Default value:  off.
.RE
.LP
This switch causes AIM to produce a printer-ready version of the
displays it presents on the computer screen.  For example, the NAP of
a 32-ms section of cegc can be printed using
.LP
> gennap length=32 postscript=on cegc | lpr -Plw
.LP
where 'lpr' is the Unix printer-driver and the 'lw' of -Plw specifies
the destination printer.  You may need to check the name of your
system's printer driver and laser printer.
.LP
Alternately the postscript version of the display may be directed to a
file using an instruction like
.LP
> gennap length=32 postscript=on cegc > cegc_nap.ps
.LP
and printed later at the users convenience. In this example, the file
name cegc_nap.ps is not generated by AIM; the '_nap.ps' suffix is
added by the user following standard conventions to indicate that the file
contains a NAP in postscript form.

.RS 3
.LP
THREE POSTSCRIPT CAUTIONS: 
.LP
Postscript files of landscape displays from AIM are very large. As a
result, we recommend
.LP
a) that you NOT switch postscript on without redirecting the output to
a file, as it will cause the output to be display on the screen in a
seemingly endless display,
.LP
b) that you be careful NOT to print postscript files on a printer
which does not understand the Postscript language, as it can cause the
printer to put out an extremely long file, one column per page!
.LP
c) that you NOT set postscript=on in an options file as it will
generate large files in the directory without your noticing.
.RE

.LP
output  Generate an output file
.RS 3
	Switch.  Default value:  off.
.RE
.LP
This switch causes the array of functions that defines AIM's
simulation of basilar membrane motion, or a neural activity pattern,
or an auditory image, to be stored in a file for subsequent processing
by the aimtools or other, user defined, operators. By convention, the
file is given the same name as the input file, but with a suffix
reflecting the entry point, to distinguish it from the input file on
the one hand and from other output files on the other hand. The naming
system enables the user to construct and store a set of output files
for one input file without the need to specify a sequence of file
names.  The suffixes are those used to identify the modules in the
listing produced by 'gen -help'.  So, for example, the following
command line:
.LP
> gennap output=on length=32 cegc
.LP
will produce an output file named cegc.nap containing a multiplexed
version of the functions that define the NAP of the first 32 ms of
cegc.  
.LP
The spectrographic representations produced by gensgm and gencgm can
be stored in the same way, as can the sequences of spectra produced by
genasa and genepn. It is the output files of genasa and gencgm that
are used to interface AIM with speech recognition systems (Robinson et
al., 1990; Patterson et al., 1995; Giguere and Woodland, 1994a).
Details of the file formats are presented in docs/aimFileFormat.
.LP
Header  Put a header on the output file
.RS 3
	Flag.  Default value:  on.
.RE
.LP
By default, a header is prepended to each output file so that
subsequent processors have access to the history of the file.  Details
of the header structure are presented in docs/aimFileFormat.
.LP
.RE 

.SS 
III. INPUT OPTIONS
.LP
The input options enable the user to process a subsection of the input
wave, and to specify characterisitcs of the wave.
.LP
The input options are: input_wave, start_wave, length_wave,
samplerate, swap_wave, bits_wave, dB_wave.
.LP
input_wave   Default input wave name
.RS 13
Filename.  Default value: none.
.RE
.LP
The name of the wave file to process.  This option permits simple
repetitive processing of the same input file without repetitive typing.  It
also enables one to circumvent the Unix convention of having the filename
last on the command line.  This option is overridden if the user supplies a
wave file name at the end of the command line.
.LP
start_wave   Start point in wave
.RS 13
Default unit: ms.  Default value: 0.
.RE
.LP
The point in the input wave at which processing should begin.  The
start_wave option is expressed in milliseconds and its default value is the
beginning of the file (i.e. 0 ms into the file).
.LP
length_wave  Length of wave
.RS 13
Default unit: ms.  Default value: remainder.
.RE
.LP
The number of milliseconds of the wave that ought to be processed,
beyond the start point.  The special value 'remainder' indicates that
the entire length of the wave from the start point to the end of the
file should be processed.
.LP
samplerate   Input wave sample rate
.RS 13
Default unit:  Hertz.  Default value:  20,000 Hz.
.RE
.LP
The rate at which the input wave was sampled.
.LP
swap_wave    Swap the bytes in each binary pair of the 
.RS 13 
input file
.RE
.RS 13
Switch. Default: off.
.RE
.LP
The order of the bytes in short integers varies between manufacturers.
Specifically the order for Sun and HP is opposite that for DEC SGI and
IBM.  The default setting (off) is for the latter byte order.
.LP
bits_wave    Bits in the input wave
.RS 13
Unit:  bits.  Default:  12. (Only alternate: 16.)
.RE
.LP
The number of significant bits in each (16-bit) word of the input
wave.  Note that gain_gtf or gaim_tlf should be changed to 0.0625 when
the number of bits is set to 16 to avoid overflow.
.LP
dB_wave      Scaling of the input wave 
.RS 13
(for physiological route only)
.RE
.RS 13
Units: dB. Default: 60 dB
.RE
.LP
This option enables the user to specify the relative level of
the input wave in decibels. It is particularly useful for 
investigating the level-dependent properties of the 
physiological version of AIM.
.LP
The functional route is level-independent and dB_wave is 
ignored no matter what its value.
.LP
dB_wave can also be used to scale the input wave in absolute 
units, i.e sound-pressure level (dB SPL), using the following 
equation:
.LP
dB_wave = dBSPL - 20log(RMS/200)
.LP
where RMS is the root-mean-square amplitude of the input wave, 
or the portion of the wave or interest, and  dBSPL is the 
desired sound-pressure level scaling (in dB). For 
example, to scale to 60 dB SPL a wave with an RMS amplitude
of 467.3, dB_wave should be set to 52.6.
.LP 
Note: The RMS value of a stored input wave can be calculated using 
the tools provided with the AIM software. 


.LP
.RE

.SH FILES 
.LP
 .genwavrc  The options file for genwav.
.SH SEE ALSO 
.LP
genbmm
.SH BUGS 
.LP
.SH COPYRIGHT
.LP
Copyright (c) Applied Psychology Unit, Medical Research Council, 1995
.LP
Permission to use, copy, modify, and distribute this software without fee 
is hereby granted for research purposes, provided that this copyright 
notice appears in all copies and in all supporting documentation, and that 
the software is not redistributed for any fee (except for a nominal 
shipping charge). Anyone wanting to incorporate all or part of this 
software in a commercial product must obtain a license from the Medical 
Research Council.
.LP
The MRC makes no representations about the suitability of this 
software for any purpose.  It is provided "as is" without express or 
implied warranty.
.LP
THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL 
THE A.P.U. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES 
OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, 
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS 
SOFTWARE.
.LP
.SH ACKNOWLEDGEMENTS
.LP
The AIM software was developed for Unix workstations by John
Holdsworth and Mike Allerhand of the MRC APU, under the direction of
Roy Patterson. The physiological version of AIM was developed by
Christian Giguere. The options handler is by Paul Manson. The revised
SAI module is by Jay Datta. Michael Akeroyd extended the postscript
facilites and developed the xreview routine for auditory image
cartoons.
.LP
The project was supported by the MRC and grants from the U.K. Defense
Research Agency, Farnborough (Research Contract 2239); the EEC Esprit
BR Porgramme, Project ACTS (3207); and the U.K. Hearing Research Trust.