.TH IM_GLOBAL_BALANCE 3 "13 May 1991"
.SH NAME
im_global_balance, im_global_balancef \- perform global mosaic balancing on 
an image
.SH SYNOPSIS
#include <vips/vips.h>

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

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

.SH 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.

.SH RETURN VALUE
All functions return 0 on success and -1 on error.
.SH SEE ALSO
im_lrmerge(3), im_lrmosaic(3).
.SH COPYRIGHT
Birkbeck College and the National Gallery, 1991 - 1995.