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