QccWAVPerceptualWeightsPrint.3

NAME

QccWAVPerceptualWeights - data structure for perceptual weighting of subbands

int QccWAVPerceptualWeightsInitialize(QccWAVPerceptualWeights *perceptual_weights);
int QccWAVPerceptualWeightsAlloc(QccWAVPerceptualWeights *perceptual_weights);
void QccWAVPerceptualWeightsFree(QccWAVPerceptualWeights *perceptual_weights);
int QccWAVPerceptualWeightsRead(QccWAVPerceptualWeights *perceptual_weights);
int QccWAVPerceptualWeightsWrite(const QccWAVPerceptualWeights *perceptual_weights);
int QccWAVPerceptualWeightsPrint(const QccWAVPerceptualWeights *perceptual_weights);
int QccWAVPerceptualWeightsApply(QccWAVSubbandPyramid *subband_pyramid, const QccWAVPerceptualWeights *perceptual_weights);
int QccWAVPerceptualWeightsRemove(QccWAVSubbandPyramid *subband_pyramid, const QccWAVPerceptualWeights *perceptual_weights);

DESCRIPTION

QccPack provides data structure QccWAVPerceptualWeights for the perceptual weighting of the subbands in a dyadic subband pyramid (data type QccWAVSubbandPyramid) decomposition of an image. The QccWAVPerceptualWeights structure contains a list of weighting factors, one for each subband of a subband pyramid. These weights can be applied to a QccWAVSubbandPyramid structure to give each subband weight appropriate to the relative perceptual importance of that subband, as established by perceptual tests with human observers. The values used as perceptual weights by QccPack are the reciprocals of the just-noticeable distortions (JND) for the subbands (see Hontsch et al.).

DATA STRUCTURE

The QccWAVPerceptualWeights data structure is defined as:

typedef struct
{
QccString filename;
QccString magic_num;
int major_version;
int minor_version;
int num_subbands;
QccVector perceptual_weights;
} QccWAVPerceptualWeights;

The fields of QccWAVPerceptualWeights are as follows:

filename: The name of the file.
magic_num, major_version, minor_version: The magic number and version of the file.
num_subbands: The number perceptual weight in perceptual_weights.
perceptual_weights: The perceptual weights.

FILE FORMAT

For reading and writing structures of type QccWAVPerceptualWeights, QccPack provides the PCP file format. This file format starts with an ASCII header followed by ASCII data. The ASCII header consists of magic-number/revision information followed by any amount of white space (space, `\t' (tab), `\n' (newline), `\r' (return)) and/or comments lines (lines starting with `#'). Following this white space, additional ASCII header information is given, separated by blanks and newlines. ASCII data follows this ASCII header information.

The PCP file format consists of the following information:

PCPX.X
<white space>
N
w1 w2...

where N is the number of perceptual weights contained in the file (which is equal to the number of subbands in the subband pyramid for which the file is to be used). The perceptual weights follow, each stored as a double in ASCII, separated by blanks and/or CRs.

ROUTINES

QccWAVPerceptualWeightsInitialize() should be called before any use of a QccWAVPerceptualWeights structure. QccWAVPerceptualWeightsInitialize() initializes the fields of perceptual_weights to the following values:

filename: NULL string
magic_num: QCCPERCEPTUALWEIGHTS_MAGICNUM
major_version, minor_version: initialized to output of QccGetQccPackVersion(3)
num_subbands: 0
perceptual_weights: NULL

QccWAVPerceptualWeightsAlloc() allocates storage space for the perceptual_weights->perceptual_weights array. If perceptual_weights->perceptual_weights is not NULL, QccWAVPerceptualWeightsAlloc() returns immediately without changing the state of any memory allocation. Otherwise, the perceptual_weights->perceptual_weights array is allocated. The value for num_subbands must be set prior to calling QccWAVPerceptualWeightsAlloc().

QccWAVPerceptualWeightsFree() frees the perceptual_weights->perceptual_weights array previously allocated by QccWAVPerceptualWeightsAlloc().

QccWAVPerceptualWeightsRead() reads perceptual weights from the PCP-format file given by perceptual_weights->filename, which must be set before calling QccWAVPerceptualWeightsRead(). QccWAVPerceptualWeightsRead() searches the path given by the environment variable QCCPACK_WAVELET_PATH for a file whose name matches perceptual_weights->filename. The contents of the first such file found are read into perceptual_weight->perceptual_weights. If perceptual_weights->perceptual_weights is NULL, perceptual_weights->perceptual_weights is allocated via a call to QccWAVPerceptualWeightsAlloc() prior to reading; otherwise, it is assumed that sufficient space has already been allocated.

QccWAVPerceptualWeightsWrite() writes the PCP-format file whose filename is given by perceptual_weights->filename. perceptual_weights->perceptual_weights is assumed to be allocated and to contain all perceptual_weights->num_subbands weight values.

QccWAVPerceptualWeightsPrint() prints a format output list of perceptual_weights->perceptual_weights to stdout.

QccWAVPerceptualWeightsApply() applies the perceptual weights given in perceptual_weights to subband_pyramid by multiplying each wavelet coefficient in subband_pyramid->matrix with the appropriate weight value (as determined by the subband in which the coefficient resides) from perceptual_weights->perceptual_weights. The number of subbands specified by perceptual_weights must match that specified by subband_pyramid.

QccWAVPerceptualWeightsRemove() performs the reverse operation of QccWAVPerceptualWeightsApply(); namely, each coefficient in subband_pyramid->matrix is divided by the appropriate weight in perceptual_weights->perceptual_weights.

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