vq.1

speech signal process tools

.\" @(#)vq.1	3.9 4/7/97 ESI
.\" Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved
.TH VQ 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"
vq - vector quantize a field in FEA records
.SH "SYNOPSIS"
.B vq
[
.BI \-x " debug_level"
] [
.BI \-h " histfile"
] [
.BI \-f " fieldname"
] [
.BI \-c " record"
] [
.BI \-i 
]
.I "cbk.fea fea.in fea.out"
.SH "DESCRIPTION"
.PP
.I Vq
reads the ESPS FEA_VQ file 
.I cbk.fea
to obtain a vector quantization codebook.  
.I Vq
then reads an file
.I fea.in,
encodes a particular field from each FEA record, and then 
outputs the encoded fields to
.I fea.out.
.I Fea.out
also contains the rest of the information from 
.I fea.in,
i.e., the contents of the two files are identical except for the 
quantized field within each record.  
.PP
If "\-" is supplied in place of 
.I fea.in, 
then standard input is used.  
If "\-" is supplied in place of 
.I fea.out,
then standard output is used.  
.PP
.I Vq
determines which distortion measure to use from the information 
stored in the FEA_VQ file.  In many cases, 
.I vq
will be used with codebooks designed using 
.I vqdes
(1\-ESPS), although this is not required.  If there are field 
to be quantized in 
.I input.ana
is larger than the dimension of the codewords in 
.I cbk.fea,
the extra elements are set to zero in the output file.  
.PP
The field to quantize (specified by the \fB-f\fP option) must be of
type FLOAT.  Note that \fIfeafunc\fP can be used to transform the data
type of fields.  
.SH OPTIONS
.PP
The following options are supported:
.TP
.BI \-x " debug_level"
If 
.I "debug_level \fR[0]\fP"
is positive,
.I vq
outputs debugging messages and other information about the codebook
design to a history file.  The messages proliferate as 
.I debug_level 
increases.  For level 0, there is no output.  For level 1, the size of
the input sequence, the average distortion, the standard deviation of
the distortion, and the maximum distortion are output.  For level 2, the
codebook itself is also output.  For level 3, information is
output for every input vector, namely the index of the closest codeword,
the distortion with respect to the closest codeword,
and the cumulative average distortion.  For level 4, the output also
includes the input vectors and the output vectors.
.TP
.BI \-h " histfile \fR[vqhist]\fP"
Specifies the file to use for history and debugging output.  
.TP
.BI \-f " fieldname \fR[spec_param]\fP"
Specifies the name of the field to be quantized in each 
.I fea.in record.  
.TP
.BI \-c " record"
Specifies an integer record number within 
.I cbk.fea
to use as the codebook.  If the \fB\-c\fP option is not used, 
then the last record in 
.I cbk.fea
is used as the codebook.  
.TP 
.BI \-i
Specifies that only the codword index and not the quantized
field \fIfieldname\fP be written to \fIfea.out\fP. 
.SH "ESPS PARAMETERS"
.PP
The ESPS parameter file is not read.  
.SH ESPS COMMON
.PP
No values are written to ESPS Common.  
.SH ESPS HEADERS
.PP
.I Vq
reads the usual information from the \fIfea.in\fP header.  The header
for \fIfea.out\fP is created using 
.I copy_header(3\-ESPS),
with the usual record-keeping fields filled in.  A field is added
which contains the codeword index associated with the quantized value
of \fIfieldname\fP. The name of this field is obtained by appending
the suffix \fI_cwndx\fP to the name of the quantized field, e.g.
the default field name is \fIspec_param_cwndx\fP.  This field is a 
single integer of data type LONG.  If the \fB\-i\fP option is
specified, the field \fIfieldname\fP is not included in the file
\fIfea.out\fP.
.PP
The generic header item \fIstart_time\fP is written in the output
file.  The value written is computed by taking the \fIstart_time\fP
value from the header of the input file (or zero, if such a header
item doesn't exist) and adding to it the relative time from the first
record in the file to the first record processed.  This relative time
is computed using the generic \fIrecord_freq\fP from the input file.
If \fIrecord_freq\fP doesn't exist in the input file, \fIstart_time\fP
is copied from the input file to the output file.
.PP
If it exists in the input file header, the generic header item
\fIrecord_freq\fP is copied to the output file header.  This item
gives the number of records per second of original data analyzed.
.PP
The generic header item \fIquantized\fP is set to YES in the output file.  
.PP
Both 
.I cbk.fea
and
.I fea.in
are added to the output header as sources.  
.PP
.I Vq
creates and writes the following generic header items (names
incremented using 
.I uniq_name
(3\-ESPS) if they exist already):
.sp
.I "quantized_field"
.PP
This is the name of the quantized field (from \fB\-f\fP option).
.sp
.I "cbk_current_size"
.PP
The size of the quantization codebook.
.sp
.I "cbk_dimen"
.PP
The dimension of codewords in the quantization codebook.
.sp
.I "cbk_dist_type"
.PP
The type of distortion used in designing the codebook and in
quantizing 
.I fea.in.
.sp
.I "cbk_cbk_struct"
.PP
The structure of the quantization codebook.
.sp
.I "cbk_cbk_type"
.PP
The type of the quantization codebook.
.sp
.I "cbk_final_dist"
.PP
The final distortion of the training sequence that was used in the
original design of the quantization codebook.
.sp
.I "encode_distortion"
.PP
The average distortion resulting from encoding 
.I fea.in.
This is left as -1 if the output is standard output.  
.SH "FUTURE CHANGES"
.PP

.SH "SEE ALSO"
.PP
.nf
vqdes(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), FEA(5\-ESPS), ESPS(5\-ESPS)
.fi
.SH "WARNINGS AND DIAGNOSTICS"
.PP
.PP
Vq will exit with a diagnostic if any of the following hold:
.IP
It can't read the input ESPS file headers or they are not of the right type.
.IP
.I Fieldname 
is not a valid record field in \fIfea.in\fP.
.IP
The field 
.I fieldname
in \fIfea.in\fP is not of type FLOAT.
.IP
The field 
.I fieldname
in \fIfea.in\fP is smaller than the size of the VQ codewords.
.IP
There are insufficient records in \fIcbk.fea\fP.  
.PP
Warnings will be issued if any of the following hold:
.IP
The field 
.I fieldname
in \fIfea.in\fP is larger than the size of the VQ codewords. 
.IP
The field
.I fieldname
in \fIfea.in\fP has a different name than the contants generic header item
\fIfea_field\fP in \fIcbk.fea\fP, if that generic header item exists. 
.IP
The generic header item \fIquantized\fP is YES in \fIfea.in\fP (i.e., 
if any quantization has occured already on the input file).  
.SH "BUGS"
.PP
None known.  
.SH "REFERENCES"
.PP
See
.I vqdesign
(3\-ESPS).  
.SH "AUTHOR"
.PP
Manual page by John Shore; program by John Shore.  Codeword index
field added by Bill Byrne.