USAGE: histmatch [-c colormode] [-s satmode] infile1 infile2 outfile
USAGE: histmatch [-h or -help]

-c .... colormode ..... colorspace/channel to use to compute the image
....................... histograms; choices are: gray, intensity, luminance,
....................... lightness, brightness, average and rgb; default=gray
-s .... satmode ....... colorspace mode to use to modify saturation;
....................... choices are: HSB or HSL; default is no
....................... change in saturation.
....................... infile2 will be modified to match infile1

PURPOSE: To modify one image to try to match its histogram and optionally saturation to that of another image.

DESCRIPTION: HISTMATCH modifies one image to try to match its histogram and optionally saturation to that of another image. The second image will be modified to match the first image. Saturation changes only apply to color images, not grayscale ones. The choice of colormode determines what colorspace or channel will be used to compute the histograms of the two images. A non-linear transformation is then computed from the cumulative histograms of the two images. This non-linear transformation is then applied to the second image using -clut to generate the output. If colormode=rgb, then each channel of the second image will be processed idependently. For all other colormodes, a common transformation will be applied to all channels of the second image.

IMPORTANT: This histogram transformation can only do so much. Once information is lost, it generally cannot be adequately recovered. For example, if the second image has too low a contrast, the histogram will be very narrow with large bin values. The histogram can be spread out to increase the dynamic range, but any one bin cannot be broken into multiple bins. Likewise, if the image has too high a contrast, the histogram will be very wide and much of the data will be contained in the very high and very low bins and little data in the middle bins. Again any one bin cannot be broken into multiple bins, but small bins can be combined.

ARGUMENTS:

-c colormode ... COLORMODE is the colorspace/channel to use to compute the histograms of the two images. The choices are: gray, intensity, luminance, lightness, brightness, average, and rgb. Values of gray and intensity are equivalent. If colormode=rgb, then each channel of the image will be processed independently. The default is gray.

Gray or Intensity uses statistics from -colorspace Gray.
Luminance uses statistics from -colorspace Rec709Luma.
Lightness uses statistics from the lightness channel of -colorspace HSL.
Brightness uses statistics from the brightness channel of -colorspace HSB.
Average uses statistics from the first channel of -colorspace OHTA.
RGB uses statistics independently from each channel of -colorspace RGB.
See definitions at: http://www.imagemagick.org/script/command-line-options.php#colorspace

Note: generally there are only slight differences between the various non-rgb colormode results. Colormode=rgb can cause color balance shifts.

-s satmode ... SATMODE is the choice of saturation colorspace to use when modifying the saturation. Choices are: HSB and HSL. The default is to make no change in saturation. If used, I recommend HSB. This argument is only applicable when both images are color (not grayscale).

REQUIRES: IM version 6.4.5-1 or higher if modifying saturation due to the use of -set option:modulate:colorspace. Otherwise, requires IM version 6.3.9-2 due to the use of -format "%[colorspace]". Also, requires NetPBM PGM. See http://netpbm.sourceforge.net/

NOTE: Thanks to Anthony Thyssen for the suggested changes from shell calculations for the histograms to the use of AWK. This has produced a 10x performance speed up.

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.