qccspihtencode.3

SPIHT的寫法~~請大家參考看看~~比較一下

.TH QCCSPIHTENCODE 1 "QCCPACK" ""
.SH NAME
QccSPIHTEncode, QccSPIHTDecode \-
encode/decode an image using the SPIHT algorithm
.SH SYNOPSIS
.B #include "libQccPack.h"
.sp
.BI "int QccSPIHTEncode(const QccIMGImageComponent *" image ", const QccIMGImageComponent *" mask ", QccBitBuffer *" buffer ", int " num_levels ", const QccWAVWavelet *" wavelet ", const QccWAVPerceptualWeights *" perceptual_weights ", int " target_bit_cnt ", int " arithmetic_coded ", FILE *" rate_distortion_file );
.sp
.BI "int QccSPIHTEncode2(QccWAVSubbandPyramid *" image_subband_pyramid ", QccWAVSubbandPyramid *" mask_subband_pyramid ", double " image_mean ", QccBitBuffer *" buffer ", int " target_bit_cnt ", int " arithmetic_coded ", FILE *" rate_distortion_file );
.sp
.BI "int QccSPIHTDecodeHeader(QccBitBuffer *" buffer ", int *" num_levels ", int *" num_rows ", int *" num_cols ", double *" image_mean ", int *" max_coefficient_bits ", int *" arithmetic_coded );
.sp
.BI "int QccSPIHTDecode(QccBitBuffer *" buffer ", QccIMGImageComponent *" image ", const QccIMGImageComponent *" mask ", int " num_levels ", const QccWAVWavelet *" wavelet ", const QccWAVPerceptualWeights *" perceptual_weights ", double " image_mean ", int " max_coefficient_bits ", int " target_bit_cnt ", int " arithmetic_coded );
.sp
.BI "int QccSPIHTDecode2(QccBitBuffer *" buffer ", QccWAVSubbandPyramid *" image_subband_pyramid ", QccWAVSubbandPyramid *" mask_subband_pyramid ", int " max_coefficient_bits ", int " target_bit_cnt ", int " arithmetic_coded );
.SH DESCRIPTION
.SS Encoding
.LP
.B QccSPIHTEncode()
encodes an image component,
.IR image ,
using the Set Partitioning In Hierarchical Trees (SPIHT) algorithm by
Said and Pearlman.
The SPIHT algorithm involves a 2D DWT followed by 
a progressive "bitplane" coding of the wavelet coefficients using a
zerotree-like quantization structure.
.LP
.I image
is the image component to be coded and
.I buffer
is the output bitstream.
.I buffer
must be of
.B QCCBITBUFFER_OUTPUT
type and opened via a prior call to
.BR QccBitBufferStart (3).
.LP
.I num_levels
gives the number of levels of dyadic wavelet decomposition to perform,
and
.I wavelet
is the wavelet to use for decomposition.
.I perceptual_weights
is the optional perceptual weights to employ (see
.BR QccWAVPerceptualWeights (3))
or use
.B NULL
for no perceptual weighting.
Note: the SPIHT algorithm as described originally by Said and
Pearlman in their ITCSVT paper does not employ perceptual weighting.
.LP
The bitstream output from the SPIHT encoder is embedded, meaning that
any prefix of the bitstream can be decoded to give a valid 
representation of the image.  The SPIHT encoder essentially produces
output bits until the number of bits output reaches
.IR target_bit_cnt ,
the desired (target) total length of the output bitstream in bits,
and then it stops.
Note that this is the bitstream length in bits, not the rate of the bitstream
(which would be expressed in bits per pixel).
.LP
As originally described by Said and Pearlman,
the SPIHT algorithm uses arithmetic coding of symbols as a final output step
to improve coding efficiency.  Alternatively, arithmetic coding can be
suppressed, producing what Said and Pearlman call "binary-uncoded"
output.
The QccPack SPIHT implementation supports both arithmetic-coded
and binary-uncoded output modes.
.I arithmetic_coded
is a flag passed to
.BR QccSPIHTEncode()
that indicates whether arithmetic coding should be performed
(1 = arithmetic coding, 0 = binary-uncoded).
.LP
.BR QccSPIHTEncode()
optionally supports the use of a shape-adaptive DWT (SA-DWT) rather than
the usual DWT. That is, 
.BR QccSPIHTEncode()
can call
.BR QccWAVSubbandPyramidShapeAdaptiveDWT (3)
as the wavelet transform rather than the usual
.BR QccWAVSubbandPyramidDWT (3).
The use of a SA-DWT is indicated by a non-NULL
.IR mask ;
if 
.I mask
is NULL, then the usual DWT is used.
In the case of a SA-DWT,
.I mask 
gives the transparency mask which indicates which pixels of the image
are non-transparent and thus have data that is to be transformed.
Refer to 
.BR QccWAVSubbandPyramidShapeAdaptiveDWT (3)
for more details on the calculation of this SA-DWT.
See "Shape-Adaptive Coding" below for details on how the SPIHT
algorithm handles shape-adaptive coding.
.LP
.I rate_distortion_file
is a pointer to an output file.
If this pointer is not
.BR NULL ,
then a rate-distortion profile is written to the file while
the image is being compressed. Essentially, this rate-distortion
profile gives numerous points on the operational rate-distortion
curve of the compressed bitstream produced by
.BR QccSPIHTEncode() ;
see "RATE-DISTORTION PROFILE" below for more details.
The file pointed to by
.I rate_distortion_file
must be opened for writing prior to calling
.BR QccSPIHTEncode() ,
and must be closed after
.BR QccSPIHTEncode() 
returns.
If
.I rate_distortion_file
is 
.BR NULL ,
no rate-distortion profile is written.
.LP
The routine
.BR QccSPIHTEncode2()
provides an alternative interface to SPIHT encoding.
Specifically,
.BR QccSPIHTEncode2()
functions indentically to
.BR QccSPIHTEncode()
described above, except that both the image and optional mask are
assumed to have had a DWT applied to them prior to calling
.BR QccSPIHTEncode2() .
As a consequence, the image and mask are passed to
.BR QccSPIHTEncode2()
in the wavelet domain as
.IR image_subband_pyramid
and
.IR mask_subband_pyramid .
We note that most applications should opt for
.BR QccSPIHTEncode()
rather than
.BR QccSPIHTEncode2() ;
however,
.BR QccSPIHTEncode()
is implemented essentially as a call to an appropriate DWT
followed by a call to
.BR QccSPIHTEncode2() .
If 
.BR QccSPIHTEncode2()
is used, it is the responsibility of the calling routine
to perform the appropriate DWT prior to calling
.BR QccSPIHTEncode2() .
.SS Decoding
.LP
.B QccSPIHTDecodeHeader()
decodes the header information 
in a bitstream previously produced by
.BR QccSPIHTEncode() .
The input bitstream is
.I buffer
which must be of
.B QCCBITBUFFER_INPUT
type and opened via a prior call to
.BR QccBitBufferStart (3).
.LP
The header information is returned in
.I num_levels
(number of levels of wavelet decomposition),
.I num_rows
(vertical size of image),
.I num_cols
(horizontal size of image),
.I image_mean
(the mean value of the original image),
.I max_coefficient_bits
(indicates the precision, in number of bits, of the wavelet coefficient
with the largest magnitude),
and
.I arithmetic_coded
(indicates whether the to data stream to follow is arithmetic-coded or not).
.LP
.B QccSPIHTDecode()
decodes the bitstream
.IR buffer ,
producing the reconstructed image component,
.IR image .
The bitstream must already have had its header read by a prior call
to
.B QccSPIHTDecodeHeader()
(i.e., you call
.B QccSPIHTDecodeHeader() 
first and then
.BR QccSPIHTDecode() ).
If
.I target_bit_cnt
is
.BR QCCENT_ANYNUMBITS ,
then decoding stops when the end of the input bitstream is reached;
otherwise, decoding stops when
.I target_num_bits
from the input bitstream have been decoded.
.LP
If a SA-DWT was used in SPIHT encoding, then the original transparency
mask should be passed to 
.BR QccSPIHTDecode()
as
.IR mask .
That is,
.I mask
should be the same transparency mask (in the spatial domain)
that was passed to
.BR QccSPIHTEncode() .
Note that
.BR QccSPIHTDecode()
will transform this
.I mask
via a Lazy wavelet transform, and then pass the transformed mask
to 
.BR QccWAVSubbandPyramidInverseShapeAdaptiveDWT (3).
If the usual DWT was used in encoding, then
.I mask
should be a NULL pointer.
.LP
.BR QccSPIHTDecode2()
provides the appropriate alternative interface to SPIHT decoding
required if encoding was done via
.BR QccSPIHTEncode2() .
Essentially, 
.BR QccSPIHTDecode()
is implemented by a call to
.BR QccSPIHTDecode2()
followed by an appropriate inverse DWT.
If
.BR QccSPIHTDecode2()
is used, it is the responsibility of the calling to routine
to perform the appropriate inverse DWT subsequent to the call
to
.BR QccSPIHTDecode2() .
As noted above, most applications should use
.BR QccSPIHTDecode()
rather than
.BR QccSPIHTDecode2() .
.SH PERFORMANCE
The QccPack implementation of the SPIHT algorithm was coded "from scratch,"
with no consultation of the original SPIHT source code produced at
RPI by Said and Pearlman.
The QccPack implementation follows as description of the SPIHT algorithm
as described by Said and Pearlman in their original ITCSVT paper
as closely as can be extrapolated from that description.
(Note that the description of the algorithm given in their patent
documents differs slightly from that of the ITCSVT description).
However, 
since no algorithm of complexity can ever be described
.I completely
in a journal article,
it is inevitable that certain subtle details
were implemented in the QccPack SPIHT coder 
differently from in the coder used by
Said and Pearlman for their results.
As a consequence, the performance of the
QccPack implementation differs slightly from that reported
by Said and Pearlman in their ITCSVT paper and from that obtained by the
binary executable SPIHT programs available from RPI
(see http://www.cipr.rpi.edu/research/SPIHT -- with 
.I arithmetic_coded
= 1, the QccPack code is similar to RPI's 
.BR codetree / decdtree
programs, and with