vqdes.diff

speech signal process tools

.\" @(#)vqdes.1	3.8 4/7/97 ESI
.\" Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved
.TH VQDES 1\-ESPS 4/7/97
.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"
vqdes - design a vector quantization codebook from a FEA file
.SH "SYNOPSIS"
.B vqdes
[
.BI \-x " debug_level"
] [
.BI \-P " param_file"
] [
.BI \-h " histfile"
] [
.BI \-k " checkfile"
] [
.BI \-i 
] 
.I "input.fea output.fea"
.SH "DESCRIPTION"
.PP
.I Vqdes
takes as input a file
.I input.fea 
and obtains a training sequence of feature vectors, each consisting 
of a contiguous subset of elements from a FEA file field of type FLOAT
(use \fIfeafunc\fP(1\-\s-1ESPS\s+1) to transform types).  
.I Vqdes
designs a vector quantization codebook from the input training sequence
with codebook characteristics determined from information in the ESPS
parameter file (see ESPS PARAMETERS).  
.PP
If the \fB\-i\fR option is given, an initial codebook is read 
from a file determined by information in the ESPS parameter file.  
.PP
The final 
codebook and all converged codebooks of intermediate sizes 
are output as records in an ESPS FEA_VQ file 
.I output.fea.  
If "\-" is supplied in place of 
.I output.fea, 
then standard output is used.  
.PP
After every pass through the training sequence, the centroid-adjusted
codebook is output to a checkpoint file.  Only a single record is kept
in the checkpoint file (it is over-written each time).  
.PP
If the total memory required to store the feature vectors from 
.I input.fea 
is less than an internal limit of 
.I vqdes,
the codebook design algorithm will run in memory.  Otherwise, 
.I vqdes
will obtain pieces from 
.I input.fea
as necessary.  
.PP
For a detailed description of the VQ design algorithm, 
see
.I vqdesign
(3\-ESPS).  
.SH OPTIONS
.PP
The following options are supported:
.TP
.BI \-x " debug_level \fR[2]\fP"
If 
.I "debug_level"
is positive,
.I vqdes
outputs debugging messages and other information about the codebook
design to a history file.  The messages proliferate as 
.I debug_level 
increases.  Levels up to 6 are supported currently.  For
information about what output results from each value of 
.I debug_level,
see the discussion of the parameter 
.I hdetail
in
.I vqdesign
(3\-ESPS).  
.IP
For the default level (2), a summary of the various design parameters
is output to the history file at the beginning of the run.  Then, the
following are written each time the codebook has converged at a given
size or after an empty cell has been filled:  current date and time,
current codebook size, size of training sequence for current
codebook, total number of clustering iterations so far, average
distortion of the current codebook, and the total number of empty
cells found so far.  Also, the average distortion with respect to the
current codebook is output each time the full training sequence is
encoded.  
.TP
.BI \-h " histfile \fR[vqdeshist]\fP"
Specifies the file to use for history and debugging output.  
.TP
.BI \-k " checkfile \fR[vqdes.chk]\fP"
Specifies the name of the checkpoint file written by 
.I vqdes.  
\.TP
.B \-i
Specifies that an initial codebook is to be used (otherwise a root
codebook is designed from the training sequence).  The filename 
and record number for the initial codebook are given respectively
by the parameters 
.I init_file
and
.I init_rec
in the ESPS parameter file.  The file must be of type FEA_VQ.  
Whether or not the initial codebook is clustered before splitting 
is determined by the parameter
.I init_behav
in the ESPS parameter file.  
.IP
The parameters
.I conv_ratio
and
.I dist_type
apply whether or not the \fB\-i\fP option is used.  If the parameter
.I cbk_type
is supplied (it's optional) it must be the same as the codebook type
of the initial codebook.  
.SH "ESPS PARAMETERS"
.PP
The following parameters are read from the parameter or common 
file:
.sp
.I "string fea_field"
.PP
This is the name of the field in \fIinput.fea\fP that contains 
the training vectors.  It must be of type FLOAT.  
.sp
.I "int fea_dim"
.PP
This is the dimension of the feature vectors and also the dimension 
of the VQ codewords.   
.I Fea_dim
must be no larger than the size of 
.I fea_field.
If there are more than 
.I fea_dim
elements in 
.I fea_field,
only the first 
.I fea_dim
are used from each record.  
.sp
.I "double conv_ratio"
.PP
Each clustering iteration of the codebook design algorithm is 
repeated until the fractional decrease in the overall average 
distortion between successive iterations falls below
.I conv_ratio.  
A reasonable initial value is .05
.sp
.I "int vq_size"
.PP
Specifies the size of the desired VQ codebook.
.sp
.I "string dist_type"
.PP
Specifies the type of distortion measure to use.  Currently supported
values are "MSE" (mean-square-error) and "MSE_LAR" (mean-square-error on log
area ratios, which assumes that the input vectors are reflection
coefficients).  
.sp
.I "string cbk_struct"
.PP
Specifies the search-structure of the desired codebook.  "FULL_SEARCH"
is the only value supported at this time.  
.sp
.I "string cbk_type"
.PP
Specifies a codebook type; the values currently supported are "MISC",
"RC_VQCBK", "RC_VCD_VQCBK", "RC_UNVCD_VQCBK", "LSF_VQCBK",
"LSF_VCD_VQCBK", and "LSF_UNVCD_VQCBK" (see <vq.h>).  Because this parameter
is stored as extra information in the codebook and does not affect
the codebook design, it is optional. The value "MISC" is assumed if 
the parameter is missing.  (However, if the parameter is present when
the \fB\-i\fP option is used, then it must match the value in the 
initial codebook.)
.sp
.I "string init_file"
.PP
Specifies the name of the file containing the initial codebook (only 
used with \fB\-i\fP option).  
.sp
.I "int init_rec"
.PP
Specifies the record number of the initial codebook in 
.I init_file
(only used with \fB\-i\fP option).  
.sp
.I "string init_behav"
.PP
If this parameter is "INIT_NOCLUSTER", the initial codebook is 
split right away.  If it is "INIT_CLUSTER", the training sequence 
is used to recluster the initial codebook (until convergence) before
splitting (only used with \fB\-i\fP option). 
.sp
.I "int max_iter"
Specifies the maximum number of iterations per level.  If this
parameter is not present, a default value of 500 is used.  
.PP
The values of parameters obtained from the parameter file are printed
if the environment variable ESPS_VERBOSE is 3 or greater.  The default
value is 3.
.SH ESPS COMMON
.PP
ESPS Common is read if
.I filename
in Common matches 
.I input. 
No values are written to ESPS Common. 
.PP
ESPS Common processing may be disabled by setting the environment variable
USE_ESPS_COMMON to "off".  The default ESPS Common file is .espscom 
in the user's home directory.  This may be overidden by setting
the environment variable ESPSCOM to the desired path.  User feedback of
Common processing is determined by the environment variable ESPS_VERBOSE,
with 0 causing no feedback and increasing levels causing increasingly
detailed feedback.  If ESPS_VERBOSE is not defined, a default value of 3 is
assumed.
.SH ESPS HEADERS
.PP
.I Vqdes
sets 
.I hd.fea\->type
to FEA_VQ, and it fills in the other header fields so 
as to define FEA records of that type. The command line is 
added as a comment, and 
.I input.fea
is added as a source file.  If there is an initial codebook
specified, its header is also added as a source.  
.I Vqdes
also creates and writes the following generic header items:
.sp
.I "design_size"
.PP
This is the number of codewords in the codebook.  
.sp
.I "codeword_dimen"
.PP
This is the dimension of each codeword.  
.sp
.I "fea_field"
.PP
This is the name of the field in \fIinput.fea\fP that was used
to form the training sequence.  
.PP
Note that both 
.I "design_size"
and
.I "codeword_dimen"
are redundant since 
the same values are stored in the FEA record itself.  However, 
they are also written in the header as they do determine the size
of the FEA file records.  
.SH "FUTURE CHANGES"
.PP
Additional values for the parameters
.I dist_type,
and
.I cbk_struct 
will be supported.  
.I Vqdes
will be modified so that standard input can be used in 
place of 
.I input.fea.
.SH "SEE ALSO"
.PP
.nf
vq(1\-ESPS), vqdesasc(1\-ESPS), vqasc(1\-ESPS), vqdesign(3\-ESPS), 
\fIfeafunc\fP(1\-\s-1ESPS\s+1), \fImergefea\fP(1\-\s-1ESPS\s+1), FEA_VQ(5\-ESPS), 
ESPS(5-ESPS), FEA(5-ESPS)
.fi
.SH "WARNINGS AND DIAGNOSTICS"
.PP
.I Vqdes 
will exit with a diagnostic if any of the following hold:
.IP
An initial codebook is used and its file name is the same as that of
the checkpoint file (this is for safety).
.IP
It can't read the input ESPS file headers or they are not of the right type.
.IP
The named field in the FEA file is not large enough.
.IP
There are insufficient records in the initial codebook file.
.IP
The named field in the FEA file is not of type FLOAT.
.IP
The dimension of the initial codebook doesn't match the dimension of
vectors in the training sequence.
.IP
An invalid distortion type was specified.  
.IP
Not enough memory could be allocated.
.IP
The parameter \fIcbk_type\fP doesn't match that of the initial
codebook when the \fB\-i\fP option is used.  
.PP
Warnings are issued if any of the following hold:
.IP
The FEA field size is larger than the specified dimension of training 
vectors.
.IP
The initial codebook type is not the same as that specified.
.IP
The initial codebook does not have a named fea_field that is the same
as that specified, or it does but it is different.  
.IP
Various warnings if characteristics of the initial codebook (\fB\-i\fP 
option) are inconsistent with the design parameters.  
.SH "BUGS"
.PP
None known.  
.SH "REFERENCES"
.nf
\fIvqdesign\fP(3\-\s-1ESPS\s+1), \fIvq\fP(1\-\s-1ESPS\s+1), \fIvqdesasc\fP(1\-\s-1ESPS\s+1), 
\fIvqasc\fP(1\-\s-1ESPS\s+1), \fIpplain\fP(1\-\s-1ESPS\s+1), \fIaddfea\fP(1\-\s-1ESPS\s+1).  
.fi
.SH "AUTHOR"
.PP
Manual page by John Shore; program by John Shore.