QccWAVSubbandPyramid3DSubbandSize.3

NAME

QccWAVSubbandPyramid3D - data structure for a three-dimensional dyadic or wavelet-packet subband decomposition of an image cube

int QccWAVSubbandPyramid3DInitialize(QccWAVSubbandPyramid3D *subband_pyramid);
int QccWAVSubbandPyramid3DAlloc(QccWAVSubbandPyramid3D *subband_pyramid);
void QccWAVSubbandPyramid3DFree(QccWAVSubbandPyramid3D *subband_pyramid);
int QccWAVSubbandPyramid3DNumLevelsToNumSubbandsDyadic(int num_levels);
int QccWAVSubbandPyramid3DNumLevelsToNumSubbandsPacket(int temporal_num_levels, int spatial_num_levels);
int QccWAVSubbandPyramid3DNumSubbandsToNumLevelsDyadic(int num_subbands);
int QccWAVSubbandPyramid3DCalcLevelFromSubbandDyadic(int subband, int num_levels);
int QccWAVSubbandPyramid3DCalcLevelFromSubbandPacket(int subband, int temporal_num_levels, int spatial_num_levels, int *temporal_level, int *spatial_level);
int QccWAVSubbandPyramid3DSubbandSize(const QccWAVSubbandPyramid3D *subband_pyramid, int subband, int *subband_num_frames, int *subband_num_rows, int *subband_num_cols);
int QccWAVSubbandPyramid3DSubbandOffsets(const QccWAVSubbandPyramid3D *subband_pyramid, int subband, int *frame_offset, int *row_offset, int *col_offset);
int QccWAVSubbandPyramid3DPrint(const QccWAVSubbandPyramid3D *subband_pyramid);

DESCRIPTION

QccPack provides data structure QccWAVSubbandPyramid3D for representing three-dimensional subband decompositions of image cubes. This subband-pyramid structure can be read from and written to SPBT-format files, or a QccWAVSubbandPyramid3D structure can be used without file input or output.

DATA STRUCTURE

The QccWAVSubbandPyramid3D data structure is defined as:

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;

The fields of QccWAVSubbandPyramid3D are as follows:

filename: The name of the file.
magic_num, major_version, minor_version: The magic number and version of the file.
transform_type: The type of transform (dyadic or wavelet-packet); this will be either QCCWAVSUBBANDPYRAMID3D_DYADIC or QCCWAVSUBBANDPYRAMID3D_PACKET.
temporal_num_levels: The number of levels of temporal decomposition in the subband pyramid.
spatial_num_levels: The number of levels of spatial decomposition in the subband pyramid. For a wavelet-packet transform, spatial_num_levels will be equal to temporal_num_levels.
num_frames, num_rows, num_cols: The overall size of the volume of coefficients.
origin_frame, origin_row, origin_col: Indicates the frame, row, and column indices of the upper corner of the volume of coefficients.
subsample_pattern_row, subsample_pattern_col: Indicates the subsampling decomposition pattern along the rows and columns.
volume: The volume of coefficients.

FILE FORMAT

For reading and writing structures of type QccWAVSubbandPyramid3D, QccPack provides the SPBT 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 must immediately follow the last component of ASCII header information before the start of the binary data.

The SPBT file format consists of the following information:

SPBTX.X
<white space>
T
[L] S
C R F
i111 i112...
i121 i122...
i211 i212...
.
.
.

where SPBT is the magic number, X.X is the version number, <white space> is white space and/or comment lines, T is the transform type (either QCCWAVSUBBANDPYRAMID3D_DYADIC or QCCWAVSUBBANDPYRAMID3D_PACKET), L is the number of levels of temporal decomposition (not present if T is QCCWAVSUBBANDPYRAMID3D_PACKET), S is the number of levels of spatial decomposition, C is the number of columns of the subband-pyramid image cube, R is the number of rows, F is the number of frames, and ikmn is the coefficient for the kth frame, mth row, nth column of the subband-pyramid image cube. T, L, S, C, R, and F are stored in ASCII. The image cube itself, ikmn, is stored as binary floating-point numbers (4 bytes each, MSB first, see QccFileWriteDouble(3) ). The values of L and S give the number of decompositions in the volume of coefficients. If S = 0, (and L = 0 for a wavelet-packet decomposition), the image cube has not been decomposed.

ROUTINES

QccWAVSubbandPyramid3DInitialize() should be called before any use of a QccWAVSubbandPyramid3D structure. QccWAVSubbandPyramid3DInitialize() initializes the fields of subband_pyramid to the following values:

filename: NULL string
magic_num: QCCSUBBANDPYRAMID3D_MAGICNUM
major_version, minor_version: initialized to output of QccGetQccPackVersion(3)
transform_type: QCCWAVSUBBANDPYRAMID3D_PACKET
temporal_num_levels: 0
spatial_num_levels: 0
num_frames: 0
num_rows: 0
num_cols: 0
origin_frame 0
origin_row 0
origin_col 0
subsample_pattern_frame: 0
subsample_pattern_row: 0
subsample_pattern_col: 0
volume: NULL

QccWAVSubbandPyramid3DAlloc() allocates storage space for subband_pyramid->volume. If subband_pyramid->volume is not NULL, QccWAVSubbandPyramid3DAlloc() returns immediately without changing the state of any memory allocation. Otherwise, the subband_pyramid->volume array is allocated. The fields subband_pyramid->num_frames, subband_pyramid->num_rows, and subband_pyramid->num_cols must be set prior to calling QccWAVSubbandPyramid3DAlloc().

QccWAVSubbandPyramid3DFree() frees the subband_pyramid->volume array previously allocated by QccWAVSubbandPyramid3DAlloc().

QccWAVSubbandPyramid3DNumLevelsToNumSubbandsDyadic() calculates the number of subbands in a dyadic subband pyramid with num_levels levels. This value is num_levels * 7 + 1.

QccWAVSubbandPyramid3DNumLevelsToNumSubbandsPacket() calculates the number of subbands in a wavelet-packet subband pyramid with temporal_num_levels temporal levels and spatial_num_levels spatial levels. This value is QccWAVSubbandPyramidNumLevelsToNumSubbands( spatial_num_levels) * temporal_num_levels + 1.

QccWAVSubbandPyramid3DNumSubbandsToNumLevelsDyadic() calculates the number of levels in a dyadic subband pyramid with num_subbands subbands.

QccWAVSubbandPyramid3DCalcLevelFromSubbandDyadic() calculates the level of the specified subband in a dyadic subband pyramid with num_levels levels. Here, subband gives the subband number of the subband in the pyramid.

QccWAVSubbandPyramid3DCalcLevelFromSubbandPacket() calculates the levels of the specified subband in a wavelet-packet subband pyramid with temporal_num_levels temporal levels and spatial_num_levels spatial levels. Here, subband gives the subband number of the subband in the pyramid. The temporal level of the specified subband is returned in temporal_level while the spatial level of the subband is returned in spatial_level.

QccWAVSubbandPyramid3DSubbandSize() calculates the size of the specified subband in subband_pyramid. The size of the subband is returned in subband_num_frames, subband_num_rows, and subband_num_cols, which must be allocated prior to calling QccWAVSubbandPyramid3DSubbandSize().

QccWAVSubbandPyramid3DSubbandOffsets() calculates the location in subband_pyramid->volume of the specified subband. The frame, row, and column offsets are returned in frame_offset, row_offset, and col_offset, respectively, which must be allocated prior to calling QccWAVSubbandPyramid3DSubbandOffsets().

QccWAVSubbandPyramid3DPrint() prints the contents of subband_pyramid to stdout.

RETURN VALUE

These routines return 0 on success, and 1 on failure.

AUTHOR

Table of Contents

NAME
SYNOPSIS
DESCRIPTION
DATA STRUCTURE
FILE FORMAT
ROUTINES
RETURN VALUE
SEE ALSO
AUTHOR