orange Documentation

orange - Detailed description of ORANGE parameter
For pixel types 1 and 2 (8-bit and 16-bit), the CORE_BASE and
CORE_MULTIPLIER keywords in the cube label are used to convert the
stored values in the cube to the "true" values being represented
according to the following equation:

        "true" value = CORE_BASE + (CORE_MULTIPLIER * stored value)

Different values of CORE_BASE and CORE_MULTIPLIER thus allow storing
different ranges of "true" pixel values.  The ORANGE parameter allows
the user to specify the desired range of "true" values that can be
represented in an output cube file.  The ISIS software automatically
computes the CORE_BASE and CORE_MULTIPLIER values that correspond to
the specified ORANGE.

For output pixel type 3 (32-bit floating point), the CORE_BASE and
CORE_MULTIPLIER keywords are not used because each pixel already
directly represents the "true" floating point value.  In this case,
the ORANGE value is ignored and the CORE_BASE and CORE_MULTIPLIER
keywords are always set to 0.0 and 1.0 in the output file.  Using
OTYPE=3 will eliminate the saturation and bin compression problems.

If ORANGE is left at the default NULL, the output cube will be able
to store the same range of "true" values as the input cube.  However,
if the input file is pixel type 3 (32-bit floating point) and the
output file is type 1 or 2 (8-bit or 16-bit), then an explicit ORANGE
value will be required because the range of possible floating point
values is much greater than the normal range of "true" ISIS pixel
values.

When an application program writes internal "true" floating point pixel
values to a type 1 or 2 (8-bit or 16-bit) output file, valid values
that are outside the specified ORANGE cannot be represented in the file
and are thus stored as the high or low "representation saturation"
values.  Most application programs report the count of such valid
pixel values that are lost by such conversion to saturated values.

Thus, if a "poor" ORANGE is selected, the output data may be saturated
or needlessly compressed into very few output "bins."  For example,
when one file is divided by another (RATIO) the output range may be
unpredictable.  The user may have to guess what a reasonable ORANGE
will be and look at a histogram of the output to decide a better range.
The resulting data may be saturated or compressed into only one or two
DN values.  If the data are saturated, a lower ORANGE(1) and/or a
higher ORANGE(2) must be used.  If the data are compressed, the ORANGE
values should be set closer to the compressed range.

The core base (ADD) and core muliplier (MULT) are determined from the
following approximate equations:

                      ORANGE(2) - ORANGE(1)
        MULT = -----------------------------------
                (VALID_MAX+0.5) - (VALID_MIN-0.5)

        ADD = ORANGE(1) - MULT*(VALID_MIN-0.5)

The inverse equations are:

        ORANGE(1) = ADD + MULT*(VALID_MIN-0.5)

        ORANGE(2) = MULT*((VALID_MAX+0.5)-(VALID_MIN-0.5))+ORANGE(1)

Where:
  VALID_MIN and VALID_MAX are set for the appropriate pixel type.
  For 8 bit: VALID_MIN=1., VALID_MAX=254.
  For 16 bit: VALID_MIN=-32752., VALID_MAX=32767.
  ORANGE(1) is the minimum expected value in the image data range
  ORANGE(2) is the maximum expected value in the image data range

Note that the VALID_MIN and VALID_MAX values are adjusted by the 0.5
factors so that the specified ORANGE is mapped into the bottom of the
lowest output bin and the top of the highest output bin.  Also, note
that the actual computations done by ISIS are somewhat more complex
than indicated by the above simplified equations.  This is due to
several reasons: 1) need to carefully deal with precision and round-off
effects, 2) need to maximize efficiency in the pixel conversion
process, and 3) need to store the binary CORE_BASE and CORE_MULTIPLIER
values in a character representation in the cube label.

For example, for a core base of 0.0 and a core multiplier of 1.0

                    For 8 bit
        ORANGE(1) = 0.0+1.0*(1.-.5)    =    .5
        ORANGE(2) = 1.0*(254.-1.+1)+.5 = 254.5

                    For 16 bit
        ORANGE(1) = 0.0+1.0*(-32752.-.5)             = -32752.5
        ORANGE(2) = 1.0*(32767.-(-32752.)+1)-32752.5 =  32767.5

Output min/max data range

--

ADDITIONAL NOTES:

Parm

Description

ORANGE

If ORANGE is NULL, then the the CORE_BASE and CORE_MULTIPLIER in the output file will be set to represent the same range of data as the input file. Output pixel data range. 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.