ratio Documentation

ratio - Ratio each spatial plane by a given spatial plane
This program computes ratios of spatial-spatial planes.  The number of
CORE bands in the output cube corresponds to the number of dividend CORE
bands, which is specified by the FROM and SFROM parameters.  (The output
file must be different from the input file(s).  I.e., TO=" " cannot be
used to write the processed data back into the input file.)  Suffix data
selected by SFROM are propagated unchanged to the output file.

There are two basic types of operations that can be selected.  First,
each dividend band can be divided by the same divisor band.  In this
case, the DIVBAND parameter selects the single divisor band, and the
REGION parameter allows specifying whether the divisor band is a CORE
band or a BACKPLANE.  (If REGION=BACKPLANE is specified, the BACKPLANE
can also be selected by name with the BCKNAME parameter.)  Second, a set
of dividend bands can be divided by a corresponding set of divisor CORE
bands.  In either case, divisor band(s) can be contained in either the
same cube as the dividend bands or a different cube.  The following is
a summary of the TAE parameters used to select the various available
processing options, where "--" indicates the TAE NULL parameter value:

SINGLE DIVISOR BAND

  Divisor contained in SAME cube as dividend bands
    CORE divisor included in SFROM:
      FROM=file.cub, SFROM=..., FROM2=--, SFROM2=--, DIVBAND=nn
    CORE divisor NOT included in SFROM:
      FROM=file.cub, SFROM=..., FROM2=file.cub, SFROM2=..., DIVBAND=nn
          (SFROM2 selects same spatial area as SFROM; no band
           selection is needed in SFROM2)
    BACKPLANE divisor included in SFROM:
      FROM=file.cub, SFROM=..., FROM2=--, SFROM2=--, REGION=BACKPLANE,
          DIVBAND=nn (or DIVBAND=--, BCKNAME=name)
    BACKPLANE divisor NOT included in SFROM:
      FROM=file.cub, SFROM=..., FROM2=file.cub, SFROM2=...,
          REGION=BACKPLANE, DIVBAND=nn (or DIVBAND=--, BCKNAME=name)
          (SFROM2 selects same spatial area as SFROM; no band
           or BACKPLANE selection is needed in SFROM2)

  Divisor contained in DIFFERENT cube
    CORE divisor:
      FROM=file1.cub, SFROM=..., FROM2=file2.cub, SFROM2=..., DIVBAND=nn
    BACKPLANE divisor:
      FROM=file1.cub, SFROM=..., FROM2=file2.cub, SFROM2=...,
          REGION=BACKPLANE, DIVBAND=nn (or DIVBAND=--, BCKNAME=name)

MULTIPLE DIVISOR BANDS

  Divisors contained in SAME cube as dividend bands
    Core divisors NOT included in SFROM:
      FROM=file, SFROM=..., FROM2=file, SFROM2=..., DIVBAND=--
          (e.g., SFROM and SFROM2 could select multiple bands to
           divide band N by band N+1)

  Divisors contained in DIFFERENT cube
    Core divisors:
      FROM=file1, SFROM=..., FROM2=file2, SFROM2=..., DIVBAND=--
          (SFROM and SFROM2 must select same number of bands)

If either the divisor pixel or the dividend pixel is any type of
"special" pixel value, then the output pixel is set to the values
shown in the chart below.


                         Divisor/Bottom (B)
Dividend/Top (T) | Valid  |  Null | Low_I  | Low_R  | High_I  | High_R
------------------------------------------------------------------------
  Valid          |  T/B   | NULL  | Low_I  | Low_R  | High_I  | High_R |
------------------------------------------------------------------------
  Null           | NULL   | NULL  | NULL   | NULL   |  NULL   |  NULL  |
------------------------------------------------------------------------
  Low_I          | Low_I  | NULL  | Low_I  | Low_I  |  Low_I  |  Low_I |
------------------------------------------------------------------------
  Low_R          | Low_R  | NULL  | Low_R  | Low_R  |  Low_R  |  Low_R |
------------------------------------------------------------------------
  High_I         | High_I | NULL  | High_I | High_I |  High_I |  High_I|
------------------------------------------------------------------------
  High_R         | High_R | NULL  | High_R | High_R |  High_R |  High_R|
------------------------------------------------------------------------

If the divisor plane is from the CORE region and a value is entered for
DIVNAME, the divisor plane is saved in a new BACKPLANE that is added to
the processed cube file.

The CTOP and CBOT parameters specify additive coefficients that are
added to the "top" and "bottom" pixel in the ratio being computed.
If the original "bottom" (divisor) pixel value (before applying the
additive coefficient) is zero then the output pixel is set to the NULL
value.  Also, the output pixel is set to NULL if the input divisor pixel
plus its additive coefficient is equal to zero.

Programmer: Tracie Sucharski, U.S.G.S., Flagstaff, AZ

Input cube file name
  (Default extension is .cub)

NONE

Input subcube specifier

--

Second input cube file name
  (Default extension is .cub)

--

Second input subcube specifier

--

Output cube file name
  (Default extension is .cub)

NONE

Location of input DIVBAND
  (CORE or BACKPLANE)

"CORE"

Divisor band number (disk coord)
      or

--

Divisor backplane name

--

Name of new divisor backplane

--

Coefficient to add to top

0.0

Coefficient to add to bottom

0.0

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. The CORE bands in this file are the dividend bands for the ratios. If the file extension is omitted, then ".cub" will be assumed.
SFROM	If the divisor band comes from the same cube as the dividend bands, it must be included in the SFROM subcube specifier or you must enter the same file name in both FROM and FROM2. 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. For example, "10-100(3):11,12,15-20:1-10(2)" will select every third sample starting with sample 10 thru 100; lines 11 and 12, and 15-20; and 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 **
FROM2	Second input cube file name. This is used if the divisor band(s) is in a different cube file from the dividend band or if the divisor band is not included in the bands chosen with SFROM. If NULL, the divisor is assumed to come from the input cube and must be included in SFROM. In this case, the same virtual cube will be used as for the primary input file. If the file extension is omitted, then ".cub" will be assumed.
SFROM2	Input subcube specifier for the second input file. Refer to the SFROM parameter help section for examples.
TO	Output cube file name. If the file extension is omitted, then ".cub" will be assumed. TO=" " cannot be used to put the computed ratios back into an input file.
REGION	Specifies whether the band selected for the divisor plane is part of the CORE or is from the BACKPLANE.
DIVBAND	Divisor band number. Specifies the band number of the divisor spatial-spatial image plane. This image plane is obtained from the input cube file (FROM2=--) or from the second input file (FROM2 specifies a file) and must be included in the bands selected by the input subcube specifier. This is specified as a band number within the coordinate system of the input disk file; it is NOT a virtual band number within the coordinate system of the virtual cube specified by the SFROM parameter. This can be a CORE band or a BACKPLANE (if REGION=BACKPLANE is specified). If you want to divide all bands in the first input cube by all bands in the second input cube, set DIVBAND to a value of NULL.
BCKNAME	This allows the user to select a backplane by name rather than with the DIVBAND parameter. This only applies when REGION="BACKPLANE". It is ignored when REGION="CORE".
DIVNAME	Name of new divisor BACKPLANE. This is the name that will be given to the new BACKPLANE that is created for saving a copy of the divisor image plane. If this parameter is not used, then the divisor plane will not be saved into a BACKPLANE. This name must be different from any input file BACKPLANES that are selected by the input subcube specifier.
CTOP	Specifies the additive coefficient to add to the "top" (dividend) pixel value. The output spatial-spatial plane for each band is thus computed as follows: OUT(S,L) = IN(S,L) + CTOP --------------- DIV(S,L) + CBOT Where: OUT(S,L) is the output pixel value at sample S, line L IN(S,L) is the input pixel value at sample S, line L DIV(S,L) is the divisor plane pixel value at sample S line L CTOP is the additive coefficient for the top of the ratio CBOT is the additive coefficient for the bottom of the ratio
CBOT	Specifies the additive coefficient to add to the "bottom" (divisor) pixel value. See description of the CTOP parameter.
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) because 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.