#include <gandalf/image/image_pyramid.h>
A quite common construction in image processing is a ``pyramid'' of
images, a multi-resolution representation of an image. We think in fact
of an inverted pyramid, with the top level of the pyramid representing
the image at the original resolution, and lower levels representing the
image at lower resolutions (the inversion of the pyramid is to avoid
changing the sense of ``high'' and ``low'' between describing the
``resolution'' and the ``level''). The pyramid is constructed as an
array of structures, one for each resolution level. The structure is
defined as
/* structure to hold image and mask at a single pyramid level */
typedef struct Gan_ImagePyramid
{
Gan_Image *img; /* image represented at a single resolution level */
Gan_Image *mask; /* mask at this level defining which pixels are set */
} Gan_ImagePyramid;
Intrinsic to the pyramid is the notion of a ``mask'' of pixels, a binary
image defining which pixels are available in the image. The convention is
that available pixels are marked in the mask as ones. Gandalf currently
supports pyramids produced in the simplest way, by averaging four adjacent
pixels to convert the image from a higher resolution image to a lower
resolution image. An example code fragment to create an image pyramid is
Gan_Image *pImage, *pMask; /* declare image and mask */
Gan_ImagePyramid *aPyramid;
/* ... create and fill pImage and pMask ... */
/* build image with four resolution levels */
gan_image_pyramid_build ( pImage, pMask, 4, &aPyramid );
The image and mask pointer at the original (highest) resolution levels can
be accessed as aPyramid[0].img and aPyramid[0].mask respectively.
There are four levels here so the lowest resolution image and mask are
aPyramid[3].img and aPyramid[3].mask. The mask can be passed
into gan_image_pyramid_build() as NULL, indicating that
all the pixels in the image are available. In this case the masks at all
resolution levels will be set to NULL.
To free the pyramid, use
gan_image_pyramid_free ( aPyramid, 4, GAN_FALSE );
The second argument here is the number of resolution levels of the pyramid.
The last argument determines whether the image/mask at the top level of
the pyramid are to freed. Here GAN_FALSE is passed, so the original
image pImage and mask pMask will not be freed and are available
for further processing.
Note that when transferring pixels to a lower resolution, a pixel is computed and a mask bit at the lower resolution only if all four corresponding pixels in the higher resolution image are set.
Error detection: gan_image_pyramid_build() returns a boolean value, which is GAN_FALSE on error, the Gandalf error handler being invoked.