getderivve.3

speech signal process tools

.\" Copyright (c) 1987-1990 Entropic Speech, Inc.
.\" Copyright (c) 1997 Entropic Research Laboratory, Inc. All rights reserved.
.\" @(#)getderivve.3	1.5 18 Apr 1997 ESI/ERL
.ds ]W (c) 1997 Entropic Research Laboratory, Inc.
.TH GET_DERIV_VEC 3\-ESPSu 18 Apr 1997
.SH NAME
get_deriv_vec \- derive a vector from elements in an ESPS FEA file
.SH SYNOPSIS
.ft B
.nf
#include <esps/esps.h>
#include <esps/fea.h>

char *
get_deriv_vec (fields, fea_rec, hd, type, length, vec)
char **fields;
struct fea_data *fea_rec;
struct header   *hd;
int type;
long *length;
char *vec;
.fi
.ft
.SH DESCRIPTION
.I get_deriv_vec
returns a pointer to a vector \fIvec\fP 
containing values from fields \fIfields\fR in an
ESPS Feature 
record \fIfea_rec\fP.
The ESPS header \fIhd\fR is the header associated with the record
\fIfea_rec\fR.
If \fIvec\fP is NULL, then memory
is allocated for the vector, otherwise \fIvec\fP is taken as a pointer
to the data area for storage.
The length of the returned vector is returned via \fIlength\fP.
.PP
\fIFields\fP is a null terminated array consisting of strings of the following
form:
.nf

	\fIfield_name\fP[\fIgeneric_range\fP]

.fi
Each \fIfield_name\fP is the name of a feature field
and each \fIgeneric_range\fP is a range specification in a form suitable for
\fIgrange_switch\fP(3\-ESPSu).  
For each string of the above form,
data from \fIfea_rec\fP
is taken from the field, \fIfield_name\fP, at the element
locations given by \fIgeneric_range\fP, and placed
into a contiguous array, \fIvec\fP.  Data is appended to the end of
\fIvec\fP until a NULL is encountered in \fIfields\fP.
.PP
If \fIfield_name\fP is not defined or the generic range does not exist
in the header pointed to by \fIhd\fP, then the program prints a
message on stderr and exits with status code 1.  A pointer to the data
is returned otherwise, and on return, the pointer must be coerced to
type \fItype\fP.
.PP
Note that fields of type CODED are stored in records as SHORTs (length 1).
To obtain the corresponding ASCII string, use
\fIfea_decode\fP(3\-\s-1ESPS\s+1).
Note also that complex types are not handled by 
\fIget_deriv_vec\fP.  
.SH EXAMPLE
.if n .ta 33
.if t .ta 3i
.nf
#include <esps/esps.h>
#include <esps/fea.h>

FILE *file;
struct fea_data *fea_rec;
struct header *ih;
char **srcfields = { "raw_power[0]", "spec_power[1,3:5]", NULL };
float *vec;

ih = read_header(file);
fea_rec = allo_fea_rec (ih);
get_fea_rec (fea_rec, ih, file);
type = FLOAT;
vec = NULL;	/* allocate memory for data */

vec = (float *) get_deriv_vec(srcfields, fea_rec, ih, type, (char *) NULL)

/*
 On return:
   vec[0] = raw_power[0]
   vec[1] = spec_power[1]
   vec[2] = spec_power[3]
   vec[3] = spec_power[4]
   vec[4] = spec_power[5]
*/
.fi
.SH DIAGNOSTICS
get_deriv_vec: range of field name %s is 0:%d, requesting element %d.
.br
get_deriv_vec: field name %s not found in ESPS Feature file.
.SH BUGS
Complex types are not handled yet.
.SH SEE ALSO
.PP
.nf
\fIclassify\fP(1\-ESPS), \fIfea_deriv\fP(1\-ESPS), \fIget_fea_deriv\fP(3\-ESPSu),
\fIcover_type\fP(3\-ESPSu), \fIset_fea_deriv\fP(3\-ESPSu), \fIfea_decode\fP(3\-\s-1ESPS\s+1),
\fIESPS\fP(5\-ESPS), \fIFEA\fP(5\-ESPS)
.fi
.SH AUTHOR
Manual page and program by Ajaipal S. Virdy