---
name: "im_tone_map"
section: "3"
platform: "linux"
package: "libvips-dev"
version: "7.20.7-1+b3"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/im_tone_build"
---

# im\_tone\_map(3)

tone-curve adjustment of LAB images

Part of [im\_tone\_build(3)](/im_tone_build/3.md).

## 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)](/im_tone_build/3.md)** 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)](/im_histplot/3.md)** to graph the curve, use  **[im\_tone\_map(3)](/im_tone_map/3.md)** to apply your curve to an image.

**[im\_tone\_map(3)](/im_tone_map/3.md)** map just the L channel of a LabQ or LabS image through a tone curve.

**[im\_tone\_analyse(3)](/im_tone_analyse/3.md)** find the histogram of a LabS or LabQ image and use that to set the Ln and Lw parameters of  **[im\_tone\_build(3)](/im_tone_build/3.md).** 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_histplot/3.md), im\_ismonotonic(3).

## COPYRIGHT

1995, National Gallery

## AUTHORS

J. Cupitt