Mercurial > hg > aim92
comparison docs/ReadMe @ 0:5242703e91d3 tip
Initial checkin for AIM92 aimR8.2 (last updated May 1997).
author | tomwalters |
---|---|
date | Fri, 20 May 2011 15:19:45 +0100 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:5242703e91d3 |
---|---|
1 bin/ReadMe: | |
2 | |
3 | |
4 AN INTRODUCTION TO THE AUDITORY IMAGE MODEL | |
5 | |
6 This is the introduction for those wanting to use AIM to process waves | |
7 once the software package has been compiled, installed and tested. | |
8 The instructions for compiling and installing AIM are in the text file | |
9 ReadMe.First in the top directory of the software package. | |
10 | |
11 | |
12 CONTENTS | |
13 | |
14 I. Overview of Aim: A description based on Patterson, Allerhand and | |
15 Giguere (1995). It illustrates the instructions used to display waves | |
16 and produce the auditory representations shown in Figures 2 and 3 of | |
17 the paper. | |
18 | |
19 II. aimdemo_* Scripts: A selection of demonstrations that illustrate | |
20 the range of auditory representations produced by AIM. A complete list | |
21 of demonstrations is contained in docs/aimDemonstrations. | |
22 | |
23 III. Overview of Documentation: A brief description of the | |
24 documentation available and how to access it. This information is also | |
25 available in docs/aimDocumentation. | |
26 | |
27 IV. Setting Up Paths for AIM and manaim: The modifications to pathnames | |
28 required to make the AIM instructions and on-line help facilites | |
29 available from all the user's directories. This information is also | |
30 available in docs/aimPaths. | |
31 | |
32 | |
33 | |
34 ______________________________________________________________________ | |
35 | |
36 I. OVERVIEW OF AIM (THE AUDITORY IMAGE MODEL) | |
37 | |
38 The Section presents a brief tour of the facilities in AIM based on a | |
39 Letter to the Editor announcing the release of AIM in the Journal of | |
40 the Acoustical Society of America (1995). It introduces the three | |
41 auditory representations that AIM was originally developed to simulate | |
42 -- basilar membrane motion (BMM), neural activty patterns (NAPs), and | |
43 stabilised auditory images (SAIs). It also introduces the main | |
44 features of the software platform by example; they are the | |
45 instructions and options that control the simulations and the displays | |
46 that present the results. | |
47 | |
48 | |
49 A. Time-Domain Modelling Of Peripheral Auditory Processing: | |
50 A Modular architecture and a Software Platform | |
51 | |
52 The text of the Letter is in PAG95.doc in aim/docs. Figure 1 of the | |
53 paper is a schematic of the architecture of the auditory image | |
54 model. It was produced with a drawing package entirely separate from | |
55 the AIM software package. A postscript version of Figure 1 is | |
56 contained in PAG95_F1.ps. It can be viewed with a postscript previewer | |
57 like ghostview. | |
58 | |
59 The demonstrations are based on the wave for the word 'hat' which is | |
60 stored in the file 'hat' with 'little-endian' byte order. (This is the | |
61 order used in DEC, IBM, and SGI machines.) A byte reversed version | |
62 with 'big-endian' order is provided in 'hat_br'. (This is the order | |
63 used in SUN, and HP machines.) | |
64 | |
65 For an automated tour type | |
66 | |
67 > aimdemo_hat or | |
68 > aimdemo_hat_br | |
69 | |
70 depending on the byte order of your machine. | |
71 | |
72 | |
73 Alternately, you can Execute the instructions individually on the | |
74 command line. | |
75 | |
76 | |
77 B. Displaying Waves Prior to Auditory Analysis: | |
78 | |
79 Waves can be displayed using the initial module of AIM, genwav. | |
80 | |
81 For a display of the complete hat file, use | |
82 | |
83 > genwav samplerate=22.05kHz top=2500 bottom=-2500 input=hat | |
84 | |
85 To restrict the display to the portion of the file with the 'hat' | |
86 sound wave, use | |
87 | |
88 > genwav samplerate=22.05kHz start=110 leng=230 top=2500 bottom=-2500 input=hat | |
89 | |
90 For the BMMs in Figures 2a and 3a, and the NAPs in Figures 2b and 3b, | |
91 we want to restrict the analysis AIM performs to a stationary segment | |
92 of the vowel which is 32 ms in duration and which starts just before a | |
93 glottal pulse. Such a segment can be displayed with | |
94 | |
95 > genwav samplerate=22.05kHz start=182 leng=32 top=2500 bottom=-2500 input=hat | |
96 | |
97 | |
98 C. The Three Main Auditory Representations Produced by AIM | |
99 | |
100 The remainder of this Section presents the AIM instructions used to | |
101 convert the wave for the word 'hat' into the auditory representations | |
102 of the sound presented in the individual panels of Figures 2 and 3 of | |
103 the paper (BMMs, NAPs and auditory images). | |
104 | |
105 Figure 2: The functional version of AIM (panels a, b and c): | |
106 | |
107 a> genbmm samplerate=22.05kHz start=182 leng=32 top=600 bot=-600 input=hat | |
108 | |
109 b> gennap samplerate=22.05kHz start=182 leng=32 top=5000 input=hat | |
110 | |
111 c> gensai samplerate=22.05kHz start=112 leng=100 top=2000 napdecay=3 input=hat | |
112 | |
113 | |
114 Figure 3: The physiological version of AIM (panels a, b and c): | |
115 | |
116 a> genbmm filter=tlf start=182 leng=32 samplerate=22.05kHz top=600 bot=-600 input=hat | |
117 | |
118 b> gennap compress=off transduction=med start=182 leng=32 samplerate=22.05kHz top=5000 input=hat | |
119 | |
120 c> The correlogram version of the auditory image is produced by | |
121 generating a NAP of the sound, converting it into a correlogram with | |
122 acgram, and then displaying it with the facilites in the auditory | |
123 image module, gensai. The instruction sequence is as follows: | |
124 | |
125 > genasi filter=tlf compress=off transduction=med leng=100 samplerate=22.05kHz output=on | |
126 > acgram start=36ms wid=64ms lag=32ms norm=off frames=1 scale=.000002 hat.nap > hat_acg.sai | |
127 > gensai -useprevious start=0 top=3000 input=hat_acg | |
128 | |
129 | |
130 | |
131 ________________________________________________________________________ | |
132 | |
133 II. AIMDEMO_* SCRIPTS | |
134 | |
135 The following is a list of demonstration scripts available to | |
136 illustrate the operation of AIM and the different auditory | |
137 representations that it produces. The scripts are stored in | |
138 [aimdirectory]/scripts. | |
139 | |
140 The syntax for the demos can be obtained by typing | |
141 | |
142 > aimdemo_???_??? help | |
143 | |
144 where '???_???' is one of the extensions listed below. The simplest | |
145 way to begin is to copy the wave file "cegc" from the waves directory | |
146 to the current working directory, and type | |
147 | |
148 > aimdemo_tlf_all cegc | |
149 | |
150 NOTE: The byte order for cegc is "little endian" (used by DEC, | |
151 IBM and SGI machines). A byte reversed version with "big-endian" | |
152 order is the wave "cegc_br". (This is the order used in SUN and HP | |
153 machines.) | |
154 | |
155 The sound in cegc is a set of stationary and gliding click trains that | |
156 play a lazy major triad (C-E-G) and its octave (C) over 2.1 sec. The | |
157 click train at the start (C) is a particularly useful test and demo | |
158 stimulus. | |
159 | |
160 Once one or two of the aimdemos have been shown to work with cegc, you | |
161 should be in a position to try them on your own waves. | |
162 | |
163 | |
164 | |
165 I. The Funcional Version of AIM: | |
166 | |
167 | |
168 1. aimdemo_gtf_all <wave_file> | |
169 | |
170 This script illustrates all stages of the functional version of AIM | |
171 using the "auditory route". It focuses on landscape displays and | |
172 the instructions involved are: | |
173 | |
174 genwav (display input waveform), | |
175 genstp (generate stapes velocity), | |
176 genbmm (generate basilar membrane motion), | |
177 gennap (generate neural activity pattern), | |
178 gensai (generate stabilized auditory image) and | |
179 genspl (generate spiral version of auditory image). | |
180 | |
181 | |
182 2. aimdemo_gtf_sai <wave_file> | |
183 | |
184 This script presents the wave in <wave_file> using genwav, and | |
185 then produces its rectangular auditory image using gensai. It is | |
186 the simplest auditory image demo. | |
187 | |
188 | |
189 3. aimdemo_gtf_spectra <wave_file> | |
190 | |
191 This script illustrates the functional version of AIM using the | |
192 "spectral route". It focuses on spactral displays and the | |
193 instructions involved are: | |
194 | |
195 genwav (display input waveform), | |
196 genasa (generate auditory spectral analysis), and | |
197 genepn (generate excitation pattern) | |
198 | |
199 | |
200 4. aimdemo_gtf_2dat <wave_file> | |
201 | |
202 The script illustrates 2-dimensional adaptive-thresholding | |
203 (2D-AT) using genwav, genstp, genbmm and finally gennap. | |
204 | |
205 | |
206 | |
207 II. The Physiological Version of AIM: | |
208 | |
209 | |
210 1. aimdemo_tlf_all <wave_file> | |
211 | |
212 This demo script illustrates the entire physiological | |
213 version of AIM using the "auditory route". It uses the | |
214 transmission-line filterbank (option filter=tlf) and the Meddis | |
215 neural transduction module (option transduction=Meddis). The | |
216 instructions involved are: | |
217 | |
218 genwav (display input waveform), | |
219 genstp (generate stapes velocity), | |
220 genbmm (generate basilar membrane motion), | |
221 gennap (generate neural activity pattern), | |
222 acgram (generate autocorrelogram). | |
223 | |
224 | |
225 2. aimdemo_tlf_med <wave_file> | |
226 | |
227 The script illustrates the Meddis Haircell module. The AIM | |
228 functions involved are genwav, genbmm and gennap. | |
229 | |
230 | |
231 3. aimdemo_tlf_spectra <wave_file> | |
232 | |
233 This script illustrates the "spectral route" through the | |
234 physiological version of AIM. It focuses on spectral displays and | |
235 the instructions involved are genwav, genasa and genepn. | |
236 | |
237 | |
238 4. aimdemo_tlf_lowhigh <wave_file> | |
239 | |
240 This script illustrates the level dependancies in the physiological | |
241 version of AIM, and its ability to simulate cochlear damage. The | |
242 instructions involved are: | |
243 | |
244 genwav [display input wave], | |
245 genbmm [cochlea level = 30dB], | |
246 genbmm [cochlea level = 90dB], | |
247 gennap [Normal cochlea + Meddis high spont-rate fibre] and | |
248 genasa [total OHC destruction, with no feedback] | |
249 Note: - very poor frequency resolution. | |
250 | |
251 | |
252 | |
253 ________________________________________________________________________ | |
254 | |
255 III. OVERVIEW OF DOCUMENTATION | |
256 | |
257 | |
258 An introduction to the Documentation for the Auditory Image Model of | |
259 Peripheral Auditory Processing | |
260 | |
261 | |
262 A. Initial Contact Points and Aquisition of the Software Package | |
263 | |
264 | |
265 1. WWW Page. | |
266 | |
267 Address: http://www.mrc-apu.cam.ac.uk/aim/ | |
268 | |
269 An overview of AIM on the internet with facilities for acquiring | |
270 the software package. | |
271 | |
272 | |
273 2. Journal reference. | |
274 | |
275 The software package is described in a recent article entitled | |
276 | |
277 "Time-domain modelling of peripheral auditory processing: | |
278 A modular architecture and a software platform" | |
279 | |
280 by Roy D. Patterson and Mike H. Allerhand and Christian Giguere, | |
281 Journal of the Acoustical Society of America, 1995 (in press). | |
282 | |
283 The text of the article is stored in [aim]/docs/PAG95.doc | |
284 | |
285 | |
286 3. ftp instructions: | |
287 | |
288 The instructions for obtaining AIM by ftp are stored in | |
289 [aim]/docs/ftp.doc | |
290 | |
291 | |
292 | |
293 B. Installation and Test | |
294 | |
295 1. ReadMe.First | |
296 | |
297 This document appears in top directory of aim when the aim.tar file is | |
298 unpacked. It is the same file as that in the ftp directory | |
299 /pub/aim. It contains the instructions for compiling AIM, testing | |
300 the installation, and setting up paths to the instructions, the | |
301 aimtools, and the online documentation (manual pages accessed | |
302 through 'manaim'). | |
303 | |
304 | |
305 | |
306 C. Introduction to the Operation of AIM | |
307 | |
308 | |
309 1. bin/ReadMe | |
310 | |
311 This is the initial ReadMe file for those wanting to use AIM once it | |
312 has been installed and tested. It begins with a guided tour of AIM and | |
313 then describes the user documentation and where to find it. | |
314 | |
315 | |
316 2. Introduction to AIM instructions: docs/aimInstructions | |
317 | |
318 An introduction to the instructions and command-line options used to | |
319 control the auditory model is stored in docs/aimInstructions. | |
320 The instructions have the form gen???. The command 'gen -help | more' | |
321 lists the three letter combinations that may replace ??? and | |
322 briefly describes the operations they invoke. | |
323 | |
324 | |
325 3. AIM on-line help: gen??? -help | |
326 | |
327 The instruction 'gen -help | more' lists the AIM instructions. | |
328 | |
329 The instructions have the form 'gen??? -options <file_name>'. | |
330 | |
331 The final three letters of the AIM instruction specify the point | |
332 in the system where the user chooses to observe the output. | |
333 Instructions of the form 'gen??? -help' cause AIM to list the | |
334 options that control AIM up to that output point along with a brief | |
335 description of the option and its current and default value. | |
336 | |
337 | |
338 4. Manual pages for AIM instructions: manaim gen??? | |
339 | |
340 The documentation for each instruction and its options is | |
341 provided in standard manual pages accessed by instructions of the | |
342 form 'manaim gen???'. Begin with 'manaim genwav' which describes | |
343 non-auditory options such as those for the AIM display and for | |
344 the input and output files. | |
345 | |
346 A complete listing of the AIM instructions is included in the listing | |
347 produced by the instruction 'manaim -k all | more'. | |
348 | |
349 Manual pages can be printed with commands of the form | |
350 'manaim gen??? | lpr'. | |
351 | |
352 | |
353 5. Manual pages for AIM tools: manaim <aimtool_name> | |
354 | |
355 The software package includes a set of 'aimtools' for generating | |
356 and manipulating input waves, and for processing the multi-channel, | |
357 multi-frame output of AIM. | |
358 | |
359 There are manual pages for the aimtools accessed by instructions of | |
360 the form 'manaim <aimtool_name>'. | |
361 | |
362 A complete listing of the aimtools is included in the listing | |
363 produced by the instruction 'manaim -k all | more'. | |
364 | |
365 | |
366 | |
367 D. Additional Facilities | |
368 | |
369 | |
370 1. Silent Options: docs/aimSilentOptions | |
371 | |
372 AIM includes a number of 'silent options' that are occassionally | |
373 useful but not sufficiently important to warrant positions on the | |
374 options lists produced by the on-line help (gen??? -help). | |
375 | |
376 A list of the silent options is provided in docs/aimSilentOptions | |
377 | |
378 | |
379 2. File Formats: docs/aimFileFormats | |
380 | |
381 A description of the layout of information in the output files | |
382 produced by AIM is presented in docs/aimFileFormats | |
383 | |
384 | |
385 | |
386 3. AIM list: mail aim@mrc-apu.cam.ac.uk | |
387 | |
388 An email list for AIM users has been set up. The instructions for | |
389 joining and retiring from the mail list are presented in | |
390 docs/aimMailList. | |
391 | |
392 Note that the list is not moderated. It is a facility whereby users | |
393 can communicate for their mutual benefit rather than a question | |
394 answering facility provided by the software developers. | |
395 | |
396 | |
397 | |
398 ______________________________________________________________________ | |
399 | |
400 IV. SETTING UP PATHS FOR AIM AND MANAIM: | |
401 | |
402 | |
403 As with all applications, the use of AIM is greatly assisted by the | |
404 setting up of appropriate pathnames for the executables and on-line | |
405 help. | |
406 | |
407 In the following ${DIR} is the pathname of the directory in which AIM is | |
408 installed in your file system. For example this might be: /usr/local/aim | |
409 | |
410 | |
411 A. Executables | |
412 | |
413 The executable files of the model, AIM tools and the script files are located | |
414 in the ${DIR}/bin directory. | |
415 | |
416 If the path name is set to this directory, these programs can be executed | |
417 from anywhere in the system. The best thing to do is to set the PATH | |
418 variable of the environment to: | |
419 | |
420 setenv PATH ${DIR}/bin:$PATH | |
421 | |
422 This can be done in the .login, .profile or any other appropriate start-up | |
423 script. | |
424 | |
425 | |
426 B. Manual Pages: | |
427 | |
428 The `manaim' script prints AIM manual pages with appropriate name in the | |
429 Unix man page format. | |
430 | |
431 If the user wishes to view the man pages through "xman", the | |
432 environment variable MANPATH needs to be setup to search the | |
433 [aim]/release/man directory along with the other default man | |
434 directories. | |
435 | |
436 Add the directory which contains the AIM manual pages to the MANPATH | |
437 in your environment, for example by including the following in your | |
438 start-up script: | |
439 | |
440 setenv MANPATH ${DIR}/man:${MANPATH} | |
441 | |
442 or, if MANPATH is an undefined variable: | |
443 | |
444 setenv MANPATH ${DIR}/man | |
445 | |
446 | |
447 For compatibility with systems which do not conventionally use a | |
448 MANPATH, the pathname of the AIM pages directory must be the first | |
449 pathname in the list. | |
450 | |
451 The AIM man pages will be appear in the "User Commands" section and | |
452 the "Local" section of xman. |