NAME

cxPyrDictCompress - compresses the reference element pyramids in a pyramid dictionary

C SPECIFICATION

#include <cx/Pyramid.h>


cxPyramidDictionary * cxPyrDictCompress( cxPyramidDictionary *src, long layer)

FORTRAN SPECIFICATION

integer function cxPyrDictCompress(src, layer)
integer src
integer layer

PARAMETERS

src
Input pyramid dictionary data structure.
layer
Input layer to which to compress the dictionary.

FUNCTION RETURN VALUE

The returned value for this function is a pointer to the newly compressed pyramid dictionary.

DESCRIPTION

cxPyrDictCompress makes a compressed version of its input pyramid dictionary, which can be used to convert a pyramid compressed at one layer to one compressed at a lower layer. Such an operation is useful in creating a module that operates on compressed pyramids of all layers, but has a preferred layer of operation (while it is possible to expand the input pyramid, it may be very inefficient to do so; converting the compressed input to the desired level may be more efficient). However, the returned cxPyramidDictionary structure is not a valid dictionary and must not be used as part of a compressed pyramid. Given a pyramid compressed at one layer, there are three steps to creating an equivalent pyramid compressed at a lower layer. For instance, consider the case of recompressing a solid element pyramid compressed at layer 3 to a planar element pyramid compressed at layer 2. The first step is to compute the representation of each layer 3 reference element (the solid elements in the 3D dictionary) as a collection of layer 2 elements; each 3D element is then stored as a pyramid compressed at layer 2. The second step is to merge all of the layer 2 elements into a single 2D pyramid dictionary, updating the references of the compressed 3D elements so that they all refer to this single pyramid dictionary. The third step is to rewrite the original 3D compressed pyramid in terms of the new 2D pyramid dictionary, converting each reference to a 3D dictionary element into several references to 2D dictionary elements. cxPyrDictCompress performs the first two steps of this operation, creating a cxPyramidDictionary structure having a compressed pyramid for each uncompressed pyramid in the src dictionary; all the compressed reference pyramids refer to the same layer dictionary. Given the returned cxPyramidDictionary structure, it is straightforward to construct the recompressed pyramid at the new layer (step 3). For instance, the modules ShrinkPyr and ExteriorPyr use this routine to perform the layer conversion on compressed inputs. It is important to note that the returned cxPyramidDictionary structure is not valid for use in a compressed pyramid; it is only a convenient form in which to represent the translation between the old compression layer and the new layer. If layer is greater than or equal to the compression layer of src, a NULL pointer is returned. The returned pyramid dictionary is a reference counted structure owned by the caller. After using the structure, it may be deleted with cxDataRefDec.

SEE ALSO

cxPyrCompress(3E), cxDataRefInc(3E), ShrinkPyr(1E), ExteriorPyr(1E)
Last modified: Mon Nov 18 13:52:34 GMT 1996
[ Documentation Home ]
© The Numerical Algorithms Group Ltd, Oxford UK. 1996