annotate docs/ReadMe @ 0:5242703e91d3 tip

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

bin/ReadMe:  


	    AN INTRODUCTION TO THE AUDITORY IMAGE MODEL

This is the introduction for those wanting to use AIM to process waves
once the software package has been compiled, installed and tested.
The instructions for compiling and installing AIM are in the text file
ReadMe.First in the top directory of the software package.


CONTENTS

I. Overview of Aim:   A description based on Patterson, Allerhand and
Giguere (1995). It illustrates the instructions used to display waves
and produce the auditory representations shown in Figures 2 and 3 of
the paper.

II. aimdemo_* Scripts:   A selection of demonstrations that illustrate
the range of auditory representations produced by AIM. A complete list
of demonstrations is contained in docs/aimDemonstrations.

III. Overview of Documentation:   A brief description of the 
documentation available and how to access it. This information is also
available in docs/aimDocumentation.

IV. Setting Up Paths for AIM and manaim: The modifications to pathnames
required to make the AIM instructions and on-line help facilites
available from all the user's directories.  This information is also
available in docs/aimPaths.



______________________________________________________________________

I. OVERVIEW OF AIM (THE AUDITORY IMAGE MODEL)

The Section presents a brief tour of the facilities in AIM based on a
Letter to the Editor announcing the release of AIM in the Journal of
the Acoustical Society of America (1995). It introduces the three
auditory representations that AIM was originally developed to simulate
-- basilar membrane motion (BMM), neural activty patterns (NAPs), and
stabilised auditory images (SAIs).  It also introduces the main
features of the software platform by example; they are the
instructions and options that control the simulations and the displays
that present the results.


A. Time-Domain Modelling Of Peripheral Auditory Processing:
	A Modular architecture and a Software Platform

The text of the Letter is in PAG95.doc in aim/docs.  Figure 1 of the
paper is a schematic of the architecture of the auditory image
model. It was produced with a drawing package entirely separate from
the AIM software package.  A postscript version of Figure 1 is
contained in PAG95_F1.ps. It can be viewed with a postscript previewer
like ghostview.

The demonstrations are based on the wave for the word 'hat' which is
stored in the file 'hat' with 'little-endian' byte order. (This is the
order used in DEC, IBM, and SGI machines.)  A byte reversed version
with 'big-endian' order is provided in 'hat_br'. (This is the order
used in SUN, and HP machines.)

For an automated tour type

> aimdemo_hat	or
> aimdemo_hat_br 

depending on the byte order of your machine.


Alternately, you can Execute the instructions individually on the
command line.


B. Displaying Waves Prior to Auditory Analysis:

Waves can be displayed using the initial module of AIM, genwav.

For a display of the complete hat file, use

> genwav samplerate=22.05kHz top=2500 bottom=-2500 input=hat

To restrict the display to the portion of the file with the 'hat'
sound wave, use

> genwav samplerate=22.05kHz start=110 leng=230 top=2500 bottom=-2500 input=hat

For the BMMs in Figures 2a and 3a, and the NAPs in Figures 2b and 3b,
we want to restrict the analysis AIM performs to a stationary segment
of the vowel which is 32 ms in duration and which starts just before a
glottal pulse. Such a segment can be displayed with 

> genwav samplerate=22.05kHz start=182 leng=32 top=2500 bottom=-2500 input=hat


C. The Three Main Auditory Representations Produced by AIM
 
The remainder of this Section presents the AIM instructions used to
convert the wave for the word 'hat' into the auditory representations
of the sound presented in the individual panels of Figures 2 and 3 of
the paper (BMMs, NAPs and auditory images).

Figure 2: The functional version of AIM (panels a, b and c):

a> genbmm samplerate=22.05kHz start=182 leng=32 top=600 bot=-600 input=hat

b> gennap samplerate=22.05kHz start=182 leng=32 top=5000 input=hat

c> gensai samplerate=22.05kHz start=112 leng=100 top=2000 napdecay=3 input=hat


Figure 3: The physiological version of AIM (panels a, b and c):

a> genbmm filter=tlf start=182 leng=32 samplerate=22.05kHz top=600 bot=-600 input=hat

b> gennap compress=off transduction=med start=182 leng=32 samplerate=22.05kHz top=5000 input=hat

c> The correlogram version of the auditory image is produced by
generating a NAP of the sound, converting it into a correlogram with
acgram, and then displaying it with the facilites in the auditory
image module, gensai. The instruction sequence is as follows:

> genasi filter=tlf compress=off transduction=med leng=100 samplerate=22.05kHz  output=on
> acgram start=36ms wid=64ms lag=32ms norm=off frames=1 scale=.000002 hat.nap > hat_acg.sai
> gensai -useprevious start=0 top=3000 input=hat_acg



________________________________________________________________________

II. AIMDEMO_* SCRIPTS

The following is a list of demonstration scripts available to
illustrate the operation of AIM and the different auditory
representations that it produces. The scripts are stored in
[aimdirectory]/scripts.

The syntax for the demos can be obtained by typing 

> aimdemo_???_??? help 

where '???_???' is one of the extensions listed below.  The simplest
way to begin is to copy the wave file "cegc" from the waves directory
to the current working directory, and type 

> aimdemo_tlf_all cegc

NOTE: The byte order for cegc is "little endian" (used by DEC,
IBM and SGI machines).  A byte reversed version with "big-endian"
order is the wave "cegc_br". (This is the order used in SUN and HP
machines.)

The sound in cegc is a set of stationary and gliding click trains that
play a lazy major triad (C-E-G) and its octave (C) over 2.1 sec.  The
click train at the start (C) is a particularly useful test and demo
stimulus. 

Once one or two of the aimdemos have been shown to work with cegc, you
should be in a position to try them on your own waves.



I. The Funcional Version of AIM:


1. aimdemo_gtf_all   <wave_file>
   
   This script illustrates all stages of the functional version of AIM
   using the "auditory route". It focuses on landscape displays and
   the instructions involved are:

	       genwav (display input waveform), 
               genstp (generate stapes velocity),
               genbmm (generate basilar membrane motion),
               gennap (generate neural activity pattern),
               gensai (generate stabilized auditory image) and
               genspl (generate spiral version of auditory image).  


2. aimdemo_gtf_sai  <wave_file>

   This script presents the wave in <wave_file> using genwav, and
   then produces its rectangular auditory image using gensai. It is
   the simplest auditory image demo.


3. aimdemo_gtf_spectra   <wave_file>
   
   This script illustrates the functional version of AIM using the
   "spectral route".  It focuses on spactral displays and the
   instructions involved are:

	       genwav (display input waveform), 
               genasa (generate auditory spectral analysis), and
               genepn (generate excitation pattern)


4. aimdemo_gtf_2dat  <wave_file>

   The script illustrates 2-dimensional adaptive-thresholding
   (2D-AT) using genwav, genstp, genbmm and finally gennap. 



II. The Physiological Version of AIM:


1. aimdemo_tlf_all    <wave_file>
 
   This demo script illustrates the entire physiological
   version of AIM using the "auditory route".  It uses the
   transmission-line filterbank (option filter=tlf) and the Meddis
   neural transduction module (option transduction=Meddis).  The
   instructions involved are:

               genwav (display input waveform), 
               genstp (generate stapes velocity),
               genbmm (generate basilar membrane motion),
               gennap (generate neural activity pattern),
               acgram (generate autocorrelogram).

   
2. aimdemo_tlf_med  <wave_file>

   The script illustrates the Meddis Haircell module.  The AIM
   functions involved are genwav, genbmm and gennap.


3. aimdemo_tlf_spectra   <wave_file>

   This script illustrates the "spectral route" through the
   physiological version of AIM.  It focuses on spectral displays and
   the instructions involved are genwav, genasa and genepn.
   

4. aimdemo_tlf_lowhigh <wave_file>

   This script illustrates the level dependancies in the physiological
   version of AIM, and its ability to simulate cochlear damage. The
   instructions involved are:

   genwav [display input wave], 
   genbmm [cochlea level = 30dB], 
   genbmm [cochlea level = 90dB],
   gennap [Normal cochlea + Meddis high spont-rate fibre] and
   genasa [total OHC destruction, with no feedback]
          Note: - very poor frequency resolution.



________________________________________________________________________

III. OVERVIEW OF DOCUMENTATION


An introduction to the Documentation for the Auditory Image Model of
Peripheral Auditory Processing


A. Initial Contact Points and Aquisition of the Software Package


1. WWW Page. 

   Address:   http://www.mrc-apu.cam.ac.uk/aim/

   An overview of AIM on the internet with facilities for acquiring
   the software package. 


2. Journal reference. 

   The software package is described in a recent article entitled

   "Time-domain modelling of peripheral auditory processing:
	A modular architecture and a software platform"

   by Roy D. Patterson and Mike H. Allerhand and Christian Giguere,
   Journal of the Acoustical Society of America, 1995 (in press).

   The text of the article is stored in  [aim]/docs/PAG95.doc


3. ftp instructions:

   The instructions for obtaining AIM by ftp are stored in
   [aim]/docs/ftp.doc



B. Installation and Test

1. ReadMe.First

   This document appears in top directory of aim when the aim.tar file is
   unpacked.  It is the same file as that in the ftp directory
   /pub/aim. It contains the instructions for compiling AIM, testing
   the installation, and setting up paths to the instructions, the
   aimtools, and the online documentation (manual pages accessed
   through 'manaim').



C. Introduction to the Operation of AIM


1. bin/ReadMe

   This is the initial ReadMe file for those wanting to use AIM once it
   has been installed and tested. It begins with a guided tour of AIM and
   then describes the user documentation and where to find it. 


2. Introduction to AIM instructions:   docs/aimInstructions

   An introduction to the instructions and command-line options used to
   control the auditory model is stored in  docs/aimInstructions.
   The instructions have the form gen???. The command 'gen -help | more'
   lists the three letter combinations that may replace ??? and
   briefly describes the operations they invoke.


3. AIM on-line help:	gen??? -help

   The instruction 'gen -help | more' lists the AIM instructions.

   The instructions have the form 'gen??? -options <file_name>'.

   The final three letters of the AIM instruction specify the point
   in the system where the user chooses to observe the output.
   Instructions of the form 'gen??? -help' cause AIM to list the
   options that control AIM up to that output point along with a brief
   description of the option and its current and default value.


4. Manual pages for AIM instructions:	manaim gen???

   The documentation for each instruction and its options is
   provided in standard manual pages accessed by instructions of the
   form 'manaim gen???'.  Begin with 'manaim genwav' which describes
   non-auditory options such as those for the AIM display and for
   the input and output files.

   A complete listing of the AIM instructions is included in the listing
   produced by the instruction 'manaim -k all | more'.

   Manual pages can be printed with commands of the form
   'manaim gen??? | lpr'.


5. Manual pages for AIM tools:	 manaim <aimtool_name>

   The software package includes a set of 'aimtools' for generating
   and manipulating input waves, and for processing the multi-channel,
   multi-frame output of AIM.

   There are manual pages for the aimtools accessed by instructions of
   the form 'manaim <aimtool_name>'.

   A complete listing of the aimtools is included in the listing
   produced by the instruction 'manaim -k all | more'.



D. Additional Facilities


1. Silent Options: 	docs/aimSilentOptions

   AIM includes a number of 'silent options' that are occassionally
   useful but not sufficiently important to warrant positions on the
   options lists produced by the on-line help (gen??? -help).

   A list of the silent options is provided in docs/aimSilentOptions


2. File Formats: 	docs/aimFileFormats

   A description of the layout of information in the output files
   produced by AIM is presented in docs/aimFileFormats



3. AIM list: 	mail [e-mail]

   An email list for AIM users has been set up. The instructions for
   joining and retiring from the mail list are presented in
   docs/aimMailList. 

   Note that the list is not moderated. It is a facility whereby users
   can communicate for their mutual benefit rather than a question
   answering facility provided by the software developers.



______________________________________________________________________

IV. SETTING UP PATHS FOR AIM AND MANAIM:


As with all applications, the use of AIM is greatly assisted by the
setting up of appropriate pathnames for the executables and on-line
help.

In the following ${DIR} is the pathname of the directory in which AIM is
installed in your file system. For example this might be: /usr/local/aim


A. Executables

The executable files of the model, AIM tools and the script files are located
in the ${DIR}/bin directory.

If the path name is set to this directory, these programs can be executed 
from anywhere in the system.  The best thing to do is to set the PATH 
variable of the environment to: 

	   setenv PATH ${DIR}/bin:$PATH

This can be done in the .login, .profile or any other appropriate start-up
script.


B. Manual Pages:

The `manaim' script prints AIM manual pages with appropriate name in the
Unix man page format.

If the user wishes to view the man pages through "xman", the
environment variable MANPATH needs to be setup to search the
[aim]/release/man directory along with the other default man
directories.

Add the directory which contains the AIM manual pages to the MANPATH
in your environment, for example by including the following in your
start-up script:

	  setenv MANPATH ${DIR}/man:${MANPATH}

or, if MANPATH is an undefined variable:

	  setenv MANPATH ${DIR}/man


For compatibility with systems which do not conventionally use a
MANPATH, the pathname of the AIM pages directory must be the first
pathname in the list.

The AIM man pages will be appear in the "User Commands" section and
the "Local" section of xman.