Help for RATIO

PURPOSE:
RATIO operates on two input pictures to generate a third (comparison) picture.
There are four modes of operation:

	1. RATIO            OUT = GAIN*(IN1/IN2)+OFFSET
	2. LOG RATIO        OUT = GAIN*LN(IN1/IN2)+OFFSET
	3. DIFFERENCE       OUT = GAIN*(IN1-IN2)+OFFSET
	4. LOG DIFFERENCE   OUT = GAIN*LN(IN1-IN2+256)+OFFSET

The GAIN and OFFSET values are calculated by RATIO so that either (centering
option, default) the mean DN of the output picture will be 128, and the 
saturation on each tail will be at most at the user-specified level, or 
(nocentering option) the saturation on each tail will be at the user-specified
level. The program F2 is used by RATIO to form the output picture.

EXECUTION:

Examples

Basic Form

RATIO INP=(PIC1,PIC2) OUT=RATIO

This is the simplest call to RATIO.  Output picture RATIO will be made using
the ratio of the two pictures, as in mode 1 above.  Ratioing, then, is the
default mode.  To use differencing, instead, specify 'DIFFEREN.  To get a
natural log output of either the ratio or the difference, use 'LOG or
MODE2=LOG.  (Note: It is possible to not give an output data set name.  In
this case, the program will print the gain and offset, but won't write an
output data set.)

Sampling Parameters

RATIO INP=(PIC1,PIC2) OUT=RATIO AREA=(1,1,1024,1024) LINC=5

In this example, only the upper-left corner will be used for sampling, and
further, only every fifth line within this area.

RATIO INP=(PIC1,PIC2) OUT=RATIO SAMPLE=20.0

Here, the SAMPLE parameter is used to specify that 20% of the lines in the
image are to be used for sampling.  The default value for SAMPLE is 5.0, so
normally, sampling is done using only 5% of the image lines.

Offset and Gain Parameters

RATIO INP=(PIC1,PIC2) OUT=DIFFPIC 'DIFF INCLUDE=(-200.0,200.0)

The INCLUDE option is used here to specify that only difference values between
-200.0 and 200.0 are to be used for statistics.  The default for this range
when calculating differences is [-249.5,250.5].  This option can also be
used to exclude certain ratio values; the default range for ratios is [0.,5.].
If the LOG mode is used, INCLUDE applies to the value before the logarithm
is calculated.

RATIO INP=(PIC1,PIC2) OUT=DIFFPIC 'DIFF THRESHOL=5.0

Here, the THRESHOLd option is used to toss out any difference values which
occur less than 5.0 percent as much as the most-frequent value; these are then
excluded from the calculations.  This option can be used for ratios, as well.
The default value is 0.0, that is, to never exclude values only on the basis
of frequency.  

RATIO INP=(PIC1,PIC2) OUT=RATIO 'NOFILTER PERCENT=2.0

Normally, a five-element box filter is used to smooth the histogram of ratio
and difference values.  'NOFILTER prevents filtering of the histogram.
    The PERCENT keyword specifies the desired saturation level (in percent).
Since the mean is pegged at DN=128, and the stretch is linear, only one end
of the histogram will be saturated at the specified percentage.  The saturation
at the other end will be less.  The default is 2.0 percent, as used in the
example.

Miscellaneous Parameters

RATIO INP=(PIC1,PIC2) OUT=LOGRAT 'LOG 'NODISPLA ATM1=-0.5 ATM2=-0.5

This last example illustrates the remaining commands.  The output picture
will be calculated from the logs of the ratios using the whole image (but
only five percent of the lines) as the sampling area.  Since we are calculating
a ratio, values outside of the range [0.0,5.0] will be excluded, but no
values will be excluded solely on the basis of frequency.  The box filtering
will be done as normal to smooth the histogram, and the program will saturate
the output image to two percent.
    Normally, the ratio (or difference) histogram is printed. 'NODISPLA
prevents this.  Finally, ATM1 and ATM2 are real numbers which will be added to
IN1 and IN2, respectively, before any ratios or differences are calculated. 
These values are generally used as atmospheric correction terms and are usually
negative.  The default is ATM1 = ATM2 = 0.0. 

OPERATION:
The region between the two INCLUDE values is divided into 500 equal parts.
These become the permissible histogram values.  The input pictures are sampled
according to the AREA, SAMPLE, and LINC parameters to form the histogram.
Values beyond the INCLUDE range are ignored.
    The histogram is filtered, then levels populated below the THRESHOLD are
set to zero.  The mean of this histogram is calculated .  Gain and offset 
values are chosen so that the mean is transformed to 128 and the higher of
the dark and bright saturation levels is equal to the requested level of
saturation.
    The histogram is displayed, and the gain and offset passed to the program 
F2, which generates the output picture.

WRITTEN BY:  A.R. Gillespie, 4 January 1974
COGNIZANT PROGRAMMER:  Ron Alley
REVISION:  4		4 June 1986