IM_HISTGR(3)

NAME
im_histcum, im_histeq, im_histgr, im_histnD, im_histnorm, im_histplot, im_histspec, im_identity, im_identity_ushort, im_ismonotonic - create, display and process histograms or luts

SYNOPSIS
#include <vips/vips.h> int im_histgr( in, out, bandno)
IMAGE *in, *out;
int bandno; int im_histnD( in, out, bins )
IMAGE *in, *out;
int bins; int im_histplot(hist, histplot)
IMAGE *hist, *histplot; int im_histcum(hist, lut)
IMAGE *hist, *lut; int im_histnorm(hist, lut)
IMAGE *hist, *lut; int im_histeq(hist, lut)
IMAGE *hist, *lut; int im_histspec(histin, histref, lut)
IMAGE *histin, *histref, *lut; int im_identity(lut, bands)
IMAGE *lut;
int bands; int im_identity_ushort(lut, bands, sz)
IMAGE *lut;
int bands;
int sz; int im_ismonotonic( IMAGE *lut, int *out )

DESCRIPTION
im_histgr() writes the histogram of image in to image out. If bandno is zero, then out will have the same number of bands as in, and each band of out will have the histogram of the corresponding band of in. Otherwise, bandno selects the band of the image for which the histogram will be found. Image in may be either FMTUCHAR or FMTUSHORT. If in is uchar, then out will have 256 elements, one for each possible pixel value. If in is ushort, then im_histgr() finds the maximum of in, and outputs a histogram with max + 1 elements. For example, suppose you have an image from a 12-bit camera, where each pixel is in the range [0,4095]. Calling im_histgr() for this image will make a histogram with at most 4096 elements. If the histogram is smaller than this, then it means that the right hand end of the histogram was all zero, and has not been generated. Also check im_histnD() below for another way to make histograms. im_histnD() makes a n-dimensional histogram from an n-band image (1, 2 and 3 bands only). Because 3D histograms can get very large very quickly, the bins parameter sets the length of each dimension, that is, the number of bins the possible numeric range of the image is divided into. Unsigned 8 and 16 bit images only. Use im_histplot() to graph the histogram for visualisation. im_histplot() graphs the LUT or histogram hist. The input image in should be an n x 1 or 1 x n image of any non-complex format. This is transformed to a n x 256 or 256 x n output image (a horizontal or vertical graph, respectively) in which the n axis represents pixel values, and the 256-pixel axis represents frequency. If input is an lut (BBCHAR, FMTUCHAR), no scaling is carried out (min and max are set to 0 and 255 respectively). In all other cases the output is scaled in such a way that: min(input)->0 and max(input)->255. If input is unsigned (for instance FMTUCHAR, FMTUSHORT, FMTUINT) the min output is set to zero. If input is FMTUCHAR the max output is set to 255 and therefore for displaying a UCHAR input no scaling is carried out. The function can be also used to display a line of 256 elements of any non-complex image. im_histcum() forms a cumulative histogram. It works for any unsigned integer format. im_histnorm() normalises a histogram. The maximum histogram value becomes equal to the number of pixels in the histogram. In effect, the histogram becomes 'square'. Each channel is normalised separately. im_histeq() takes as input a histogram held by the IMAGE descriptor hist and creates an unsigned char look up table (held by the IMAGE descriptor lut) which when applied on the original image, (with histogram held by hist) histogram equalises it. Histogram equalisation is carried out for each band of hist individually. im_histspec() creates a lut for transforming an image with histogram held by histin according to the pdf (probability density function) of a reference image with histogram held by histref. histin and histref should have the same number of bands. im_identity() creates an look-up-table with Xsize=256, Ysize=1, Bands=bands, Bbits=BBBYTE, BandFmt=FMTUCHAR, Type=LUT, which is held by the IMAGE descriptor lut. The created image consist a bands linear (ramp) lut and is the basis for building look-up tables. im_identity_ushort() creates an look-up-table with Xsize=sz, Ysize=1, Bands=bands, Bbits=BBSHORT, BandFmt=FMTUSHORT, Type=LUT, which is held by the IMAGE descriptor lut. The created image consist of a linear (ramp) lut and is the basis for building look-up tables. im_ismonotonic() sets out to non-zero if the look-up table (or histogram) in lut is monotonic, that is, if it's slope is always >0.

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

SEE ALSO
im_hist(3), im_hsp(3), im_heq(3), im_maplut(3), im_tone_map(3).

COPYRIGHT
The National Gallery and Birkbeck College, 1991 - 1994.