mask Documentation

mask - Mask cube with single core band, all core bands or a backplane
MASK will stencil a cube using a single core band or backplane by
setting all pixels to NULL that are outside of SRANGE in the mask band.
The mask plane is taken from the input cube file and applied to all core
bands and, optionally, all backplanes.  Another option is to use all
core planes as the stencil and output only those pixels that are common
to all of the input core planes and within the specified SRANGE.

The user may select the mask plane from either the core or backplane
region.  The mask plane MUST be included/selected by the input subcube
specifier.  To select a core band as the mask, set REGION=CORE and BAND
equal to the actual band number.  If all input core planes are to be
used as the mask, set REGION=CORE and BAND=--.  A backplane used as a
mask may be selected one of two ways. Either set REGION=BACKPLANE and
and use BAND or BCKNAME to select the desired backplane.  If BCKNAME is
specified, BAND is ignored and BCKNAME specifies the name of a backplane
in the suffix of the band axis to use as a stencil mask.  If BCKNAME is
NULL, then BAND selects the actual suffix number of the desired
backplane in the band axis.  Note that the data type of the selected
suffix must be one of the three standard supported numerical data types.

The values of the SRANGE parameter apply only to the mask plane(s).  The
range given represent the "true values" in the core plane(s) or
backplane used as the mask.  All valid values in the mask plane(s) less
than SRANGE(1) and greater than SRANGE(2) will result in the
corresponding pixel in the output cube being set to the NULL data value.
Special pixel values encountered in the mask plane(s) are not included
in the range test.  All mask values that fall within (inclusive) the
given range in the mask band result in the corresponding pixels in the
input band being propagated to the output cube file unchanged.

Note that sideplanes and bottomplanes are NOT included in the mask
operation, but are propagated unchanged to the output cube file.
Backplanes, however, may optionally be masked based on the DO_BCK flag.
If DO_BCK=YES, all the backplanes will be masked along with the core.
If DO_BCK=NO, all backplanes will be propagated to the output cube file
unchanged.

The user may also preserve the mask plane or choose to have it masked.
This option is supplied because the mask plane must be included in the
input subcube specifier.  If DO_MASK=YES, then the mask plane will be
masked as all other planes.  If DO_MASK=NO and the mask plane is
encountered, it will be propagated to the output cube file unchanged.
Note that if the mask is from a backplane and DO_BCK=NO, then DO_MASK is
ignored and all backplanes are propagated unchanged to the output cube.
Also, if the mask is from a second input file, DO_MASK is ignored.

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

--

Location of BAND
  (CORE or BACKPLANE)

"CORE"

Core band(s) or backplane to be
used as the mask
       OR

--

Name of backplane to be used
as mask

--

Band(s) to exclude from all
inclusive mask

--

File containing list of band(s)
to exclude.

--

IN  = Mask inside the region of
      interest
OUT = Mask outside the region
      of interest

"OUT"

Region of interest name

--

Output cube file name
  (Default extension is .cub)

NONE

Range of values in the mask
plane to preserve (inclusive
limits)

--

Which special pixels to mask
NULL=Mask only NULLs
ALL=Mask all special pixels

"NULL"

Mask the mask plane

YES

Mask the backplanes

NO

Comment for user

" "

ADDITIONAL NOTES:

Parm	Description
FROM	Input cube file name. 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 subcube specifier. 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. 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. If SFROM2 is NULL, the same subcube specifier used in FROM will be applied to FROM2. Refer to the SFROM parameter help section for examples.
REGION	Specifies whether the band selected for the divisor plane is part of the CORE or is from the BACKPLANE.
BAND	Specifies the core band(s) or backplane to be used as the mask. This is the actual plane(s) in the core or backplane in relation to the physical dimensions of the input cube, not an index into the virtual cube. The band(s) selected with this parameter must be included in the subcube specifier. If all core bands are to be used as the mask, BAND should be set to NULL, and REGION set to "CORE". This will output only pixels common to all core planes and within the given SRANGE.
BCKNAME	Allows the user to select a backplane by name rather than with the BAND parameter. This only applies when REGION=BACKPLANE. It is ignored when REGION=CORE. If BCKNAME is NULL or " ", then the BAND parameter selects a suffix plane that must be selected by the input subcube specifier, otherwise, the name given must be a backplane in the input cube selected by the input subcube specifier in the band axis. The selected suffix must be one of the three supported numerical data types allowed in suffixes.
EXCLUDE	If all bands in the cube are to be used as the mask, this parameter will allow you to exclude specific bands from this operation.
ROIOPT	If ROIOPT = "IN", all pixels within the given regions of interest will be set to NULL in the output file, while all pixels outside of the given regions of interest will be retained in the output file. If ROIOPT = "OUT", all pixels outside of the given regions of interest will be set to NULL in the output file, while all pixels within the given regions of interest will be retained in the output file.
ROINAME	Region of interest name to use as the mask. This can be found in the labels in the group for the backplane which contains the region of interest.
TO	Output cube file name. If the file extension is omitted, then ".cub" will be assumed.
SRANGE	Specifies the range of values in the mask plane used to determine which pixels in the input cube are preserved. All values in the mask plane that are less than SRANGE(1) and greater than SRANGE(2) will result in the corresponding pixel of the input cube being nulled in the output cube file. Note that this range specifies the "true values" as represented in either the core or the specified backplane used as the mask. If the default value of NULL is used, the range of inclusive values will be the ISIS defined valid minimum and maximum for the input bit type.
SPECMASK	Which special pixels to mask NULL=Mask only NULL special pixels, all other special pixel values will be preserved ALL=Mask all special pixels This parameter is only valid if masking all bands together in a cube.
DO_MASK	This flag specifies whether the plane selected as the mask is to be stenciled as all the other planes. If DO_MASK=YES, the plane will be masked. If DO_MASK=NO, then when the mask band is encountered, it is propagated unchanged to the output cube file, whether a core or backplane.
DO_BCK	This flag specifies whether the backplanes are to be masked also. The user has the option to have the backplanes masked or preserved and propagated to the output cube file as is with no masking. Note that if the user chooses to have the suffix masked and the mask plane is from this suffix, the DO_MASK variable will apply here as with the core.
USERNOTE	Specifies a comment that will be entered into the output log file and history entry in the output file.