Man Linux: Main Page and Category List

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)