fea_vq.5t

speech signal process tools

.\" Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved
.\" @(#)fea_vq.5t	1.8 25 Sep 1997 ESI
.TH FEA_VQ 5\-ESPS 25 Sep 1997
.ds ]W "\fI\s+4\ze\h'0.05'e\s-4\v'-0.4m'\fP\(*p\v'0.4m'\ Entropic Speech, Inc.
.SH NAME
ESPS VQ Feature File Subtype \- (.vq)
.SH SYNOPSIS
.nf
.ft B
#include <esps/esps.h>
#include <esps/fea.h>
#include <esps/vq.h>
.fi
.SH DESCRIPTION
.PP
The FEA_VQ file is a subtype of the FEA file.  If \fIhd\fR is a 
pointer to the header of such a file, then \fIhd\->hd.fea\->fea_type\fR
== FEA_VQ.  Such files are created by calling 
.I init_vqfea_hd
(3\-ESPSu) after 
.I new_header
(3\-ESPSu).  
.PP
The header of a FEA_VQ file contains definitions for the record fields
as given by the following table:
.PP
.TS
center, box, tab(;);
c | c | c | c | c | c 
l | l | l | l | l | l.
Name;Size;Rank;Dimen;Type;Enums
=
conv_ratio;1;0;NULL;double;NULL
final_dist;1;0;NULL;double;NULL
train_length;1;0;NULL;long;NULL
design_size;1;0;NULL;long;NULL
current_size;1;0;NULL;long;NULL
dimen;1;0;NULL;long;NULL
num_iter;1;0;NULL;long;NULL
num_empty;1;0;NULL;long;NULL
cbk_struct;1;0;NULL;coded;\fIcbk_structs\fR
dist_type;1;0;NULL;coded;\fIdist_types\fR
cbk_type;1;0;NULL;coded;\fIvq_cbk_types\fR
codebook;row*cols;2;{\fIrow,cols\fR};float;NULL
clustersize;rows;1;NULL;long;NULL
clusterdist;rows;1;NULL;float;NULL
field_rep;16;1;NULL;char;NULL
field;16;1;NULL;char;NULL
source_name;32;1;NULL;char;NULL
signal_name;16;1;NULL;char;NULL
source_type;16;1;NULL;char;NULL
.TE
.PP
In the above table, \fIcbk_structs, dist_types,\fR and\fI
vq_cbk_types\fR are arrays of of the possible values the field can take.
These are defined in the FEA_VQ library support module.   \fIRow\fR and
\fIcols\fR are the number of rows and columns in the codebook.
See \fIFEA\fR(5\-ESPS) for additional information on the meaning of the
table columns.
.PP
.ne 10
In addition to the record field definitions, the header for a FEA_VQ
file consists of the following generic header items:
.PP
.TS
center, box, tab(;);
c | c | c
l | l | l.
Name;Size;Type
=
design_size;1;long
codeword_dimen;1;long
.TE
.PP
In most cases, programs that deal with FEA_VQ files will use the support
routines provided in the ESPS library and will not have to make direct
use of the information in the above tables.   The library routine
.I init_vqfea_hd
(3\-ESPSu) creates these fields.
.PP
Programs that deal with FEA_VQ files do so in terms of structures of
type (struct vqcbk) \- pointers to structures of this type are returned by 
.I allo_vqfea_rec
(3\-ESPSu), and the FEA_VQ read and write routines (\fIget_vqfea_rec\fR
and \fIput_vqfea_rec\fP) have parameters of type (struct vqcbk).  Here is 
the definition of the vqcbk struct (given in \fI<esps/vq.h>\fR):
.if t .bp
.PP
.TS
l1 l1 l1 l.
struct vqcbk {
  double	*conv_ratio;	/\(** fractional distortion convergence threshold \(**/
  double	*final_dist;	/\(** average distortion of current codebook \(**/
  float	**codebook;	/\(** codeword matrix; codeword[j] points to jth codeword \(**/
  float	*clusterdist;	/\(** distortion of cluster corresponding to each codeword \(**/
  long	*clustersize;	/\(** size of the cluster corresponding to each codeword \(**/
  long	*train_length;	/\(** length of training sequence used \(**/
  long	*design_size;	/\(** design goal for number of codewords \(**/
  long	*current_size;	/\(** current number of codewords in codebook \(**/
  long	*dimen;	/\(** dimension of codewords \(**/
  long	*num_iter;	/\(** total number of cluster iterations \(**/
  long	*num_empty;	/\(** total number of times empty cell found \(**/
  short	*cbk_type;	/\(** codebook type, e.g, RC_VQCBK;
		see definitions above \(**/
  short	*dist_type;	/\(** distortion type, e.g, MSE; see
		definitions above \(**/
  short	*cbk_struct;	/\(** codebook structure, e.g., FULL_SEARCH;
		see definitions above \(**/
  char	*field_rep;	/\(** spec_param value in FEA_ANA files, if
		appropriate \(**/
  char	*field;	/\(** field represented by codebook \(**/
  char	*source_name;	/\(** name of the signal source \(**/
  char	*signal_name;	/\(** type of signal \(**/
  char	*source_type;	/\(** subcategory of source \(**/
  struct fea_data	*fea_rec;	/\(** pointer to corresponding FEA record \(**/
};
.TE
.PP
For a discussion of the meaning of each of the fields in this 
structure, see the manual page for 
.I vqdesign
(3\-ESPSsp).  Note that the storage for the \fIcodebook\fP is shared 
with the underlying FEA record; thus, one cannot assign an arbitrary 
pointer to \fIcodebook\fP and expect \fIput_vqfea_rec\fP to work 
properly.  
.SH SEE ALSO
.PP
.IR init_vqfea_hd (3\-ESPSu),
.IR allo_vqfea_rec (3\-ESPSu),
.br
.IR get_vqfea_rec (3\-ESPSu),
.IR put_vqfea_rec (3\-ESPSu),
.br
.IR vqdesign (3\-ESPSsp),
.IR vqencode (3\-ESPSsp), 
.br
.IR FEA (5\-ESPS),
.IR ESPS (5\-ESPS)
.SH RECORD ELEMENT FILE STRUCTURE
.PP
In order to use this (or any other) FEA file type with a generic ESPS
program (one that operates on any file type) it is necessary to know the
way that record elements are positioned in the file.   For a FEA file
that information is obtained by running the program
\fIfea_element\fR(1\-ESPS) on the file in question.
.SH AUTHOR
Manual page by John Shore and Alan Parker