gtrencode.1

QccPack implementation in C

.TH GTRENCODE 1 "QCCPACK" ""
.SH NAME
gtrencode \- encode using generalized threshold replenishment (GTR)
.SH SYNOPSIS
.B gtrencode
.RB "[\|" \-l
.IR  lambda "\|]"
.RB "[\|" \-w
.IR omega "\|]"
.RB "[\|" \-ic
.IR initial\_codebook "\|]"
.RB "[\|" \-cs
.IR max\_codebook\_size "\|]"
.RB "[\|" \-fc
.IR final\_codebook "\|]"
.I datfile
.I codebook\_coder
.I channelfile
.I sideinfofile
.SH OPTIONS
.TP
.BI \-l " lambda"
Float. Rate-distortion parameter. Default value = 16.0.
.TP
.BI \-w " omega"
Float. Windowing parameter. Default value = 100.0.
.TP
.BI \-ic " initial\_codebook"
String. Read the initial codebook from
.IR initial\_codebook .
.TP
.BI \-cs " max\_codebook\_size"
Integer.  Use online initialization until the codebook size reachs
.IR max\_codebook\_size .
Default value = 256.
.TP
.BI \-fc " final\_codebook"
String. Output the final state of the codebook after encoding to
.IR final\_codebook .
.SH DESCRIPTION
.LP
.B gtrencode
implements the generalized-threshold-replenishment (GTR) algorithm
for adaptive vector quantization (AVQ).
The vectors of
.I datfile
(DAT format)
are encoded using the GTR algorithm, with
.I initial\_codebook
(CBK format), if specified,
being the initial codebook.
.B gtrencode
outputs a channel of VQ indices,
.I channelfile
(CHN format), and side information,
.I sideinfofile
(SID format).
.I codebook\_coder
gives the scalar quantizer used to implement the codebook coder and
generate the side information (see below).
Note:
.B gtrencode
implements the move-to-front variant of the GTR algorithm.
.LP
If 
.B \-ic
is given, then the initial codebook is read from
.IR initial\_codebook .
If 
.B \-cs
is given, then
.I max\_codebook\_size
gives the maximum allowable codebook size.  That is, when vectors update the
codebook, they are allowed to be added to the codebook 
by increasing the codebook size until the number of codewords in the
codebook reaches
.IR max\_codebook\_size .
After that point, each vector update replaces an existing codeword in the
codebook.
If 
.B \-cs
is given
and no initial codebook is specified (no
.B \-ic
option given), the codebook starts empty and the first vector coded must 
update the codebook.
If
.B \-ic
is given, then
.I max\_codebook\_size
is set to be the size of
.I initial\_codebook
regardless of whether
.B \-cs
is given or not.
If neither
.B \-ic
nor
.B \-cs
is given, 
.I max\_codebook\_size
defaults to 256 and the codebook starts empty.
.LP
.B gtrdecode
is used for the corresponding decoding of 
.I channelfile 
and
.IR sideinfofile ;
.B avqrate
calculates the bit rate for the GTR algorithm as represented by
this channel and the side information.
See
.BR gtrdecode (1)
and
.BR avqrate (1)
for more details.
.LP
If option
.B \-fc
is specified, 
.B gtrencode
outputs the final state of the codebook, taking into account all codebook
updates performed during coding, to
.IR final\_codebook .
.SH "SIDE INFORMATION"
.LP
The side information output by
.B gtrencode
consists of a series of flags
indicating whether or not the codebook is updated at a given time, as well as
the vectors added to the codebook during a codebook update.
The side-information file,
.IR sideinfofile ,
consists of a sequence of symbols of the following form:
.nf

.I "    <symbol type>" <symbol value>

.fi
where
.I <symbol type>
is 1 for a flag, and 3 for an update vector.
If 
.I <symbol type>
= 1, then the current symbol is a flag, and, in this case,
.I <symbol value>
can be either 0 or 1. If
.I <symbol value>
= 1, then the symbol indicates that a codebook update is to be performed,
and the next symbol will be the new codeword.
.I <symbol value>
= 0 for no update.
If
.I <symbol type>
= 3, then the current symbol is a vector.
In this case,
.I <symbol value>
= 
.IR "v[1] v[2] " \|.\|.\|. " v[dim]" .
The scalar quantizer 
.I codebook\_coder 
(SQ format) is used to
quantize each component of the vector that updates the
codebook.
Thus, each
.I v[i]
is an index output from this scalar quantizer.
Note:
.I dim
is the vector dimension specified in the header of 
.I sideinfofile
(see
.BR QccPack (1)).
Note: in all instances,
.I <symbol value>
and 
.I <symbol type>
are stored in ASCII characters.
The value of 
.I N
(see
.BR QccPack (1))
specified in the header of 
.I sideinfofile
gives the number of symbols with
.I <symbol type>
= 1, i.e. the number of flags stored in
.IR sideinfofile .
.SH "SEE ALSO"
.BR gtrdecode (1),
.BR avqrate (1),
.BR QccPackAVQ (3),
.BR QccPack (3)

J. E. Fowler and S. C. Ahalt, "Adaptive Vector Quantization Using Generalized
Threshold Replenishment," in 
.I "Proceedings of the IEEE Data Compression Conference" 
(J. A. Storer and M. Cohn, eds.),
(Snowbird, UT), pp. 317-326, IEEE Computer Society Press, March 1997-2005.

.SH AUTHOR
Copyright (C) 1997-2005  James E. Fowler
.\"  The programs herein are free software; you can redistribute them and/or
.\"  modify them under the terms of the GNU General Public License
.\"  as published by the Free Software Foundation; either version 2
.\"  of the License, or (at your option) any later version.
.\"  
.\"  These programs are distributed in the hope that they will be useful,
.\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"  GNU General Public License for more details.
.\"  
.\"  You should have received a copy of the GNU General Public License
.\"  along with these programs; if not, write to the Free Software
.\"  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.