qccwavperceptualweights.3

QccPack implementation in C

.TH QCCWAVPERCEPTUALWEIGHTS 3 "QCCPACK" ""
.SH NAME
QccWAVPerceptualWeights \- data structure
for perceptual weighting of subbands
.SH SYNOPSIS
.B #include "libQccPack.h"
.sp
.BI "int QccWAVPerceptualWeightsInitialize(QccWAVPerceptualWeights *" perceptual_weights );
.br
.BI "int QccWAVPerceptualWeightsAlloc(QccWAVPerceptualWeights *" perceptual_weights );
.br
.BI "void QccWAVPerceptualWeightsFree(QccWAVPerceptualWeights *" perceptual_weights );
.br
.BI "int QccWAVPerceptualWeightsRead(QccWAVPerceptualWeights *" perceptual_weights );
.br
.BI "int QccWAVPerceptualWeightsWrite(const QccWAVPerceptualWeights *" perceptual_weights );
.br
.BI "int QccWAVPerceptualWeightsPrint(const QccWAVPerceptualWeights *" perceptual_weights );
.br
.BI "int QccWAVPerceptualWeightsApply(QccWAVSubbandPyramid *" subband_pyramid ", const QccWAVPerceptualWeights *" perceptual_weights );
.br
.BI "int QccWAVPerceptualWeightsRemove(QccWAVSubbandPyramid *" subband_pyramid ", const QccWAVPerceptualWeights *" perceptual_weights );
.SH DESCRIPTION
QccPack provides data structure
.B QccWAVPerceptualWeights
for the perceptual weighting of the subbands in a
dyadic subband pyramid (data type
.BR QccWAVSubbandPyramid )
decomposition of an image.
The
.B QccWAVPerceptualWeights
structure contains a list of weighting factors, one for each
subband of a subband pyramid.  These weights can be applied to a
.B 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
.B QccPack
are the reciprocals of the just-noticeable distortions (JND)
for the subbands (see Hontsch
.IR "et al" .).
.SH "DATA STRUCTURE"
The
.B QccWAVPerceptualWeights
data structure is defined as:
.RS
.nf

typedef struct
{
  QccString filename;
  QccString magic_num;
  int major_version;
  int minor_version;
  int num_subbands;
  QccVector perceptual_weights;
} QccWAVPerceptualWeights;
.fi
.RE
.LP
The fields of
.B QccWAVPerceptualWeights
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 num_subbands
The number perceptual weight in
.IR perceptual_weights .
.TP
.IR perceptual_weights
The perceptual weights.
.SH "FILE FORMAT"
For reading and writing structures
of type
.BR QccWAVPerceptualWeights ,
QccPack provides the
.B 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.
.LP
The
.B PCP
file format consists of the following information:
.RS
.sp
.BI PCP X.X
.br
.I "<white space>"                                                   
.br
.I "N"
.br
.IR "w1 w2" \|.\|.\|.
.sp
.RE
where
.IR 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.
.SH "ROUTINES"
.B QccWAVPerceptualWeightsInitialize()
should be called before any use of a
.B QccWAVPerceptualWeights
structure.
.B QccWAVPerceptualWeightsInitialize()
initializes the fields of
.I perceptual_weights
to the following values:
.RS

.IR filename :
.B NULL
string
.br
.IR magic_num :
.B QCCPERCEPTUALWEIGHTS_MAGICNUM
.br
.IR major_version ", " minor_version :
initialized to output of 
.BR QccGetQccPackVersion (3)
.br
.IR num_subbands :
0
.br
.IR perceptual_weights :
.B NULL
.RE
.LP
.B QccWAVPerceptualWeightsAlloc()
allocates storage space for the
.I perceptual_weights->perceptual_weights
array.
If 
.I perceptual_weights->perceptual_weights
is not
.BR NULL ,
.B QccWAVPerceptualWeightsAlloc()
returns immediately without changing the state of any memory allocation.
Otherwise,
the 
.I perceptual_weights->perceptual_weights
array is allocated.
The value for
.IR num_subbands 
must be set prior to calling
.BR QccWAVPerceptualWeightsAlloc() .
.LP
.B QccWAVPerceptualWeightsFree()
frees the
.I perceptual_weights->perceptual_weights
array previously allocated by
.BR QccWAVPerceptualWeightsAlloc() .
.LP
.B QccWAVPerceptualWeightsRead()
reads perceptual weights from the 
.BR PCP -format
file given by
.IR perceptual_weights->filename ,
which must be set before calling
.BR QccWAVPerceptualWeightsRead() .
.B QccWAVPerceptualWeightsRead()
searches the path given by the environment variable
.B QCCPACK_WAVELET_PATH
for a file whose name matches
.IR perceptual_weights->filename .
The contents of the first such file found are read
into
.IR perceptual_weight->perceptual_weights .
If 
.I perceptual_weights->perceptual_weights
is 
.BR NULL ,
.I perceptual_weights->perceptual_weights
is allocated via a call to 
.B QccWAVPerceptualWeightsAlloc()
prior to
reading; otherwise, it is assumed that sufficient space has already
been allocated.
.LP
.B QccWAVPerceptualWeightsWrite()
writes the 
.BR PCP -format
file whose filename is given by 
.IR perceptual_weights->filename .
.I perceptual_weights->perceptual_weights
is assumed to be allocated and to contain all
.I perceptual_weights->num_subbands
weight values.
.LP
.B QccWAVPerceptualWeightsPrint()
prints a format output list of
.I perceptual_weights->perceptual_weights
to stdout.
.LP
.B QccWAVPerceptualWeightsApply()
applies the perceptual weights given in
.I perceptual_weights
to
.I subband_pyramid
by multiplying each wavelet coefficient in
.I subband_pyramid->matrix
with the appropriate weight value (as determined by the subband in which the
coefficient resides) from
.IR perceptual_weights->perceptual_weights .
The number of subbands specified by
.I perceptual_weights
must match that specified by
.IR subband_pyramid .
.LP
.B QccWAVPerceptualWeightsRemove()
performs the reverse operation of
.BR QccWAVPerceptualWeightsApply() ;
namely, each coefficient in 
.I subband_pyramid->matrix
is divided by the appropriate weight in
.IR perceptual_weights->perceptual_weights .
.SH "RETURN VALUE"
These routines return 0 on success, and 1 on failure.
.SH "SEE ALSO"
.BR QccPackWAV (3),
.BR QccWAVSubbandPyramid (3),
.BR QccPack (3)
.LP
I. Hontsch, L. J. Karam, and R, J. Safranek, "A Perceptually Tuned Embedded
Zerotree Image Coder," in 
.I "Proceedings of the International Conference on Image Processing" ,
vol. 1, pp. 41-44, Oct. 1997.
.LP
N. Jayant, J. Johnston, and R. Safranek, "Signal Compression Based on Models
of Human Perception,"
.IR "Proceedings of the IEEE" ,
vol. 81, no. 10, pp. 1385-1422, Oct. 1993.
.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.