fea.5t

speech signal process tools

When available, this will occupy
.\" This occupies
the same space in memory as BYTE or CHAR but
will be
.\" is
packed into single bits in the external file.
Type codes SHORT and CODED stand for types of the same size,
but SHORT is used for arithmetic (signed integer) data,
while CODED data consists of arbitrary codes that each designate
one of a set of strings defined in the header.
(See
.I enums
below).
.IP enums
This item points to the beginning of an array of pointers.
Each of these pointers is NULL unless the corresponding type
is CODED, and then it indicates the possible values for each item of the
corresponding field.
More specifically, the pointer, if not NULL, 
points to the beginning of a null-terminated array
of strings suitable as an argument of the function
.IR lin_search2 (3\-ESPSu);
these strings are the possible values.
Functions are available to find the code corresponding to a given string
and vice versa; see
.IR fea_encode (3\-ESPSu),
.IR fea_decode (3\-ESPSu).
.IP starts
This points to the beginning of an array of longs.  Each element gives
the starting point of the data for the corresponding field relative to
the pointer of the correct type in the data record.
(Type CODED is treated as a SHORT).
.IP derived
This points to the beginning of an array of shorts, one for each field.  
A non-zero value means that the corresponding field was "derived" from 
another FEA file.  That is, each element in the field corresponds to 
some particular element in another FEA file with a different field structure
(see \fIsrcfields\fP).
.IP srcfields
This item points to the beginning of an array of character pointers.  Each of 
these pointers is NULL unless the corresponding field is derived 
(see \fIderived\fP), in which case it points the beginning of a
null-terminated array of strings.  Each string has the form
.nf

    <fieldname> [ <element_range> ]

.fi
where <fieldname> is a field name (usually not a field in the 
current FEA file), and where <element_range> is a list of 
elements in a form suitable for the function \fIgrange_switch\fP (3\-ESPS).  
The total number of elements described in this way 
must equal the size of the corresponding field.  For example, suppose 
that a FEA file contains a derived field named 
.I svector
of size 5.  The contents of the corresponding array of strings in 
.I srcfields 
might be as follows: "raw_power[0]", "spec_param[1,3:5]".  This is 
interpreted to mean that the five elements of 
.I svector
were derived from elements in the 
.I raw_power
and
.I spec_param
fields of some other FEA file \- in particular, the 5 elements of 
.I svector
correspond to \fIraw_power\fP[0], \fIspec_param\fP[1],
\fIspec_param\fP[3], \fIspec_param\fP[4], and \fIspec_param\fP[5]
(see 
.I set_fea_deriv
(3\-ESPSu)).  
.IP spares
There are FEA_SPARES spare shorts.
.IP "ndouble, ndcplx, .\ .\ .\ , nbcplx"
These give the total number of scalar items of each of the types
DOUBLE, DOUBLE_CPLX, .\ .\ .\ , BYTE_CPLX
in a record.
The total for type CODED is included in
.I nshort
along with the total for SHORT,
and the totals for types BIT and CHAR are included in
.I nbyte
along with the total for BYTE.
Some of these items have the same names as items in the common part of the
header, but their values may be different.
For example
.I ndouble
in the common part of the header includes a count of 2 doubles for every
double_cplx item in a FEA record and so is equal to
.IR ndouble "+ 2*" ndcplx
in terms of these members of the FEA-specific part of the header.
.PP
The data follows the header.
The default data format in the file is that suggested by the following
pseudo-C structure declaration.
.PP
.nf
struct fea_data {
.TS
l1 l1 l1 l.
    long	tag;	/\(** position tag \(**/ 
    double	d_data[ndouble]; 	/\(** double data \(**/
    float	f_data[nfloat]; 	/\(** float data \(**/
    long	l_data[nlong]; 	/\(** long data \(**/
    short	s_data[nshort]; 	/\(** short and coded data \(**/
    char	b_data[char]; 	/\(** byte, char, and bit data \(**/
.TE
};
.fi
.PP
The variables
.I ndouble, nfloat, nlong, nshort,
and
.I nchar
here refer to the items in the common part of the header.
They cannot actually occur in a C declaration,
but are used by the FEA support routines.
An alternative external format is used if the item
.I field_order
has the value YES\*-see
.I field_order
above.
.PP
In memory, the data is held in a structure like the one below,
which is defined in
.I <esps/fea.h>.
The variables
.I ndouble, .\ .\ .\ , nbyte, .\ .\ .\ , nbcplx
here refer to the items in the FEA-specific part of the header.
Again, these items do not actually occur in a C declaration;
however, a function is available to allocate memory for this data structure,
based on the values in a particular header.
See 
.IR allo_fea_rec (3\-ESPSu).
.PP
.nf
struct fea_data {
.TS
l1 l1 l1 l.
    long	tag;	/\(** position tag \(**/ 
    double	d_data[ndouble]; 	/\(** double record items \(**/
    float	f_data[nfloat]; 	/\(** float record items \(**/
    long	l_data[nlong]; 	/\(** long record items \(**/
    short	s_data[nshort]; 	/\(** short and coded record items \(**/
    char	b_data[nbyte]; 	/\(** byte, char, and bit record items \(**/
    double_cplx	dc_data[ndcplx];	/\(** double complex record items \(**/
    float_cplx	fc_data[nfcplx];	/\(** float complex record items \(**/
    long_cplx	lc_data[nlcplx];	/\(** long complex record items \(**/
    short_cplx	sc_data[nscplx];	/\(** short complex record items \(**/
    byte_cplx	bc_data[nbcplx];	/\(** byte complex record items \(**/
.TE
};
.fi
.PP
A feature file may have a position tag in each record.  
This tag refers to records in the file named in the header field
\fIcommon.refer\fR.
In addition there
is space for 
.I ndcplx
pairs of doubles,
.I ndouble
doubles, 
.I nfcplx
pairs of floats,
.I nfloat
floats, 
.I nlcplx
pairs of longs,
.I nlong
longs, 
.I nscplx
pairs of shorts,
.I nshort
shorts,
.I nbcplx
pairs of bytes, and
.I nbyte
bytes,
(where these are values from the FEA-specific part of the ESPS file header).
.PP
Space in
.I d_data
for fields of type DOUBLE is allocated in the order of occurrence of the
fields' names in
.I names.
Space in the other data arrays in a record is allocated similarly.
However, programs generally need not and should not depend on this
information about record format.  Functions are available to get a
pointer to the beginning of the storage in a given record for the field
with a given name; see
.IR get_fea_ptr (3\-ESPSu).
.SH EXAMPLES
.PP
Assume declarations
.PP
.nf
.TS
l1 l1 l.
    struct header	*hd;
    struct fea_data	*rec;
    int	siz, rnk, *dim;
    double	*pd;
    short	*pe;
.TE
.fi
.PP
Suppose
.I hd
and
.I rec
have properly initialized, for example by
.IR new_header (3\-ESPSu)
or
.IR read_header (3\-ESPSu)
and by
.IR allo_fea_rec (3\-ESPSu).
Then the statement
.IP
pd = (double *)get_fea_ptr(rec, "energy", hd);
.PP
will assign to
.I pd
a pointer to the first double in the storage in
.I rec
for the field named "energy", provided that the field exists.
Now a statement like
.IP
*pd = 3.7
.PP
will store a value into the field in
.I rec.
If the field has several elements, a subscripted variable like
.I pd[3]
can be used instead of
.I *pd.
If
.I rec
already contains data, for example as a result of calling
.IR get_fea_rec (3\-ESPSu),
the data can be accessed by using
.I *pd
or a subscripted
.I pd
in an expression.  The statement
.IP
pe = (short *)get_fea_ptr(rec, "voicing", hd);
.PP
will assign to
.I pe
a pointer to a short integer in the storage in
.I rec
that holds a code for a value in the field named "voicing".
A statement like
.IP
*pe = fea_encode("voiced", "voicing", hd);
.PP
will assign the code for the string "voiced" to the short integer,
and the expression
.IP
fea_decode(*pe, "voicing", hd);
.PP
will get the string value corresponding to the code that is there.
.SH SEE ALSO
.nf
\fIallo_fea_rec\fR(3\-ESPSu), \fIget_fea_rec\fR(3\-ESPSu), \fIput_fea_rec\fR(3\-ESPSu),
\fIadd_fea_fld\fR(3\-ESPSu), \fIset_fea_deriv\fR(3\-ESPSu), \fIget_fea_deriv\fR(3\-ESPSu),
\fIset_seg_lab\fR(3\-ESPSu), \fIget_fea_ptr\fR(3\-ESPSu), \fIfea_encode\fR(3\-ESPSu), 
\fIfea_decode\fR(3\-ESPSu), \fInew_header\fR(3\-ESPSu), \fIread_header\fR(3\-ESPSu), 
\fIwrite_header\fR(3\-ESPSu), \fIlin_search\fR(3\-ESPSu), ESPS(5\-ESPS)
.fi
.SH FUTURE CHANGES
Make BIT type available.
Support for packed bit fields in memory.
Define additional values for the
.I type
field in the header.
.SH AUTHOR
Manual page by Rodney Johnson.
Incorporates suggestions by Joe Buck, Alan Parker, and John Shore.
Implementation by Alan Parker.