hstret Documentation

hstret - Calculate stretch table from histograms of each band
GENERAL DESCRIPTION - This program calculates a table of stretch pair
values that can be used by the "stretch" program to perform a linear
transformation on the pixel values in a cube file.  In addition to the
stretch input min/max values, the table file will contain the band
numbers of the input cube file that identify each set of stretch
parameters.  (Note that these band numbers will NOT be band numbers
within the virtual cube selected by the input subcube specifier SFROM.
Also, these will NOT be the "original" band numbers recorded by the
BAND_BIN_ORIGINAL_BAND keyword in the label of the cube file.)

The following are the column names, data types, default text formats,
and descriptions for the columns in the output table data object:
    BAND (INTEGER*4, I5) - Band number in input cube file
    IMIN (REAL*4, E15.7) - Stretch input minimum value
    IMAX (REAL*4, E15.7) - Stretch input maximum value
    OMIN (REAL*4, E15.7) - Stretch output minimum value
    OMAX (REAL*4, E15.7) - Stretch output maximum value
Note that the values in the OMIN/OMAX columns are specified by the
OMIN/OMAX TAE parameters and thus will be the same in each row of
the table object.

The SFROM subcube specifier selects the part of the input cube file
that is to be examined.  The output stretch table file will contain
one row of stretch parameters for each input band selected by SFROM.
Only core data values are examined.  All suffix data are ignored.


INITIAL STRETCH COMPUTATION - First, "hstret" examines the histogram of
each band and computes the stretch min and max values for that band so
that the specified fraction of the total number of pixels would be
saturated, i.e., lie outside the computed min/max range.  The MINSAT
and MAXSAT parameters specify the desired fraction of pixels to be
saturated.  All pixel values that are non-NULL (i.e., valid or
saturated) are used for these calculations.  Note that pixels that
are already saturated in the input cube file will be included along
with the count of pixels that would be saturated by the stretch.


FINDING RANGE OF VALUES IN EACH BAND - If the MINSAT and/or MAXSAT
parameters are 0.0, then the corresponding initial min/max values that
are computed will be the minimum and/or maximum values that occur
within each band.  In this situation, if any band contains any
saturated input values, then the min/max values in the table file will
be the smallest and/or largest valid values that can be represented in
the file.

If MINSAT=0.0 and MAXSAT=0.0 are specified for a 32-bit input cube file,
then the details of the computation of the range of values within each
band depend upon the BINMODE parameter.  When BINMODE=FIXED is
specified, the initial stretch computation involves mapping a range
of 32-bit values into 16-bit histogram bin numbers.  (See below for
more details on the binning operation.)  The initial stretch min/max
values will then be the floating point values that correspond to the
centers of the lowest and highest occupied bins.  This will be slightly
different from the actual range of values in the input cube file, which
corresponds to the extreme ends of the lowest and highest occupied bins.
When BINMODE=AUTO is specified along with MINSAT=0.0 and MAXSAT=0.0,
the binning operation is omitted and the initial stretch min/max is
the exact range of 32-bit floating point values found within each band.


EXPANSION FACTOR - After computing the initial min/max stretch values
based on MINSAT, MAXSAT and the histogram, "hstret" will next compute
new min/max values by expanding the range by the specified expansion
factor.  This expansion is done so that the center of the new range is
the same as the center of the original range.  See the description of
the EXPFACT parameter for more details.


8-BIT OR 16-BIT BINNING - When examining an 8-bit or 16-bit cube file,
the histogram binning is done using one bin for each possible 8-bit
or 16-bit pixel value.


32-BIT BINNING - When examining a 32-bit floating point cube file, the
floating point values are binned by converting them to 16-bit format
and using one bin for each possible resulting 16-bit value.  The
BINMODE parameter specifies how this binning operation is to be done.

If BINMODE=AUTO is specified, then the range of values that actually
occurs within each band will be determined and this range will be
mapped into the range of 16-bit bins.  This will result in different
bins being used for each band.  This option is useful for processing
a cube file in which there is a wide variation in the range of values
in different bands.

If BINMODE=FIXED is specified, then the RANGE parameter specifies the
range of floating point values that are to be mapped into the range
of 16-bit bins.  This will result in the same bins being used for each
different band of the input cube file.  During this binning operation,
some 32-bit floating point pixels may have values that lie outside the
specified RANGE of values being mapped into the 16-bit histogram bins.
The number of pixels that are thus saturated by this binning operation
will be reported.  These are values that are considered to be
saturated when computing the resulting min/max stretch.  If the number
of such values is non-zero, then the computation of the stretch
min/max may not have the desired effect.  Specifying a RANGE that
includes all the pixel values in the file will avoid this problem.
However, specifying a range that is much greater than the range of
values that actually occurs in the file will result in loss of
precision because the floating point pixel values will be put into a
smaller number of bins.  (Note that the "dsk2dsk" program can be used
to examine a cube file and report the actual range of pixel values
that occur in the file.)  Using the BINMODE=FIXED option for
processing a file that has a wide variation in the range of values in
different bands might result in loss of precision in those bands which
have a very small range of values.


OUTPUT STRETCH VALUES - The output table file will contain the real
numbers that correspond to the min/max bin numbers.  The file will
NOT contain the integer bin numbers used for computing the histograms.

If the range of pixel values within a band of the input file is too
small (or if the pixel values are all the same), then the stretch
parameters in the IMIN/IMAX columns in the output table file will be
set to (0.0, 0.0).  This will cause the corresponding band to be set to
all NULL values when processed by the "stretch" program.

Programmer:  Jim Mathews, U.S.G.S., Flagstaff, AZ

Input cube file name
  (default extension is .cub)

NONE

Input subcube specifier

--

Stretch table file name
  (default extension is .tbl)

"strtable.tbl"

Stretch table object name
  (default is TABLE)

"TABLE"

Fraction saturated at MIN

0.01

Fraction saturated at MAX

0.01

Expansion factor

1.0

Binning mode for 32-bit files
  (AUTO or FIXED)

"AUTO"

Range of values for FIXED
binning of 32-bit cube file

0.0, 1023.0

Output minimum value

0.0

Output maximum value

1023.0

User comment

" "

ADDITIONAL NOTES:

Parm	Description
FROM	Specifies the disk file that contains the image cube that is to be examined. If the file extension is omitted, then ".cub" will be assumed.
SFROM	Input subcube specifier. Selects the part of the input cube file that is to be examined. SFROM specifies the subcube using a single string for all three dimensions of the cube. The order of the three dimensions is always "samples:lines:bands". If a dimension is left blank, all the data for that dimension is selected. The default value of NULL for SFROM selects the entire cube. Any application below can be used for any dimension. To select specific data from any dimension: "10-100(3):11,12,15-20:1-10(2)" = This example will select every third sample starting with sample 10 thru 100. It selects lines 11 and 12, and 15-20. It selects every other band, starting with band 1 thru 10. There are special characters that can be used for selecting a subcube efficiently, such as "*","#", and "~". For examples type "help sfrom" in TAE. **NOTE** For more examples and explanation of the many features of the SFROM parameter, tutor the sfrom.pdf or refer to Introduction To ISIS, Section 6, of the ISIS User's Manual **
TBLTO	Specifies the name of the output stretch table file. If no file extension is specified, then ".tbl" will be assumed.
OBJNAM	Name of the table object in TBLTO that contains the stretch values. If a NULL value (all blanks) is specified, then "TABLE" will be assumed.
MINSAT	Specifies the fraction of the total number of non-NULL pixels in each band that should be saturated at the minimum value. This should be a number in the range 0.0 to 1.0. If 0.0 is specified, then the IMIN/IMAX columns of the output table file will contain the minimum values found in each band.
MAXSAT	Specifies the fraction of the total number of non-NULL pixels in each band that should be saturated at the maximum value. This should be a number in the range 0.0 to 1.0. If 0.0 is specified, then the IMIN/IMAX columns of the output table file will contain the maximum values found in each band.
EXPFACT	Specifies the expansion factor to be applied to the min/max range that was calculated based on the MINSAT and MAXSAT parameters. The new min/max values that are written to the output table file are thus calculated as follows: AVE = (MIN+MAX) / 2.0 DELTA = MAX - MIN NEW_MIN = AVE - (EXPFACT * (DELTA/2.0)) NEW_MAX = AVE + (EXPFACT * (DELTA/2.0))
BINMODE	Specifies the mode of binning to be used for examining a 32-bit cube file. BINMODE=AUTO specifies that the actual range of values found within each band should be used as the range to map into the available histogram bins. A different binning range is thus used for each different band. BINMODE=FIXED specifies that the range given by the RANGE parameter should be used as the range to map into the available histogram bins. The same binning range is thus used for all bands. BINMODE is ignored for 8-bit or 16-bit cube files.
RANGE	Specifies the range of floating point cube file values that is to be mapped into the available histogram bins. This parameter is used only when BINMODE=FIXED is used with 32-bit cube files. It is ignored for 8-bit or 16-bit cube files or when BINMODE=AUTO is used for 32-bit files.
OMIN	The output minimum value that will be written to the OMIN columns of the output table file to be used by the "stretch" program.
OMAX	The output maximum value that will be written to the OMAX columns of the output table file to be used by the "stretch" program.
USERNOTE	Comment from the user. This will be recorded in the ISIS session log file and also in the History entry that is put into the History object of the output file.