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 () 
Description
Histograms and lookup tables are 1xn or nx1 images, where n is less than 256 or less than 65536, corresponding to 8 and 16bit unsigned int images. They are tagged with a VipsInterpretation of VIPS_INTERPRETATION_HISTOGRAM and usually displayed by userinterfaces 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 prepress 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 onebandlut
to this band ofin
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()
.
Parameters
in 
input image 

out 
output image 

lut 
lookup table 

... 

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()
.
Parameters
in 
input image 

percent 
threshold percentage 

threshold 
output threshold value 

... 

vips_stdif ()
int vips_stdif (VipsImage *in
,VipsImage **out
,int width
,int height
,...
);
Optional arguments:
a
: weight of new meanm0
: target meanb
: 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 lowcontrast images with lots of detail, such as Xray 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 oneband uchar images only, and writes a oneband uchar image as its result. The output image has the same size as the input.
See also: vips_hist_local()
.
Parameters
in 
input image 

out 
output image 

width 
width of region 

height 
height of region 

... 

vips_hist_cum ()
int vips_hist_cum (VipsImage *in
,VipsImage **out
,...
);
Form cumulative histogram.
See also: vips_hist_norm()
.
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()
.
vips_hist_equal ()
int vips_hist_equal (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:

band
: band to equalise
Histogramequalise in
. Equalise using band bandno
, or if bandno
is 1,
equalise bands independently.
See also:
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)
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()
.
Parameters
in 
input histogram 

ref 
reference histogram 

out 
output histogram 

... 

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()
.
Parameters
in 
input image 

out 
output image 

width 
width of region 

height 
height of region 

... 

vips_hist_ismonotonic ()
int vips_hist_ismonotonic (VipsImage *in
,gboolean *out
,...
);
Test in
for monotonicity. out
is set nonzero if in
is monotonic.
Parameters
in 
lookuptable to test 

out 
set nonzero if 

... 

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 histogramvalue / sumofhistogramvalues.
Parameters
in 
input histogram 

out 
image entropy 

... 
