Create a mosaic using a list of map projected cubes
Overview
Parameters
Example 1
Description
This application mosaics together ISIS cubes from a user-entered text file containing the
input cube filenames (FROMLIST). If the output file (MOSAIC) does not already exist, the
program will create it from the input cubes. Otherwise, the input cubes will be placed
into the existing mosaic cube.
REQUIREMENT: The listed input cubes must be map projected (Level2).
The input cubes are required to be projected to the EXACT SAME ProjectionName,
PixelResolution (or MapScale), EquatorialRadius, PolarRadius, LatitudeType,
LongitudeDirection, as well as specific map projection keywords (e.g., CenterLatitude,
CenterLongitude). If these map projection requirements are not met, an error will be
encountered.
Note: The latitude and longitude range of the individual input cubes may vary.
By default, the input cubes are placed into the mosaic in the order in which they appear
in the input list. Automos automatically determines the size of the new output
mosaic by examining the latitude and longitude range of each input cube. The user may
override this by entering their own latitude/longitude extents for the output mosaic
cube by setting the GRANGE parameter.
Integrity-check Parameters:
MATCHBANDBIN = TRUE, 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 automos 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)
Depricated CubeProjection and ProjectionManager to ProjectionFactory
Elizabeth Miller
2006-08-03
Added user entered range and helper button
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.
Sean Crosby
2007-02-28
Added an exception that reports which input cube is causing a problem while mosaicking.
Sean Crosby
2007-03-06
Program no longer throws an exception when an input cube does not fit into the output mosaic.
Instead, any files that are not included in the output are listed in the application log.
Sean Crosby
2007-03-20
Corrected bug in determining if an image fits into the output mosaic
Sean Crosby
2007-03-20
Fixed one of the application tests
Stuart Sides
2007-04-16
Fixed bug where input cubes where incorrectly not processed.
Steven Lambright
2008-05-13
This program now utilizes ProcessMapMosaic
Sharmila Prasad
2009-10-19
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.
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
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
Sharmila Prasad
2011-09-07
Fixed bug #0000390 - tracking should continue even if the first image does
not map onto the mosaic
Sharmila Prasad
2011-10-25
Fixed bug #0000464 - add optional list TOLIST containing all the files names
that were added onto the mosaic.
Sharmila Prasad
2011-11-07
Updated documentation for Average priority. Fixes #553
Steven Lambright and Stuart Sides
2012-07-16
Fixed a border condition that caused only a few samples of an input image to be put into an
output mosaic. The trigger for this condition was an input image that spanned more than the
0-360 domain by just a sample or two on the 0 side (started at -0.000?? degrees longitude
instead of zero). Other cases of spanning more than the world - or just crossing the seam -
could have exhibited problems. Fixes #967.
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. Also
modified mapmos and handmos to do the same. Fixes #976.
Debbie A. Cook
2012-12-10
Changed to use TProjection instead of Projection. References #775
Debbie A. Cook
2013-04-03
Fixed type in specification of TYPE default in Band Priority group discovered when creating
ringsautomos. It was fixed here to make the applications consistent. References #775
Added parameter checking to XML MAXLON and MAXLAT to check if they are greater than their
minimum counterpart. Fixes #5148
Summer Stapleton
2018-08-13
Updated 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
A list of map projected cubes to mosaic (Level2). Each cube in the list must have
the same ProjectionName, PixelResolution (or MapScale), EquatorialRadius,
PolarRadius, LatitudeType, LongitudeDirection and specific map projection keywords
such as CenterLatitude and CenterLongitude. This includes the output mosaic
if it already exists. The latitude and longitude extents of each input file may
vary.
If this mosaic cube already exists, then the cubes listed in the input list will
be combined with this cube. The Mapping Group keywords must match between the
existing mosaic and the input cubes. If this output file does not exist, it will
be created from the input cubes in the cube list.
This optional output list contains the names of the images that overlapped within the
latitude and longitude boundaries of the output mosaic and were added. Automos
does not fail and will only display a warning for the input images that fall completely
outside the boundaries of the mosaic, this list will not include these images.
This parameter is used to determine the placement of the input pixels
in the output mosaic.
Type
string
Default
ONTOP
Option List:
Option
Brief
Description
ONTOP
Input cube will be placed on top of the mosaic
A Valid input pixel will replace an output mosaic pixel.
Special input pixels will be copied onto the mosaic only if the
special pixel flags are set. Refer to HIGHSATURATION, LOWSATURATION and
NULL for special pixel values.
Exclusions
TYPE
CRITERIA
NUMBER
KEYNAME
KEYVALUE
BENEATH
Input cube will be placed beneath the mosaic
If the output mosaic pixel is NULL, then the Valid input pixel
will be written onto the mosaic, otherwise it remains unchanged.
Exclusions
TYPE
CRITERIA
NUMBER
KEYNAME
KEYVALUE
HIGHSATURATION
LOWSATURATION
NULL
Inclusions
TRACK
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
(i.e., replaces the mosaic pixel). This applies to all the corresponding Valid band
pixels. Special pixels in the corresponding bands will not replace the output mosaic
pixel unless the HIGHSATURATION, LOWSATURATION and NULL flags are set to TRUE. Refer
to parameters HIGHSATURATION, LOWSATURATION, and NULL. This means, if the results
of the priority band comparison shows that the input pixel should be on top, but the
input pixel on any other band is NULL, without the NULL=TRUE, the output mosaic pixel
will remain unchanged for that band.
Inclusions
TYPE
CRITERIA
AVERAGE
Average of valid input and the mosaic pixels
If the Input and Mosaic pixels are valid then the output will be the average of the
2 values. A count-band is created in the output mosaic and holds the count of images
corresponding to the output Average DN value of each pixel in the mosaic.
NOTE: If an existing mosaic does not already contain a count-band, an error
will be encountered with Priority=AVERAGE.
The keyword values can be found on the labels of the input files under
the "BandBin" Group. For instance, KEYNAME=NAME where the KEYVALUE
can then be set to "Phase Angle", "Emission Angle", "Incidence Angle",
"Pixel Resolution".
The keyword values can be found on the labels of the input files under
the "BandBin" Group. For instance, KEYNAME=NAME where the KEYVALUE
can then be set to "Phase Angle", "Emission Angle", "Incidence Angle",
"Pixel Resolution". Refer to the phocube application that will
create these 'Named' Bands.
Select which type of comparison to perform on the priority band pixels.
The choice is whether the lesser or greater value between the current input
priority band pixel or mosaic priority band pixel will replace or retain the output
mosaic pixel. The results of this criteria will apply to all corresponding bands
in the output mosaic. The special pixel values in the remaining bands will be
replaced by valid pixels of the corresponding mosaic bands. Refer to the
parameters HIGHSATURATION, LOWSATURATION and NULL to override this and propagate
input special pixel values to all bands in the output mosaic.
Type
string
Default
LESSER
Option List:
Option
Brief
Description
LESSER
The lower DN value of the input priority band will replace the mosaic pixel
If the DN value of a pixel in the priority band of the input cube
is lesser than the corresponding pixel in the mosaic priority band,
then the output pixel of the mosaic will be replaced by the input
cube pixel. This will apply to all bands at this pixel location.
GREATER
The greater DN value of the input priority band will replace the mosaic pixel
If the DN value of a pixel in the priority band of the input cube
is greater than the corresponding pixel in the mosaic priority band,
then the output pixel of the mosaic will be retained on NOT be
replaced by the input cube pixel. This will apply to all bands at
this pixel location.
AUTO is the default for this parameter. By default the ground range is
calculated automatically based on the list of input cubes. The user can
override this default. If the USER option is selected, values must be
entered for the MINLAT, MAXLAT, MINLON, and MAXLON parameters.
Type
string
Default
AUTO
Option List:
Option
Brief
Description
AUTO
Automatically Calculate Range
The program will automatically calculate the ground range for the
mosaic by examining that latitude and longitude range of all the
cubes contained in the list passed to FROMLIST. This is the
default option.
Exclusions
MINLAT
MAXLAT
MINLON
MAXLON
USER
User Entered Range
The program will apply the ground range values you entered for
the mosaic.
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 automos 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.
This option set to TRUE causes the application to fail if the BandBin group keywords
are not identical for all input cubes and the output mosaic cube. The default
for this parameter is TRUE in order to preserve integrity of a multi-band
(multi-wavelength) mosaic product. The order of band wavelengths of the input
cubes must match each other and the mosaic. If MATCHBANDIN is set to FALSE,
then the BandBin Group keywords of the input images do not have to match the mosaic
BandBin Group labels. Note: The output mosaic BandBin Group and number
of output bands is established with the first input file into the mosaic.
The default is FALSE. If set to TRUE, this application will create a
Mosaic Group in the keyword labels of the new output mosaic cube including
a ShapeModel keyword. The output mosaic is created with the first input
cube listed in the FROMLIST file, the ShapeModel keyword and its value
will be propagated to the Mosaic Group of the output mosaic cube file.
Subsequently, the ShapeModel keyword value of the remaining input cubes will
be checked against the ShapeModel value in the mosaic cube. This application
will fail if the ShapeModel keywords don't match.
The ShapeModel keyword can be found in the Kernels group of the individual
input Level2 cubes. This keyword is established in spiceinit when a DEM
radius file is chosen for the image surface reference and orthorectification
in cam2map-Level2.
This option causes an input High Saturation special pixel value
(both Instrument and Representation) to replace the output mosaic pixel
irrespective of the priority set or the original value of the mosaic pixel.
This option causes an input Low Saturation special pixel value
(both Instrument and Representation) to replace the output mosaic pixel
regardless of the priority set or the original value of the mosaic pixel.
This option causes input NULL pixel values to replace the output mosaic pixel
irrespective of the priority set or the original value of the mosaic pixel.
Example of automos run with two multiband cubes and band priority.
Description
This example shows what happens to the output mosaic when PRIORITY=BAND. Special pixels
will not be propagated to the output mosaic if the flags are not set, regardless of the
comparison of the priority band. Also, special pixels are not used in the lesser or
greater comparison. Special pixels in the mosaic will strictly be replaced by valid input
pixels and special pixels in the input will not replace valid mosaic pixels, unless the
special pixel flags are set.
The input list has two two-band cubes. Each band has had special pixels introduced to
clarify what happens during the mosaic process.
The output mosaic shows the result of the second input image being mosaicked with the
first input image. You can see in band one that none of the special pixels were retained
because none of the special pixel flags were set. In other words, regardless of whether
there was a valid comparison at that pixel of the priority band, all other bands will
try to retain valid data.
In band two, you can still see where the special pixels were in the second input image.
The second image would have been "on top" because in band two, the pixels are less than
those of the mosaic. However, the valid data in the mosaic was disregarded because the
special pixel flags were not set. You cannot see the special pixels from the first image
because the valid pixels from the second image were kept instead.