![]() |
![]() |
![]() |
VIPS Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#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
);
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.
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()
.
|
input image |
|
output image |
|
band to equalise |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
output image |
|
number of bins to make on each axis |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
input image |
|
output image |
Returns : |
0 on success, -1 on error |
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()
.
|
output image |
|
number of bands to create |
Returns : |
0 on success, -1 on error |
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()
.
|
output image |
|
number of bands to create |
|
size of LUT to create |
Returns : |
0 on success, -1 on error |
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 mask |
|
output LUT |
|
generate this much |
Returns : |
0 on success, -1 on error |
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 mask |
|
output image |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
sums of rows |
|
sums of columns |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error |
int im_histcum (VipsImage *in
,VipsImage *out
);
Form cumulative histogram.
See also: im_histnorm()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error |
int im_histeq (VipsImage *in
,VipsImage *out
);
Histogram equalisation: normalised cumulative histogram.
See also: im_heq()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
reference histogram |
|
output image |
Returns : |
0 on success, -1 on error |
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()
.
|
lookup-table to test |
|
set non-zero if lut is monotonic |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
output image |
|
look-up table |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
output image |
|
band to plot |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
reference histogram |
|
output image |
Returns : |
0 on success, -1 on error |
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()
|
input image |
|
output image |
|
gamma factor |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
threshold percentage |
|
output threshold value |
Returns : |
0 on success, -1 on error |
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()
.
|
input histogram image |
|
threshold percentage |
|
output threshold value |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
output image |
|
band to equalise |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
output image |
|
width of region |
|
height of region |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
output image |
|
weight of new mean |
|
target mean |
|
weight of new deviation |
|
target deviation |
|
width of region |
|
height of region |
Returns : |
0 on success, -1 on error |
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()
.
|
output image |
|
input range |
|
output range |
|
black-point [0-100] |
|
white-point [0-100] |
|
shadow point (eg. 0.2) |
|
mid-tone point (eg. 0.5) |
|
highlight point (eg. 0.8) |
|
shadow adjustment (+/- 30) |
|
mid-tone adjustment (+/- 30) |
|
highlight adjustment (+/- 30) |
Returns : |
0 on success, -1 on error |
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()
.
|
output image |
|
black-point [0-100] |
|
white-point [0-100] |
|
shadow point (eg. 0.2) |
|
mid-tone point (eg. 0.5) |
|
highlight point (eg. 0.8) |
|
shadow adjustment (+/- 30) |
|
mid-tone adjustment (+/- 30) |
|
highlight adjustment (+/- 30) |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
output image |
|
shadow point (eg. 0.2) |
|
mid-tone point (eg. 0.5) |
|
highlight point (eg. 0.8) |
|
shadow adjustment (+/- 30) |
|
mid-tone adjustment (+/- 30) |
|
highlight adjustment (+/- 30) |
Returns : |
0 on success, -1 on error |
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()
.
|
input image |
|
output image |
|
look-up table |
Returns : |
0 on success, -1 on error |