add Documentation

add - add a band or a cube to a cube

The "add" program adds a single "reference band" or every band in a cube
to each band of an input cube.  The OPTION parameter determines which
option the program will use in computing the output cube.  "C2RB" will
add a single "reference band" to each band of the input cube.  The
"reference band" can be obtained either from the input cube or from a
second cube file.  Also, the "reference band" can be obtained either
from the CORE or BACKPLANE region of the file.  "C2C" will add each
band of a cube to each band of the input cube.  The two cubes must
have the same dimensions.  Additive and multiplicative factors can be
applied during the computation.

The algorithm for "add" follows:

If "C2RB" is chosen, NP = (DN * MUL) + (DNREF * MULREF) + ADD, or if
"C2C" is chosen, NP = (DN * MUL) + (DN2CUBE * MUL2) + ADD, where

   NP = new pixel value
   DN = pixel value from the input cube
   MUL = multiplication factor
   DNREF = pixel value from the reference band at the same line and
           sample location as the pixel value from the input file
   MULREF = the multiplication factor for the reference band
   DN2CUBE = pixel value from second input cube
   MUL2 = the multiplication factor for the 2nd input cube
   ADD = user defined constant

The user should enter a multiplication factor (MUL) and a constant
factor (ADD) for each band of the input cube that will be used to
create the output cube (ie. each band selected using the SFROM
parameter).  The MUL and ADD factors can be entered in two ways.
The first is to simply type each factor under the TAE ADD or MUL
prompt.  The second is to enter the factors using a binary table file
(TBLMUL).  TBLMUL has 2 columns of real numbers and can be created
using a text editor to create the ASCII file and the "asc2tbl" ISIS
program to convert the file to binary form.  If more than 50 MUL and
ADD factors are being entered, the user must use the binary
table file option.  If you wish to use the same MUL or ADD factor
for all bands in the FROM cube, enter a single MUL or ADD factor
at the TAE prompt.

If "C2C" is chosen, the values for MUL2 can be enter in two ways.
The first is to simply type each factor under the TAE MUL2 prompt.
The second is to enter the factors using a binary table file
(TBL2MUL).  TBL2MUL has a single column of real numbers and can be
created using a text editor to create the ASCII file and the
"asc2tbl" ISIS program to convert the file to binary form.
If more than 50 MUL2 factors are being entered, the user must use
the binary table file option.  If you wish to use the same MUL2
factor for all bands in the FROM2 cube, enter a single MUL2 factor
at the TAE prompt.

If a special pixel value is encountered in either the FROM cube or
the FROM2 reference band or cube, the new pixel value will be set
to the value of the input cube.

Programmer:  Jim Mathews, 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

Program computation option
  (C2RB or C2C)

"C2RB"

Location of input BAND
  (CORE or BACKPLANE)

"CORE"

Input band/backplane number
	OR

1

Input backplane name

--

Table file of multiplication
factors and additive values

NONE

Multipication factors.
Used only when TBLMUL=--.

1.0

Constants to add to product.
Used only when TBLMUL=--.

0.0

Multiplication factor for
  the reference band

1.0

Table file of multiplication
factors for 2nd input cube.
Used only when OPTION="C2C".

NONE

Multiplication factors for
2nd input cube.
Used only when TBL2MUL=--.

1.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. 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 **
FROM2	Second input cube file name. If NULL, process from the first input cube. If the file extension is omitted, then ".cub" will be assumed.
SFROM2	Input subcube specifier for the second input file. You must select the same spatial size as the SFROM parameter. 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.
OPTION	You have 2 options in running the program. "C2RB" will add a single reference band to the input cube. "C2C" will add a second cube to the input cube. The two cubes must have the same dimensions for OPTION = C2C.
REGION	Specifies whether the band selected from the second input file is part of the core or is from the suffix.
BAND	Specifies the band number to be used as the reference band when OPTION=C2RB. The BAND parameter is ignored when OPTION=C2C. The band number to be entered is the actual band number in the input disk file, not an index into the virtual cube specified by the subcube specifier, SFROM. For example, if you want to use band 3 as the reference band and you have an input file with 10 bands and you use SFROM to select only bands 3, 4, and 5, the value of BAND should be 3. Also, the band selected with the BAND parameter must be included in the virtual cube selected by the subcube specifier for the input file. The BAND parameter can also be used to denote a reference band that resides in a backplane. If REGION = BACKPLANE is specified and BCKNAM is the NULL (default) value, then BAND specifies the number of the backplane to use as the reference band. Also, the BAND parameter is ignored if REGION = BACKPLANE and a backplane name is specified with the BCKNAM parameter.
BCKNAM	This parameter is ignored if REGION = CORE is specified. If REGION = BACKPLANE is specified, then this parameter allows the user to select a backplane by name rather than with the BAND parameter. (BAND is ignored if a BCKNAM value is supplied.)
TBLMUL	A binary table file of multipication factors and ADD values. The table contains two columns called MUL and ADD and both are real numbers. One MUL and one ADD value factor should be used for each band selected in the subcube specifier.
MUL	Enter multipication factors for each band selected in the subcube specifier. A maximum of 50 values can be entered using this parameter. If only one value is entered, it will be used for all the bands. Use this parameter only if TBLMUL is set to the NULL value. Computation: (x*MUL)+ADD
ADD	Enter an additive constant for each band selected in the subcube specifier. A maximum of 50 values can be entered using this parameter. If only one value is entered, it will be used for all the bands. Use this parameter only if TBLMUL is set to the NULL value. Computation: (x*MUL)+ADD
MULREF	The multiplication factor for the reference band. This parameter is used only when OPTION=C2RB.
TBL2MUL	A binary table file of multipication factors. The table contains a single column called MUL2 and is a real number. One MUL2 value should be used for each band selected in the subcube specifier of the FROM2 cube.
MUL2	Enter multipication factors for each band selected in the subcube specifier of the second input cube. A maximum of 50 values can be entered using this parameter. If only one value is entered, it will be used for all the bands. Use this parameter only if TBL2MUL is set to the NULL value and OPTION=C2C.
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.