cubestack Documentation

cubestack - Stacks two input cube files in the LINE dimension

CUBESTACK takes two standard input cube files and stacks them, one on
top the other, in the LINE dimension.  CUBESTACK will only deal with
standard cube files (Note that BIP (Band Interleaved by Pixel) storage
order is not supported by CUBESTACK).

Since CUBESTACK merges two separate files into a single output file,
there are many possibilities that can make this type of merge rather
complex. To minimize some of the complexity, some decisions and
restrictions have been placed on the merge operation.  The file
specified in the FROM1 parameter will be referred to henceforth as the
primary input file;  the FROM2 file is the secondary input file.  The
creation of the output cube file will be governed first by the state of
the primary input file.  The following guidelines describe how the
output cube file is created:

  1) The storage order of the output cube will be the same as the
     primary input cube.

  2) The output cube core will be determined as follows:

      a) The number of elements in the SAMPLE axis will be the maximum
         of the two input cube SAMPLE axis dimensions.  If the
         dimensions are not the same, then the file that has the smaller
         dimension will result in padding of NULLs in the output file at
         the end of each line to meet the size of the other file.

      b) The number of elements in the LINE dimension is the sum of the
         LINE axis dimensions of the two input cubes.  The primary input
         file will be placed at the "top" of the stack.  The secondary
         input file will be appended to the primary input file at the
         "bottom" of the stack.

      c) The number of bands in the BAND axis will be the number of
         bands selected by the subcube specification of the primary
         input file.  Note that the bands of the input files are
         correlated by the original band values stored in the
         BAND_BIN_ORIGINAL_BAND keyword in the BAND_BIN group.  Should
         the secondary input file not contain (or the subcube specifier
         not select) an original band selected in the primary input cube
         file, then NULLs are substituted in the core where the
         secondary band is to be placed in the output cube file.  Bands
         selected in the secondary input file that do not have an
         original band also selected in the primary input file are
         IGNORED and NOT propagated to the output file.

  3) Sideplane and bottomplane suffixes are NOT propagated to the output
     file.  However, backplanes are propagated to the output file
     subject to the following guidelines:

      a) All backplanes selected by the input subcube specifier in the
         primary input file will always be propagated to the output
         file.

      b) Backplanes in the secondary input file that share common names
         and parameter values with backplanes in the primary input file
         are stacked in the same fashion as the core.  Should the
         parameters in the backplane of the secondary input file that
         share a common name with a backplane in the primary input file
         differ in any way, then the secondary input backplane will be
         NULLed and placed in the stack as is with the core.

      c) All backplanes in the primary and secondary input files that do
         not share common names will be propagated to the output cube
         file.  The input file that does not contain the backplane will
         be NULLed and placed in the appropriate place in the stack.

      d) The order of the backplanes in the output cube will be the same
         as the order encountered in the primary input file with all
         uncommon backplanes from the secondary input file appended to
         the backplane suffix also in the order in which they are
         encountered.

  4) Processing of the HISTORY object is controlled by the user.  See
     the HOPT parameter.

  5) All other objects that exist in the primary input file are
     propagated to the output cube file.  Those that exist in the
     secondary input file are ignored.


CUBESTACK allows the user to select the desired output pixel data type
with the OTYPE parameter.  If the default value OTYPE=0 is used, then
the output file pixel type will be the same as the primary input file.
The user can select a specific output file pixel type by specifying a
non-zero value for OTYPE.  If the output pixel type is not floating
point, then the ORANGE parameter specifies the range of values that
can be represented in the output file.  If the default value ORANGE=
(0.0,0.0) is used, then the range of values that can be represented in
the output file will be the same as in the primary input file.  If the
primary input file is floating point format and the output file is not
floating point format, then a specific range must be specified for
ORANGE because the range of values in the primary input file is not
known.

It is sometimes desirable to stack two cubes that contain different
ranges of values.  For example, one cube might contain normalized values
in the range 0.0 to 1.0 and the other cube might contain un-normalized
values that cover a much larger range.  It this situation it might be
desirable to apply a linear scaling to one or both input files so that
the core data in the two parts of the output file contain the same
range of values.  This will make it easier to compare the two parts of
the stacked cube when it is displayed.  In general, RANGE1 and RANGE2
specify the ranges of input file values that are to be scaled into the
range of output file values specified by ORANGE.  Thus, ORANGE serves
two purposes: it specifies the range of values that can be represented
in the output file (if the output file is not floating point), and it
specifies the output range of values into which the input values are
scaled.  Input values that lie outside the ranges specified by RANGE1
and RANGE2 are converted into the special high or low representation
saturation values.  (If the output file is floating point format, then
the scaling does not result in any valid input values being converted
into saturation values since all valid input values can be represented
in floating point format after scaling.)  The following describes the
various combinations of input/output pixel types and range
specifications in more detail:


  1) If the input and output file pixel types are the SAME then:

     a) If the pixel type is not 3 (floating point) and a range for the
        input file is specified, but no range for the output file was
        specified, then the input range is scaled into the entire
        representable range of the output file, which is the same as the
        representable range of the primary input file.

        If no input range is specified but an output range was
        specified, then the entire representable range of the input file
        is scaled to the range specified for the output file.

        If no ranges are supplied for both the input and output cube
        file, the output cube file range is the same as the primary
        input file and the entire representable range of the input file
        is scaled to the entire representable range of the output file.


     b) For pixel type 3 (floating point), a rescaling occurs only when
        a range is specified for both the input and output cube files.
        If only one or neither of the ranges is specified, then this
        amounts to a direct copy of data from the input file to the
        output file.  A single specified range is ignored in this case.

  2) If the input pixel type DIFFERS from the output pixel type, then
     you can be assured that at least one scaling/conversion will be
     performed, whether explicitly or implicitly.

      a) If the input pixel type is 3 (floating point) and a range is
         specified for the input file, then the range specified for the
         input file is scaled to the entire representable range of the
         output file, which is specified by ORANGE.

      b) If the output pixel type is 3 (floating point) and a range is
         specified for the output cube file and a range is specified for
         the input cube file, then the specified input range is scaled
         to the range of the output file.

      c) For all other cases, conversion can be performed exactly to
         user input specifications.  If a range is not specified for the
         output cube file, then the representable range of the output
         file will be the same as the primary input cube file.  If no
         range is specified for both the input and output cube files,
         then the entire representable range of the input file is scaled
         to the entire representable range of the output file.  If a
         range is specified for the input file, then this range is
         scaled to the entire representable range of the output cube
         file.  If a range is specified for the output file but not the
         input file, then the entire representable range of the input
         file is scaled to the range specified for the output file.

PROGRAMMER: Kris Becker, USGS, Flagstaff, Az.

Primary input cube file name
  (default extension is .CUB)

NONE

Primary input subcube specifier

" "

Secondary input cube file name
  (default extension is .CUB)

NONE

Secondary input subcube
specifier

" "

Output cube file name
  (default extension is .CUB)

NONE

Specifies data range of primary
input file

0.0,0.0

Specifies data range of
secondary input file

0.0,0.0

Output pixel type

0

Output minimum and maximum
data range

0.0,0.0

History propagation option
1 - propagated primary history
    object only
2 - merge history from both
    input files
3 - no history from either
    input file

2

ADDITIONAL NOTES:

Parm	Description
FROM1	The primary input cube file. This file governs many aspects of how the output file is created. The output core dimension of the BAND axis is the number selected by the input subcube specifier for this input file. It also dictates the order of the stack (primary on top), the output cube storage order and the order of backplanes in the BAND suffix. Also all other objects that exist in this file are propagated to this file. Example: dev:[dir]primary
SFROM1	The primary input subcube specifier. Allows the user to select a subarea of the input cube for processing. The default " " selects the entire cube.
FROM2	The secondary input cube file. Bands from this cube are placed at the bottom of the stack in the cube. Only the original bands selected in this file that also exist in the primary input file specification will be propagated to the output file. Example: dev:[dir]secondary
SFROM2	The secondary input subcube specifier. Allows the user to select a subarea of the input cube for processing. The default " " selects the entire cube.
TO	The output cube file created by CUBESTACK. Will be the same storage order and number of bands as the primary input file. All common backplanes and uncommon backplanes from this file are propagated to the output file. Example: dev:[dir]output
RANGE1	This parameter allows the user to select a specific data range from the primary input cube. If the default is used, then the entire range will be preserved in the output cube file. Note that some rescaling may be performed, whether it be implied or explicit (determined by pixel type of the output file and ORANGE).
RANGE2	This parameter allows the user to select a specific data range from the secondary input cube. If the default is used, then the entire range will be preserved in the output cube file. Note that some rescaling may be performed, whether it be implied or explicit (determined by pixel type of the primary input file and the output file and ORANGE).
OTYPE	The output pixel type. This parameter allows the user to specify the output pixel type. The default of 0 will result in the same pixel type as the primary input file.
ORANGE	This parameter allows the user to select the range of values that can be represented in the output file. (This is not applicable for floating point format.) For all output pixel data types (including floating point), this parameter also specifies the output range of values into which the input ranges of values are scaled.
HOPT	This parameter allows the user to specify how the history object is to be handled for the file merger. HOPT=1 instructs CUBESTACK to simply propagate the processing history from the primary input cube. HOPT=2 will result in a merging of the primary and secondary processing histories. HOPT=3 will not propagate history from either input file. For all options, the history entry for the current run will be inserted into the history object of the output file.
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.