fea.doc

speech signal process tools

       ETM-S-86-25:rap                                                page 11


            int
            get_anafea_rec(rec, hd, strm)
                struct anafea *rec;
                struct header *hd;
                FILE *strm;
            {
                if (hd->common.type != FT_FEA) error("Not a feature file");
                if (hd->hd.fea->fea_type != FEA_ANA) error("Not a FEA_ANA file");

                if (get_fea_rec(rec->fea_rec, hd, strm) == EOF) return EOF;
                return (1);
            }

       6 .  Other Parts of the Support Module

            In addition to these routines the support module  should  contain
       definitions  for  any global variables needed by the feature file sub-
       type.  The most common  examples  of  required  global  variables  are
       string  arrays  used to define possible values for coded or enumerated
       data fields in the record.  See lin_search(3-ESPS).

            For a more complete (and more complex) example of a feature  file
       subtype  support  routine  see  vqsupport.c in the ESPS library source
       directory.  The most significant difference  between  vqsupport.c  and
       the  example  here  that  one  of the items in the data structure is a
       two-dimensional array, so the data is moved between the  feature  file
       record  and the vq record.  This could have been done by setting up an
       array  of  pointers   with   the   correct   values.    The   function
       marg_index(3-ESPSu)  is intended for that purpose; see its manual page
       for an example of its use.  But  since  vq  files  do  not  have  many
       records  it  did not seem necessary at the time.   Of course, it could
       be changed without affecting existing programs.  The other  difference
       between  vqsupport.c  and this example is that it is complete and does
       compile and execute.

       7 .  Extension of Predefined Feature-File Subtypes

            Sometimes an application arises for which a  predefined  feature-
       file  subtype is suitable except that a little extra information needs
       to be recorded in each record.  Rather than define an entire new  sub-
       type that differs only slightly from the existing subtype, you can use
       the support functions for the existing subtype unchanged and just  use
       auxiliary  functions to take care of the additional fields.  If just a
       single additional field is needed, the basic  feature-file  facilities
       may be enough.

            Suppose for example that a FEA_ANA file with an additional scalar
       field  comb_cm_lag  of  type  float is called for.  (The name is taken
       from an actual application.) To create a header,  you  can  just  call
       add_fea_fld after using init_anafea_hd:

            hd = new_header(FT_FEA);
            if (init_anafea_hd(hd, maxraw, maxlpc, maxpulses, order_vcd, order_unvcd) != 0)


       Version 3.3                      ERL                           1/22/93







       ETM-S-86-25:rap                                                page 12


                    error("error filling FEA_ANA header");
            if (add_fea_fld("comb_cm_lag",
                            1L, 0, (long *) NULL, FLOAT, (char **) NULL, hd) == -1)
                    error("error adding auxiliary field");

       After creating or reading such a  header,  you  can  allocate  a  data
       record as usual:

            ana = allo_anafea_rec(hd);

       this creates space for the new field as well as the predefined fields.
       The  latter  are  accessed as usual through the pointers in the anafea
       structure:

            *ana->frame_len = some_length;

       The new field is accessed through a pointer obtained from get_fea_ptr:

            comb_cm_lag_p = (float *) get_fea_ptr(ana->fea_rec, "comb_cm_lag", hd);
                /* . . . */
            old_val = *comb_cm_lag_p;
            *comb_cm_lag_p = new_val;

       Finally, nothing new is needed for reading or writing the record:

            get_anafea_rec(ana, hd, istrm);

       will read a record, including the new field, from an input file istrm,
       and

            put_anafea_rec(ana, hd, ostrm);

       will write the record, including the new  field,  to  an  output  file
       ostrm.

            If several new fields are needed, it may be worthwhile to  define
       an  auxiliary data structure and support functions.  For example, sup-
       pose these fields are required:

                       _____________________________________
                       |___Name_____|__Size___|_Rank_|_Type_|
                       |cm_lag      | n_rows  | 1    | NULL |
                       |comb_cm_lag | 1       | 0    | NULL |
                       |posteriors  | n_vclas | 1    | NULL |
                       |____________|_________|______|______|


            A support function parallel to init_anafea_hd will take  care  of
       defining the new fields.

            #define ADDFLD(name, size, rank, dimen, type, enums) \
                    {if (add_fea_fld((name), (long)(size), (rank), (long*)(dimen), \
                            type, (char**)(enums), hd) == -1) return 1;}


       Version 3.3                      ERL                           1/22/93







       ETM-S-86-25:rap                                                page 13


            int
            init_auxana_hd(hd, n_rows, n_vclas)
                struct header *hd;  /* FEA file header */
                int n_rows;         /* number of elements of cm_lag */
                int n_vclas         /* number of elements of posteriors */
            {
                int i;

                *add_genhd_l("n_rows", (long *) NULL, 1, hd) = n_rows;
                *add_genhd_l("n_vclas", (long *) NULL, 1, hd) = n_vclas;

                ADDFLD("cm_lag", n_rows, 1, NULL, FLOAT, NULL)
                ADDFLD("comb_cm_lag", 1, 0, NULL, FLOAT, NULL)
                ADDFLD("posteriors", n_vclas, 1, NULL, FLOAT, NULL)
                return 0;
            }

       This is called along with init_anafea_hd when a new header is created:

            hd = new_header(FT_FEA);
            if (init_anafea_hd(hd, maxr, maxl, maxp, o_vcd, o_unv) != 0)
                    error("error filling FEA_ANA header");
            if (init_auxana_hd(hd, n_rows, n_vclas) != 0)
                    error("error adding auxiliary fields");

       For record access, define a pointer structure

            struct auxana
            {
                float *cm_lag;      /* vector */
                float *comb_cm_lag; /* scalar */
                float *posteriors;  /* vector */
            };

       This can be put in a private include file.  For each anafea structure,
       the program should have a corresponding auxana structure:

            struct anafea *ana;
            struct auxana *aux;

       The structure is allocated and the pointer values filled in by a  sup-
       port function parallel to allo_anafea_rec:

            #define GETPTR(member, type, field) \
                    {aux_rec->member = (type *) get_fea_ptr(fea_rec, field, hd);}

            struct auxana *
            allo_auxana_rec(hd, rec)
                struct header *hd;
                struct anafea *rec;
            {
                int i;
                struct auxana *aux_rec;


       Version 3.3                      ERL                           1/22/93







       ETM-S-86-25:rap                                                page 14


                struct fea_data *fea_rec;

                aux_rec = (struct auxana *) calloc(1, sizeof(struct auxana));
                fea_rec = rec->fea_rec;

                GETPTR(cm_lag, float, "cm_lag")
                GETPTR(comb_cm_lag, float, "comb_cm_lag")
                GETPTR(posteriors, float, "posteriors")
                return aux_rec;
            }

       This is called after each invocation of allo_anafea_rec:

            ana = allo_anafea_rec(hd);
            aux = allo_auxana_rec(hd, ana);

       Then the predefined fields are accessed as usual  through  the  anafea
       structure, as before, and the new fields are accessed through the aux-
       ana structure:

            old_val = *aux->comb_cm_lag;
            *aux->comb_cm_lag = new_val;

       8 .  Documentation for Official Feature File Subtypes

            This section describes the standard documentation format  for  an
       official  feature  file  subtype.  The feature file header has a field
       for a type code to allow for the definition of new file  types  imple-
       mented with feature files.   When this is done, the new file type must
       be documented so that other programmers can properly  design  programs
       that must use these files.

            The format of the documentation for these  files  is  nearly  the
       same  as  the  existing section 5 manual pages for files types such as
       SD.  The information that a programmer must have to use a feature file
       includes:

           file type code,
           generic header items and their meaning,
           listing of the fields in the feature file and their size information,
           the data structure of the record if one is appropriate, and
           manual pages for supporting functions as appropriate.


            In most cases when a new file type is implemented  using  feature
       files,  the  designer should provide a data structure like our FEA_ANA
       example above for other programmers to use.   This  will  go  into  an
       include  file  that  will be installed in the ESPS include-file direc-
       tory.  This header file should also include declarations for any  sup-
       port functions for the new file type.   See <esps/vq.h> for an example
       of this.




       Version 3.3                      ERL                           1/22/93







       ETM-S-86-25:rap                                                page 15


            When a feature file subtype is to be made official, the  designer
       will submit the following to the ESPS maintainer:

           section 5 manual page,
           section 3 manual pages for support functions,
           support functions as described above in a C module xxsupport.c, and
           include file <esps/xx.h> with structure declarations,

       where xx is a name for the subtype.

            The ESPS maintainer  will  assign  the  file  type  a  type  code
       (FEA_xx)  and  add  this  to  the  others  in  <esps/fea.h>.  The file
       ftypes.c in the ESPS library source directory contains the  definition
       of  an  array  fea_file_type of strings that associates each type code
       with its name; for example

            fea_file_type[FEA_ANA] == "FEA_ANA"

       The ESPS maintainer will update the definition of  fea_file_type  when
       the new type code is assigned.



































       Version 3.3                      ERL                           1/22/93