feasd.doc

speech signal process tools

       file  (Subsection 4.1) and the external format of its records (Subsec-
       tion 4.2).  It also describes the support data structure that has been
       defined  for  holding  sampled data in memory (Subsection 4.3) and the
       support functions that are provided  for  working  with  FEA_SD  files
       using  this  structure.   These  include  functions for initializing a
       FEA_SD file header, allocating an instance of the  support  structure,
       reading  data  from a FEA_SD file into the structure, and writing data
       from the structure to a FEA_SD file.

            The support structure permits data to  be  read  and  written  in
       blocks,  rather than one sample at a time, provided certain conditions
       are met---file, and the byte order of the data on  the  external  file
       must match the native byte order of the machine.  There are provisions
       for automatic data-type conversion on input or  output,  but  programs
       that  do  not  actually  cause conversions to be done do not incur the
       overhead.

            Much of the information in this section  is  extracted  from  the
       FEA_SD(5-ESPS)   manual  section  or  (in  Subsection  4.4)  from  the
       feasd_recs(3-ESPSu) manual section.  See  the  manual  sections  them-
       selves for complete details.

       4 .1 .  Header

            The SD manual section defines a  type-specific  header  structure
       with  over 20 items, many of which are relevant to only a few special-
       ized programs.  They are present because the SD file type was designed
       before generic header items (see add_genhd(3-ESPS), get_genhd(3-ESPS))
       were introduced in ESPS.  In current ESPS, the preferred way  of  han-
       dling such specialized information is with generic header items, which
       programs that need them may use and other programs  may  ignore.   The
       FEA_SD specification calls for only two mandatory header items and one
       predefined optional item.

            The header of a FEA_SD file may  contain  the  following  generic
       header items.  The first two are always present.  The remaining one is
       not present in every file, but if present has the meaning given below.


       Version 1.3                      ERL                           1/22/93







       ETM-S-89-49:rwj                                                 page 6


                    ____________________________________________
                    |___Name_____|____Size_____|__Type__|_Enums_|
                    |start_time  | 1 or no. of | double | NULL  |
                    |            |   channels  |        |       |
                    |record_freq | 1           | double | NULL  |
                    |____________|_____________|________|_______|
                    |max_value   | 1 or no. of | double | NULL  |
                    |____________|___channels__|________|_______|


            The items have the following meanings.

       start_time
            Time corresponding to the first record  in  the  file---given  in
            seconds.   If  start_time has more than one element, each applies
            to  a  separate  channel.   Separate  starting  times  might   be
            appropriate  if,  for  example, samples from the various channels
            were recorded in rotation, rather than simultaneously.

       record_freq
            The sampling frequency in Hz.

       max_value
            This item is optional.  If it is present, no  sample  may  exceed
            this value in magnitude.  It is permissible for all samples to be
            smaller---that is, max_value is an upper  bound  rather  than  an
            exact  maximum.   For  example,  if the data are from an A/D con-
            verter, max_value may be used to indicate the maximum value  that
            can  be  represented  by  the  converter.  In multichannel files,
            max_value may have one component for each channel  or  may  be  a
            single value applying to all channels.

       The header of a FEA_SD file also contains a definition for  one  field
       given by the following table:

       _________________________________________________________________________
       |_Name___|______Size_______|_Rank_|_____Dimen______|____Type_____|_Enums_|
       |samples | no. of channels |  1   | NULL or {size} | any numeric | NULL  |
       |________|_________________|______|________________|_____________|_______|


       The field can be created by calling init_feasd_hd(3-ESPSu).

       4 .2 .  External Record Format

            When the size of the field "samples" is  1,  there  is  a  single
       channel;  if no additional fields are present, each record is a single
       sample of the given type, and the part of the file after the header is
       just  a sequence of such samples.  That is, the non-header part of the
       file is identical to that of an SD file of the same data type and con-
       taining the same data.  When the size is greater than 1, the file con-
       tains multi-channel data.  The data portion of the file is still  just
       a sequence of samples when no additional fields are present.  However,


       Version 1.3                      ERL                           1/22/93







       ETM-S-89-49:rwj                                                 page 7


       the samples are conceptually grouped into vectors, each containing one
       sample  from  each  channel.  In general, each record in the file con-
       tains such a vector.

            Each complex item is represented externally by a consecutive pair
       of real items with the real part first.

       4 .3 .  Internal Record Format---The Support Structure

            Most programs that deal with FEA_SD files will  use  the  support
       routines in the ESPS library and will not directly use the information
       in the tables above.  (These routines are discussed in the  next  sub-
       section.)   For  example  programs  will  usually define the "samples"
       field  in  a   file   header   by   calling   the   support   function
       init_feasd_hd(3-ESPSu)  rather  than by calling add_fea_field(3-ESPSu)
       directly.

            Programs that deal with FEA_SD files do so in terms of  C  struc-
       tures  of  a particular type (struct feasd).  A structure of this type
       contains the location of a data array together with other  information
       that  provides  convenient access to the data or is used by the FEA_SD
       support  functions.   For  example  the  read  and  write   functions,
       get_feasd_recs(3-ESPSu),         get_feasd_orecs(3-ESPSu),         and
       put_feasd_recs(3-ESPSu), take pointers to such structures  as  parame-
       ters and either read data into the associated data array or write data
       from it.

            Here is the  definition  of  the  feasd  structure  as  given  in
       <esps/feasd.h>:

           struct feasd {
            short       data_type;
            long        num_records, num_channels;
            char        *data, *ptrs;
           };

       The structure members have the following meanings.

       data_type
            An integer code indicating the data type of the samples as stored
            in  memory.  Legal values are give by the ten type-code constants
            DOUBLE, FLOAT, etc. shown in the table in Subsection  2.2.   They
            are  defined in the include file esps/esps.h.  This type need not
            match the data type of a FEA_SD file used for input or output; if
            the  types  are  different, automatic type conversion takes place
            upon input or output.

       num_records
            The number of consecutive records that may be stored in the  data
            part of this feasd structure (see below).

       num_channels
            The number of channels of sampled data.


       Version 1.3                      ERL                           1/22/93







       ETM-S-89-49:rwj                                                 page 8


       data A pointer to the beginning of a data array for storing  the  sam-
            pled  data  from  num_records  elements  of the type indicated by
            data_type.  For single-channel data, the pointer data can  simply
            be  cast  to  an appropriate type and regarded as pointing to the
            beginning of a one-dimensional array of samples.  The appropriate
            types  are  (char  *)  for  BYTE  data, (short *) for SHORT data,
            (double_cplx *) for DOUBLE_CPLX data,  etc.   For  example,  with
            declarations

            struct feasd     *rec;
            short     *s_data;

            suppose rec points to a feasd structure initialized to hold SHORT
            data.  (So rec->data_type==SHORT.) Then, after the assignment

            s_data = (short *) rec->data;

            sample number s may be accessed as s_data[s].  For  multi-channel
            files,  the  storage  is  conceptually a 2-dimensional array with
            num_records rows and as many columns as there are  channels.   It
            is  the  purpose of the structure member ptrs, discussed next, to
            make access to the data as convenient as indexing an actual  two-
            dimensional array.

       ptrs When appropriately cast, ptrs, if not NULL, points to  the  first
            element of an array of num_records pointers, each of which points
            to the first element of a row of  the  data  array.   Appropriate
            types  for  the  cast are (char **) for BYTE data, (short **) for
            SHORT data, etc.  To continue the example begun above under data,
            suppose a declaration

            short     **s_ptr;

            and a cast

            s_ptr = (short **) rec->ptrs;

            then sample number s of channel c can be accessed as s_ptr[s][c].
            The function allo_feasd_recs(3-ESPSu), which creates feasd struc-
            tures, has a parameter that determines  whether  to  set  up  the
            pointer array or to make the ptrs structure member NULL.

       4 .4 .  FEA_SD Support Functions

            There are five FEA_SD support functions:

            init_feasd_hd    --- initialize a FEA file header for subtype FEA_SD
            allo_feasd_recs  --- allocate memory for FEA_SD file records
            get_feasd_recs   --- get data records from an ESPS FEA_SD data file
            get_feasd_orecs  --- get overlapping data from an ESPS FEA_SD data file
            put_feasd_recs   --- write data records to an ESPS FEA_SD file




       Version 1.3                      ERL                           1/22/93







       ETM-S-89-49:rwj                                                 page 9


       See the feasd_recs(3-ESPSu) manual entry for full documentation.

       4 .4 .1 .  init_feasd_hd

            Before a newly created FEA file header (i.e.  one  obtained  from
       new_header(3-ESPSu))  can  be used as a FEA_SD header, it must be ini-
       tialized, preferably by init_feasd_hd.  A call of  this  function  has
       the form

            init_feasd_hd(hd, data_type, num_channels, start_time, mult_st_t,
            record_freq)

       The function takes a pointer hd to an ESPS FEA  header  and  sets  the
       item hd->hd.fea->fea_type in the FEA-specific part of the header equal
       to FEA_SD.  (This is an integer  code,  defined  in  esps/fea.h,  that
       identifies  the file as a FEA_SD file).  The function also initializes
       the header to define the  field  "samples".   The  argument  data_type
       determines  the  data type of the field; legal values are given by the
       ten data-type constants BYTE, SHORT, LONG, etc.  The integer  argument
       num_channels  gives  the  size of the field.  The arguments start_time
       and record_freq initialize the required generic header items (see Sub-
       section  4.1).   The  argument  mult_st_t is a flag indicating whether
       there is a starting time for each channel or just one for  the  entire
       file.   If  the value is YES, start_time points to the beginning of an
       array containing the values.  If the value  is  NO,  start_time  is  a
       pointer  to  a  single  element.   By  contrast, record_freq holds the
       actual value, not a pointer to it.  The function  returns  a  value  0
       upon successful completion and a nonzero error code otherwise.

       4 .4 .2 .  allo_feasd_recs

            Before a FEA_SD file can be read or written by the support  func-
       tions,  a  feasd structure must be created.  This is done by the func-
       tion allo_feasd_recs.  A call has the form

            allo_feasd_recs(hd, data_type, num_records, data, make_ptrs)

            The function allocates memory for a feasd structure and fills  in
       values for the structure members.  If requested, it will also allocate