diff docs/ReadMe @ 0:5242703e91d3 tip

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

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/ReadMe	Fri May 20 15:19:45 2011 +0100
@@ -0,0 +1,452 @@
+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.