ISIS Application Documentation
Hand place a cube into a mosaic
Description
This application creates a mosaic by placing an input image in the
output by a sample, line, and band pixel position. An input
cube can be mosaicked into an existing output mosaic cube or a
new output file can be created. If a portion of the input cube
falls outside of the dimensions of the mosaic, it will be
clipped. The line, sample, band dimensions of the output mosaic
are required to be specified at the time of creation. This
application does not require a camera model, Instrument Group or
Mapping Group keywords as required by the other mosaic applications, mapmos and automos.
Integrity-check Parameters:
MATCHBANDBIN = FALSE, the default is to require all the BandBin group and wavelength
keywords of the input cube files exactly match the output mosaic.
MATCHDEM = FALSE, the default does not check the SHAPEMODEL keyword of the input cube
files and does not propagate what DEM Shapemodel that was used when the input files were
projected.
The PRIORITY parameter will determine how each input cube is combined with the current
output mosaic cube. The process involves replacing an output mosaic pixel (or not) with
an input pixel at the same location. There are many user options and criteria that
influence the pixel replacement. Use of the PRIORITY parameter with and without other
options is explained in the tables and descriptions below.
The TRACK feature creates a separate tracking cube in addition to the mosaic cube, and
contains information for the source files of every pixel within the output mosaic.
This cube will have the same base-name as the mosaic cube, but will end in
"_tracking.cub". The tracking cube must always reside in the same directory as the
mosaic cube to be properly accessed; this means that if the mosaic cube is copied or
moved, then its associated tracking cube must be copied or moved to the same location.
The tracking cube will always be of type unsigned integer. Depending on the
bit-type of the mosaic cube and/or the number of bands it contains, the tracking cube
may be as much as four times the size of the mosaic cube itself.
The tracking cube can be used appropriately through the QVIEW-AdvancedTracking
tool. As the user pans across the displayed mosaic, for every mosaic pixel location,
QVIEW-AdvancedTracking will interactively report the index, the filename and the
serial number of the input cube that was input to handmos for that specific pixel
location. Since the tracking cube is of bit-type unsigned integer, the DN values of
0, 1 and 2 are reserved for NULL, LRS and LIS, respectively, so valid pixel DN values
will begin at an offset of 3. In other words, a pixel of DN value 3 in the tracking
cube means that this same pixel within the mosaic was taken from the first input
image. The tracking cube cannot be used outside of the QVIEW-AdvancedTracking tool
except as a visual representation of the source cubes for the different pixels.
The TRACK feature works with Priority options ONTOP and BENEATH for single band input
cubes. It works for multiband cubes for PRIORITY=ONTOP only when the NULL,
HIGHSATURATION and LOWSATURATION options are set to true. It also works for multiband
cubes when PRIORITY=BAND. Furthermore, this feature is NOT supported when
PRIORITY=AVERAGE.
Please Note: Prior to ISIS version 3.6.0, tracking for the various mosaicking apllications
was being handled with an internal tracking band. Tracking is now being handled by an
external tracking cube that contains the associated tracking information. This application
can no longer add to mosaics of the old format. In order to continue to use these
older mosaics with the updated mosaicking applications, you must first use the
trackextract utility application to extract the tracking band and the associated
tracking information into an external tracking cube.
The following table describes how the program will determine the pixel value in the output
mosaic for areas of image overlap.
| PRIORITY | RESULT |
| ONTOP |
This is the default. The current input image will be placed on top of the
output mosaic. Thus in any area of overlap, the Valid pixel values for the
current input image will appear in the output mosaic (it replaces the output mosaic
pixel). Invalid input Special Pixels
(NULL,HRS,HIS,LRS,LIS) will NOT
replace an existing Valid output mosaic pixel unless the optional flags are set. Refer
to parameters HIGHSATURATION,LOWSATURATION, and NULL to override replacement of Valid
output mosaic pixels.
NOTE: When using this priority with multi-band mosaics and with the TRACK
option set, all Special Pixel flags must be set as well. This is because the same
pixel within different bands of a single input image may hold both Valid and Special
Pixel values, and since our Tracking capabilities can only track one input image per
pixel (as it is a single band), it must accept the values for that particular pixel
from every band in the input image being placed on top.
|
| BENEATH |
The current input image will be placed beneath the output mosaic. Thus in
any area of overlap, the Valid pixel values for the current mosaic will remain in
the output mosaic. The Valid pixel values for the current input image will only
replace the NULL pixels values in the output mosaic. The HRS,HIS,LRS and LIS special
pixel values in the output mosaic will NOT be replaced by the Valid input pixel.
The parameters HIGHSATURATION, LOWSATURATION and NULL are not supported under this
priority.
|
| BAND |
The input image pixels will be placed in the output mosaic based on the "Lesser" or
"Greater" criteria of a priority band defined by the user. Parameters that apply to
this priority feature are TYPE, NUMBER, KEYNAME, KEYVALUE, CRITERIA.
|
| AVERAGE |
Overlapping Valid pixel values from the current input image and output mosaic will be
averaged for the new mosaic pixel values. A count-band is created with the output
mosaic file. The count-band keeps track of the number of images involved in the
averaging of the input DN values for each pixel in the mosaic. Invalid input pixel
values will not be included in the average. In the case where only one Valid pixel
exists between the input image pixels or the current mosaic pixel, the Valid pixel is
retained in the current output mosaic. Refer to parameters HIGHSATURATION,
LOWSATURATION, and NULL to override replacement of valid output mosaic pixels.
Choosing this priority will cause the mosaic to have twice the number of bands of
the input image. Hence the file (byte) size of the mosaic is increased due to
the count-bands.
NOTE: If an existing mosaic does not already contain a count-band, an error
will be encountered.
|
Each of the following priority option tables indicates the resulting output pixel for a
particular input pixel, given the selected special pixel options (parameters
HIGHSATURATION for HRS, HIS; LOWSATURATION for LRS, LIS; and NULL) in each table row.
| PRIORITY=ONTOP |
| Options |
Images |
| High Saturation |
Low Saturation |
Null |
Input Pixel Value Type |
Current Mosaic Pixel Value Type |
Output Mosaic Pixel Value Source |
| False |
False |
False |
Valid |
Special or Valid |
Input |
| False |
False |
False |
Special |
High Saturation or Low Saturation or Valid |
Mosaic |
| False |
False |
False |
Special or Valid |
Null |
Input |
| True or False |
True or False |
True |
Valid |
Special or Valid |
Input |
| True or False |
True or False |
True |
Special |
Special or Valid |
Input |
| PRIORITY=BENEATH |
| Input Pixel Value Type |
Current Mosaic Pixel Value Type |
Output Mosaic Pixel Value Source |
| Special or Valid |
Null |
Input |
| Special or Valid |
High Saturation or Low Saturation or Valid |
Mosaic |
| PRIORITY=BAND |
| Options |
Images |
| High Saturation | Low Saturation | Null |
Input Pixel Value Type | Current Mosaic Pixel Value Type |
Output Mosaic Pixel Value Source |
| False |
False |
False |
Valid |
Valid |
Criteria based |
| False |
False |
False |
Valid |
Special |
Input |
| False |
False |
False |
Special |
High Saturation or Low Saturation or Valid |
Mosaic |
| False |
False |
False |
Special or Valid |
Null |
Input |
| True or False |
True or False |
True |
Special |
Special or Valid |
Input |
| True or False |
True or False |
True |
Valid |
Valid |
Criteria based |
| True or False |
True or False |
True |
Valid |
Special |
Input |
| PRIORITY=AVERAGE |
| Options |
Images |
| High Saturation | Low Saturation | Null |
Input Pixel Value Type | Current Mosaic Pixel Value Type |
Output Mosaic Pixel Value Source |
Count Band Pixel Value (# of images used for average) |
| False |
False |
False |
Valid |
Valid |
Average |
increment count by 1 |
| False |
False |
False |
Valid |
Special |
Input |
count = 1 |
| False |
False |
False |
Special |
Special |
Mosaic |
count = 0 |
| False |
False |
False |
Special |
Valid |
Mosaic |
count unchanged |
| True or False |
True or False |
True |
Special |
Special or Valid |
Input |
count = 0 |
| True or False |
True or False |
True |
Valid |
Valid |
Average |
increment count by 1 |
| True or False |
True or False |
True |
Valid |
Special |
Input |
count = 1 |
Categories
Related Applications to Previous Versions of ISIS
This program replaces the following
application
existing in previous versions of ISIS:
Applications
History
| Jeff Anderson | 2003-07-14 |
Original version
|
| Stuart Sides | 2003-07-29 |
Modified filename parameters to be cube parameters where necessary
|
| Jeff Anderson | 2003-09-19 |
Added option to initialize the base mosaic
|
| Jeff Anderson | 2004-02-17 |
Updated progress text and made output create use input cube attributes
|
| Elizabeth Miller | 2006-09-01 |
Added the MATCHBANDBIN option that checks to make sure the input
cube bandbin group matches the mosaic bandbin group. The default is true.
|
| Elizabeth Miller | 2006-09-28 |
Added history entry to the output cube
|
| Steven Lambright | 2008-05-06 |
Expanded upon position parameters
|
| Eric Hyer | 2009-06-11 |
Parameter "INPUT" now called "PRIORITY" to be consistent with the mapmos app
|
| Sharmila Prasad | 2009-09-04 |
Added option "TRACK" to track pixel origin. Also added new priority called
BAND where specified input and mosaic band is compared for moving input
to mosaic and to track the pixel origin. Added parameter "TYPE" to choose
Band "NUMBER" or PVL "KEYWORD" from the BandBin group. If "BANDNUMBER" is
chosen, then "NUMBER" is activated to enter band number. If "KEYWORD"
is chosen then parameter "KEYNAME" and "KEYVALUE" are activated to enter
key name and value from the BandBin group for band comparison. Band
comparison "CRITERIA" are "LESSER" or "GREATER" than. Also there are
options "HIGHSATURATION", "LOWSATURATION" and "NULL", set to true will
cause HS, LS and NULL input pixels to be copied to the mosaic regardless
of the priorities and criteria. These options are not supported for
"BENEATH" priority.
|
| Sharmila Prasad | 2009-12-16 |
Always place an input pixel over a NULL mosaic pixel.
Track the origin for multiband ONTOP priority if all the Special Pixel flags are set.
Store the Serial numbers of the input mosaic in the mosaic along with the file name.
|
| Sharmila Prasad | 2010-10-27 |
Process Input Image's Attributes
|
| Sharmila Prasad | 2011-01-19 |
Added "AVERAGE" priority where the mosaic will be average of valid input
and mosaic pixels.
|
| Sharmila Prasad | 2011-01-24 |
Option to match DEM and also added new group "mosaic" to hold ShapeModel
attributes for the mosaic
|
| Steven Lambright | 2011-10-19 |
Output cube when CREATE=yes no longer propagates labels other than the
band bin information.
|
| Sharmila Prasad | 2011-11-07 |
Updated documentation for Average priority. Fixes #553
|
| Stuart Sides | 2012-01-19 |
Added option to have the BLOBs and labels transferred from the input
cube transferred to the output mosaic from the input cube.
|
| Kimberly Oyama | 2012-09-18 |
When an image is placed twice (usually because the longitude range is greater than 360 and
encompasses the image more than once) only the last occurance was written to the log file.
This has been fixed so that there is an entry in the log file for every image placement.
References #976.
|
| Kimberly Oyama | 2014-03-28 |
Added an app test for the error check when PRIORITY=AVERAGE and the mosaic does not have
a count band. References #746.
|
| Tammy Becker and Kimberly Oyama | 2014-04-07 |
Updated user documentation. Backward Compatibility Issue: The MATCHBANDBIN parameter now
defaults to FALSE because the input cubes for handmos are not required to have the BandBin
group in the cube labels which could impact processing scripts/pipelines. Fixes #1620.
References #1623.
|
| Summer Stapleton | 2018-08-13 |
Updated code and documentation to reflect new handling of tracking capabilities with an
external tracking cube as well as clarify why special pixel flags are required when
priority=ontop for multiband mosaics. References #2092
|
|
Parameter Groups
Files
|
Name
|
Description
|
| FROM |
Cube to be placed in the mosaic
|
| MOSAIC |
Mosaic output cube
|
| PRIORITY |
The priority of pixel placement
|
Band Priority
|
Name
|
Description
|
| TYPE |
Indicate the name or number to use for the comparison
|
| NUMBER | Enter the Band Number |
| KEYNAME |
Enter the Key name as it appears in the cube labels
|
| KEYVALUE |
Enter the value associated with the "KEYNAME"
|
| CRITERIA |
Determines pixel placement given a band
|
Placement
|
Name
|
Description
|
| INSAMPLE | This sample in the input cube will be placed
at OUTSAMPLE in the mosaic
|
| INLINE | This line in the input cube will be placed
at OUTLINE in the mosaic
|
| INBAND | This band in the input cube will be placed
at OUTBAND in the mosaic
|
| OUTSAMPLE | The INSAMPLE sample will be placed at this sample in the mosaic |
| OUTLINE | The INLINE line will be placed at this line in the mosaic |
| OUTBAND | The INBAND band will be placed at this band in the mosaic |
Options
|
Name
|
Description
|
| MATCHBANDBIN | Input and mosaic BandBin Groups must match |
| MATCHDEM | Enforce DEM Match |
| HIGHSATURATION | Copy Input HS (Instrument and Representation) values |
| LOWSATURATION | Copy Input LS (Instrument and Representation) values |
| NULL | Copy Input NULL values |
Initialization
|
Name
|
Description
|
| CREATE | Create the output mosaic |
| TRACK |
Track the source filenames for each mosaic pixel
|
| PROPAGATE |
Propagate the labels, tables, and BLOBs from the input cube
|
| NSAMPLES | The number of samples to allocate in the mosaic |
| NLINES | The number of lines to allocate in the mosaic |
| NBANDS | The number of bands to allocate in the mosaic |
|
Files:
FROM
Description
This cube will be placed into the mosaic. It must have the same ProjectionName,
PixelResolution, EquatorialRadius, PolarRadius, LatitudeType, and LongitudeDirection as
the mosaic. The projection specific keywords, such as CenterLatitude and CenterLongitude,
must match as well.
|
Type
| cube |
|
File Mode
| input |
|
Filter
|
*.cub
|
Files:
MOSAIC
Description
The mosaic cube which will have the input cube placed in it. If the selected cube does
not already exist as a mosaic, the CREATE option must be selected and it will be created.
In this case NSAMPLES, NLINES, and NBANDS must be entered.
|
Type
| cube |
|
File Mode
| output |
|
Filter
|
*.cub
|
Files:
PRIORITY
Description
This parameter determines how the pixels from the input cube will overlap with the pixels
in the mosaic.
|
Type
| string |
|
Default
|
ONTOP
|
|
Option List:
|
|
Option |
Brief |
Description |
| ONTOP |
Input cube is placed on top of the mosaic
|
Valid input pixels will always be copied onto the mosaic. Any input pixel will be
placed onto a NULL mosaic pixel. If the mosaic pixel is not NULL and the input pixel
is special, it will only be copied onto the mosaic if the special pixel flags are set.
Exclusions
- TYPE
- CRITERIA
- NUMBER
- KEYNAME
- KEYVALUE
|
| BENEATH |
Input cube is placed beneath the mosaic
|
If the mosaic pixel is NULL, then the input pixel will be placed on top of the
mosaic. Otherwise, it remains unchanged.
Exclusions
- TYPE
- CRITERIA
- NUMBER
- KEYNAME
- KEYVALUE
- HIGHSATURATION
- LOWSATURATION
- NULL
Inclusions
|
| BAND |
Input pixel is placed on top of the mosaic based on the criteria in the selected band
|
If the input and mosaic pixel of the priority band, specified by NUMBER or KEYNAME
and KEYVALUE are valid, a less than or greater than comparison is done. Depending on
the CRITERIA selected, the lower or higher of the two pixels is placed on top.
Special and NULL pixels are not placed on top unless their flags are set. So, if the
comparison of the priority band says that the input pixel should be on top but the
input pixel on any other band is null, without the null option being selected, the
mosaic pixel will remain unchanged for that band.
Inclusions
|
| AVERAGE | Average of valid input and the mosaic pixels |
If the Input and Mosaic pixels are valid, the output will be the average of
the 2 values. A count band is created for each corresponding band in the mosaic and
holds the count of the images corresponding to the Average DN value of each pixel in
the mosaic.
Exclusions
- TYPE
- CRITERIA
- NUMBER
- KEYNAME
- KEYVALUE
- TRACK
|
|
Band Priority:
TYPE
Description
This option allows the user to select the method in which they want to specify the band
to use for the pixel comparison.
|
Type
| string |
|
Default
|
BANDNUM
|
|
Option List:
|
|
Option |
Brief |
Description |
| BANDNUMBER | Band Number |
The band number to use in the pixel comparison.
Exclusions
Inclusions
|
| KEYWORD |
PVL Keyword in "BandBin" group
|
Selecting this option allows the user to enter the Keyword name and value
corresponding to the band to use in the pixel comparison.
Exclusions
Inclusions
|
|
Band Priority:
NUMBER
Description
This is the ban dnumber selected for the pixel comparison.
Band Priority:
KEYNAME
Description
The entered keyword name must match the name in the BandBin group.
|
Type
| string |
|
Default
| OriginalBand |
Band Priority:
KEYVALUE
Description
This value must match the value associated with the KEYNAME parameter.
Band Priority:
CRITERIA
Description
Select which type of comparison to do on the pixels. You can choose whether the lesser
or greater of the two pixels will be placed on top of the mosaic.
|
Type
| string |
|
Default
| LESSER |
|
Option List:
|
|
Option |
Brief |
Description |
| LESSER |
The lower DN value between the input and mosaic pixels will be placed on top
|
The lower DN value between the input and mosaic pixels will be placed on top of
the mosaic.
|
| GREATER |
The larger DN value between the input and mosaic pixels will be placed on top
|
The larger DN value between the input and mosaic pixels will be placed on top of
the mosaic.
|
|
Placement:
INSAMPLE
Description
This is a sample in the input image. This sample in the input cube will be placed at
OUTSAMPLE in the mosaic.
Placement:
INLINE
Description
This is a line in the input image. This line in the input cube will be placed at
OUTLINE in the mosaic.
Placement:
INBAND
Description
This is a band in the input image. This band in the input cube will be placed at
OUTBAND in the mosaic.
Placement:
OUTSAMPLE
Description
This parameter is used to select the starting sample where
the input cube will be placed. The sample INSAMPLE will be placed at
this sample in the output mosaic.
Placement:
OUTLINE
Description
This parameter is used to select the starting line where
the input cube will be placed. The line INLINE will be placed at
this line in the output mosaic.
Placement:
OUTBAND
Description
This parameter is used to select the starting band where
the input cube will be placed. The band INBAND will be placed at
this band in the output mosaic.
Options:
MATCHBANDBIN
Description
This option causes the application to fail if the input bandbin group does not
match the mosaic bandbin group. This parameter will only
apply when the input labels contain a BandBin Group with
wavelength keywords.
|
Type
| boolean |
|
Default
| FALSE |
Options:
MATCHDEM
Description
This option causes the application to fail if the input DEM
shapemodel does not match the mosaic's' shapemodel. This
parameter will only apply when the input labels contain a
ShapeModel keyword in the Kernels Group.
|
Type
| boolean |
|
Default
| FALSE |
Options:
HIGHSATURATION
Description
This option causes High Saturation values (both Instrument and
Representation) in the input image to be automatically copied to the
mosaic regardless of the priority.
|
Type
| boolean |
|
Default
| FALSE |
Options:
LOWSATURATION
Description
This option causes Low Saturation values (both Instrument and
Representation) in the input image to be automatically copied to the
mosaic regardless of the priority.
|
Type
| boolean |
|
Default
| FALSE |
Options:
NULL
Description
This option causes NULL values in the input image to be automatically
copied to the mosaic regardless of the priority.
|
Type
| boolean |
|
Default
| FALSE |
Initialization:
CREATE
Description
This parameter is used to specify whether the mosaic needs to be created.
|
Type
| string |
|
Default
| NO |
|
Option List:
|
|
Option |
Brief |
Description |
| NO | The output mosaic already exists |
Choose this option if the output mosaic already exists.
Exclusions
- NSAMPLES
- NLINES
- NBANDS
- TRACK
- PROPAGATE
|
| YES | Create the output mosaic |
The output mosaic does not exist and will be created.
Inclusions
- NSAMPLES
- NLINES
- NBANDS
- PROPAGATE
|
|
Initialization:
TRACK
Description
The Track feature creates a separate tracking cube containing the index values for
the source of every pixel in the output mosaic. The tracking cube can only be used
appropriately through the QVIEW-AdvancedTracking tool. As the user pans across the
displayed mosaic, for every mosaic pixel location QVIEW-AdvancedTracking will
interactively report the filename, the serial number and the index of the input cube
that was input to handmos for that specific pixel location. The tracking cube cannot
be used outside the QVIEW-AdvancedTracking tool except as a visual representation of
the source cubes for the different pixels. TRACK must be set to TRUE at the time of
mosaic creation only and cannot be turned on after the mosaic is created. When a
mosaic is created with TRACK=TRUE, all subsequent runs will default to TRACK=TRUE.
When a mosaic is created with TRACK=FALSE, an error will be encountered if subsequent
runs have TRACK=TRUE. The tracking cube will always be of type unsigned integer.
Depending on the bit-type of the mosaic cube and/or the number of bands it contains,
the tracking cube may be as much as four times the size of the mosaic cube itself.
WARNING:
If Tracking is turned on in a mosaic, any subsequent applications that modify DN
values, such as the applicationreduce, will corrupt the DN values in the
tracking cube.
|
Type
| boolean |
|
Default
| FALSE |
Initialization:
PROPAGATE
Description
If selected the application will transfer the labels, tables,
and BLOBs from the input cube to the output mosaic. If not selected
only the Band Bin information will be transferred. This option can
only be used when the mosaic is being created (i.e., CREATE=YES).
|
Type
| boolean |
|
Default
| TRUE |
Initialization:
NSAMPLES
Description
This parameter is used to specify the number of samples
in the output mosaic.
|
Type
| integer |
|
Minimum
| 1
(inclusive)
|
Initialization:
NLINES
Description
This parameter is used to specify the number of lines
in the output mosaic.
|
Type
| integer |
|
Minimum
| 1
(inclusive)
|
Initialization:
NBANDS
Description
This parameter is used to specify the number of bands
in the output mosaic.
|
Type
| integer |
|
Minimum
| 1
(inclusive)
|