STRING - A standard Vicar input data set, and an optional data set
containing a histogram of the input image previously
generated by the program HISTGEN.
STRING - A standard Vicar output file.
FOUR INTEGERS - A standard Vicar size field specifying starting line,
starting sample, number of lines, and number of samples.
INTEGER - Starting line
INTEGER - Starting sample
INTEGER - Number of lines
INTEGER - Number of samples
INTEGER - Specifies the minimum DN value of the input data.
The domain of the stretch function (and the
histogram if it is required) is DNMIN to DNMAX.
DNMIN must be 0 for byte data and must be in the
range (-32768 to 0) for halfword data. If a HISTGEN
created histogram is supplied as the second input
DNMIN must be 0 regardless of data format. Any DN
values in the input less than DNMIN will be treated
as having a value of DNMIN.
(Default is DNMIN=0 for both byte, -32768 for halfword data.)
INTEGER - Specifies the maximum DN value of the input data.
The domain of the stretch function (and the
histogram if it is required) is DNMIN to DNMAX.
DNMAX has a maximum of 255 for byte data and 32767
for halfword data. Any DN values in the input greater
than DNMAX will be treated as having a value of DNMAX.
(Default is DNMAX=255 [byte] or DNMAX=32767 [halfword])
KEYWORD - These keywords control the printing of histograms and cumulative
distribution functions (CDF's). The CDF value for DN level N is
defined as the sum of the frequencies of all DN levels less than
or equal to N. That is,
N
CDF(N)= SUM HIST(J)
J=0
where CDF(N) is the CDF value of DN level N and HIST(J)
is the number of occurrences of DN level J in the image.
There are four valid values for HIST: IHIST, OHIST, ICDF, and OCDF.
More than one value may be specified. If all four keywords are used,
four separate histograms will be printed.
IHIST - The histogram of the input image will be printed.
OHIST - The histogram of the output image will be printed.
ICDF - The CDF of the input image will be printed.
OCDF - The CDF of the output image will be printed.
These keywords are valid for byte data only; halfword histograms
are not implemented in stretch. For IHIST and OHIST, the display
is normalized to the N+1 spike, where N is the value specified by
the parameter SPIKES. The default is for none of the histograms
or CDF's to be printed.
TWO INTEGERS - LINEAR=(min,max) performs the following transform:
a = (dnmax-dnmin)/(max-min)
DN(out) = a*(DN(in)-min) + dnmin
if DN(out) would be less than DNMIN: DN(out) = DNMIN
if DN(out) would be greater than DNMAX: DN(out) = DNMAX
INTEGER - If n > 0, the binary representation of the intensity
level is shifted n bits to the left and the n
most significant bits are truncated.
If n < 0, the binary representation of the intensity
level is shifted n bits to the right and the n
least significant bits are truncated.
INTEGER - Input intensities which are a multiple of n are set to the value specified by the DNVALUE parameter.
N INTEGERS - The input DN values specified are set the value
specified by the DNVALUE parameter.
This parameter causes a "gamma" stretch to be performed. The gamma
stretch is defined by the following formula:
/ \
DN = DNRANGE * | (DN -DN ) / DNRANGE | ** (1.0/gamma)
out | in min |
\ /
where the user specifies the parameter, gamma.
For byte data, this equation reduces to the form:
DN = 255.0 * ( DN / 255.0 ) ** (1.0/gamma)
out in
In all cases, the output DN is rounded to the nearest integer prior to
output.
N PAIRS REALS - TABLE=(in1,out1,in2,out2,..,inN,outN) will set the
input DN values in1,in2,... to the DN values
out1,out2,... and will linearly interpolate between
these points to compute the intervening DN values.
All DN values outside the range in1 to inN will
remain unchanged unless the parameter BACKGND is
also specified. In that case, all DN values
outside the range in1 to inN will be set to
the BACKGND value. The maximum number of pairs
which may be specified is 100. The values
in1,in2,...,inN must be specified in increasing
order.
N PAIRS INTEGERS - ITABLE=(in1,out1,in2,out2,...,inN,outN) will
set the input DN values in1,in2,... to the DN values
out1,out2,... but will not do any interpolation.
All DN values not explicitly specified, including
those outside the range in1 to inN will remain
unchanged unless the BACKGND parameter is also
specified. In that case, all DN values not
explicitly specified, including those outside the
range in1 to inN, will be set to the BACKGND value.
The maximum number of pairs which may be specified
is 100.
STRING - Allows the user to explicitly specify the transfer
function as a FORTRAN type expression with the
keyword DN as the independent variable. This
is similar to the VICAR program F2. For example,
FUNCTION="2*DN+3" will multiply each input DN
value by 2 and add 3. This will then be the output
DN value, provided it is in the range DNMIN to DNMAX.
If it is less than DNMIN it is set to DNMIN or if it
is greater than DNMAX it is set to DNMAX.
INTEGER - Specifies that a Power law histogram stretch is to
be performed. The program will stretch the input
image so that the output image's histogram will
approximate the shape of a power function. That is,
OCDF = (1.0 - |x|**power) / 2.0 for -1 < x < 1
The value specified, which must be greater than zero, is
used as the exponent in the function. The POWER stretch
is generated from the histogram of the input image after
the histogram has been modified according to the REXCLUDE,
IEXCLUDE, INCLUDE, and CUT parameters.
KEYWORD There are eight stretch options that are specified by a keyword.
These eight (ASTRETCH, GAUSS, SMOOTH, MEAN, PEAK, COMP, PSTRETCH,
and ELLIPSE) options are lumped together here.
ASTRETCH - Specifies that an Auto-stretch is to be performed. This is the
default stretch. The program will compute linear stretch values
such that a specified percentage of the data is saturated at
either end of the DN range and use these values to perform a
linear stretch on the data. The percentage of the data to
saturate is specified by the parameters PERCENT, HPERCENT, and
LPERCENT. Note: The program will first set the saturation
percentages at both ends to PERCENT/2 and then, if LPERCENT and/or
HPERCENT is specified, use these values as the saturation
percentage at the appropriate end. (Default is PERCENT=12.0)
COMP - Causes intensity levels to be complemented. The actual transform
is: DN(out) = DNMAX+DNMIN-DN(in)
GAUSS - Specifies a Gaussian stretch is to be performed. The program will
stretch the input image so that the output image's histogram will
approximate a Gaussian distribution. The mean DN level of the
resulting histogram will be (DNMAX-DNMIN)/2. The standard
deviation of the resultant histogram will be such that 2*GSIGMA
standard deviations of the Gaussian encompass the range DNMIN to
DNMAX. (Where GSIGMA may be specified by the user and has a
default value of GSIGMA=3.0). For GSIGMA=3.0 the output will have
a Gaussian distribution with standard deviation equal to
(DNMAX-DNMIN+1)/6. For values of GSIGMA less than 1.0, the
distribution will tend toward uniformity. The GAUSS stretch is
generated from the histogram of the input image after the
histogram has been modified according to the REXCLUDE, IEXCLUDE,
INCLUDE, and CUT parameters.
SMOOTH - Specifies a smooth stretch is to be performed. The program will
stretch the input image so that the output image's histogram
approximates a uniform distribution. Each level in the histogram
of the output image will have nearly the same frequency as every
other DN level. As a result, the cumulative distribution function
of the resulting histogram will approximate a constant ramp. The
smooth stretch is generated from the histogram of the input image
after the histogram has been modified according to the REXCLUDE,
IEXCLUDE, INCLUDE, and CUT parameters.
ELLIPSE - Specifies that an Elliptic histogram stretch is to be performed.
The program will stretch the input image so that the output image's
histogram will approximate the shape of an ellipse function. The
ELLIPSE stretch is generated from the histogram of the input image
after the histogram has been modified according to the REXCLUDE,
IEXCLUDE, INCLUDE, and CUT parameters.
MEAN - Specifies that a symmetrical stretch about the mean DN of the
picture is to be performed. The program will compute linear
stretch values in one of several ways and use these values to
perform a linear stretch on the data. The manner in which the
stretch values are computed depends on the parameters RANGE and
FACTOR. If the RANGE parameter is specified the data will be
stretched to the specified range about the mean. If FACTOR is
specified the mean DN is centered in the middle of the available
DN range and the data is stretched the specified factor about this
value. If neither RANGE nor FACTOR are specified, a symmetrical
stretch about the mean is performed saturating the percentage of
data specified by the PERCENT parameter (default=12.0). The MEAN
stretch is analogous to the PEAK stretch, with the mean DN used
instead of the peak DN. Note: The mean DN of the image is
calculated using the input histogram after it has been modified
according to the REXCLUDE, IEXCLUDE, INCLUDE, and CUT parameters.
PEAK - Specifies that a symmetrical stretch about the DN with the maximum
frequency in the image is to be performed. The program will
compute linear stretch values in one of several ways and use these
values to perform a linear stretch on the data. The manner in
which the stretch values are computed depends on the parameters
RANGE and FACTOR. If the RANGE parameter is specified the data
will be stretched to the specified range about the peak. If
FACTOR is specified the peak DN is centered in the middle of the
available DN range and the data is stretched the specified factor
about this value. If neither RANGE nor FACTOR are specified, a
symmetrical stretch about the peak is performed saturating the
percentage of data specified by the PERCENT parameter
(default=12.0). The PEAK stretch is analogous to the MEAN
stretch, with the peak DN used instead of the mean DN. Note:
The peak DN of the image is calculated using the input histogram
after it has been modified according to the REXCLUDE, IEXCLUDE,
INCLUDE, and CUT parameters.
PSTRETCH - Specifies that a periodic stretch is to be performed.
The transfer function is:
DN(out)=AMPL/2*SIN[2*PI*FREQ*DN(in)/(DNMAX-DNMIN)+PHI]+DC
where PI = 3.14159
and AMPL,FREQ,PHI,DC are parameters which may be specified
seperately by the user and which have the following defaults:
AMPL= DNMAX-DNMIN
FREQ= 1.0
PHI = 0.0
DC = (DNMAX-DNMIN)/2
TWO INTEGERS - Specifies that a linear post stretch will be performed
following the initial stretch. The initial stretch
will performed over the range DNMIN to DNMAX.
Specifying a post stretch of POST=(LVAL,HVAL) will
then take DN value DNMIN to LVAL and DN value DNMAX
to HVAL. Actually only one stretch is performed;
the composite of the initial and post stretches.
(Default is that no post-stretch is performed.)
INTEGER - Specifies the number of DN level frequency counts to saturate when printing histograms. The remaining frequency counts will be normalized to the N+1 spike. This scaling does not affect the frequency values printed out with the histogram, nor does it affect the operation of the program in generating the output image. (Default is SPIKES = 3)
SETS OF FOUR INTEGERS - (Starting line,Starting sample,Number of lines, Number of samples) - Defines the area of the input image which is used to calculate the histogram of the input image. This histogram is then used to generate the stretch parameters for certain stretches. Once the stretch parameters have been generated, the entire image or the portion specified in the SIZE field will be stretched. (Default is to calculate the histogram based on the entire image, or the portion specified in the size field.)
INTEGER - Specifies the line subsampling used to generate the histogram of the input image. Every N'th line of the input image is used to generate the histogram. The initial line will be the first line of the region specified by AREA, the first line specified in the size field ( if AREA is not specified ), or the first line of the input image if neither SIZE nor AREA is used. The value specified must be in the range 1 to 100. (Default is LINC=1)
N PAIRS INTEGERS - Specifies one or more DN ranges to exclude from
the stretch computation. The first value in each pair
must be less than the second and both must be in the
range DNMIN to DNMAX. A maximum of 100 pairs may be
specified. Overlapping DN ranges may be specified.
The frequencies of all excluded DN values are set to
zero in the input image histogram prior to using the
histogram to generate stretch parameters.
(Default is not to exclude any range of DN values, but to
exclude 0 and the maximum DN unless the INCLUDE keyword is
specified.)
N INTEGERS - Specifies individual DN values to exclude from the
stretch computation. A maximum of 100 values may be
specified. The frequencies of all excluded DN values
are set to zero in the input image histogram prior
to using the histogram to generate stretch parameters.
(Default is to exclude 0 and the maximum DN unless
the INCLUDE keyword is specified.)
KEYWORD - This parameter has one valid keyword value: INCLUDE.
If specified, it suppresses the default exclusion of 0 DN and
max DN ( 255 for byte data and 32767 for halfword data ) from
auto-stretch.
On the surface, this default exclusion may seem like a strange
default, but experience over the years has shown this to be
the most useful default. The default exclusion makes a
difference when there are a significant number of pixels with
0 DN or the maximum DN. Most often areas of 0 DN are background
areas or areas for which there are no data. Users
want to not include these areas generally. They are concerned
only about the part of the image that contains meaningful data.
Similarly, when there are lots of pixels with the maximum DN,
it generally means there is a saturated area that contains
no useful information, and is thus not of interest.
The INCLUDE keyword should generally be specified for
halfword images where 0 and negative DNs represent valid
image data.
REAL - Specifies a percentage of the maximum frequency count in the input image histogram. All DN values with a frequency count less than this pecentage of the maximum frequency count will be excluded from the stretch computation. The frequencies of these excluded DN values are set to zero in the input image histogram prior to using the histogram to generate stretch parameters. CUT must be in the range 0.0 to 100.0 (Default is not to cut any DN values.)
INTEGER - Specifies the DN value to use for the CONTOUR and ALARM stretches. The appropriate DN's will be set to this DN value. (Default is DNVALUE=DNMAX)
INTEGER - Specifies a DN value to use as background for the TABLE and ITABLE stretches. All DN values outside the range specified by TABLE, or all those not explicitly specified by ITABLE will be set to this value. (Default is to leave these DN's unchanged.)
REAL - Specifies the frequency to be used in the case of the PSTRETCH (periodic) stretch. (Default is FREQ=1.0)
REAL - Specifies the amplitude to be used in the case of the PSTRETCH (periodic) stretch. (Default is AMPL=DNMAX-DNMIN)
REAL - Specifies the phase to be used in the case of the PSTRETCH (periodic) stretch. (Default is PHI=0)
REAL - Specifies the mean to be used in the case of the PSTRETCH (periodic) stretch. (Default is DC=(DNMAX-DNMIN)/2 )
REAL - Used with the GAUSS stretch. The standard deviation of the resultant histogram will be such that twice GSIGMA standard deviations of the Gaussian encompass the histogram range. For GSIGMA = 3.0 there will be a Gaussian distribution with mean DN of mid-RANGE and standard deviation equal to one-sixth of the histogram range. For values of GSIGMA less than 1.0, the distribution will tend toward uniformity. (Default is GSIGMA = 3.0)
INTEGER - Specifies the manner in which a PEAK or MEAN stretch is to be done. This parameter will cause the PEAK/MEAN stretch to saturate all but the specified range symmetrically arranged about the peak/mean DN of the image. The specified stretch is always performed even if it is necessary to generate a stretch whose transform is defined by DN values which lie outside the range of the image. If neither PEAK nor MEAN is specified, the RANGE parameter is ignored. (Default in the case of a PEAK or MEAN stretch is to saturate, as close as possible, PERCENT of the data symmetrically about the peak/mean DN.)
REAL - Specifies the manner in which a PEAK or MEAN stretch is to be done. This parameter will cause the PEAK/MEAN stretch to generate a FACTOR times stretch about the peak/mean DN. The peak/mean DN is centered at DN = (DNMAX-DNMIN)/2. The appropriate keyword, (PEAK or MEAN), must also be specified. The specified stretch is always performed even if it is necessary to generate a stretch whose transformation is defined by DN values which lie outside the range of the image. FACTOR must be in the range 1 to (DNMAX-DNMIN+1)/2. (Default in the case of a PEAK or MEAN stretch is to saturate, as close as possible, PERCENT of the data symmetrically about the peak/mean DN.)
REAL - Specifies the total percentage of the input image to be saturated. The result is equivalent to specifying the parameters LPERCENT and HPERCENT where LPERCENT = PERCENT/2 and HPERCENT = PERCENT/2. This percentage applies to the input image DN distribution after exclusions have been performed. PERCENT must be in the range 0.0 to 100.0 (Default is PERCENT=12.0)
REAL - Specifies the percentage of the input image to be saturated at the low end. This percentage of the data will be saturated to DNMIN. This percentage applies to the input image DN distribution after exclusions have been performed. LPERCENT must be in the range 0.0 to 100.0 (Default is LPERCENT=PERCENT/2)
REAL - Specifies the percentage of the input image to be saturated at the high end. This percentage of the data will be saturated to DNMAX. This percentage applies to the input image DN distribution after exclusions have been performed. HPERCENT must be in the range 0.0 to 100.0 (Default is HPERCENT=PERCENT/2)
Parameters for STRETCH may be specified in the PARMS file or in the command line or in both. If any of the parameters are given in both, the command line value takes precedence.