feasd.doc

speech signal process tools

       storage for the associated data array, the  pointer  array,  or  both.
       (See data and ptrs in the previous subsection.) The function allocates
       the data array if the argument data is (char *) NULL.  If the argument
       is  non-NULL,  it should point to the beginning of a suitable block of
       storage, and the pointer value is simply copied into the  data  member
       of  the  structure.   When the value of the argument make_ptrs is YES,
       the function creates the pointer array.  When make_ptrs is NO, ptrs is
       made NULL.  The dimensions of the array are determined by the argument
       num_records and the size of the "samples" field defined in the  header
       *hd,  which  gives  the  number  of  channels.  The data_type argument
       determines the data type of the array.  Legal values are given by  the
       ten  data-type  constants  BYTE,  SHORT, LONG, etc.  The data_type and
       num_records members of the structure are filled in with the values  of
       the corresponding function arguments.  The returned value is a pointer


       Version 1.3                      ERL                           1/22/93







       ETM-S-89-49:rwj                                                page 10


       to the structure upon  successful  completion,  or  NULL  in  case  of
       failure.   When  the data area is supplied by the programmer, its size
       should be at least num_records *  num_channels  *  typesiz(data_type),
       where    num_channels    may    be    obtained   as   the   value   of
       get_fea_siz("samples", hd,(short *) NULL,(long **) NULL).

       4 .4 .3 .  get_feasd_recs

            With a feasd structure and a FEA_SD header in  hand  and  a  file
       open  for reading, it is possible to read some data.  The FEA_SD func-
       tion  analogous  to  the  SD  support  functions  get_sd_rec{dfs}   is
       get_feasd_recs.  A call has the form

            get_feasd_recs(rec, start, num_records, hd, file)

       The function attempts to read the next num_records FEA_SD records from
       stream  file and store the contents of the "samples" fields in the the
       structure pointed to by rec, beginning with element  (or  row)  number
       start.   Usually  start  will  be 0, for the first element or row; the
       argument is provided for occasions when one might wish to start  read-
       ing  into  the  data buffer at some point after the beginning.  If any
       fields besides "samples" are present, their contents are ignored; they
       do,  however,  make  reading slower.  The sum start + num_records must
       not exceed rec->num_records.  The function returns the  actual  number
       of  records read.  In particular, it returns 0 at end of file.  If the
       type of data in the file differs from  rec->data_type,  the  data  are
       converted.   If fewer than the requested number num_records of records
       are read, the deficit is made up with zero fill.

       4 .4 .4 .  get_feasd_orecs

            To read overlapping or noncontiguous frames of sampled data,  use
       the   FEA_SD   function   analogous   to   the  SD  support  functions
       get_sd_orec{dfs}, namely get_feasd_orecs.  A call has the form

            get_feasd_orecs(rec, start, framelen, step, hd, file)

       Like get_feasd_recs, this function reads frames of sampled data from a
       FEA_SD  file.  However, while get_feasd_recs moves a full frame length
       between calls, get_feasd_orecs moves by an arbitrary step.

            A frame consists  of  the  data  from  the  "samples"  fields  of
       framelen  records of the file.  Each frame after the first begins step
       records further along in the file than the previous frame; thus frames
       overlap  when  step<framelen, are exactly abutted when step==framelen,
       and are separated by gaps when step>framelen.  Each call of the  func-
       tion  stores  a  frame  in  a buffer that consists of a segment of the
       structure pointed to by rec, beginning  with  element  or  row  number
       start   (usually   0).    The   sum  start+framelen  must  not  exceed
       rec->num_records, and any elements or rows preceding number  start  or
       following  number start+framelen-1 are left unchanged by the function.
       All data read are converted, as necessary, from the type indicated  in
       the header to the type indicated in rec->data_type.  If a read attempt


       Version 1.3                      ERL                           1/22/93







       ETM-S-89-49:rwj                                                page 11


       yields fewer records than required (end of file), the deficit is  made
       up  by zero fill.  The function returns the number of valid samples in
       the buffer.  This equals framelen when the requested number of records
       are successfully read; otherwise it is some smaller number.

            The buffer is assumed to contain data from a prior invocation  of
       get_feasd_orecs  or get_feasd_recs.  Then, if step<framelen, the func-
       tion drops the first step elements or rows of the buffer,  shifts  the
       next  step  positions  toward the beginning, and attempts to read more
       records to fill out the vacated positions at the end  of  the  buffer.
       The returned value is the number of records read plus (framelen-step).

            If step>=framelen, the function ignores the previous contents  of
       the buffer, skips step-framelen records in the file, and then attempts
       to read the next framelen records---i.e.,  after  skipping  a  gap  of
       step-framelen  records  between  frames, get_feasd_orecs operates like
       get_feasd_recs.  Note that if step==framelen, the result is  adjacent,
       non-overlapping frames such as get_feasd_recs produces.

       4 .4 .5 .  put_feasd_recs

            To write data, use the FEA_SD function analogous to the  SD  sup-
       port functions put_sd_rec{dfs}, namely put_feasd_recs.  A call has the
       form

            put_feasd_recs(rec, start, num_records, hd, file)

       The function takes data from the structure pointed to by rec, starting
       with element (or row) number start (usually 0 for the first element or
       row).  It puts the data  into  the  "samples"  fields  of  num_records
       FEA_SD  records  and  writes  the  records to the stream file.  Unlike
       get_feasd_recs and get_feasd_orecs,  this  function  will  not  handle
       records containing fields other than "samples".  Programs that need to
       write FEA_SD files with additional fields  should  use  put_fea_rec(3-
       ESPSu).   The  sum start+num_records must not exceed rec->num_records.
       If data type of the data in  the  file  differs  from  the  data  type
       rec->data_type, conversions are performed.  The file should be an open
       FEA_SD file.  The header must be written to the file before this func-
       tion is called.  The function returns 0 upon successful completion and
       a non-zero error code otherwise.

       5 .  BACKWARD COMPATIBILITY

            Two changes in ESPS library modules  other  than  FEA_SD  support
       have been made to make it easier to get existing programs working with
       FEA_SD files in addition to SD files.

       5 .1 .  Using SD Support Functions with FEA_SD Files

            One set of changes involved the SD support functions:  they  were
       extended to work with single-channel FEA_SD files as well as SD files.
       For example get_sd_recd(3-ESPS), if called with a pointer to a  FEA_SD
       header  as  its  third argument, rather than a poiner to an SD header,


       Version 1.3                      ERL                           1/22/93







       ETM-S-89-49:rwj                                                page 12


       will simply go ahead and read the data from the FEA_SD file.  It  will
       convert  the data to double and put it in the same buffer it would use
       if reading from an SD file.  (This is a one-dimensional double  array,
       not  a  feasd structure.) Much code that works with SD files will thus
       now work wihout change with FEA_SD files.

       5 .2 .  Automatic Reading of SD Files as FEA_SD Files

            The other change involved the function eopen(3-ESPSu), which will
       open  an  ESPS  file,  read  the  header, and check the type.  The new
       behavior occurs when the call has the form

            eopen(prog_name, file_name, "r", FT_FEA, FEA_SD, &hdr, &strm)

       That is, the calling program expects to read a FEA_SD file  and  wants
       eopen  to  check for file type FEA and subtype FEA_SD.  If eopen finds
       an SD file instead, it will on the spot convert the  SD  header  to  a
       FEA_SD  header and pass that out to the calling program instead of the
       SD header.  Thus the calling program is fooled  into  thinking  it  is
       reading  a  FEA_SD  file.   This  works because the format of the non-
       header part of an SD file is compatible with the FEA_SD format.   Thus
       simply  replacing the header suffices to convert an SD file to FEA_SD.
       The converted header is a new FEA_SD header that maintains ESPS record
       keeping  by containing the original SD header as a source header.  The
       conversion is done by the library function sdtofea(3-ESPSu).

       6 .  PROGRAM CONVERSION

            With the enhancements to the SD support  functions  and  eopen(3-
       ESPSu)  covered  in the previous section, very few changes are usually
       necessary  for  a  ``minimal  conversion'':   making  a  program  read
       single-channel,  real  FEA_SD  files  as  well  as  SD files and write
       single-channel FEA_SD files instead of SD files.  The strategy  is  to
       use the new eopen to open input sampled-data fies as FEA_SD files, but
       to use the existing calls on SD ``get'' and ``put'' functions, without
       change,  for  all  reading  of sampled data.  Then all statements that
       allocate buffers and access the data can be left unchanged as well.

            Near the beginning of the program put the lines

            #include <esps/fea.h>
            #include <esps/feasd.h>

       if they aren't  there  already.   You  should  retain  the  line  that
       includes  esps/sd.h as long as any SD support functions are used.  The
       line that includes esps/feasd.h is unnecessary if  (struct  feasd)  is
       not  mentioned  and no FEA_SD support functions at all are used.  This
       may be the case if the program uses sampled-data files only for input.

            Change statements such as

            filename = eopen(ProgName,  filename,  "r",  FT_SD,  NONE,  &hdr,
            &strm);


       Version 1.3                      ERL                           1/22/93







       ETM-S-89-49:rwj                                                page 13


       to

            filename = eopen(ProgName, filename, "r", FT_FEA,  FEA_SD,  &hdr,
            &strm);

       Statements that open output files probably won't have to be changed.

            Change instances of new_header(FT_SD) to new_header(FT_FEA),  and
       use init_feasd_hd(3-ESPSu) instead of set_sd_type(3-ESPSu).

            Certain header items may have to be handled differently,  notably
       the sampling frequency.  For example, to get the sampling frequency of
       an input file, you will have to change something like

            freq = hdr->hd.sd->sf;

       into something like

            freq = get_genhd_val("record_freq", hdr, 0.0);

            If the  program  uses  get_sd_recsize(3-ESPSu),  use  size_rec(3-
       ESPSu) instead.

            A program converted in this way will read  complex  sampled  data
       without  complaint, but get_sd_recd(3-ESPSu), get_sd_recf(3-ESPSu), or
       get_sd_recs(3-ESPSu) will convert the data to double, float, or short,
       and  converting  complex  data  to  a real type discards the imaginary
       part.  (See type_convert(3-ESPSu).) Depending on the  application,  it
       may or may not be useful to allow the program to read complex data and
       discard the imaginary part.  If you want to insert a check for complex
       data,   the  functions  is_file_complex(3-ESPSu),  is_field_complex(3-
       ESPSu), and is_type_complex(3-ESPSu) may be  helpful.   To  check  for
       multichannel data, remember that the number of channels is

            get_fea_siz("samples", hdr, (short) NULL, (long) NULL)

            Much more extensive changes are necessary if a program is  to  be
       not  merely  converted  from SD to FEA_SD input/output but extended to
       deal in a useful way with complex and multichannel data.   Then  there
       will  be  no  avoiding  the  need for a full-scale conversion to using
       feasd structures to hold data and replacing SD support functions  with
       corresponding  FEA_SD support functions.  A look at the source code of
       fft(1-ESPS) and fftinv(1-ESPS) may be helpful.   These  programs  have
       both been extended to deal with complex data in full generality.  They
       can serve as examples of a program that reads both  real  and  complex
       FEA_SD files and a program that writes such files.









       Version 1.3                      ERL                           1/22/93