qccwavsubbandpyramid3d.3

QccPack implementation in C

.TH QCCWAVSUBBANDPYRAMID3D 3 "QCCPACK" ""
.SH NAME
QccWAVSubbandPyramid3D \- data structure
for a three-dimensional dyadic or wavelet-packet
subband decomposition of an image cube
.SH SYNOPSIS
.B #include "libQccPack.h"
.sp
.BI "int QccWAVSubbandPyramid3DInitialize(QccWAVSubbandPyramid3D *" subband_pyramid );
.br
.BI "int QccWAVSubbandPyramid3DAlloc(QccWAVSubbandPyramid3D *" subband_pyramid );
.br
.BI "void QccWAVSubbandPyramid3DFree(QccWAVSubbandPyramid3D *" subband_pyramid );
.br
.BI "int QccWAVSubbandPyramid3DNumLevelsToNumSubbandsDyadic(int " num_levels );
.br
.BI "int QccWAVSubbandPyramid3DNumLevelsToNumSubbandsPacket(int " temporal_num_levels ", int " spatial_num_levels );
.br
.BI "int QccWAVSubbandPyramid3DNumSubbandsToNumLevelsDyadic(int " num_subbands );
.br
.BI "int QccWAVSubbandPyramid3DCalcLevelFromSubbandDyadic(int " subband ", int " num_levels );
.br
.BI "int QccWAVSubbandPyramid3DCalcLevelFromSubbandPacket(int " subband ", int " temporal_num_levels ", int " spatial_num_levels ", int *" temporal_level ", int *" spatial_level );
.br
.BI "int QccWAVSubbandPyramid3DSubbandSize(const QccWAVSubbandPyramid3D *" subband_pyramid ", int " subband ", int *" subband_num_frames ", int *" subband_num_rows ", int *" subband_num_cols );
.br
.BI "int QccWAVSubbandPyramid3DSubbandOffsets(const QccWAVSubbandPyramid3D *" subband_pyramid ", int " subband ", int *" frame_offset ", int *" row_offset ", int *" col_offset );
.br
.BI "int QccWAVSubbandPyramid3DPrint(const QccWAVSubbandPyramid3D *" subband_pyramid );
.SH DESCRIPTION
QccPack provides data structure
.B QccWAVSubbandPyramid3D
for representing three-dimensional subband decompositions of
image cubes.
This subband-pyramid structure can be read from and written to 
.BR SP3 -format
files, or a
.B QccWAVSubbandPyramid3D
structure can be used without file input or output.
.SH "DATA STRUCTURE"
The
.B QccWAVSubbandPyramid3D
data structure is defined as:
.RS
.nf

typedef struct
{
  QccString filename;
  QccString magic_num;
  int major_version;
  int minor_version;
  int transform_type;
  int temporal_num_levels;
  int spatial_num_levels;
  int num_frames;
  int num_rows;
  int num_cols;
  int origin_frame;
  int origin_row;
  int origin_col;
  int subsample_pattern_frame;
  int subsample_pattern_row;
  int subsample_pattern_col;
  QccVolume volume;
} QccWAVSubbandPyramid3D;
.fi
.RE
.LP
The fields of
.B QccWAVSubbandPyramid3D
are as follows:
.TP
.I filename
The name of the file.
.TP
.IR magic_num ", " major_version ", " minor_version
The magic number and version of the file.
.TP
.IR transform_type
The type of transform (dyadic or wavelet-packet); this will be either
.BR QCCWAVSUBBANDPYRAMID3D_DYADIC
or
.BR QCCWAVSUBBANDPYRAMID3D_PACKET .
.TP
.IR temporal_num_levels
The number of levels of temporal decomposition in the subband pyramid.
.TP
.IR spatial_num_levels
The number of levels of spatial decomposition in the subband pyramid.
For a wavelet-packet transform, 
.IR spatial_num_levels
will be equal to
.IR temporal_num_levels .
.TP
.IR num_frames ", " num_rows ", " num_cols
The overall size of the volume of coefficients.
.TP
.IR origin_frame ", " origin_row ", " origin_col
Indicates the frame, row, and column indices
of the upper corner of the volume of coefficients.
.TP
.IR subsample_pattern_row ", " subsample_pattern_col
Indicates the subsampling decomposition pattern along the rows and
columns.
.TP
.I volume
The volume of coefficients.
.SH "FILE FORMAT"
For reading and writing structures
of type
.BR QccWAVSubbandPyramid3D ,
QccPack provides the
.B SP3
file format.
This file format starts with an ASCII header followed by
binary data.
The ASCII header consists of magic-number/revision
information
followed by any amount of white space
(space, `\\t' (tab), `\\n' (newline), `\\r' (carriage return)) and/or
comments lines (lines starting with `#').  Following this white space,
additional ASCII
header information is given, separated by blanks and newlines.
Binary data follows this ASCII header information.
Note:  one (and only one) newline 
.B must
immediately follow the last component of ASCII header information before the
start of the binary data.
.LP
The
.B SP3
file format consists of the following information:
.RS
.sp
.BI SP3 X.X
.br
.I "<white space>"
.br
.I T
.br
.RI [ L ]
.I S
.br
.I "C R F"
.br
.IR "i111 i112" \|.\|.\|.
.br
.IR "i121 i122" \|.\|.\|.
.br
.IR "i211 i212" \|.\|.\|.
.br
\|.
.br
\|.
.br
\|.
.br
.sp
.RE
where
.B SP3
is the magic number,
.I X.X
is the version number,
.I "<white space>"
is white space and/or 
comment lines, 
.I T
is the transform type (either
.BR QCCWAVSUBBANDPYRAMID3D_DYADIC
or
.BR QCCWAVSUBBANDPYRAMID3D_PACKET ),
.I L
is the number of levels of temporal decomposition (not present if
.I T
is 
.BR QCCWAVSUBBANDPYRAMID3D_PACKET ),
.I S
is the number of levels of spatial decomposition,
.I C
is the number of columns of the subband-pyramid image cube,
.I R
is the number of rows, 
.I F
is the number of frames, and
.I ikmn
is the coefficient for the 
.IR k th
frame,
.IR m th
row, 
.IR n th
column of the subband-pyramid image cube.
.IR T ", " L ", " S ", " C ", " R ", and " F
are stored in ASCII.  The image cube itself,
.IR ikmn ,
is stored as binary floating-point numbers (4 bytes each, MSB first,
see
.BR QccFileWriteDouble (3)).
The values of 
.I L
and
.I S
give the number of decompositions in the 
volume of coefficients.
If 
.I S
= 0, (and
.I L
= 0 for a wavelet-packet decomposition),
the image cube has not been decomposed.
.SH "ROUTINES"
.B QccWAVSubbandPyramid3DInitialize()
should be called before any use of a
.B QccWAVSubbandPyramid3D
structure.
.B QccWAVSubbandPyramid3DInitialize()
initializes the fields of
.I subband_pyramid
to the following values:
.RS

.IR filename :
.B NULL
string
.br
.IR magic_num :
.B QCCSUBBANDPYRAMID3D_MAGICNUM
.br
.IR major_version ", " minor_version :
initialized to output of 
.BR QccGetQccPackVersion (3)
.br
.IR transform_type :
.BR QCCWAVSUBBANDPYRAMID3D_PACKET
.br
.IR temporal_num_levels :
0
.br
.IR spatial_num_levels :
0
.br
.IR num_frames :
0
.br
.IR num_rows :
0
.br
.IR num_cols :
0
.br
.IR origin_frame
0
.br
.IR origin_row
0
.br
.IR origin_col
0
.br
.IR subsample_pattern_frame :
0
.br
.IR subsample_pattern_row :
0
.br
.IR subsample_pattern_col :
0
.br
.IR volume :
.B NULL
.RE
.LP
.B QccWAVSubbandPyramid3DAlloc()
allocates storage space for 
.IR subband_pyramid->volume .
If 
.I subband_pyramid->volume
is not
.BR NULL ,
.B QccWAVSubbandPyramid3DAlloc()
returns immediately without changing the state of any memory allocation.
Otherwise,
the 
.I subband_pyramid->volume
array is allocated.
The fields
.IR subband_pyramid->num_frames , 
.IR subband_pyramid->num_rows ,
and
.IR subband_pyramid->num_cols 
must be set prior to calling
.BR QccWAVSubbandPyramid3DAlloc() .
.LP
.B QccWAVSubbandPyramid3DFree()
frees the
.I subband_pyramid->volume
array previously allocated by
.BR QccWAVSubbandPyramid3DAlloc() .
.LP
.B QccWAVSubbandPyramid3DNumLevelsToNumSubbandsDyadic()
calculates the number of subbands in a dyadic subband pyramid with
.I num_levels 
levels. This value is 
.I num_levels
* 7 + 1.
.LP
.B QccWAVSubbandPyramid3DNumLevelsToNumSubbandsPacket()
calculates the number of subbands in a wavelet-packet subband pyramid with
.I temporal_num_levels 
temporal levels and
.I spatial_num_levels
spatial levels. This value is 
.BR QccWAVSubbandPyramidNumLevelsToNumSubbands (
.IR spatial_num_levels )
.RI "* " temporal_num_levels " + 1."
.LP
.B QccWAVSubbandPyramid3DNumSubbandsToNumLevelsDyadic()
calculates the number of levels in a dyadic subband pyramid with
.I num_subbands 
subbands.
.LP
.B QccWAVSubbandPyramid3DCalcLevelFromSubbandDyadic()
calculates the level of the specified
.I subband
in a dyadic subband pyramid with
.I num_levels
levels.
Here,
.I subband
gives the subband number of the subband in the pyramid.
.LP
.B QccWAVSubbandPyramid3DCalcLevelFromSubbandPacket()
calculates the levels of the specified
.I subband
in a wavelet-packet subband pyramid with
.I temporal_num_levels
temporal levels and
.I spatial_num_levels
spatial levels.
Here,
.I subband
gives the subband number of the subband in the pyramid.
The temporal level of the specified subband is returned in
.IR temporal_level 
while the spatial level of the subband is returned in
.IR spatial_level .
.LP
.B QccWAVSubbandPyramid3DSubbandSize()
calculates the size of the specified
.I subband
in 
.IR subband_pyramid .
The size of the subband is returned in
.IR subband_num_frames ,
.IR subband_num_rows ,
and
.IR subband_num_cols ,
which must be allocated prior to calling
.BR QccWAVSubbandPyramid3DSubbandSize() .
.LP
.B QccWAVSubbandPyramid3DSubbandOffsets()
calculates the location in
.I subband_pyramid->volume
of the specified
.IR subband .
The frame, row, and column offsets
are returned in
.IR frame_offset ,
.IR row_offset ,
and
.IR col_offset ,
respectively,
which must be allocated prior to calling
.BR QccWAVSubbandPyramid3DSubbandOffsets() .
.LP
.B QccWAVSubbandPyramid3DPrint()
prints the contents of
.I subband_pyramid
to stdout.
.SH "RETURN VALUE"
These routines return 0 on success, and 1 on failure.
.SH "SEE ALSO"
.BR QccWAVSubbandPyramid3DDWT (3),
.BR QccWAVSubbandPyramid3DInverseDWT (3),
.BR QccPackWAV (3),
.BR QccPack (3)
.LP
B.-J. Kim, Z. Xiong, and W. A. Pearlman,
"Low Bit-Rate Scalable Video Coding with 3-D Set Partitioning
in Hierarchical Trees (3-D SPIHT),"
.IR "IEEE Transactions on Circuits and Systems for Video Technology" ,
vol. 10, no. 8, pp. 1374-1387, December 2000.
.LP
M. Antonini, M. Barlaud, P. Mathieu, and I. Daubechies,
"Image Coding Using Wavelet Transform,"
.IR "IEEE Transactions on Image Processing" ,
vol. 1, pp. 205-220, April 1992.
.SH AUTHOR
Copyright (C) 1997-2005  James E. Fowler
.\"  The programs herein are free software; you can redistribute them an.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.