wvBool wvBasisPackIntoMatrix(const WVbasis basis, WVmatrix *targetMatrix);

wvBuildBasis returns a WVbasis for matrix by applying the coarse and detail filters (transforms) of wavelet successively to each component (i.e., tensor products) of matrix. This is the wavelet decomposition stage. Where necessary, matrix is extended by applying the extension function.

wvReconstructFromBasisIntoMatrix reconstructs a WVbasis into an existing matrix, whereas wvReconstructFromBasis creates and returns a matrix reconstructed from basis. Both work by applying the coarse and detail reconstruction filters (transforms) of wavelet. Where necessary, the coarse and detail coefficients are extended by applying coarseExt or detailExt, respectively.

wvDestroyBasis frees the memory used by basis. It is the application programmer's responsibility to free this memory (by calling this function).

The *ByDim* functions allow the programmer to specify a different wavelet (and extension method) for each of the dimensions (coordinate directions) of the matrix. These functions take arrays of wavelets and extension methods. These arrays must be of length equivalent to the number of dimensions of the data. In each dimension, the corresponding wavelet and extension functions are applied.

The *ByLevel* functions allow the programmer to specify a different wavelet (and extension method) for each of the level of the decomposition/reconstruction. These functions take arrays of wavelets and extension methods. These arrays must be of length equivalent to the number of dyadic levels of the data. At each level, the corresponding wavelet and extension functions are applied.

wvBasisPackIntoMatrix takes the coefficients of a regular basis and packs them into a single matrix (whose size must be the same as the size of the original data). The all-detail submatrices will be represented by the block-diagonal portion of the matrix starting with the smallest (singleton) submatrix at (1,1,...1). The rest will be stored around that block diagonal in the intuitive way. The element of the matrix at (0,0,...0) will hold the singleton all-coarse coefficient. This routine only accepts bases of square dyadic original data.

The process

The process of creating a WVbasis from a matrix and then reconstructing a matrix from that WVbasis is lossless, to machine precision. A WVbasis may be compressed by some lossy method in the interim (by quantizing the coefficients with wvBasisApplyThreshold, for example) and the reconstruction process then yields an approximation of the original matrix.

Predefined wavelet filters

Predefined wavelet filters can be used by including the file wv_filter_std.h. The predefined wavelets are:

WV_HAAR_WAVELET	Haar wavelet (Daubechies' 1st-order wavelet)
WV_BIORTH_2_2_WAVELET	Biorthogonal 2/2 wavelet (an alternate implementation of the Haar wavelet)
WV_BIORTH_2_6_WAVELET	Biorthogonal 2/6 wavelet
WV_BIORTH_6_10_WAVELET	Biorthogonal 6/10 wavelet

The library also has two extension functions: wvSymmetricEvenExt and wvSymmetricOddExt. Normally, wvSymmetricEvenExt is used for extending the matrix and the coarse coefficients, and wvSymmetricOddExt is used for extending the detail coefficients.

The WVbasis structure

The WVbasis structure is an array of WVbasisMatrix pointers. For this reason, the datatype can also be referenced as a WVbasisMatrixPtrArr.

A WVbasisMatrix is a block-diagonal matrix. This is implemented as a WVmatrix array, with each WVmatrix representing a block on the diagonal. The array goes from the upper-left block to the lower-right block. The last block is always a singleton matrix and none of the other blocks are singletons, so there is no need to store the length of the array.

A WVbasis includes a number of WVbasisMatrices, one for each combination of coarse and detail filters for the number of dimensions represented. For example, when representing a 2-D matrix (an image), a WVbasis would be be composed of four WVbasisMatrices: one for each combination coarse-coarse, coarse-detail, detail-coarse, and detail-detail.

The WVbasis structure is defined in <wv/bas_normal.h> as follows:

typedef struct _WVbasisMatrix {
    WVmatrix **mat;    /* array of matrices (the diagonal sub-matrices) */
} WVbasisMatrix, *WVbasisMatrixPtr, **WVbasisMatrixPtrArr;

#define WVbasis WVbasisMatrixPtrArr

#include <wv/bas_normal.h>
#include <wv/wv_filter_std.h>
  
    .
    .
    .
{
    WVmatrix *orig;
    WVmatrix *recon;
    WVbasis basis;

    /* The orig matrix data is initialized */
    .
    .
    .

    basis = wvBuildBasis(orig, WV_BIORTH_6_10_WAVELET,
	    wvSymmetricEvenExt);

    /* The WVbasis is processed for compression or other
     * objectives
     */
    .
    .
    .

    recon = wvReconstructFromBasis(basis,
	    WV_BIORTH_6_10_WAVELET, wvSymmetricEvenExt,
	    wvSymmetricOddExt);

    wvDestroyBasis(basis);
}