histogram

histogram — find, manipulate and apply histograms and lookup tables

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <vips/vips.h>

int                 vips_maplut                         (VipsImage *in,
                                                         VipsImage **out,
                                                         VipsImage *lut,
                                                         ...);
int                 vips_percent                        (VipsImage *in,
                                                         double percent,
                                                         int *threshold,
                                                         ...);
int                 vips_stdif                          (VipsImage *in,
                                                         VipsImage **out,
                                                         int width,
                                                         int height,
                                                         ...);
int                 vips_hist_cum                       (VipsImage *in,
                                                         VipsImage **out,
                                                         ...);
int                 vips_hist_norm                      (VipsImage *in,
                                                         VipsImage **out,
                                                         ...);
int                 vips_hist_equal                     (VipsImage *in,
                                                         VipsImage **out,
                                                         ...);
int                 vips_hist_plot                      (VipsImage *in,
                                                         VipsImage **out,
                                                         ...);
int                 vips_hist_match                     (VipsImage *in,
                                                         VipsImage *ref,
                                                         VipsImage **out,
                                                         ...);
int                 vips_hist_local                     (VipsImage *in,
                                                         VipsImage **out,
                                                         int width,
                                                         int height,
                                                         ...);
int                 vips_hist_ismonotonic               (VipsImage *in,
                                                         gboolean *monotonic,
                                                         ...);

Description

Histograms and look-up tables are 1xn or nx1 images, where n is less than 256 or less than 65536, corresponding to 8- and 16-bit unsigned int images. They are tagged with a VipsType of IM_TYPE_HISTOGRAM and usually displayed by user-interfaces such as nip2 as plots rather than images.

These functions can be broadly grouped as things to find or build histograms (im_histgr(), im_buildlut(), in_identity()), operations that manipulate histograms in some way (im_histcum(), im_histnorm()), operations to apply histograms (im_maplut()), and a variety of utility operations.

A final group of operations build tone curves. These are useful in pre-press work for adjusting the appearance of images. They are designed for CIELAB images, but might be useful elsewhere.

Details

vips_maplut ()

int                 vips_maplut                         (VipsImage *in,
                                                         VipsImage **out,
                                                         VipsImage *lut,
                                                         ...);

Optional arguments:

band: apply one-band lut to this band of in

Map an image through another image acting as a LUT (Look Up Table). The lut may have any type and the output image will be that type.

The input image will be cast to one of the unsigned integer types, that is, VIPS_FORMAT_UCHAR, VIPS_FORMAT_USHORT or VIPS_FORMAT_UINT.

If lut is too small for the input type (for example, if in is VIPS_FORMAT_UCHAR but lut only has 100 elements), the lut is padded out by copying the last element. Overflows are reported at the end of computation. If lut is too large, extra values are ignored.

If lut has one band and band is -1 (the default), then all bands of in pass through lut. If band is >= 0, then just that band of in passes through lut and other bands are just copied.

If lut has same number of bands as in, then each band is mapped separately. If in has one band, then lut may have many bands and the output will have the same number of bands as lut.

See also: im_histgr(), vips_identity().

in :

input image

out :

output image

lut :

look-up table

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

vips_percent ()

int                 vips_percent                        (VipsImage *in,
                                                         double percent,
                                                         int *threshold,
                                                         ...);

vips_percent() returns (through the threshold parameter) the threshold above which there are percent values of in. If for example percent=10, the number of pels of the input image with values greater than threshold will correspond to 10% of all pels of the image.

The function works for uchar and ushort images only. It can be used to threshold the scaled result of a filtering operation.

See also: vips_hist_find(), vips_profile().

in :

input image

percent :

threshold percentage

threshold :

output threshold value

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

vips_stdif ()

int                 vips_stdif                          (VipsImage *in,
                                                         VipsImage **out,
                                                         int width,
                                                         int height,
                                                         ...);

Optional arguments:

a: weight of new mean m0: target mean b: weight of new deviation s0: target deviation

vips_stdif() preforms statistical differencing according to the formula given in page 45 of the book "An Introduction to Digital Image Processing" by Wayne Niblack. This transformation emphasises the way in which a pel differs statistically from its neighbours. It is useful for enhancing low-contrast images with lots of detail, such as X-ray plates.

At point (i,j) the output is given by the equation:

vout(i,j) = a * m0 + (1 - a) * meanv + (vin(i,j) - meanv) * (b * s0) / (s0 + b * stdv)

Values a, m0, b and s0 are entered, while meanv and stdv are the values calculated over a moving window of size width, height centred on pixel (i,j). m0 is the new mean, a is the weight given to it. s0 is the new standard deviation, b is the weight given to it.

Try:

vips stdif $VIPSHOME/pics/huysum.v fred.v 0.5 128 0.5 50 11 11

The operation works on one-band uchar images only, and writes a one-band uchar image as its result. The output image has the same size as the input.

See also: vips_hist_local().

in :

input image

out :

output image

width :

width of region

height :

height of region

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

vips_hist_cum ()

int                 vips_hist_cum                       (VipsImage *in,
                                                         VipsImage **out,
                                                         ...);

Form cumulative histogram.

See also: vips_hist_norm().

in :

input image

out :

output image

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

vips_hist_norm ()

int                 vips_hist_norm                      (VipsImage *in,
                                                         VipsImage **out,
                                                         ...);

Normalise histogram ... normalise range to make it square (ie. max == number of elements). Normalise each band separately.

See also: vips_hist_cum().

in :

input image

out :

output image

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

vips_hist_equal ()

int                 vips_hist_equal                     (VipsImage *in,
                                                         VipsImage **out,
                                                         ...);

Optional arguments:

band: band to equalise

Histogram-equalise in. Equalise using band bandno, or if bandno is -1, equalise bands independently.

See also:

in :

input image

out :

output image

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

vips_hist_plot ()

int                 vips_hist_plot                      (VipsImage *in,
                                                         VipsImage **out,
                                                         ...);

Plot a 1 by any or any by 1 image file as a max by any or any by max image using these rules:

unsigned char max is always 256

other unsigned integer types output 0 - maxium value of in.

signed int types min moved to 0, max moved to max + min.

float types min moved to 0, max moved to any (square output)

in :

input image

out :

output image

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

vips_hist_match ()

int                 vips_hist_match                     (VipsImage *in,
                                                         VipsImage *ref,
                                                         VipsImage **out,
                                                         ...);

Adjust in to match ref. If in and ref are normalised cumulative histograms, out will be a LUT that adjusts the PDF of the image from which in was made to match the PDF of ref's image.

See also: vips_maplut(), vips_hist_find(), vips_hist_norm(), vips_hist_cum().

in :

input histogram

ref :

reference histogram

out :

output histogram

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

vips_hist_local ()

int                 vips_hist_local                     (VipsImage *in,
                                                         VipsImage **out,
                                                         int width,
                                                         int height,
                                                         ...);

Performs local histogram equalisation on in using a window of size xwin by ywin centered on the input pixel.

The output image is the same size as the input image. The edge pixels are created by copy edge pixels of the input image outwards.

See also: vips_hist_equal().

in :

input image

out :

output image

width :

width of region

height :

height of region

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

vips_hist_ismonotonic ()

int                 vips_hist_ismonotonic               (VipsImage *in,
                                                         gboolean *monotonic,
                                                         ...);

Test in for monotonicity. out is set non-zero if in is monotonic.

in :

lookup-table to test

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

See Also

image