1TONE(3)                    Library Functions Manual                    TONE(3)
2
3
4

NAME

6       im_tone_build,   im_tone_map,  im_tone_analyse,  im_tone_build_range  -
7       tone-curve adjustment of LAB images
8

SYNOPSIS

10       int
11       im_tone_build_range(
12          int in_max, int out_max,
13          IMAGE *lut,
14          double Lb, double Lw,
15          double Ps, double Pm, double Ph,
16          double S, double M, double H )
17
18       int
19       im_tone_build(
20          IMAGE *lut,
21          double Lb, double Lw,
22          double Ps, double Pm, double Ph,
23          double S, double M, double H )
24
25       int
26       im_tone_analyse(
27          IMAGE *in,
28          IMAGE *lut,
29          double Ps, double Pm, double Ph,
30          double S, double M, double H )
31
32       int
33       im_tone_map( IMAGE *in, IMAGE *out, IMAGE *lut )
34
35

DESCRIPTION

37       Various functions relating  to  tone  curve  adjustment.  Example  tone
38       curve:
39
40        repro L* out
41            ^
42            |
43        100 | . . . . . . . . . . . . . . . .*
44            |                              * .
45         Lw | . . . . . . . . . . . . . .*   .
46            |                          * .   .
47            |                        /*  .   .
48            |                      / *   .   .
49            |                    / .*    .   .
50            |              * * /* *.     .   .
51            |           * *  /     .     .   .
52            |         *    / .     .     .   .
53            |        *   /   .     .     .   .
54            |       *  /     .     .     .   .
55            |      * / .     .     .     .   .
56            |     */   .     .     .     .   .
57         Lb | . .*     .     .     .     .   .
58            |  * .     .     .     .     .   .
59            |*   .     .     .     .     .   .
60          0 +--------------------------------------->
61            0    Lb    Ls    Lm    Lh    Lw  100   L* in
62
63       im_tone_build_range(3)  generates  a  tone  curve for the adjustment of
64       image levels. The curve is an unsigned 16-bit image with (in_max  +  1)
65       entries, each in the range [0, out_max].
66
67       The  parameters are expressed as 0-100, as in LAB colour space, but you
68       specify the scaling for the input and output images with the in_max and
69       out_max parameters.
70
71       Parameters:
72
73           Lb  - black point
74           Lw  - white point
75
76       Both in L* units, ie. in the range [0,100]. These should be set by his‐
77       togram analysis of the image to be transformed to 0.1% and 99.9% of the
78       full range of the image. See im_tone_analyse() below.
79
80           Ps  - shadow point
81           Pm  - mid-tone point
82           Ph  - highlight point
83
84       All  in  [0,1],  meaning max of shadow section of curve should be posi‐
85       tioned at Lb+Ps(Lw-Lb), etc. Suggested values: Ps,  Pm,  Ph  should  be
86       0.2,  0.5  and  0.8.   Ps  is limited to the range [0.1,0.3], Pm to the
87       range [0.4,0.6] and Ph to [0.7,0.9].
88
89           S  - shadow adjustment factor (+/- 15)
90           M  - mid-tone adjustment factor (+/- 30)
91           H  - highlight adjustment factor (+/- 15)
92
93       These are the principal parameters, controlling the brightness  in  the
94       shadow, mid-tone and highlight areas. Suggested values:
95
96           0, 0,  0   - no change to input image
97           5, 0, -2   - boost shadows a little, depress highlights slightly
98
99       im_tone_build(3)    is    a    convenience    function    that    calls
100       im_tone_build_range(3) with ranges suitable for tone correcting a  LABQ
101       image to a LABS image.
102
103       Use  im_ismonotonic(3)  to  check  that the slope of your tone curve is
104       always >0, use im_histplot(3) to graph the curve, use im_tone_map(3) to
105       apply your curve to an image.
106
107       im_tone_map(3) map just the L channel of a LabQ or LabS image through a
108       tone curve.
109
110       im_tone_analyse(3) find the histogram of a LabS or LabQ image  and  use
111       that  to  set  the Ln and Lw parameters of im_tone_build(3).  All other
112       parameters as above.
113
114       Example:
115
116         example% im_tone_analyse $VIPSHOME/pics/master.v /tmp/lut.v       0.2
117       0.5 0.8 6.3 0.8 -3
118         example% im_ismonotonic /tmp/lut.v
119         255
120         example%     im_tone_map    $VIPSHOME/pics/master.v    /tmp/master2.v
121       /tmp/lut.v
122
123

RETURN VALUE

125       All functions returns 0 on success and -1 on error.
126

SEE ALSO

128       im_histplot(3), im_ismonotonic(3).
129

131       1995, National Gallery
132

AUTHORS

134       J. Cupitt
135
136
137
138                                  10 May 1991                          TONE(3)
Impressum