| .TH IM_HISTGR 3 "10 May 1991" |
| .SH NAME |
| im_histcum, |
| im_histeq, |
| im_histgr, |
| im_histnD, |
| im_histnorm, |
| im_histspec, |
| im_identity, |
| im_identity_ushort, |
| im_ismonotonic |
| \- create, display and process histograms or luts |
| .SH SYNOPSIS |
| #include <vips/vips.h> |
| |
| int im_histgr( in, out, bandno ) |
| .br |
| IMAGE *in, *out; |
| .br |
| int bandno; |
| |
| int im_histnD( in, out, bins ) |
| .br |
| IMAGE *in, *out; |
| .br |
| int bins; |
| |
| int im_histcum(hist, lut) |
| .br |
| IMAGE *hist, *lut; |
| |
| int im_histnorm(hist, lut) |
| .br |
| IMAGE *hist, *lut; |
| |
| int im_histeq(hist, lut) |
| .br |
| IMAGE *hist, *lut; |
| |
| int im_histspec(histin, histref, lut) |
| .br |
| IMAGE *histin, *histref, *lut; |
| |
| int im_identity(lut, bands) |
| .br |
| IMAGE *lut; |
| .br |
| int bands; |
| |
| int im_identity_ushort(lut, bands, sz) |
| .br |
| IMAGE *lut; |
| .br |
| int bands; |
| .br |
| int sz; |
| |
| int im_ismonotonic( IMAGE *lut, int *out ) |
| |
| .SH DESCRIPTION |
| .B im_histgr(3) |
| writes the histogram of image in to image out. If bandno is -1, |
| 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, numbering from |
| zero. |
| |
| 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 |
| .B im_histgr(3) |
| 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 |
| .B im_histgr(3) |
| 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 |
| .B im_histnD(3) |
| below for another way to make histograms. |
| |
| .B im_histnD(3) |
| 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 |
| .B 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 |
| .B im_histplot(3) |
| to graph the histogram for visualisation. See the separate manpage. |
| |
| .B im_histcum(3) |
| forms a cumulative histogram. |
| |
| .B im_histnorm(3) |
| 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. |
| |
| .B im_histeq(3) |
| 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. |
| |
| .B im_histspec(3) |
| 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. |
| |
| .B im_identity(3) |
| 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. |
| |
| .B im_identity_ushort(3) |
| 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. |
| |
| .B im_ismonotonic(3) |
| 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. |
| |
| .SH RETURN VALUE |
| All functions return 0 on success and -1 on error. |
| .SH SEE ALSO |
| im_hist(3), im_hsp(3), im_heq(3), im_maplut(3), im_tone_map(3), |
| im_histplot(3). |
| .SH COPYRIGHT |
| The National Gallery and Birkbeck College, 1991 \- 1994. |