USAGE: redist [-g] [-s shape] [-m colormodel] [-c channel] [mean[,lo[,hi]]] infile outfile
USAGE: 3Drotate [-h or -help]

-g ............... display the grayscale histogram (graph) with
.................. distribution function overlay
-s . shape ....... redistribution shape - choice of Gaussian or Uniform;
.................. default is Gaussian
-m . colormodel .. processing (color) model; default=RGB
-c . channel ..... channel number to process; channel=0,1,2;
.................. default -> see below
mean ............. desired mean for Gaussian distribution;
.................. mean in range 0 to 100; default=60
lo ............... desired 1 sigma roll-off point of distribution on the
.................. low side of the Gaussian peak; lo > 0; default=60
hi ............... desired 1 sigma roll-off point of distribution on the
.................. high side of the Gaussian peak; hi > 0; default=60

PURPOSE: To modify an image so that its (grayscale) histogram has either a Gaussian (sometimes called normal or bell-shaped) distribution or a Uniform (constant height) distribution. The latter is equivalent to histogram equalization.

DESCRIPTION: REDIST is designed to apply an intensity mapping transformation to an image such that the resulting image's grayscale histogram has a specified distribution shape (Gaussian or Uniform). It works by first converting the image to some color space, nominally HSL or RGB. Then it computes the grayscale cumulative histogram of for the image. If the image is converted to other than RGB, then the grayscale will come from an intensity-like channel. Otherwise, if the color space is RGB, the RGB image is converted to a simple grayscale image. The script then generates the integral of the specified distribution scaled to the last value in the cumulative histogram. For each value in the image's cumulative histogram, it finds the closest value in the integral and then looks to see what is its graylevel. It uses those graylevel values as the y-value in a mapping transformation whose x-values range from 0-255. This mapping transformation is expressed as a 1-D image and used with the IM function -fx or -clut to transform the input image's values in each of its channels. If a graph is desired, it is normally just viewed. However, a default parameter in the program can be set to allow it to be saved as outfilename_graph.gif. To end the script, close/quit the graph image.

ARGUMENTS:

-h or -help ....... displays help information.

-g ................ displays graph of intensity mapping function.

-s SHAPE defines the desired distribution shape, which can be either Gaussian (also known as normal or bell-shaped) or Uniform (constant height). The default is Gaussian if -s shape is not specified.

-m COLORMODEL defines the color model to use for the processing of a color image into a grayscale image in order to compute the required cumulative histogram. If a color space other than RGB is specified, then the image is first transformed into that color space and an intensity-like channel will then be used to compute the cumulative histogram. If RGB is selected, the RGB image is converted to grayscale, which is then used to generate the cumulative histogram. The default value is RGB when -m colormodel is not provided. Note that results vary between the different color models. Generally HSL, RGB or sRGB tend to produce the best results, but OHTA, YIQ and YUV also produce meaningful and similar results. If colormodel is Gray, then the result will be a grayscale image even if the original image is true color.

-c CHANNEL defines which channel to use for the histogram processing. Values for channel may be 0, 1 or 2, which correspond to those generated by the conversion to that color space. For RGB, this is R=0, G=1, B=2. For HSL, this is H=0, S=1, L=2. The same goes for the other color spaces. This will override the default value which is set for most colorspaces to the most intensity-like channel. For HSL and HSB, this is channel 2. For all others except RGB, sRGB and Gray, this is channel 0. For RGB, sRGB and Gray, the default is to use the grayscale version of the image to get the histogram.

MEAN is the desired center point for the peak in the Gaussian distribution. It is an integer in the range of 0 to 100 (graylevel %). Its default value is 60.

LO is the desired 1 sigma roll-off point on the low side of the distribution, expressed as pixels from the peak. This is where the Gaussian shape has dropped to 61% of its maximum value. The range between the peak and this point, will contain 34% of all the pixels in the image. It is an integer which is greater than zero. Its default is 60.

HI is the desired 1 sigma roll-off point on the high side of the distribution, expressed as pixels from the peak. This is where the Gaussian shape has dropped to 61% of its maximum value. The range between the peak and this point, will contain 34% of all the pixels in the image. It is an integer which is greater than zero. Its default is 60. If LO is provided, but not HI, then HI will be set equal to LO.

REQUIRES: NetPBM PGM format intermediate image. See http://netpbm.sourceforge.net/