fea.doc

speech signal process tools

                         ENTROPIC RESEARCH LABORATORY, INC.


       TECHNICAL MEMORANDUM

       SUBJECT: Guidelines for Implementing ESPS Feature File Subtypes

       ID: ETM-S-86-25:rap

       VERSION: 3.3

       DATE: 1/22/93

       AUTHOR: Alan Parker

       LAST REVISED BY: Rodney Johnson

       REFERENCES:

        [1] ESPS User's Manual

        [2] J. Shore and R. Parker, Introduction to the Entropic Signal  Pro-
            cessing System (ESPS)

        [3] ETM-S-86-13:rap/jtb, Data Files in the Entropic Signal Processing
            System (ESPS)

        [4] ETM-S-86-14, Entropic Signal Processing System Programming Guide-
            lines

       1 .  Introduction

            This document describes how to use the  ESPS  Feature  file  type
       (fea(5-ESPS)). ESPS feature files allow the user  to  create  an  ESPS
       data  file  with named fields of different data types and sizes.  They
       can be used to define  a  new  public  ESPS  file  type  (known  as  a
       feature-file  subtype)  or  to  implement  a private file type for the
       user's own work.  The private file type may be a completely  new  type
       or  an  extension  of an existing type.  When used in conjunction with
       the generic header feature (see add_genhd(3-ESPS)), FEA files  provide
       a very general way for the user to create ESPS data files.

            The general model for using feature files depends on whether  the
       file  is  being used for input or output, but in either case a program
       must obtain a file header before doing anything else with a file.  Not
       only  is the header the first piece of information to be read or writ-
       ten, it must be referred to by the routines that  allocate  space  for
       data  records  and  read, access, and write them.  The common part and
       ____________________
          c                                                                 c
            Copyright 1987-90 Entropic Speech, Inc.; All rights  reserved.
       Copyright 1990-93 Entropic Research Lab, Inc.; All rights reserved.











       ETM-S-86-25:rap                                                 page 2


       the variable part of the header in a feature  file  contain  the  same
       information,  including  generic  header items, as in other ESPS files
       (see ESPS(5-ESPS)).  The type-specific part of the header contains the
       definition  of  each data field, including its name, size, dimensions,
       and location within the record (see FEA(5-ESPS)).

            When an output feature file is created,  a  new  header  must  be
       built unless a copy of an existing header can be suitably modified.  A
       new feature-file header is created  with  new_header;  then  the  data
       fields  are  defined  with  add_fea_fld,  and generic header items are
       created with the functions add_genhd_*(3-ESPS).  Details are given  in
       Section  3.   After  all the header information is fixed in place, the
       header is written out, as with any other kind of ESPS file.  After the
       header  has been written to the file, the program can allocate storage
       for a data record and start filling in data and writing  out  records.
       Methods for dealing with the data are discussed in Sections 4 and 5.

            For input feature files, life is simpler since  the  fields  have
       already  been  defined (when the file was created).  After reading the
       header, the program can allocate storage for a data record  and  start
       reading  in  records  and  accessing the data in them.  The programmer
       will usually know what the fields are and their types.  The  sizes  of
       the  fields might be known by definition or through header items.  But
       in all cases this information is  in  the  FEA  header  and  available
       through access functions (see get_fea_siz(3-ESPS)).

            If the feature file is a predefined public subtype (public in the
       sense  that a file type like SD is public), then documentation of that
       subtype will list the fields and give their type and size information.
       Usually a support module will be provided:  a data structure and func-
       tions for dealing with the subtype more conveniently than through  the
       basic  feature-file  facilities.   The  functions support initializing
       headers, allocating record storage, and reading and  writing  records.
       The  use  of a typical set of such support functions is illustrated in
       Section 2.

            Sections 3 through 6 show how the functions of a  support  module
       are  implemented  in terms of the basic feature-file facilities.  Sec-
       tion 7 shows how a predefined subtype can be extended with  additional
       fields  to  meet special needs.  Section 8 describes the documentation
       and other material that should be provided  when  a  new  feature-file
       subtype is installed for general use.

       2 .  Example - Use of a Subtype Support Module

            This document uses as  an  example  a  simplified  version  of  a
       feature-file  subtype  FEA_ANA that was created to hold the results of
       analysis of speech data.  The subtype is defined to be tagged  and  to
       have  four vector fields and a scalar field as listed in the following
       table:

          ________________________________________________________________
              Name                  Size                  Rank      Type
          ________________________________________________________________
           raw_power     maxraw                        1 (vector)   float
           lpc_power     maxlpc                        1 (vector)   float
           p_pulse_len   maxpulses                     1 (vector)   float
           ref_coeff     MAX(order_vcd, order_unvcd)   1 (vector)   float
          _frame_len_____1_____________________________0_(scalar)___long__




       ETM-S-86-25:rap                                                 page 3



          |            |                             |            |       |
          |            |                             |            |       |
       The|variables in|the Size column refer to the |ollowing gen|ric hea|er
       ite|s, which are|also part of the FEA_ANA defi|ition.      |       |
          |            |                             |            |       |
          |            |    _________________________|_           |       |
          |            |    |___Name_____|_Size_|_Typ|_|          |       |
          |            |    |maxraw      | 1    | lon| |          |       |
          |            |    |maxlpc      | 1    | lon| |          |       |
          |            |    |maxpulses   | 1    | lon| |          |       |
          |            |    |order_vcd   | 1    | lon| |          |       |
          |            |    |order_unvcd | 1    | lon| |          |       |
          |            |    |____________|______|____|_|          |       |
          |            |                             |            |       |
       (If|you consult |he FEA_ANA(5-ESPS) manual pag| you  will  |ind  ot|er
       fie|ds  and head|r items listed, but these are|enough for a| illust|a-
       tio|.)          |                             |            |       |
          |            |                             |            |       |
          | To use the |EA_ANA file subtype, we have |o create a h|ader  w|th
       the| field  defi|itions  if  it is a new file.| The basic E|PS util|ty
       fun|tion  new_he|der   will   create   the   h|ader.    The|  funct|on
       ini|_anafea_hd  |rom the FEA_ANA support modul| will add th| necess|ry
       fie|d definition| and generic header items.  T|is  function| takes |as
       arg|ments  the  |alues  that determine the rec|rd size.  Th| follow|ng
       wil| do the job:|                             |            |       |
          |            |                             |            |       |
          | hd = new_he|der(FT_FEA);                 |            |       |
          | init_anafea|hd(hd, maxraw, maxlpc, maxpul|es, order_vc|, order|unvcd);
          |            |                             |            |       |
       The|functions ne|_header and init_anafea_hd re|lly  may  re|urn  er|or
       cod|s,  but  I'm| ignoring  that  here.   Othe| header init|alizati|ns
       sho|ld also be d|ne, such as filling in  the  |omment  fiel|  and  |he
       sou|ce  files,  |ut  these  are not shown, as |hey are not |eculiar|to
       fea|ure files.  |ow assuming that the header i| complete, w| write |it
       out|            |                             |            |       |
          |            |                             |            |       |
          | write_heade|(hd, file);                  |            |       |
          |            |                             |            |       |
       jus| as with any|other ESPS file.             |            |       |
          |            |                             |            |       |
          | One simple |ay  to  use  feature-file  da|a  records  |s  to  |et
       poi|ters to the |ata and then move data betwee| variables i| your p|o-
       gra| and the fea|ure file record.  But with  t|e  pointers |it's  e|en
       eas|er  to  use |the  memory in the feature-fi|e record ins|ead of |he
       pro|ram variable|.  This is one reason  C  has| pointers.  |It's  c|n-
       ven|ent to defin| a data structure to hold all|the pointers|       |
          |            |                             |            |       |
          | struct anaf|a                            |            |       |
          | {          |                             |            |       |
          |     long *t|g;                           |            |       |
          |     float *|aw_power;                    |            |       |
                float *lpc_power;


       Version 3.3                      ERL                           1/22/93







       ETM-S-86-25:rap                                                 page 4


                float *p_pulse_len;
                float *ref_coeff;
                long *frame_len;
                struct fea_data *fea_rec;
            }

       For a public feature subtype, a structure  declaration  like  this  is
       provided  as  part  of  the support module and included in the program
       with a line like

            #include <esps/anafea.h>

       near the beginning.  Besides pointers for the tag and the  5  feature-
       file  fields,  we  have a pointer fea_rec to a fea_data structure con-
       taining the data values.  This is used by functions get_anafea_rec and
       put_anafea_rec that are introduced further down.

            Now an anafea structure must be allocated.   The  support  module
       contains  a  function  allo_anafea_rec  for  that purpose.  Assuming a
       declaration

            struct anafea *ana;

       the statement

            ana = allo_anafea_rec(hd);

       will allocate the anafea  structure  and  the  fea_data  structure  it
       refers to and assign the proper pointer values.

            Now, let's use the data.  Note that you have two ways for knowing
       the  size  of an array, such as lpc_power.  One way is to know that it
       is maxlpc from the header.  In case you don't know that, or the  rules
       change, you can get the size of a feature file field with get_fea_siz.
       Assignments as in

            for (i=0; i<maxlpc; i++)
                ana->lpc_power[i] = some_expression;

       will store values in the pool of memory set up by the  allo_anafea_rec
       call.  The stored values can be used in expressions as in

            something = ana->lpc_power[some_index] + something_else;

       Of course, you could be a real C programmer and avoid the use of array
       subscripts entirely and just increment the pointer value.

            As for the scalars (tag and frame_len) you just have to  remember
       that they are pointers.  So to set the frame_len value do

            *ana->frame_len = xx;




       Version 3.3                      ERL                           1/22/93







       ETM-S-86-25:rap                                                 page 5


       You can use *ana->frame_len in any expression as often as you  please.
       No  need  to assign it to another variable.  You can access the tag by
       *ana->tag.

            Once values have been assigned to all the fields in  the  record,
       copy the data in the allocated storage to the file by doing

            put_anafea_rec(ana, hd, file);

       Then you are ready to assign new values to the fields, output  another
       record with put_anafea_rec, and so on as often as you like.  After the
       initial call, you never call allo_anafea_rec again.

            The functions new_header and  init_anafea_hd  are  not  used  for
       input  files.   If  you are reading a FEA_ANA file instead of creating
       one, get the header with

            hd = read_header(file);

       or use eopen(3-ESPSu).  With the header in  hand,  allocate  a  record
       structure just as above:

            ana = allo_anafea_rec(hd);

       Before you can use the data (for an input file) it must be  read  from
       the file:

            get_anafea_rec(rec, hd);

       This reads a record from  a  file  into  the  memory  set  up  by  the
       allo_anafea_rec  call.   Now  you  can access the data by referring to
       ana->lpc_power[i], *ana->frame_len, and the other fields.  After  pro-
       cessing  one  record,  you  can use get_anafea_rec to read another and
       repeat.  Since get_anafea_rec returns EOF on end of file (and a  posi-
       tive integer otherwise), it is possible to use a loop of the form

            while (get_anafea_rec(ana, hd, file) != EOF)
            {
                /* Process one record. */
            }

       to process an entire file.

       3 .  Creating Headers

            To use the FEA_ANA file subtype, we have to create a header  with
       the  field  definitions  if  it is a new file.  Here is how to do this
       with the basic feature-file facilities.  Use

            hd = new_header(FT_FEA);

       to create the header.  Then do



       Version 3.3                      ERL                           1/22/93