histogram: libvips Reference Manual

## histogram histogram — find, manipulate and apply histograms and lookup tables |

## Stability Level

Stable, unless otherwise indicated

## Functions

int | vips_maplut ()
int | vips_percent ()
int | vips_stdif ()
int | vips_hist_cum ()
int | vips_hist_norm ()
int | vips_hist_equal ()
int | vips_hist_plot ()
int | vips_hist_match ()
int | vips_hist_local ()
int | vips_hist_ismonotonic ()
int | vips_hist_entropy ()
int | vips_case ()

## Includes

    #include <vips/vips.h>

## 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 VipsInterpretation of VIPS_INTERPRETATION_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 (`vips_hist_find()`, `vips_hist_find_indexed()`, `vips_hist_find_ndim()`, `vips_buildlut()`, `vips_identity()`), operations that manipulate histograms in some way (`vips_hist_cum()`, `vips_hist_norm()`), operations to apply histograms (`vips_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.

## Functions

### 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: `vips_hist_find()`, `vips_identity()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
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 below which there are `percent` values of `in` . For example:

    1
    2
    $ vips percent k2.jpg 90
    214

Means that 90% of pixels in `k2.jpg` have a value less than 214.

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()`.

[method]

#### Parameters

in | input image |
percent | threshold percentage |
threshold | output threshold value. | [out]
... | `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() performs 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:

    1
    2
    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:

    1
    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()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
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()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `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. The maximum of each band becomes equal to the maximum index, so for example the max for a uchar image becomes 255. Normalise each band separately.

See also: `vips_hist_cum()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `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. The output format is always the same as the input format.

See also:

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `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:

<emphasis>unsigned char</emphasis> max is always 256

<emphasis>other unsigned integer types</emphasis> output 0 - maximum value of `in` .

<emphasis>signed int types</emphasis> min moved to 0, max moved to max + min.

<emphasis>float types</emphasis> min moved to 0, max moved to any (square output)

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `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()`.

[method]

#### Parameters

in | input histogram |
ref | reference histogram |
out | output histogram. | [out]
... | `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,
                     ...);

Optional arguments:

- `max_slope` : maximum brightening

Performs local histogram equalisation on `in` using a window of size `width` by `height` centered on the input pixel.

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

If `max_slope` is greater than 0, it sets the maximum value for the slope of the cumulative histogram, that is, the maximum brightening that is performed. A value of 3 is often used. Local histogram equalization with contrast limiting is usually called CLAHE.

See also: `vips_hist_equal()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
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 *out,
                           ...);

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

[method]

#### Parameters

in | lookup-table to test |
out | set non-zero if `in` is monotonic. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_hist_entropy ()

    int
    vips_hist_entropy (VipsImage *in,
                       double *out,
                       ...);

Estimate image entropy from a histogram. Entropy is calculated as:

    1
    -sum(p * log2(p))

where p is histogram-value / sum-of-histogram-values.

[method]

#### Parameters

in | input histogram |
out | image entropy. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_case ()

    int
    vips_case (VipsImage *index,
               VipsImage **cases,
               VipsImage **out,
               int n,
               ...);

Use values in `index` to select pixels from `cases` .

`index` must have one band. `cases` can have up to 256 elements. Values in `index` greater than or equal to `n` use the final image in `cases` . The images in `cases` must have either one band or the same number of bands. The output image is the same size as `index` . Images in `cases` are expanded to the smallest common format and number of bands.

Combine this with `vips_switch()` to make something like a case statement or a multi-way `vips_ifthenelse()`.

See also: `vips_maplut()`, `vips_switch()`, `vips_ifthenelse()`.

[method]

#### Parameters

index | index image |
cases | array of case images. | [array length=n]
out | output image. | [out]
n | number of case images |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

## See Also

<link linkend="VipsImage">image</link> <link linkend="libvips-arithmetic">arithmetic</link> <link linkend="libvips-create">create</link>