ReadMe.First ============================================================================ AIM R8 AUDITORY IMAGE MODEL Release 8.2 Medical Research Council, Applied Psychology Unit Cambridge, CB2 2EF, UK April 1997 At the Applied Psychology Unit, we have developed a time-domain model of auditory processing to simulate the auditory images produced by complex sounds like music, speech, bird song, engines, etc.* The Auditory Image Model (AIM) constructs its simulation of what we hear in three stages: 1) Using an auditory filterbank, it converts the digitized sound wave into a simulation of the basilar membrane motion (BMM) that the sound would produce in the cochlea. 2) Using a bank of haircell simulators, it 'transduces' the BMM into a simulation of the Neural Activity Pattern (NAP) that the sound would produce in the auditory nerve. 3) Finally, it applies a new form of Strobed Temporal Integration (STI) to each channel of the NAP to convert the array of NAP channels into the models simulation of our auditory image of the sound. The NAP includes the phase-locking information encoded by the inner haircells because it is assumed that this information plays an important role in auditory perception and speech perception. STI performs the temporal integration without destroying the phase-locking information of regular sounds -- the phase locking information that we hear. Thus, AIM is a time-domain auditory model for studying the role of phase locking and temporal fine-structure in auditory perception. Sequences of auditory images can be replayed to produce cartoons of auditory events that illustrate the dynamic response of the auditory system to everyday sounds. * Note that the 'auditory images' constructed by AIM are meant to represent our initial sensations or perceptions of a sound rather than images of past events recalled from memory. There are now a number of ways to produce auditory images, and in October 1995, we published a short paper describing a software package that we use to assemble and run different forms of Auditory Image Model. The full reference for the paper is Patterson, R.D., Allerhand, M., and Giguere, C., (1995). "Time-domain modelling of peripheral auditory processing: A modular architecture and a software platform," J. Acoust. Soc. Am. 98, 1890-1894. You can read about AIM on our WWW page http://www.mrc-apu.cam.ac.uk/aim/ You can pick up the source code and documentation from the web page, or by annonymous ftp from ftp.mrc-apu.cam.ac.uk directory pub/aim This ReadMe.First file explains how to to acquire the source code, how to compile it, and how to get started. There are currently two releases of AIM: aimR7 and aimR8. aimR7 is the version described in Patterson et al., (1995). It was released in September of 1995. aimR8 is the latest version, released originally in August 1996 as R8.1 and again with a few bugs fixed in May 1997 as R8.2. The differences between R7 and R8 are described in aimR8announcement. The changes have to do with the simulation of auditory compression and loss of phase locking at high frequencies. There are also a number of new facilitites including a) a Matlab interface for AIM, b) instructions for assembling a Meddis and Hewitt (1991) model of pitch perception, c) optional power compression for the functional versions of AIM, d) a set of silent options for postscript printing of AIM displays. ============================================================================ This file contains: 1. General information: A. Disclaimer and copyright. B. Acknowledgements. C. Contact addresses. D. Ftp instructions for obtaining the software. 2. Getting started: A. Installing the software [compilation]. B. Running the model. C. Setting the environment variables PATH and the MANPATH. 3. Compiling the model - further details. A. X11 libraries. B. Alternative compilers. C. A note on color workstations. 4. Next step after installing AIM. ============================================================================ 1. GENERAL INFORMATION: ============================================================================ A. Disclaimer and Copyright Permission to use, copy, modify, and distribute the software described in this document 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. The MRC makes no representations about the suitability of the software described in this document for any purpose. It is provided `as is' without express or implied warranty. The MRC disclaims all warranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall the MRC 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. ============================================================================ B. Acknowledgements 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. 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. ============================================================================ C. Contact Addresses: Roy D Patterson (for the functional version of AIM) MRC APU, 15 Chaucer Road, Cambridge CB2 2EF, England. Phone +44 1223 355294 Fax +44 1223 359062 email: roy.patterson@mrc-apu.cam.ac.uk Christian Giguere (for the physiological version of AIM) University of Ottawa, Ottawa, Ontario, Canada email: cgiguere@aix1.uottawa.ca c.giguere@med.ruu.nl Michael Akeroyd (for postscript printing and auxtools) MRC IHR, University Park, Nottingham, NG7 2RD, U.K. email: michael.akeroyd@ihr.mrc.ac.uk Minoru Tsuzaki (for the matlab interface AIMMAT) ATR HIP Seika-cho, Soraku-gun, Kyoto, Japan email: tsuzaki@hip.atr.co.jp ============================================================================ D. ftp Instructions for Obtaining the Software Access to the APU site via ftp is by the address: ftp.mrc-apu.cam.ac.uk Use ="anonymous" and =your email address. Once inside the APU ftp system, cd to the AIM directory, pub/aim/. The AIM software is in the compressed archive `aimR8.tar.Z'. The ReadMe.First file contains the text of this document. The AIM documentation is in the compressed archive `aimR8docs.tar.Z'. Copy all the three files. For example: ftp ftp.mrc-apu.cam.ac.uk Name (mrc-apu.cam.ac.uk:you): anonymous Password: your email address cd pub/aim get ReadMe.First get aimR8.tar.Z get aimR8docs.tar.Z Details of machine and address Name: sirius.mrc-apu.cam.ac.uk Address: 192.18.195.1 Aliases: dns0.mrc-apu.cam.ac.uk ============================================================================ 2. GETTING STARTED: ============================================================================ A. Installing the Software It is best to make a new directory (e.g. aim) for the software. Put aimR8.tar.Z, aimR8docs.tar.Z and ReadMe.First in the directory and unpack the source code using the commands: zcat aimR8.tar.Z | tar xvf - zcat aimR8docs.tar.Z | tar xvf - The current directory should then contain a makefile and a set of subdirectories. Five of these contain the C source code for AIM (filter, glib, model, stitch, and wdf). The tools directory contains C code for ancillary routines to construct stimuli and process the multi-channel output that AIM produces. The man directory contains online manual pages available through MANPATH and the instruction 'manaim'. The scripts directory contains guided tours of AIM in the form of scripts that also serve to test the installation and illustrate a typical mode of operation. The waves directory contains test waves demonstration waves including 'hat'. These sounds were all sampled at 20 kHz and each sample is a 2-byte word in little-endian order (i.e. Dec and PC order). The bytes need to be reversed for Sun, HP and SGI machines. The bin directory contains executable routines and links to executable routines produced by the compilation. Compile the source code using make TARGET= where: = sun | sgi | hp | vax | dec | sungcc | linux (For other options try 'make -help' of see: "Compiling the model - further details"). The file `gen' in directory bin is the AIM program itself. There are some auxillary tools that only compile with the gcc compiler (saisummary, xreview, synthdramp and synthirn). If you want to try them and have a gcc compiler you can try make CC=gcc TARGET= ============================================================================ B. Running the model. To verify that AIM is operational, move to the bin directory and type: gen -help This should print general usage information on the standard output. ============================================================================ C. Setting Up the Environment Variables PATH and MANPATH. The software is now ready. Before setting off, however, we recommend that you a) Set your PATH to include [aim_directory]/bin (instructions in docs/aimPaths) b) Set your MANPATH to include [aim_directory]/man (instructions in docs/aimPaths) ============================================================================ 3. COMPILING THE MODEL - FURTHER DETAILS. ============================================================================ In the root directory, the command "make help" prints a list of the targets and parameters for compilation. The machine-specific details refer only to the location of the X11 libraries and header files on the target machine. ============================================================================ A. X11 Libraries The AIM graphics library is based upon X11, and the library (libX11.a) and included header files (X11/X.h and X11/Xlib.h) are expected to be in standard places. The command "make " assigns the paths usually used on the particular machine. For example, the command make decstation assigns paths so that the following files are expected: /usr/lib/libX11.a /usr/include/X11/X.h /usr/include/X11/Xlib.h If the X11 library and header files are in non-standard directories, then the path for the directories can be given to the root makefile using the parameters X11DIR (for the directory containing the files files X11/X.h and X11/Xlib.h) and X11LIB (for the directory containing the library libX11.a). These parameters override the default parameters assigned for a particular machine. For example decstation paths could also be assigned using:- make X11DIR=/usr/include X11LIB=/usr/lib [] sun paths could also be assigned using:- make X11DIR=/usr/openwin/include X11LIB=/usr/lib [] To see what the internal defaults are for a particular machine, type: make TARGET=help This prints a complete list of the makefile targets, arguments, and defaults on the standard output. The values of the arguments X11DIR and X11LIB are the default paths associated with the specified machine. ============================================================================ B. Alternative compilers The default compiler is the traditional C compiler cc. Alternative compilers can be specified by giving the name of the compiler to the root makefile, (assuming it exists in the current path). For example, the GNU Project C compiler, gcc, is specified as follows, (including it's -ansi flag, for compatability with ansi cc): make CC=gcc CFLAGS="-O -ansi" We find following produces code which runs significantly faster that the traditional cc compiler: make CC=gcc CFLAGS=-O2 ============================================================================ C. A Note on Color Workstations The AIM software X11 interface is designed for monochrome screens, and not for multiplane color screens. The software will run on a color screen, except that when bitmaps are created they are the same depth as the screen, since they are exact copies of the screen memory. This also happens, for example, when the "animate" option is on, or when the "xreview" program is used. The symptoms are a very slow response time, and huge bitmap files. There is a hidden option "mono=on" (short for "monochrome") which forces the bitmap to be a single plane of the screen memory. By default, it copies plane 1; if this does not work, the plane can be varied with the hidden option "planemask=". ============================================================================ 4. Next step after installing AIM. ============================================================================ When the installation is complete go to the 'bin' directory. It contains the compiled programs and the user ReadMe file which is the start point for the user documentation. bin/ReadMe provides an overview of AIM, a set of demonstrations, an overview of the AIM documentation, and PATH information.