NAME
im_tone_build, im_tone_map, im_tone_analyse, im_tone_build_range -
tone-curve adjustment of LAB images
SYNOPSIS
int
im_tone_build_range(
int in_max, int out_max,
IMAGE *lut,
double Lb, double Lw,
double Ps, double Pm, double Ph,
double S, double M, double H )
int
im_tone_build(
IMAGE *lut,
double Lb, double Lw,
double Ps, double Pm, double Ph,
double S, double M, double H )
int
im_tone_analyse(
IMAGE *in,
IMAGE *lut,
double Ps, double Pm, double Ph,
double S, double M, double H )
int
im_tone_map( IMAGE *in, IMAGE *out, IMAGE *lut )
DESCRIPTION
Various functions relating to tone curve adjustment. Example tone
curve:
repro L* out
^
|
100 | . . . . . . . . . . . . . . . .*
| * .
Lw | . . . . . . . . . . . . . .* .
| * . .
| /* . .
| / * . .
| / .* . .
| * * /* *. . .
| * * / . . .
| * / . . . .
| * / . . . .
| * / . . . .
| * / . . . . .
| */ . . . . .
Lb | . .* . . . . .
| * . . . . . .
|* . . . . . .
0 +--------------------------------------->
0 Lb Ls Lm Lh Lw 100 L* in
im_tone_build_range(3) generates a tone curve for the adjustment of
image levels. The curve is an unsigned 16-bit image with (in_max + 1)
entries, each in the range [0, out_max].
The parameters are expressed as 0-100, as in LAB colour space, but you
specify the scaling for the input and output images with the in_max and
out_max parameters.
Parameters:
Lb - black point
Lw - white point
Both in L* units, ie. in the range [0,100]. These should be set by
histogram analysis of the image to be transformed to 0.1% and 99.9% of
the full range of the image. See im_tone_analyse() below.
Ps - shadow point
Pm - mid-tone point
Ph - highlight point
All in [0,1], meaning max of shadow section of curve should be
positioned at Lb+Ps(Lw-Lb), etc. Suggested values: Ps, Pm, Ph should be
0.2, 0.5 and 0.8. Ps is limited to the range [0.1,0.3], Pm to the
range [0.4,0.6] and Ph to [0.7,0.9].
S - shadow adjustment factor (+/- 15)
M - mid-tone adjustment factor (+/- 30)
H - highlight adjustment factor (+/- 15)
These are the principal parameters, controlling the brightness in the
shadow, mid-tone and highlight areas. Suggested values:
0, 0, 0 - no change to input image
5, 0, -2 - boost shadows a little, depress highlights slightly
im_tone_build(3) is a convenience function that calls
im_tone_build_range(3) with ranges suitable for tone correcting a LABQ
image to a LABS image.
Use im_ismonotonic(3) to check that the slope of your tone curve is
always >0, use im_histplot(3) to graph the curve, use im_tone_map(3) to
apply your curve to an image.
im_tone_map(3) map just the L channel of a LabQ or LabS image through a
tone curve.
im_tone_analyse(3) find the histogram of a LabS or LabQ image and use
that to set the Ln and Lw parameters of im_tone_build(3). All other
parameters as above.
Example:
example% im_tone_analyse $VIPSHOME/pics/master.v /tmp/lut.v 0.2
0.5 0.8 6.3 0.8 -3
example% im_ismonotonic /tmp/lut.v
255
example% im_tone_map $VIPSHOME/pics/master.v /tmp/master2.v
/tmp/lut.v
RETURN VALUE
All functions returns 0 on success and -1 on error.
SEE ALSO
im_histplot(3), im_ismonotonic(3).
COPYRIGHT
1995, National Gallery
AUTHORS
J. Cupitt
10 May 1991 TONE(3)