.TH TONE 3 "10 May 1991"
.SH NAME
im_tone_build, im_tone_map, im_tone_analyse, im_tone_build_range \- tone-curve adjustment of LAB
images
.SH SYNOPSIS

int 
.br
im_tone_build_range( 
.br
   int in_max, int out_max,
.br
   IMAGE *lut, 
.br
   double Lb, double Lw,
.br
   double Ps, double Pm, double Ph,
.br
   double S, double M, double H )

int 
.br
im_tone_build( 
.br
   IMAGE *lut, 
.br
   double Lb, double Lw,
.br
   double Ps, double Pm, double Ph,
.br
   double S, double M, double H )

int 
.br
im_tone_analyse( 
.br
   IMAGE *in, 
.br
   IMAGE *lut, 
.br
   double Ps, double Pm, double Ph,
.br
   double S, double M, double H )

int 
.br
im_tone_map( IMAGE *in, IMAGE *out, IMAGE *lut )

.SH 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

.B 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

.B im_tone_build(3)
is a convenience function that calls 
.B im_tone_build_range(3)
with ranges suitable for tone correcting a LABQ image to a LABS image.

Use 
.B im_ismonotonic(3) 
to check that the slope of your tone curve is always >0,
use 
.B im_histplot(3) 
to graph the curve, use 
.B im_tone_map(3) 
to apply your curve to an image.

.B im_tone_map(3)
map just the L channel of a LabQ or LabS image through a tone
curve.

.B im_tone_analyse(3)
find the histogram of a LabS or LabQ image and use that to
set the Ln and Lw parameters of 
.B 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

.SH RETURN VALUE
All functions returns 0 on success and -1 on error.
.SH SEE ALSO
im_histplot(3), im_ismonotonic(3).
.SH COPYRIGHT
1995, National Gallery 
.SH AUTHORS
J. Cupitt