## histograms_lut

histograms_lut — find, manipulate and apply histograms and lookup tables

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

    int                 im_histgr                           (VipsImage *in,
                                                             VipsImage *out,
                                                             int bandno);
    int                 im_histnD                           (VipsImage *in,
                                                             VipsImage *out,
                                                             int bins);
    int                 im_hist_indexed                     (VipsImage *index,
                                                             VipsImage *value,
                                                             VipsImage *out);
    int                 im_identity                         (VipsImage *lut,
                                                             int bands);
    int                 im_identity_ushort                  (VipsImage *lut,
                                                             int bands,
                                                             int sz);
    int                 im_invertlut                        (DOUBLEMASK *input,
                                                             VipsImage *output,
                                                             int lut_size);
    int                 im_buildlut                         (DOUBLEMASK *input,
                                                             VipsImage *output);
    int                 im_project                          (VipsImage *in,
                                                             VipsImage *hout,
                                                             VipsImage *vout);
    int                 im_histnorm                         (VipsImage *in,
                                                             VipsImage *out);
    int                 im_histcum                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_histeq                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_histspec                         (VipsImage *in,
                                                             VipsImage *ref,
                                                             VipsImage *out);
    int                 im_ismonotonic                      (VipsImage *lut,
                                                             int *out);
    int                 im_histplot                         (VipsImage *in,
                                                             VipsImage *out);
    int                 im_maplut                           (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsImage *lut);
    int                 im_hist                             (VipsImage *in,
                                                             VipsImage *out,
                                                             int bandno);
    int                 im_hsp                              (VipsImage *in,
                                                             VipsImage *ref,
                                                             VipsImage *out);
    int                 im_gammacorrect                     (VipsImage *in,
                                                             VipsImage *out,
                                                             double exponent);
    int                 im_mpercent                         (VipsImage *in,
                                                             double percent,
                                                             int *out);
    int                 im_mpercent_hist                    (VipsImage *hist,
                                                             double percent,
                                                             int *out);
    int                 im_heq                              (VipsImage *in,
                                                             VipsImage *out,
                                                             int bandno);
    int                 im_lhisteq                          (VipsImage *in,
                                                             VipsImage *out,
                                                             int xwin,
                                                             int ywin);
    int                 im_stdif                            (VipsImage *in,
                                                             VipsImage *out,
                                                             double a,
                                                             double m0,
                                                             double b,
                                                             double s0,
                                                             int xwin,
                                                             int ywin);
    int                 im_tone_build_range                 (VipsImage *out,
                                                             int in_max,
                                                             int out_max,
                                                             double Lb,
                                                             double Lw,
                                                             double Ps,
                                                             double Pm,
                                                             double Ph,
                                                             double S,
                                                             double M,
                                                             double H);
    int                 im_tone_build                       (VipsImage *out,
                                                             double Lb,
                                                             double Lw,
                                                             double Ps,
                                                             double Pm,
                                                             double Ph,
                                                             double S,
                                                             double M,
                                                             double H);
    int                 im_tone_analyse                     (VipsImage *in,
                                                             VipsImage *out,
                                                             double Ps,
                                                             double Pm,
                                                             double Ph,
                                                             double S,
                                                             double M,
                                                             double H);
    int                 im_tone_map                         (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsImage *lut);

## 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

### im_histgr ()

    int                 im_histgr                           (VipsImage *in,
                                                             VipsImage *out,
                                                             int bandno);

Find the histogram of `in`. Find the histogram for band `bandno` (producing a one-band histogram), or for all bands (producing an n-band histogram) if `bandno` is -1.

`in` must be u8 or u16. `out` is always u32.

See also: `im_hist_indexed()`, `im_histeq()`.

`in` : | input image
`out` : | output image
`bandno` : | band to equalise
Returns : | 0 on success, -1 on error

### im_histnD ()

    int                 im_histnD                           (VipsImage *in,
                                                             VipsImage *out,
                                                             int bins);

Make a one, two or three dimensional histogram of a 1, 2 or 3 band image. Divide each axis into a certain number of bins .. ie. output is 1 x bins, bins x bins, or bins x bins x bins bands. uchar and ushort only.

See also: `im_histgr()`, `im_histindexed()`.

`in` : | input image
`out` : | output image
`bins` : | number of bins to make on each axis
Returns : | 0 on success, -1 on error

### im_hist_indexed ()

    int                 im_hist_indexed                     (VipsImage *index,
                                                             VipsImage *value,
                                                             VipsImage *out);

Make a histogram of `value`, but use image `index` to pick the bins. In other words, element zero in `out` contains the sum of all the pixels in `value` whose corresponding pixel in `index` is zero.

`index` must have just one band and be u8 or u16. `value` must be non-complex. `out` always has the same size and format as `value`.

This operation is useful in conjunction with `im_label_regions()`. You can use it to find the centre of gravity of blobs in an image, for example.

See also: `im_histgr()`, `im_label_regions()`.

`index` : | input image
`value` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_identity ()

    int                 im_identity                         (VipsImage *lut,
                                                             int bands);

Creates a image file with Xsize=256, Ysize=1, Bands=`bands`, BandFmt=IM_BANDFMT_UCHAR, Type=IM_TYPE_HISTOGRAM.

The created image consist a `bands`-bands linear lut and is the basis for building up look-up tables.

See also: `im_identity_ushort()`, `im_make_xy()`.

`lut` : | output image
`bands` : | number of bands to create
Returns : | 0 on success, -1 on error

### im_identity_ushort ()

    int                 im_identity_ushort                  (VipsImage *lut,
                                                             int bands,
                                                             int sz);

As `im_identity()`, but make a ushort LUT. ushort LUTs can be up to 65536 elements - `sz` is the number of elements required.

The created image consist a `bands`-bands linear lut and is the basis for building up look-up tables.

See also: `im_identity()`, `im_make_xy()`.

`lut` : | output image
`bands` : | number of bands to create
`sz` : | size of LUT to create
Returns : | 0 on success, -1 on error

### im_invertlut ()

    int                 im_invertlut                        (DOUBLEMASK *input,
                                                             VipsImage *output,
                                                             int lut_size);

Given a mask of target values and real values, generate a LUT which will map reals to targets. Handy for linearising images from measurements of a colour chart. All values in [0,1]. Piecewise linear interpolation, extrapolate head and tail to 0 and 1.

Eg. input like this:

4 | 3 |  |
0.1 | 0.2 | 0.3 | 0.1
0.2 | 0.4 | 0.4 | 0.2
0.7 | 0.5 | 0.6 | 0.3

Means a patch with 10% reflectance produces an image with 20% in channel 1, 30% in channel 2, and 10% in channel 3, and so on.

Inputs don't need to be sorted (we do that). Generate any precision LUT, typically you might ask for 256 elements.

It won't work too well for non-monotonic camera responses (we should fix this). Interpolation is simple piecewise linear; we ought to do something better really.

See also: `im_buildlut()`, `im_invertlut()`

`input` : | input mask
`output` : | output LUT
`lut_size` : | generate this much
Returns : | 0 on success, -1 on error

### im_buildlut ()

    int                 im_buildlut                         (DOUBLEMASK *input,
                                                             VipsImage *output);

This operation builds a lookup table from a set of points. Intermediate values are generated by piecewise linear interpolation.

For example, consider this 2 x 2 matrix of (x, y) coordinates:

0 | 0
255 | 100

We then generate:

Index | Value
--- | ---
0 | 0
1 | 0.4
... | etc. by linear interpolation
255 | 100

This is then written as the output image, with the left column giving the index in the image to place the value.

The (x, y) points don't need to be sorted: we do that. You can have several Ys, each becomes a band in the output LUT. You don't need to start at zero, any integer will do, including negatives.

See also: `im_identity()`, `im_invertlut()`.

`input` : | input mask
`output` : | output image
Returns : | 0 on success, -1 on error

### im_project ()

    int                 im_project                          (VipsImage *in,
                                                             VipsImage *hout,
                                                             VipsImage *vout);

Find the horizontal and vertical projections of an image, ie. the sum of every row of pixels, and the sum of every column of pixels. The output format is uint, int or double, depending on the input format.

Non-complex images only.

See also: `im_histgr()`, `im_profile()`.

`in` : | input image
`hout` : | sums of rows
`vout` : | sums of columns
Returns : | 0 on success, -1 on error

### im_histnorm ()

    int                 im_histnorm                         (VipsImage *in,
                                                             VipsImage *out);

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

See also: `im_histcum()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_histcum ()

    int                 im_histcum                          (VipsImage *in,
                                                             VipsImage *out);

Form cumulative histogram.

See also: `im_histnorm()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_histeq ()

    int                 im_histeq                           (VipsImage *in,
                                                             VipsImage *out);

Histogram equalisation: normalised cumulative histogram.

See also: `im_heq()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_histspec ()

    int                 im_histspec                         (VipsImage *in,
                                                             VipsImage *ref,
                                                             VipsImage *out);

Creates a lut which, when applied to the image from which histogram `in` was formed, will produce an image whose PDF matches that of the image from which `ref` was formed.

See also: `im_hsp()`, `im_histgr()`, `im_maplut()`.

`in` : | input image
`ref` : | reference histogram
`out` : | output image
Returns : | 0 on success, -1 on error

### im_ismonotonic ()

    int                 im_ismonotonic                      (VipsImage *lut,
                                                             int *out);

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

See also: `im_tone_build_range()`.

`lut` : | lookup-table to test
`out` : | set non-zero if `lut` is monotonic
Returns : | 0 on success, -1 on error

### im_histplot ()

    int                 im_histplot                         (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)

See also: `im_hist_indexed()`, `im_histeq()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_maplut ()

    int                 im_maplut                           (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsImage *lut);

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, IM_BANDFMT_UCHAR, IM_BANDFMT_USHORT or IM_BANDFMT_UINT.

If `lut` is too small for the input type (for example, if `in` is IM_BANDFMT_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, then all bands of `in` pass through it. 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()`, `im_identity()`.

`in` : | input image
`out` : | output image
`lut` : | look-up table
Returns : | 0 on success, -1 on error

### im_hist ()

    int                 im_hist                             (VipsImage *in,
                                                             VipsImage *out,
                                                             int bandno);

Find and plot the histogram of `in`. If `bandno` is -1, plot all bands. Otherwise plot the specified band.

See also: `im_histgr()`, `im_histplot()`.

`in` : | input image
`out` : | output image
`bandno` : | band to plot
Returns : | 0 on success, -1 on error

### im_hsp ()

    int                 im_hsp                              (VipsImage *in,
                                                             VipsImage *ref,
                                                             VipsImage *out);

Maps image `in` to image `out`, adjusting the histogram to match image `ref`. Both images should have the same number of bands.

See also: `im_histspec()`, `im_histgr()`.

`in` : | input image
`ref` : | reference histogram
`out` : | output image
Returns : | 0 on success, -1 on error

### im_gammacorrect ()

    int                 im_gammacorrect                     (VipsImage *in,
                                                             VipsImage *out,
                                                             double exponent);

Gamma-correct an 8- or 16-bit unsigned image with a lookup table. The output format is the same as the input format.

See also: `im_identity()`, `im_powtra()`, `im_maplut()`

`in` : | input image
`out` : | output image
`exponent` : | gamma factor
Returns : | 0 on success, -1 on error

### im_mpercent ()

    int                 im_mpercent                         (VipsImage *in,
                                                             double percent,
                                                             int *out);

`im_mpercent()` returns (through the `out` parameter) the threshold above which there are `percent` values of `in`. If for example percent=.1, the number of pels of the input image with values greater than the returned int 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: `im_histgr()`, `im_profile()`.

`in` : | input image
`percent` : | threshold percentage
`out` : | output threshold value
Returns : | 0 on success, -1 on error

### im_mpercent_hist ()

    int                 im_mpercent_hist                    (VipsImage *hist,
                                                             double percent,
                                                             int *out);

Just like `im_mpercent()`, except it works on an image histogram. Handy if you want to run `im_mpercent()` several times without having to recompute the histogram each time.

See also: `im_mpercent()`.

`hist` : | input histogram image
`percent` : | threshold percentage
`out` : | output threshold value
Returns : | 0 on success, -1 on error

### im_heq ()

    int                 im_heq                              (VipsImage *in,
                                                             VipsImage *out,
                                                             int bandno);

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

See also: `im_lhisteq()`, `im_histgr()`, `im_histeq()`.

`in` : | input image
`out` : | output image
`bandno` : | band to equalise
Returns : | 0 on success, -1 on error

### im_lhisteq ()

    int                 im_lhisteq                          (VipsImage *in,
                                                             VipsImage *out,
                                                             int xwin,
                                                             int ywin);

Performs local histogram equalisation on `in` using a window of size `xwin` by `ywin` centered on the input pixel. Works only on monochrome images.

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: `im_stdif()`, `im_heq()`.

`in` : | input image
`out` : | output image
`xwin` : | width of region
`ywin` : | height of region
Returns : | 0 on success, -1 on error

### im_stdif ()

    int                 im_stdif                            (VipsImage *in,
                                                             VipsImage *out,
                                                             double a,
                                                             double m0,
                                                             double b,
                                                             double s0,
                                                             int xwin,
                                                             int ywin);

`im_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 `xwin`, `ywin` 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 im_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: `im_lhisteq()`.

`in` : | input image
`out` : | output image
`a` : | weight of new mean
`m0` : | target mean
`b` : | weight of new deviation
`s0` : | target deviation
`xwin` : | width of region
`ywin` : | height of region
Returns : | 0 on success, -1 on error

### im_tone_build_range ()

    int                 im_tone_build_range                 (VipsImage *out,
                                                             int in_max,
                                                             int out_max,
                                                             double Lb,
                                                             double Lw,
                                                             double Ps,
                                                             double Pm,
                                                             double Ph,
                                                             double S,
                                                             double M,
                                                             double H);

`im_tone_build_range()` generates a tone curve for the adjustment of image levels. It is mostly designed for adjusting the L* part of a LAB image in way suitable for print work, but you can use it for other things too.

The curve is an unsigned 16-bit image with (`in_max` + 1) entries, each in the range [0, `out_max`].

`Lb`, `Lw` are expressed as 0-100, as in LAB colour space. You specify the scaling for the input and output images with the `in_max` and `out_max` parameters.

See also: `im_ismonotonic()`, `im_tone_map()`, `im_tone_analyse()`.

`out` : | output image
`in_max` : | input range
`out_max` : | output range
`Lb` : | black-point [0-100]
`Lw` : | white-point [0-100]
`Ps` : | shadow point (eg. 0.2)
`Pm` : | mid-tone point (eg. 0.5)
`Ph` : | highlight point (eg. 0.8)
`S` : | shadow adjustment (+/- 30)
`M` : | mid-tone adjustment (+/- 30)
`H` : | highlight adjustment (+/- 30)
Returns : | 0 on success, -1 on error

### im_tone_build ()

    int                 im_tone_build                       (VipsImage *out,
                                                             double Lb,
                                                             double Lw,
                                                             double Ps,
                                                             double Pm,
                                                             double Ph,
                                                             double S,
                                                             double M,
                                                             double H);

As `im_tone_build_range()`, but set 32767 and 32767 as values for `in_max` and `out_max`. This makes a curve suitable for correcting LABS images, the most common case.

See also: `im_tone_build_range()`.

`out` : | output image
`Lb` : | black-point [0-100]
`Lw` : | white-point [0-100]
`Ps` : | shadow point (eg. 0.2)
`Pm` : | mid-tone point (eg. 0.5)
`Ph` : | highlight point (eg. 0.8)
`S` : | shadow adjustment (+/- 30)
`M` : | mid-tone adjustment (+/- 30)
`H` : | highlight adjustment (+/- 30)
Returns : | 0 on success, -1 on error

### im_tone_analyse ()

    int                 im_tone_analyse                     (VipsImage *in,
                                                             VipsImage *out,
                                                             double Ps,
                                                             double Pm,
                                                             double Ph,
                                                             double S,
                                                             double M,
                                                             double H);

As `im_tone_build()`, but analyse the histogram of `in` and use it to pick the 0.1% and 99.9% points for `Lb` and `Lw`.

See also: `im_tone_build()`.

`in` : | input image
`out` : | output image
`Ps` : | shadow point (eg. 0.2)
`Pm` : | mid-tone point (eg. 0.5)
`Ph` : | highlight point (eg. 0.8)
`S` : | shadow adjustment (+/- 30)
`M` : | mid-tone adjustment (+/- 30)
`H` : | highlight adjustment (+/- 30)
Returns : | 0 on success, -1 on error

### im_tone_map ()

    int                 im_tone_map                         (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsImage *lut);

Map the first channel of `in` through `lut`. If `in` is IM_CODING_LABQ, unpack to LABS, map L and then repack.

`in` should be a LABS or LABQ image for this to work sensibly.

See also: `im_maplut()`.

`in` : | input image
`out` : | output image
`lut` : | look-up table
Returns : | 0 on success, -1 on error

## See Also

image