TONE(3X)

NAME
im_tone_build, im_tone_map, im_tone_analyse - tone-curve adjustment of LAB images

SYNOPSIS
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(): generate tone curve for adjustment of Lab image. LUT we make is always 1024 elements, each element is a LabS L value. 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 Use im_ismonotonic() to check that the slope of your tone curve is always >0, use im_histplot() to graph the curve, use im_tone_map() to apply your curve to an image. im_tone_map(): map just the L channel of a LabQ or LabS image through a tone curve. im_tone_analyse(): find the histogram of a LabS or LabQ image and use that to set the Ln and Lw parameters of im_tone_build(). All other parameters as above. Example:
  example% tone_analyse $VIPSHOME/pics/master.v /tmp/lut.v 0.2 0.5 0.8 6.3 0.8 -3
  example% ismonotonic /tmp/lut.v
  255
  example% 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(3X), im_ismonotonic(3X).

COPYRIGHT
1995, National Gallery

AUTHORS
J. Cupitt