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