.TH QCCWAVPERCEPTUALWEIGHTS 3 "QCCPACK" "".SH NAMEQccWAVPerceptualWeights \- data structurefor 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 DESCRIPTIONQccPack provides data structure.B QccWAVPerceptualWeightsfor the perceptual weighting of the subbands in adyadic subband pyramid (data type.BR QccWAVSubbandPyramid )decomposition of an image.The.B QccWAVPerceptualWeightsstructure contains a list of weighting factors, one for eachsubband of a subband pyramid.  These weights can be applied to a.B QccWAVSubbandPyramidstructure to give each subband weight appropriate to the relativeperceptual importance of that subband, as established byperceptual tests with human observers.The values used as perceptual weights by.B QccPackare the reciprocals of the just-noticeable distortions (JND)for the subbands (see Hontsch.IR "et al" .)..SH "DATA STRUCTURE"The.B QccWAVPerceptualWeightsdata structure is defined as:.RS.nftypedef struct{  QccString filename;  QccString magic_num;  int major_version;  int minor_version;  int num_subbands;  QccVector perceptual_weights;} QccWAVPerceptualWeights;.fi.RE.LPThe fields of.B QccWAVPerceptualWeightsare as follows:.TP.I filenameThe name of the file..TP.IR magic_num ", " major_version ", " minor_versionThe magic number and version of the file..TP.IR num_subbandsThe number perceptual weight in.IR perceptual_weights ..TP.IR perceptual_weightsThe perceptual weights..SH "FILE FORMAT"For reading and writing structuresof type.BR QccWAVPerceptualWeights ,QccPack provides the.B PCPfile format.This file format starts with an ASCII header followed byASCII data.The ASCII header consists of magic-number/revisioninformationfollowed by any amount of white space(space, `\\t' (tab), `\\n' (newline), `\\r' (return)) and/orcomments lines (lines starting with `#').  Following this white space,additional ASCIIheader information is given, separated by blanks and newlines.ASCII data follows this ASCII header information..LPThe.B PCPfile format consists of the following information:.RS.sp.BI PCP X.X.br.I "<white space>"                                                   .br.I "N".br.IR "w1 w2" \|.\|.\|..sp.REwhere.IR Nis the number of perceptual weights contained in the file (which is equalto the number of subbands in the subband pyramid for which the fileis to be used).The perceptual weights follow, each stored as a double in ASCII, separatedby blanks and/or CRs..SH "ROUTINES".B QccWAVPerceptualWeightsInitialize()should be called before any use of a.B QccWAVPerceptualWeightsstructure..B QccWAVPerceptualWeightsInitialize()initializes the fields of.I perceptual_weightsto the following values:.RS.IR filename :.B NULLstring.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_weightsarray.If .I perceptual_weights->perceptual_weightsis not.BR NULL ,.B QccWAVPerceptualWeightsAlloc()returns immediately without changing the state of any memory allocation.Otherwise,the .I perceptual_weights->perceptual_weightsarray 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_weightsarray previously allocated by.BR QccWAVPerceptualWeightsAlloc() ..LP.B QccWAVPerceptualWeightsRead()reads perceptual weights from the .BR PCP -formatfile 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_PATHfor a file whose name matches.IR perceptual_weights->filename .The contents of the first such file found are readinto.IR perceptual_weight->perceptual_weights .If .I perceptual_weights->perceptual_weightsis .BR NULL ,.I perceptual_weights->perceptual_weightsis allocated via a call to .B QccWAVPerceptualWeightsAlloc()prior toreading; otherwise, it is assumed that sufficient space has alreadybeen allocated..LP.B QccWAVPerceptualWeightsWrite()writes the .BR PCP -formatfile whose filename is given by .IR perceptual_weights->filename ..I perceptual_weights->perceptual_weightsis assumed to be allocated and to contain all.I perceptual_weights->num_subbandsweight values..LP.B QccWAVPerceptualWeightsPrint()prints a format output list of.I perceptual_weights->perceptual_weightsto stdout..LP.B QccWAVPerceptualWeightsApply()applies the perceptual weights given in.I perceptual_weightsto.I subband_pyramidby multiplying each wavelet coefficient in.I subband_pyramid->matrixwith the appropriate weight value (as determined by the subband in which thecoefficient resides) from.IR perceptual_weights->perceptual_weights .The number of subbands specified by.I perceptual_weightsmust match that specified by.IR subband_pyramid ..LP.B QccWAVPerceptualWeightsRemove()performs the reverse operation of.BR QccWAVPerceptualWeightsApply() ;namely, each coefficient in .I subband_pyramid->matrixis 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).LPI. Hontsch, L. J. Karam, and R, J. Safranek, "A Perceptually Tuned EmbeddedZerotree Image Coder," in .I "Proceedings of the International Conference on Image Processing" ,vol. 1, pp. 41-44, Oct. 1997..LPN. Jayant, J. Johnston, and R. Safranek, "Signal Compression Based on Modelsof Human Perception,".IR "Proceedings of the IEEE" ,vol. 81, no. 10, pp. 1385-1422, Oct. 1993..SH AUTHORCopyright (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.