tomwalters@0: 
tomwalters@0: 
tomwalters@0: Appendix C       Output File Formats
tomwalters@0: 
tomwalters@0: This Appendix describes the format of output from the ASP modules, for
tomwalters@0: users who wish to process this output with another program of their own.
tomwalters@0: For example, gensai produces a stabilised auditory image which is suitable
tomwalters@0: as input to a speech recognition system.  In most cases the output file
tomwalters@0: will probably require an additional processing step before it may be used
tomwalters@0: by another program.
tomwalters@0: 
tomwalters@0: Each ASP module produces an output file in response to the -output option.
tomwalters@0: These output files consist of a header (containing information concerning
tomwalters@0: the makeup and history of the file) followed by a series of 16-bit data
tomwalters@0: items which represent the actual data contained in the file.
tomwalters@0: 
tomwalters@0: There are two obvious ways in which such a data file may be used as input
tomwalters@0: to a user's own program; firstly, the user's program may be adapted to read
tomwalters@0: and interpret the header of ASP output files before actually processing the
tomwalters@0: data in them, and secondly, the header may be removed and the relevant
tomwalters@0: information entered into the user's program manually before it proceeds to
tomwalters@0: process the data section of the ASP output file.  The former of these
tomwalters@0: techniques is preferable in many ways, providing consistency and insulating
tomwalters@0: the user from the details of ASP headers, although it may require some
tomwalters@0: effort to alter the user's program to correctly process these headers.  The
tomwalters@0: second method may be preferable if the user is merely interested in testing
tomwalters@0: the ASP software's suitability as a preprocessor for their program, or if
tomwalters@0: the program in question cannot be altered (either because it was purchased
tomwalters@0: from someone else, or because it would be too complicated to change it).
tomwalters@0: 
tomwalters@0: The second method merely requires a reliable way to separate an ASP output
tomwalters@0: file into header and data sections, and the user must then 'translate' the
tomwalters@0: information in the header into the terms understood by the parameters of
tomwalters@0: his/her program.  To this end, the ASP package includes two programs called
tomwalters@0: head and tail which take an ASP output file as their argument and produce
tomwalters@0: another file containing its header and data sections, respectively.  The
tomwalters@0: header is adapted to resemble very closely an ASP module's options file,
tomwalters@0: and ought to be easily understood by anyone familiar with the ASP modules
tomwalters@0: and the way in which they are used.  As far as translation concepts from
tomwalters@0: ASP to another program is concerned, we can only volunteer this
tomwalters@0: documentation as a guide to the interpretation of each ASP option.
tomwalters@0: 
tomwalters@0: The former of the two methods requires rather more detailed understanding
tomwalters@0: of the output file structure, and this discussion will be divided into two
tomwalters@0: parts, one on the header and the other on the data itself.
tomwalters@0: 
tomwalters@0: Head and Tail
tomwalters@0: 
tomwalters@0: For users who wish to remove the header part of an ASP output file, the
tomwalters@0: software includes two programs called head and tail which take an ASP
tomwalters@0: output file as their argument and produce another file containing its
tomwalters@0: header and data sections, respectively.  The header is adapted to resemble
tomwalters@0: very closely an ASP module's options file, and ought to be easily
tomwalters@0: understood by anyone familiar with the ASP modules and the way in which
tomwalters@0: they are used.  As far as translation of concepts from ASP to another
tomwalters@0: program is concerned we can only volunteer this documentation as a guide to
tomwalters@0: the interpretation of each ASP option.
tomwalters@0: 
tomwalters@0: Whichever method the user chooses in combining ASP output files with their
tomwalters@0: own programs, some information regarding the types and format of
tomwalters@0: information in ASP output modules will be needed.  Discussion of the
tomwalters@0: structure of the output files will be divided into two sections, one on the
tomwalters@0: header and the other on the data itself.
tomwalters@0: 
tomwalters@0: The header
tomwalters@0: 
tomwalters@0: Each ASP module's output file contains a header which provides information
tomwalters@0: about the origin and history of the data in the file.  This information is
tomwalters@0: used by subsequent modules in the ASP hierarchy, as described in Appendix
tomwalters@0: B.  The header is a sequence of ASCII characters (and is thus readable, so
tomwalters@0: even using more on the output file would produce sensible text for the
tomwalters@0: duration of the header).  This sequence is divided into three parts.
tomwalters@0: 
tomwalters@0: 1	An identifying line.
tomwalters@0: 
tomwalters@0: 2	A series of option setting lines.
tomwalters@0: 
tomwalters@0: 3	NULL (ASCII 0) character.
tomwalters@0: 
tomwalters@0: The identifying line is a means of determining, from the first few
tomwalters@0: characters in a file, whether that file is in fact an ASP output file.  It
tomwalters@0: also is used for determining the length of the header as a whole; thus,
tomwalters@0: each output file begins with a string such as:
tomwalters@0: 
tomwalters@0: header_bytes=0000709
tomwalters@0: 
tomwalters@0: where header_bytes is the identifying string (which actually descended from
tomwalters@0: the 'pipes' signal processing language) and the header is 709 bytes long.
tomwalters@0: The length of the header includes the identifying line and the final NULL
tomwalters@0: character.
tomwalters@0: 
tomwalters@0: Each option setting line is of the form:
tomwalters@0: 
tomwalters@0: <option name>=<option value>
tomwalters@0: 
tomwalters@0: and these lines taken together will closely resemble a normal ASP options
tomwalters@0: file, although there may be some options which are not familiar to even an
tomwalters@0: experienced ASP user.  These options are 'hidden' ones which are passed
tomwalters@0: between ASP modules, but which are of no interest to users of the software.
tomwalters@0:  They may, however, be of interest to programmers who wish to take ASP
tomwalters@0: output as input to their own programs, so a complete list of these hidden
tomwalters@0: options is given at the end of this Appendix.
tomwalters@0: 
tomwalters@0: The data
tomwalters@0: 
tomwalters@0: The structure of the actual data section of an ASP output file will be
tomwalters@0: dependent on the ASP module which produced it.  Since we are then committed
tomwalters@0: to describing each of the output structures in detail, we will begin with
tomwalters@0: the data structure that ASP modules expect in input waveforms.
tomwalters@0: 
tomwalters@0: Input waveform structure
tomwalters@0: 
tomwalters@0: For convenience, the ASP software assumes that input waveforms do not have
tomwalters@0: headers of any form.  The only information about the structure of an input
tomwalters@0: waveform that is required relates to the samplerate at which the waveform
tomwalters@0: was generated or collected, and the number of significant bits that are in
tomwalters@0: the data.  These two attributes are taken as options which must be entered
tomwalters@0: by the user, but they could just as easily be viewed as the contents of a
tomwalters@0: suitable header for a waveform.  The actual data section of a waveform
tomwalters@0: consists of a single stream of (16-bit, or 'short') integers whose length
tomwalters@0: determines the actual length, in points, of the waveform.  To view the
tomwalters@0: waveform only the user can use genwav.
tomwalters@0: 
tomwalters@0: Basilar membrane motion output structure
tomwalters@0: 
tomwalters@0: The genbmm module takes a waveform of the structure defined above and
tomwalters@0: produces the basilar membrane motion corresponding to this input waveform
tomwalters@0: by using a gammatone filter bank.  The output data is expressed as the
tomwalters@0: multiplexed output of a series of channels, one per channel in the filter
tomwalters@0: bank.  Thus the first n data points (where n is the number of channels) in
tomwalters@0: the output correspond to the first output data point for each of the n
tomwalters@0: channels, beginning with the highest frequency channel and ending with
tomwalters@0: lowest.  The second batch of n data points in the output file correspond to
tomwalters@0: the second data point for each of the n channels in turn, and so on.  There
tomwalters@0: will be m of these n-data item segments, where m is the length of the input
tomwalters@0: file in data points, and the length of a sgm output file will thus be the m
tomwalters@0: x n, which may obviously be quite large.
tomwalters@0: 
tomwalters@0: Prepended to this data is a header which contains information related to
tomwalters@0: the way in which the data was produced.  Some of this information was
tomwalters@0: supplied by the user of the genbmm program (eg samplerate, length_wave,
tomwalters@0: mincf_afb, etc) and some was derived from other sources (eg channels and
tomwalters@0: pointsperchannel, which were computed by genbmm from the mincf_afb,
tomwalters@0: maxcf_afb, dencf_afb, and length_wave options).
tomwalters@0: 
tomwalters@0: Cochleogram output structure
tomwalters@0: 
tomwalters@0: The output of gencgm is of identical structure to that of genbmm, although
tomwalters@0: of course the header will contain extra information related to how the
tomwalters@0: cochleogram was generated.
tomwalters@0: 
tomwalters@0: Stablised auditory image output structure
tomwalters@0: 
tomwalters@0: The output of gensai is a series of 'frames', one per graphical image that
tomwalters@0: is displayed by gensai and revsai.  Each of these frames has the structure
tomwalters@0: of an entire data section of a genbmm or gencgm output file.  Thus the .sai
tomwalters@0: data is structured as a series of multiplexed waveforms.  The size of a
tomwalters@0: .sai file will be m x n x f, where f is the number of frames generated by
tomwalters@0: gensai, and is thus likely to be huge.  Again, the header will have
tomwalters@0: additional information related to the generation of the stabilised auditory
tomwalters@0: image.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: 
tomwalters@0: