USAGE: tonemap4 [-m method] [-k kind] [-t threshold] [-b bri] [-c con] [-s sat] [-e edge] [-r ramp] [-b blur] [-s shadows] [-h highlights] [-w window] [-g gvals] [-l log] [-A] [-C] infile outfile
USAGE: tonemap4 [-help]

-m ... method ....... method of dual gamma processing; ramp (r) or
..................... adaptive (a); default=ramp
-k ... kind ......... kind of extra processing; none (n), equalize (e),
..................... gaussian (g), space (s), or retinex (r);
..................... default=retinex
-t ... thresh ....... threshold for separating shadow and highlight
..................... regions; integers between 0 and 100; default is
..................... the mean graylevel of the brightness channel
-b ... bri .......... brightness enhancement percent; integer between
..................... -100 and 100; default=0
-c ... con .......... contrast enhancement percent; integer between
..................... -100 and 100; default=0
-s ... sat .......... saturation enhancement factor; float>0;
..................... default=0.6
-e ... edge ......... edge enhancement amount; float>=0;
..................... default=0
-r ... ramp ......... ramp amount in pixels for method=ramp; integer>=0;
..................... default=20
-B ... blur ......... blur amount for method=adaptive; float>0;
..................... default=3
-S ... shadows ...... desired shadow brightness in range 0 to 100 used
..................... for autogamma processing; also can be used to
..................... increase/decrease brightness in shadows;
..................... default=50
-H ... highlights ... desired highlight brightness in range 0 to 100 used
..................... for autogamma processing; also can be used to
..................... increase/decrease brightness in highlights;
..................... default=70
..................... positive or negative integer; default=0
-w ... window ....... window size as percent of image dimensions for
..................... kind=space; float>0; default=12.5
-g ... gvals ........ gaussian redistribution mean,lo,hi values for
..................... kind=gaussian; integers>0; default=60,60,60
-l ... log .......... amount of scaling for log preprocessing expressed as
..................... exponent for power of 10; default=0 (none)
-A .................. preprocessing to apply autolevel stretch; default is
..................... not to apply autolevel stretch
-C ... colorproc .... preprocessing to change colorspace to: RGB, sRGB; ..................... default is no change

PURPOSE: Enhances the shadows and/or highlight regions in an image using a dual gamma function plus an extra processing function.

DESCRIPTION: TONEMAP4 the shadows and/or highlight regions in an image using a dual gamma function plus an extra processing function, which can be either: none, equalize (histogram equalization), gaussian (histogram redistribution), retinex (multiscale method) or space (spatially adaptive contrast enhancement). The image is first converted to HSB colorspace. Then the channels are separated. The brightness channel is then thresholded to separate the shadow and highlight regions. The thresholded image is used as a mask against the brightness image to find the mean values in the two regions. These mean values are then used to compute appropriate gamma values, which are then applied separately to the brightness channel. These two modified brightness images are merged either by a ramped blending or by an adaptive blending based upon the local variances in the two modified brightness images. The resulting megerd brightness image is then combined with the hue and (optionally enhanced) saturation channels. Finally the resulting image is converted back to RGB.

ARGUMENTS:

-m method ... METHOD of dual gamma processing; ramp (r) or adaptive (a). The default=ramp.

-k kind ... KIND of extra processing. The choices are: none (n), equalize (e), gaussian (g), retinex (r) or space (s). Equalize is a histogram equalization. Gaussian is gaussian histogram redistribution. Retinex is multiscale enhancement. Space is a spatially adaptive contrast enhancement. Generally, retinex and none work the best, but for certain images, one or more of the other approaches may also work as well or better. The default=retinex.

-t threshold ... THRESHOLD for separating shadow and highlight regions. Values are integers between 0 and 100. The default is the mean graylevel of the brightness channel.

-b bri ... BRIGHTNESS enhancement percent. Values are integers between -100 and 100. The default=0

-c con ... CONTRAST enhancement percent. Values are integers between -100 and 100. The default=0

-s sat ... SATURATION enhancement factor. Values are floats>0. A value of sat=1 is no change. The default=0.6

-e edge ... EDGE enhancement amount. Values are floats>=0. The default=0

-r ramp ... RAMP amount in pixels for method=ramp. Values are integers>=0; The default=0

-B blur ... BLUR amount for method=adaptive. Values are floats>0. The default=0

-S shadows ... desired SHADOW brightness in the range 0 to 100, which is used for autogamma processing. It can also can be used to increase or decrease brightness in shadows, though generally it does not need to be adjusted. The default=50

-H highlights ... desired HIGHLIGHT brightness in the range 0 to 100, which is used for autogamma processing. It can also can be used to increase or decrease brightness in shadows, though generally it does not need to be adjusted. The default=50

-w window ... WINDOW is the moving window percentage of image size for kind=space. Values are floats>0 and are nominally between 5 and 20. Larger or smaller values can mitigate ringing. Larger values narrow ringing and smaller values broaden or diffues ringing. The default=12.5

-g gvals ... GVALS are the gaussian redistribution mean,lo,hi values for kind=gaussian. Values are comma separated integers>0. The default=60,60,60.

-l log ... LOG is the amount of scaling for log preprocessing expressed as exponent for power of 10. Generally this will only be needed for HDR images with very high dynamic range that require log processing in IM HDRI mode. The default=0 (no log processing).

-A ... Optional AUTOLEVEL preprocessing step. Generally this will only be needed for HDR images with very high dynamic range that require log processing in IM HDRI mode.

-C colorproc ... COLORPROC is an optional preprocessing step to convert the input image from some other colorspace to either RGB or sRGB. This seems to be needed for HDR Radiance images in XYZ colorspace (.hdr suffix) prior to a bug fix in .hdr images in IM 6.7.2.0. The choices are: RGB and sRGB. The default is no change. Note that somewhere between IM 6.7.5.5 and IM 6.7.6.7, colorspace RGB and sRGB were swapped to correct their meaning.

REQUIREMENTS: redist, space and retinex scripts. Also IM 6.5.9-0 to support the -brightness-contrast function.

NOTE: kind=space will be slow due to the use of -fx when not in HDRI mode.

Note: For IM 6.7.5.5 or higher, in order to reproduce some of the examples below, one may have to add, remove or change -C arguments, due to the swap of the meaning of -colorspace RGB and -colorspace sRGB. Also if -c is not none for .hdr images, then some parameter changes may be needed. For more details, see http://www.fmwconcepts.com/imagemagick/tonemap4/tonemap_tests.txt

Reference for adaptive method:
http://www.ieice.org/proceedings/ITC-CSCC2008/pdf/p457_A4-3.pdf

CAVEAT: No guarantee that this script will work on all platforms, nor that trapping of inconsistent parameters is complete and foolproof. Use At Your Own Risk.