stretch Documentation

stretch - Stretch pixel values in a cube file

This program "stretches" the pixel values in the core of a cube file
by applying a linear scaling to the pixel values.  The STRTYPE
parameter allows selection of several different ways of determining
how the range of input values is scaled into the desired range of
output values, which is specified by the STRETCH parameter or in a
table file.

STRTYPE=MINMAX will apply the same scaling to all wavelength bands.

STRTYPE=TMINMAX will apply a different scaling to each band.  The
scaling to use for each band is supplied by a table file, which can
be produced by the HSTRET program or a text editor.  If an ASCII file
is created, you must run the ASC2TBL program to convert the ASCII
file to a binary table file.  The table file contains 5 columns:
BAND, IMIN, IMAX, OMIN, and OMAX.  Different stretch values can be
applied to parts of the input pixel value range of each band by
repeating the band number with different IMIN/IMAX, OMIN/OMAX values.

STRTYPE=BANDRANGE will apply a different scaling to each band.  For
this option, the total range of input values within each band is
scaled into the specified range of output values.

See the description of the STRTYPE parameter for additional information
on the stretch options.

The SATURAT parameter is a switch to allow the user to stretch
values that fall outside the minimum or maximum stretch values.
If SATURAT = YES, those values that fall outside the
minimum and maximum stretch values will be set to either low or
high representation saturation values.  If SATURAT = NO, the
values that lie outside the minimum and maximum stretch values will
be stretched the same as values that lie within the minimum and
maximum stretch values.

In addition to specifying the range of output values into which the
input values are scaled, the ORANGE parameter also specifies the range
of values that can be represented in the output file if the output
pixel type is 1 (8-bit) or 2 (16-bit).  In this case, input values
that lie outside the selected range of input values will be scaled into
output values that lie outside the range of values that can be
represented.  These will thus be stored in the output file as the
special high or low representation saturation values.

Any special pixel values found in the input file will be propogated
to the output file unchanged unless a valid value is entered for
NULVAL, HRSVAL, HISVAL, LRSVAL, and LISVAL.  These five parameters
represent NULL, High Resolution Saturation (HRS), High Instrument
Saturation (HIS), Low Resolution Saturation (LRS), and Low Instrument
Saturation (LIS) values, respectively.

Any suffix data selected by the input subcube specifier are
propagated unchanged to the output file.

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

Input cube file name
  (default extension is .cub)

NONE

Input subcube specifier

--

Output cube file name
  (default extension is .cub)

NONE

Stretch type:
  MINMAX, TMINMAX, BANDRANGE

BANDRANGE

Output saturation values:
  YES, NO

YES

Stretch pairs
  (for STRTYPE = MINMAX)
  Max of 7 decimal places

0.0, 0.0, 100.0, 255.0

Stretch table file name
  (default extension is .tbl)

--

Stretch table object name
  (default is TABLE)

"TABLE"

Value to change NULL
  special pixel values to

--

Value to change HRS
  special pixel values to

--

Value to change HIS
  special pixel values to

--

Value to change LRS
  special pixel values to

--

Value to change LIS
  special pixel values to

--

Output pixel type
 NULL = input type
    1 = 8 bit
    2 = 16 bit
    3 = 32 bit

--

Output min/max data range

--

User comment

" "

ADDITIONAL NOTES:

Parm	Description
FROM	Input cube file name. If the file extension is omitted, then ".cub" will be assumed.
SFROM	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 **
TO	Output cube file name. If the file extension is omitted, then ".cub" will be assumed.
STRTYPE	Specifies the type of linear stretch function that is to be applied. The available options include MINMAX, TMINMAX, and BANDRANGE. MINMAX specifies that a single stretch function is to be applied to all the pixels in the input file. The STRETCH parameter specifies the range of input and output values for stretching the pixel values. The values for STRETCH should be entered in the form IMIN1, OMIN1, IMIN2, OMIN2, etc. Input values outside the min/max range of input values entered in the STRETCH parameter are converted to the high or low representation saturation values unless the SATURAT parameter is set to "YES". If you would like the values outside the intended min/max output values to be represented as the min or max value the stretch function should contain duplicate output values for the low or high ends. For example, if the intended min/max output values are 10.0 and 100.0 and you would like values above or below this to be set to 10.0 or 100.0, the STRETCH parameter would look like, STRETCH=input1, 10.0, input2, 10.0, input3, 100.0, input4, 100.0. This same technique can be used in the table file for STRTYPE=TMINMAX discussed below. TMINMAX specifies that a different linear IMIN/IMAX stretch is to be applied to each different wavelength band. The STRFILE parameter specifies the name of the disk file that contains the table of IMIN/IMAX, OMIN/OMAX values to be used. (This file can be produced by the HSTRET program.) For each band, the range of values specified in the corresponding table file entry is linearly scaled into the range of output values specified by OMIN/OMAX. Different stretch values can be applied to parts of the input pixel value range of each band by repeating the band number with different IMIN/IMAX, OMIN/OMAX values. If the table file does not contain an entry for an input file band (or if the IMIN value is greater than or equal to the IMAX value), then the entire output band is set to NULL values. BANDRANGE specifies that a different MIN/MAX stretch is to be applied to each different wavelength band. The input range that actually occurs in each band is determined and that range of values is linearly scaled into the range of output values specified by ORANGE.
SATURAT	Set this value to "YES" if you wish to set those values that lie outside the minimum and maximum stretch values to the special pixel values, low- or high-representation saturation values. Set this value to "NO" if you wish to stretch those values that lie outside the minimum and maximum stretch values the same as those that fall within the minimum and maximum stretch values.
STRETCH	Enter input and output stretch pairs to scale the core pixel values into. Up to 25 pairs may be entered and are of the form input1, output1, input2, output2, etc. For example, if you entered STRETCH = 0.0,0.0,1.0,0.0,10.0,255.0. This would be interpreted as follows: INPUT OUTPUT 0.0 0.0 1.0 0.0 10.0 255.0 The input values must be increasing and a maximum of 7 deciamal places will be read. This parameter is used only for STRTYPE=MINMAX.
STRFILE	Specifies the name of the stretch table file. This parameter is used only for STRTYPE=TMINMAX. This file can be produced by the HSTRET program. If no file extension is specified, then the default extension .TBL is used.
TBLOBJ	Name of the table object in STRFILE that contains the stretch values. If a NULL value (all blanks) is specified, then "TABLE" will be assumed.
NULVAL	If you want the NULL values found in the input file to be changed to a valid value, enter the valid value. If you want the NULL values found in the input file to be propogated to the output file unchanged, leave this parameter as the default (--) value.
HRSVAL	If you want the High Resolution Saturation (HRS) values found in the input file to be changed to a valid value, enter the valid value. If you want the HRS values found in the input file to be propogated to the output file unchanged, leave this parameter as the default (--) value.
HISVAL	If you want the High Instrument Saturation (HIS) values found in the input file to be changed to a valid value, enter the valid value. If you want the HIS values found in the input file to be propogated to the output file unchanged, leave this parameter as the default (--) value.
LRSVAL	If you want the Low Resolution Saturation (LRS) values found in the input file to be changed to a valid value, enter the valid value. If you want the LRS values found in the input file to be propogated to the output file unchanged, leave this parameter as the default (--) value.
LISVAL	If you want the Low Instrument Saturation (LIS) values found in the input file to be changed to a valid value, enter the valid value. If you want the LIS values found in the input file to be propogated to the output file unchanged, leave this parameter as the default (--) value.
OTYPE	Output pixel data type. Permitted values are: NULL = output type is same as input file pixel type 1 = 8-bit (integer with type conversion parameters) 2 = 16-bit (integer with type conversion parameters) 3 = 32-bit (floating point) When processed data are being written back into the input file, the output pixel type must be the same as the existing pixel type in the input file.
ORANGE	Output pixel data range. If ORANGE is NULL, then the CORE_BASE and CORE_MULTIPLIER in the output file will be set to represent the same range of data as the input file. If OTYPE=1 (8-bit) or OTYPE=2 (16-bit), then the CORE_BASE and CORE_MULTIPLIER in the output file will be set to values that allow representing the specified range of output values. Output values outside this range will be stored as a special "representation saturation" value. The ORANGE parameter is ignored if OTYPE=3 (32-bit) since the CORE_BASE and CORE_MULTIPLIER are not applicable to floating point pixel values. **NOTE** For a more detailed explanation of ORANGE, tutor the orange.pdf.
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.