SYNOPSIS

#include <vips/vips.h>

int
im_global_balance( IMAGE *in, IMAGE *out, double gamma )

int
im_global_balance_float( IMAGE *in, IMAGE *out, double gamma )

DESCRIPTION

These functions takes an image assembled with the mosaicing functions (im_*merge*(), im_*mosaic*()), take it apart, and reassemble it, globally optimising the image balance. This is useful for assembling image mosaics from sources where the exposure is uncontrolled and may vary from tile to tile --- such as video, or photographic sources.

The function finds a set of factors, one for each of the input images, and scales each image by its factor before reassembling. The factors are chosen so as to minimise the average grey-level difference between neighboring images at their overlaps. Trivial overlaps (where the width and height of the overlap are both less than 20 pixels) are ignored.

The gamma parameter is the gamma of the image input system. It is used during brightness adjustment. Set to 1.0 to disable gamma, to 1.6 for a typical IR vidicon camera, or 2.3 for a typical video camera.

It relies on information left by the mosaicing functions in ".desc" files. If the ".desc" file of the input image has been corrupted, or is strangely complicated, or if any of the original input images have been moved or deleted, the function can fail.

The function will fail for mosaics larger than about 7 by 7 frames, since it will run out of file descriptors (UNIX sets a limit of 256 per process). To balance larger mosaics, just assemble them in 7x7 sections, balancing and saving each part in turn, before loading, assembling and balancing the final image. The function can also fail if there are significant mosaicing errors.

im_global_balancef() works as im_global_balance(), but outputs a float rather than a uchar image. This lets you adjust the range of the image manually, if the automatically-found scales are causing burn-out.

RETURN VALUE

All functions return 0 on success and -1 on error.

COPYRIGHT

Birkbeck College and the National Gallery, 1991 - 1995.