diff man/man1/edframe.1 @ 0:5242703e91d3 tip

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

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/man1/edframe.1	Fri May 20 15:19:45 2011 +0100
@@ -0,0 +1,347 @@
+.TH EDFRAME 1 "1 September 1993"
+
+.SH NAME
+ edframe \-  Edit AIM output files.
+
+.SH SYNTAX 
+edframe  [[-]frame=a[-b]]  [[-]time=a[-b]]  [[-]freq=a[-b]]  [file]
+
+.SH DESCRIPTION
+Read an AIM output file which must include a header.
+Edit the file using the prescription given in the optional arguments to the
+edframe program, and write the result on the stdout as a new AIM output file
+with an appropriately modified header.
+
+AIM output consists of one or more frames. AIM programs such as genwav, genbmm,
+gennap, gensgm, gencgm, and gensas all generate a single frame of output
+which may be graphically displayed as a single image. AIM programs such as
+genasa, genepn, gensep, gensai, and genspl all generate multiple frames of
+output which may be graphically displayed as a sequence of images in a time-varying
+cartoon.
+
+AIM output may be generated by:
+.nf
+  genXXX  output=on  file1
+.fi
+which creates a file called file1.XXX. This can be edited to create a new
+AIM output file by:
+.nf
+  edframe  [options]  file1.XXX  >  file2.XXX
+.fi
+Alternatively the AIM output can be edited in situ by:
+.nf
+  genXXX  output=stdout  file1  |  edframe  [options]  >  file2.XXX
+.fi
+Edited output may be displayed using the "useprevious" option, for example:
+.nf
+  genXXX  useprevious=on file2
+.fi
+Note that that file2.XXX must have a different base-name to the genXXX input
+(file1) because genXXX will remove any file1.XXX as a side-effect.
+
+Each frame is a matrix of numbers consisting of one or more rows and columns.
+Rows and cols are numbered 0,1,2,..., with the origin (0,0) at the bottom-left
+corner of the graphical image of each frame.
+Editing functions select sub-sequences of frames (when the file consists of
+multiple frames), and partition each of the selected frames using the
+prescription given as program arguments.
+The edited output consists of the selected sub-sequence of partitioned
+sub-matrices. The format of the edited output file corresponds to that of the
+respective input file, and the header is modified to describe the new frame
+size.
+
+.SH OPTIONS
+
+1. time, freq.
+
+These options prescribe the partition of each frame.
+The partition output for each frame is a sub-matrix with width, height, and
+origin with respect to the frame origin described in terms of rows and columns.
+The time and freq options are ranges in the respective dimensions which are
+converted to rows and columns internally. The ranges are given as:
+.nf
+  time=a[-b]
+  freq=a[-b]
+.fi
+The upper limit `b' is optional,
+and when it is missing then the range is a single value,
+otherwise `a' and `b' are inclusive range limits.
+The strings "min" and "max" are recognised as extreme limits, otherwise
+the values of `a' and `b' are numbers with optional units.
+
+The units of the time selector are s or ms
+(seconds and milliseconds respectively), or samples (numbered 0,1,2...)
+if no units are given. Options with time units are converted to samples internally using
+the `samplerate' option.
+
+The units of the freq selector are Hz or kHz
+or filterbank channel (numbered 0,1,2...) if no units are given.
+Options with frequency units are converted to channel numbers internally using the
+filterbank parameters `mincf_afb', `maxcf_afb', `dencf_afb', and `channels_afb'
+given in the AIM header. The channel number which is "closest" in terms of
+centre frequency to the given frequency is chosen.
+
+For most gen programs the time option controls the width of the partition in terms of
+cols (or samples along the horizontal axis of the frame image) and the freq option
+controls the height of the partition in terms of rows
+(or filterbank channels up the vertical axis of the frame image).
+The exceptions to this are
+genwav (where the vertical axis contains just one wave), and the excitation
+patterns genasa, genepn, and gensep in which frequency is measured
+along the horizontal axis of the image, so that it is more appropriate for the
+freq option to control the width of the partition in terms of cols
+(or filterbank channels along the horizontal axis of the frame image).
+
+In the case of gensai (and genspl) the horizontal (or spiral) axis measures
+lag rather than absolute time, but the time option is used to control this
+axis. (Note that time is measured from the left end of the frame image, which
+is actually the maximum lag).
+
+2. frame.
+
+When the input consists of a cartoon of multiple frames
+then single frames or a range of sequential frames may be selected from the
+input using:
+.nf
+  frame=a[-b]
+.fi
+The upper limit `b' is optional,
+and when it is missing then the range is a single frame,
+otherwise `a' and `b' are inclusive range limits.
+The strings "min" and "max" are recognised as extreme limits, otherwise
+the values of `a' and `b' are frame numbers: 0,1,2,...
+
+The frame selector may also take time units (s, or ms) to specify frames
+"closest" to the given time, being the frame number which is the greatest
+integer multiple of the framestep (`frstep_epn' or `frstep_aid') which does
+not exceed the given time, measured from the start of the input file.
+
+3. info.
+
+The option flag:
+.nf
+  -info
+.fi
+causes frame size information to be printed on the stdout.
+The option flag:
+.nf
+  info=fbank
+.fi
+causes channel centre-frequency information to be printed on the stdout for
+those channels selected by the `freq' option.
+This may be used to discover the exact centre-frequency occupied by a given
+channel number within a given filterbank, (as specified by
+the filterbank parameters given in the input header).
+
+4. Header.
+
+The option flag:
+.nf
+  Header=off
+.fi
+causes the modified header to be suppressed from the output.
+
+5. Transpose.
+
+The option flag:
+.nf
+  Transpose=on
+.fi
+causes a matrix transpose (swap rows and columns) of the output
+partition of each input frame.
+When a frame partition has a height greater than it's width
+(ie. cols < rows) then setting Transpose=on may provide a
+preferable display orientation. For example, this enables
+a very narrow (eg. single column) time-slice to be plotted
+horizontally, so that a time-slice of filterbank output may
+be plotted as a spectrum on a horizontal frequency axis.
+In general the transpose option changes the file format of each frame
+from column wise to row wise and vice versa.
+A row wise format (ie. consecutive channels) may be a more useful form of
+output from programs such as genbmm or gennap which normally use a column
+wise output format.
+
+.SH EXAMPLES
+
+.nf
+Selecting particular frames from AIM output.
+.fi
+
+1. Plot gennap output and its transpose.
+
+.nf
+  gennap output=stdout ... | edframe         >  file1.sai
+  gennap output=stdout ... | edframe Tran=on >  file2.sai
+  gensai useprevious=on file1
+  gensai useprevious=on file2
+.fi
+
+2. Select and plot frame 2 (ie. the 3rd frame) of gensai output.
+
+.nf
+  gensai output=stdout ... | edframe frame=2  >  file.sai
+  gensai useprevious=on file
+.fi
+
+3. Select the frames of gensai output which start between 16ms and 47ms from
+the start of it's input. (When the option frstep_aid=16ms then this would
+select the 2nd and 3rd frames).
+
+.nf
+  gensai output=stdout ... | edframe frame=16ms-47ms >  file.sai
+.fi
+
+4. Select the 5th to the last frame inclusively of gensai output.
+
+.nf
+  gensai output=stdout ... | edframe frame=4-max  >  file.sai
+.fi
+
+5. Select the first frame of genepn output and plot the spectrum.
+
+.nf
+  genepn output=stdout ... | edframe frame=min > file1.epn
+  genepn useprevious=on file1
+.fi
+
+
+.nf
+Editing frames to select particular frequency ranges or channels (ie rows).
+.fi
+
+6. Select and plot the channel with centre-frequency closest to 1kHz from
+gennap output.
+
+.nf
+  gennap output=stdout ... | edframe freq=1kHz  >  file.nap
+  gennap useprevious=on file
+.fi
+
+7. Select and plot channel 40 then the channel with the lowest and then
+the highest centre-frequency over all frames of gensai output.
+
+.nf
+  gensai output=stdout ... | edframe freq=40  >  file.sai
+  gensai useprevious=on file
+
+  gensai output=stdout ... | edframe freq=min  >  file.sai
+  gensai useprevious=on file
+
+  gensai output=stdout ... | edframe freq=max  >  file.sai
+  gensai useprevious=on file
+.fi
+
+8. Select and plot all channels of genbmm output from channel 10 to
+the channel with centre-frequency closest to 1kHz inclusively.
+
+.nf
+  genbmm output=stdout ... | edframe freq=10-1000Hz  >  file.bmm
+  genbmm useprevious=on file
+.fi
+
+9. Select and plot a portion of the spectrum from the first frame of genepn
+output between 1kHz and 2kHz.
+Note: frequency controls the horizontal (ie cols) dimension for genepn.
+
+.nf
+  genepn output=stdout ... | edframe frame=min freq=1kHz-2kHz > file.epn
+  genepn useprevious=on file
+.fi
+
+
+.nf
+Editing frames to select particular time slices (ie cols).
+.fi
+
+10. Plot column (ie sample) 100 of the 3rd frame of gensai output as a row.
+
+.nf
+  gensai output=stdout ... | edframe frame=2 time=100 Tran=on >  file.sai
+  gensai useprevious=on file
+.fi
+
+11. Plot column of sample at 20ms from start of gennap output as a row
+
+.nf
+  gennap output=stdout ... | edframe time=20ms Tran=on >  file.nap
+  gennap useprevious=on file
+.fi
+
+12. Edit a wave to select the stretch between 4ms and 16ms, strip the
+header and plot the resulting wave.
+
+.nf
+  genwav output=stdout ... | edframe time=4ms-16ms Header=off > file
+  genwav file
+.fi
+
+
+.nf
+Editing frames to select partitions.
+.fi
+
+13. Plot a partition of channels 40 to 44 over the last 5ms (ie near the
+trigger point on the right of the image) of all frames of gensai output.
+Then plot a partition of frequency range 1kHz to 1.5kHz over the first
+20ms (on the left of the image) of all frames of gensai output.
+
+.nf
+  gensai pwidth=35ms nwidth=0 output=stdout ... | edframe time=30ms-max > file.sai
+  gensai useprevious=on file
+  gensai output=stdout ... | edframe freq=1kHz-1.5kHz time=min-20ms > file.sai
+  gensai useprevious=on file
+.fi
+
+14. Plot the highest-frequency channel over the last 20ms of gennap output.
+
+.nf
+  gennap output=stdout ... | edframe freq=max time=20ms-max > file.sai
+  gennap useprevious=on file
+.fi
+
+
+.nf
+Changing the aim output format.
+.fi
+
+15. Convert the genbmm output format (column wise) to row wise format, and
+strip the aim header.
+The resulting file will consist of consecutive blocks of N samples, where
+N = length * samplerate.
+The first block is the output from the lowest centre frequency channel,
+the second is from the second channel, and so on.
+By default the whole frame is transposed, but any partition of the frame
+could be selected using the time and frequency options.
+(Note: the transpose takes place after the partition has been made).
+
+.nf
+  genbmm output=stdout ... | edframe Tranpose=on Header=off > file
+.fi
+
+
+.SH "SEE ALSO"
+options hdr fbank
+
+.SH COPYRIGHT
+.LP
+Copyright (c) Applied Psychology Unit, Medical Research Council, 1995
+.LP
+Permission to use, copy, modify, and distribute this software 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.
+.LP
+The MRC makes no representations about the suitability of this 
+software for any purpose.  It is provided "as is" without express or 
+implied warranty.
+.LP
+THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
+ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL 
+THE A.P.U. 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.