Mercurial > hg > aim92
comparison man/man1/edframe.1 @ 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 .TH EDFRAME 1 "1 September 1993" | |
2 | |
3 .SH NAME | |
4 edframe \- Edit AIM output files. | |
5 | |
6 .SH SYNTAX | |
7 edframe [[-]frame=a[-b]] [[-]time=a[-b]] [[-]freq=a[-b]] [file] | |
8 | |
9 .SH DESCRIPTION | |
10 Read an AIM output file which must include a header. | |
11 Edit the file using the prescription given in the optional arguments to the | |
12 edframe program, and write the result on the stdout as a new AIM output file | |
13 with an appropriately modified header. | |
14 | |
15 AIM output consists of one or more frames. AIM programs such as genwav, genbmm, | |
16 gennap, gensgm, gencgm, and gensas all generate a single frame of output | |
17 which may be graphically displayed as a single image. AIM programs such as | |
18 genasa, genepn, gensep, gensai, and genspl all generate multiple frames of | |
19 output which may be graphically displayed as a sequence of images in a time-varying | |
20 cartoon. | |
21 | |
22 AIM output may be generated by: | |
23 .nf | |
24 genXXX output=on file1 | |
25 .fi | |
26 which creates a file called file1.XXX. This can be edited to create a new | |
27 AIM output file by: | |
28 .nf | |
29 edframe [options] file1.XXX > file2.XXX | |
30 .fi | |
31 Alternatively the AIM output can be edited in situ by: | |
32 .nf | |
33 genXXX output=stdout file1 | edframe [options] > file2.XXX | |
34 .fi | |
35 Edited output may be displayed using the "useprevious" option, for example: | |
36 .nf | |
37 genXXX useprevious=on file2 | |
38 .fi | |
39 Note that that file2.XXX must have a different base-name to the genXXX input | |
40 (file1) because genXXX will remove any file1.XXX as a side-effect. | |
41 | |
42 Each frame is a matrix of numbers consisting of one or more rows and columns. | |
43 Rows and cols are numbered 0,1,2,..., with the origin (0,0) at the bottom-left | |
44 corner of the graphical image of each frame. | |
45 Editing functions select sub-sequences of frames (when the file consists of | |
46 multiple frames), and partition each of the selected frames using the | |
47 prescription given as program arguments. | |
48 The edited output consists of the selected sub-sequence of partitioned | |
49 sub-matrices. The format of the edited output file corresponds to that of the | |
50 respective input file, and the header is modified to describe the new frame | |
51 size. | |
52 | |
53 .SH OPTIONS | |
54 | |
55 1. time, freq. | |
56 | |
57 These options prescribe the partition of each frame. | |
58 The partition output for each frame is a sub-matrix with width, height, and | |
59 origin with respect to the frame origin described in terms of rows and columns. | |
60 The time and freq options are ranges in the respective dimensions which are | |
61 converted to rows and columns internally. The ranges are given as: | |
62 .nf | |
63 time=a[-b] | |
64 freq=a[-b] | |
65 .fi | |
66 The upper limit `b' is optional, | |
67 and when it is missing then the range is a single value, | |
68 otherwise `a' and `b' are inclusive range limits. | |
69 The strings "min" and "max" are recognised as extreme limits, otherwise | |
70 the values of `a' and `b' are numbers with optional units. | |
71 | |
72 The units of the time selector are s or ms | |
73 (seconds and milliseconds respectively), or samples (numbered 0,1,2...) | |
74 if no units are given. Options with time units are converted to samples internally using | |
75 the `samplerate' option. | |
76 | |
77 The units of the freq selector are Hz or kHz | |
78 or filterbank channel (numbered 0,1,2...) if no units are given. | |
79 Options with frequency units are converted to channel numbers internally using the | |
80 filterbank parameters `mincf_afb', `maxcf_afb', `dencf_afb', and `channels_afb' | |
81 given in the AIM header. The channel number which is "closest" in terms of | |
82 centre frequency to the given frequency is chosen. | |
83 | |
84 For most gen programs the time option controls the width of the partition in terms of | |
85 cols (or samples along the horizontal axis of the frame image) and the freq option | |
86 controls the height of the partition in terms of rows | |
87 (or filterbank channels up the vertical axis of the frame image). | |
88 The exceptions to this are | |
89 genwav (where the vertical axis contains just one wave), and the excitation | |
90 patterns genasa, genepn, and gensep in which frequency is measured | |
91 along the horizontal axis of the image, so that it is more appropriate for the | |
92 freq option to control the width of the partition in terms of cols | |
93 (or filterbank channels along the horizontal axis of the frame image). | |
94 | |
95 In the case of gensai (and genspl) the horizontal (or spiral) axis measures | |
96 lag rather than absolute time, but the time option is used to control this | |
97 axis. (Note that time is measured from the left end of the frame image, which | |
98 is actually the maximum lag). | |
99 | |
100 2. frame. | |
101 | |
102 When the input consists of a cartoon of multiple frames | |
103 then single frames or a range of sequential frames may be selected from the | |
104 input using: | |
105 .nf | |
106 frame=a[-b] | |
107 .fi | |
108 The upper limit `b' is optional, | |
109 and when it is missing then the range is a single frame, | |
110 otherwise `a' and `b' are inclusive range limits. | |
111 The strings "min" and "max" are recognised as extreme limits, otherwise | |
112 the values of `a' and `b' are frame numbers: 0,1,2,... | |
113 | |
114 The frame selector may also take time units (s, or ms) to specify frames | |
115 "closest" to the given time, being the frame number which is the greatest | |
116 integer multiple of the framestep (`frstep_epn' or `frstep_aid') which does | |
117 not exceed the given time, measured from the start of the input file. | |
118 | |
119 3. info. | |
120 | |
121 The option flag: | |
122 .nf | |
123 -info | |
124 .fi | |
125 causes frame size information to be printed on the stdout. | |
126 The option flag: | |
127 .nf | |
128 info=fbank | |
129 .fi | |
130 causes channel centre-frequency information to be printed on the stdout for | |
131 those channels selected by the `freq' option. | |
132 This may be used to discover the exact centre-frequency occupied by a given | |
133 channel number within a given filterbank, (as specified by | |
134 the filterbank parameters given in the input header). | |
135 | |
136 4. Header. | |
137 | |
138 The option flag: | |
139 .nf | |
140 Header=off | |
141 .fi | |
142 causes the modified header to be suppressed from the output. | |
143 | |
144 5. Transpose. | |
145 | |
146 The option flag: | |
147 .nf | |
148 Transpose=on | |
149 .fi | |
150 causes a matrix transpose (swap rows and columns) of the output | |
151 partition of each input frame. | |
152 When a frame partition has a height greater than it's width | |
153 (ie. cols < rows) then setting Transpose=on may provide a | |
154 preferable display orientation. For example, this enables | |
155 a very narrow (eg. single column) time-slice to be plotted | |
156 horizontally, so that a time-slice of filterbank output may | |
157 be plotted as a spectrum on a horizontal frequency axis. | |
158 In general the transpose option changes the file format of each frame | |
159 from column wise to row wise and vice versa. | |
160 A row wise format (ie. consecutive channels) may be a more useful form of | |
161 output from programs such as genbmm or gennap which normally use a column | |
162 wise output format. | |
163 | |
164 .SH EXAMPLES | |
165 | |
166 .nf | |
167 Selecting particular frames from AIM output. | |
168 .fi | |
169 | |
170 1. Plot gennap output and its transpose. | |
171 | |
172 .nf | |
173 gennap output=stdout ... | edframe > file1.sai | |
174 gennap output=stdout ... | edframe Tran=on > file2.sai | |
175 gensai useprevious=on file1 | |
176 gensai useprevious=on file2 | |
177 .fi | |
178 | |
179 2. Select and plot frame 2 (ie. the 3rd frame) of gensai output. | |
180 | |
181 .nf | |
182 gensai output=stdout ... | edframe frame=2 > file.sai | |
183 gensai useprevious=on file | |
184 .fi | |
185 | |
186 3. Select the frames of gensai output which start between 16ms and 47ms from | |
187 the start of it's input. (When the option frstep_aid=16ms then this would | |
188 select the 2nd and 3rd frames). | |
189 | |
190 .nf | |
191 gensai output=stdout ... | edframe frame=16ms-47ms > file.sai | |
192 .fi | |
193 | |
194 4. Select the 5th to the last frame inclusively of gensai output. | |
195 | |
196 .nf | |
197 gensai output=stdout ... | edframe frame=4-max > file.sai | |
198 .fi | |
199 | |
200 5. Select the first frame of genepn output and plot the spectrum. | |
201 | |
202 .nf | |
203 genepn output=stdout ... | edframe frame=min > file1.epn | |
204 genepn useprevious=on file1 | |
205 .fi | |
206 | |
207 | |
208 .nf | |
209 Editing frames to select particular frequency ranges or channels (ie rows). | |
210 .fi | |
211 | |
212 6. Select and plot the channel with centre-frequency closest to 1kHz from | |
213 gennap output. | |
214 | |
215 .nf | |
216 gennap output=stdout ... | edframe freq=1kHz > file.nap | |
217 gennap useprevious=on file | |
218 .fi | |
219 | |
220 7. Select and plot channel 40 then the channel with the lowest and then | |
221 the highest centre-frequency over all frames of gensai output. | |
222 | |
223 .nf | |
224 gensai output=stdout ... | edframe freq=40 > file.sai | |
225 gensai useprevious=on file | |
226 | |
227 gensai output=stdout ... | edframe freq=min > file.sai | |
228 gensai useprevious=on file | |
229 | |
230 gensai output=stdout ... | edframe freq=max > file.sai | |
231 gensai useprevious=on file | |
232 .fi | |
233 | |
234 8. Select and plot all channels of genbmm output from channel 10 to | |
235 the channel with centre-frequency closest to 1kHz inclusively. | |
236 | |
237 .nf | |
238 genbmm output=stdout ... | edframe freq=10-1000Hz > file.bmm | |
239 genbmm useprevious=on file | |
240 .fi | |
241 | |
242 9. Select and plot a portion of the spectrum from the first frame of genepn | |
243 output between 1kHz and 2kHz. | |
244 Note: frequency controls the horizontal (ie cols) dimension for genepn. | |
245 | |
246 .nf | |
247 genepn output=stdout ... | edframe frame=min freq=1kHz-2kHz > file.epn | |
248 genepn useprevious=on file | |
249 .fi | |
250 | |
251 | |
252 .nf | |
253 Editing frames to select particular time slices (ie cols). | |
254 .fi | |
255 | |
256 10. Plot column (ie sample) 100 of the 3rd frame of gensai output as a row. | |
257 | |
258 .nf | |
259 gensai output=stdout ... | edframe frame=2 time=100 Tran=on > file.sai | |
260 gensai useprevious=on file | |
261 .fi | |
262 | |
263 11. Plot column of sample at 20ms from start of gennap output as a row | |
264 | |
265 .nf | |
266 gennap output=stdout ... | edframe time=20ms Tran=on > file.nap | |
267 gennap useprevious=on file | |
268 .fi | |
269 | |
270 12. Edit a wave to select the stretch between 4ms and 16ms, strip the | |
271 header and plot the resulting wave. | |
272 | |
273 .nf | |
274 genwav output=stdout ... | edframe time=4ms-16ms Header=off > file | |
275 genwav file | |
276 .fi | |
277 | |
278 | |
279 .nf | |
280 Editing frames to select partitions. | |
281 .fi | |
282 | |
283 13. Plot a partition of channels 40 to 44 over the last 5ms (ie near the | |
284 trigger point on the right of the image) of all frames of gensai output. | |
285 Then plot a partition of frequency range 1kHz to 1.5kHz over the first | |
286 20ms (on the left of the image) of all frames of gensai output. | |
287 | |
288 .nf | |
289 gensai pwidth=35ms nwidth=0 output=stdout ... | edframe time=30ms-max > file.sai | |
290 gensai useprevious=on file | |
291 gensai output=stdout ... | edframe freq=1kHz-1.5kHz time=min-20ms > file.sai | |
292 gensai useprevious=on file | |
293 .fi | |
294 | |
295 14. Plot the highest-frequency channel over the last 20ms of gennap output. | |
296 | |
297 .nf | |
298 gennap output=stdout ... | edframe freq=max time=20ms-max > file.sai | |
299 gennap useprevious=on file | |
300 .fi | |
301 | |
302 | |
303 .nf | |
304 Changing the aim output format. | |
305 .fi | |
306 | |
307 15. Convert the genbmm output format (column wise) to row wise format, and | |
308 strip the aim header. | |
309 The resulting file will consist of consecutive blocks of N samples, where | |
310 N = length * samplerate. | |
311 The first block is the output from the lowest centre frequency channel, | |
312 the second is from the second channel, and so on. | |
313 By default the whole frame is transposed, but any partition of the frame | |
314 could be selected using the time and frequency options. | |
315 (Note: the transpose takes place after the partition has been made). | |
316 | |
317 .nf | |
318 genbmm output=stdout ... | edframe Tranpose=on Header=off > file | |
319 .fi | |
320 | |
321 | |
322 .SH "SEE ALSO" | |
323 options hdr fbank | |
324 | |
325 .SH COPYRIGHT | |
326 .LP | |
327 Copyright (c) Applied Psychology Unit, Medical Research Council, 1995 | |
328 .LP | |
329 Permission to use, copy, modify, and distribute this software without fee | |
330 is hereby granted for research purposes, provided that this copyright | |
331 notice appears in all copies and in all supporting documentation, and that | |
332 the software is not redistributed for any fee (except for a nominal | |
333 shipping charge). Anyone wanting to incorporate all or part of this | |
334 software in a commercial product must obtain a license from the Medical | |
335 Research Council. | |
336 .LP | |
337 The MRC makes no representations about the suitability of this | |
338 software for any purpose. It is provided "as is" without express or | |
339 implied warranty. | |
340 .LP | |
341 THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING | |
342 ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL | |
343 THE A.P.U. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES | |
344 OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, | |
345 WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, | |
346 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS | |
347 SOFTWARE. |