Intel® Integrated Performance Primitives (Intel® IPP) Developer Guide and Reference

ID 790148
Date 3/22/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

WTFwd

Performs one-level wavelet decomposition of an image.

Syntax

IppStatus ippiWTFwd_32f_C1R (const Ipp32f* pSrc, int srcStep, Ipp32f* pApproxDst, int approxStep, Ipp32f* pDetailXDst, int detailXStep, Ipp32f* pDetailYDst, int detailYStep, Ipp32f* pDetailXYDst, int detailXYStep, IppiSize dstRoiSize, const IppiWTFwdSpec_32f_C1R* pSpec, Ipp8u* pBuffer);

IppStatus ippiWTFwd_32f_C3R (const Ipp32f* pSrc, int srcStep, Ipp32f* pApproxDst, int approxStep, Ipp32f* pDetailXDst, int detailXStep, Ipp32f* pDetailYDst, int detailYStep, Ipp32f* pDetailXYDst, int detailXYStep, IppiSize dstRoiSize, const IppiWTFwdSpec_32f_C3R* pSpec, Ipp8u* pBuffer);

Include Files

ippi.h

Parameters

pSrc
Pointer to the source image ROI.
srcStep
Distance, in bytes, between the starting points of consecutive lines in the source image buffer.
pApproxDst
Pointer to ROI of the destination approximation image.
approxStep
Distance, in bytes, between the starting points of consecutive lines in the approximation image buffer.
pDetailXDst
Pointer to ROI of the destination horizontal detail image.
detailXStep
Distance, in bytes, between the starting points of consecutive lines in the horizontal detail image buffer.
pDetailYDst
Pointer to ROI of the destination vertical detail image.
detailYStep
Distance, in bytes, between the starting points of consecutive lines in the vertical detail image buffer.
pDetailXYDst
Pointer to ROI of the destination diagonal detail image.
detailXYStep
Distance, in bytes, between the starting points of consecutive lines in the diagonal detail image buffer.
dstRoiSize
Size of the ROI in pixels for all destination images.
pSpec
Pointer to the allocated and initialized forward DWT specification structure.
pBuffer
Pointer to the allocated buffer for intermediate operations

Description

This function operates with ROI (see Regions of Interest in Intel IPP). This function performs one-level wavelet decomposition of a source image pointed to by pSrc into four destination subimages pointed to by pApproxDst, pDetailXDst, pDetailYDst, and pDetailXYDst. See Figure “Equivalent Scheme of Wavelet Decomposition Algorithm” for the equivalent algorithm of ippiWTFwd function operation.

Wavelet parameters are contained in the forward transform specification structure pSpec. Before using this function, compute the size of the structure and work buffer using the WTFwdGetSize function and initialize the structure using WTFwdInit.

Product and Performance Information

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.

Notice revision #20201201

The pointer pSrc points to memory location of the source image rectangular ROI of size srcWidth by srcHeight which is uniquely determined by the size of destination ROI as:

srcWidth = 2 * dstRoiSize.width

srcHeight = 2 * dstRoiSize.height

The source image ROI size always has even dimensions, as it is computed from the dstRoiSize parameter as follows:

srcRoiSize.width = 2 * dstRoiSize.width

srcRoiSize.height = 2 * dstRoiSize.height

To use this function for images with uneven width or height, you should truncate the last column/row or extend an image to even dimensions.

NOTE:

The source image ROI does not include border pixels necessary to compute some destination pixels. It means that prior to using ippiWTFwd function the application program must apply some border extension model (symmetrical, wraparound or another) to the source image ROI through filling of neighboring memory locations. As a result, the size of memory block allocated for the source image must be extended to accommodate for added border pixels outside ROI formal boundaries.

Figure “Extended Source Image for Wavelet Decomposition” schematically shows the source image ROI and extended image area.

Extended Source Image for Wavelet Decomposition

Use the following C-language expressions to calculate extended image border sizes:

int leftBorderLow   = lenLow   - 1 - anchorLow;
int leftBorderHigh  = lenHigh  - 1 - anchorHigh;
int rightBorderLow  = anchorLow;
int rightBorderHigh = anchorHigh;
int leftTopBorder     = IPP_MAX(leftBorderLow, leftBorderHigh);
int rightBottomBorder = IPP_MAX(rightBorderLow, rightBorderHigh);

See the description of the function WTFwdInit for the explanation of the parameters.

Note that the left and top borders have equal size. The same holds for the right and bottom borders which have equal size too.

The size of the source image area extended by border pixels can be defined as

srcWidthWithBorders = srcWidth  + leftTopBorder + rightBottomBorder;    
srcHeightWithBorders = srcHeight + leftTopBorder + rightBottomBorder;

All destination images have equal size specified by the parameter dstRoiSize.

Conversely, to perform a wavelet reconstruction of the full size source image from the component images obtained by decomposition, use extended component images for the reconstruction pass. See the description of the function ippiWTInv for more details.

The ROI concept used in wavelet transform functions can be applied to processing large images by blocks, or ‘tiles'. To accomplish this, the source image should be subdivided into overlapping blocks in the following way:

  • Main part (ROI) of each block is adjacent to neighboring blocks and has no intersection with neighbor's ROIs;
  • Extended borders of each block overlap with ROIs of neighboring blocks.

This subdivision scheme is illustrated in Figure “Image Division into Blocks with Overlapping Borders” .

Image Division into Blocks with Overlapping Borders

For an example on how to use this function, refer to the example provided with the WTInv function description.

Return Values

ippStsNoErr

Indicates no error. Any other value indicates an error or a warning.

ippStsNullPtrErr

Indicates an error condition if any of the specified pointers is NULL.

ippStsSizeErr

Indicates an error condition if dstRoiSize has a field with zero or negative value.

ippStsStepErr

Indicates an error condition if step through any buffer is less than or equal to zero.

ippStsContextMatchErr

Indicates an error condition if a pointer to an invalid specification structure is passed.

See Also