Home
About ISIS
Support
Download

ISIS 3

Documentation
Tutorials
Technical Documents

ISIS 2

Documentation
Tutorials
Technical Documents

Search
USGS

ISIS 3 Application Documentation

automos

Printer Friendly View | TOC | Home

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 propogate 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 band in the output mosaic file containing the index values for every pixel in the output mosaic. The Track-band can only be used appropriately through the QVIEW-AdvancedTracking tool. As the user interactively pans across the displayed mosaic band (Band1), for every mosaic pixel location QVIEW-AdvancedTracking will report the source cube filename that was input to automos. The Track-band cannot be used outside the QVIEW-AdvancedTracking tool. The file (byte) size of the mosaic is increased due to the track-band.

The Track feature works with Priority options ONTOP (with HIGHSATURATION and LOWSATURATION parameters) and BENEATH for single band input cubes. It does NOT support multiple band input cubes with these priority options. It does work for multiband cubes when PRIORITY=BAND. Furthermore, this feature is NOT supported when PRIORITY=AVERAGE.

The following table describes how the program will determine the pixel value in the output mosaic for areas of image overlap.

PRIORITYRESULT
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. Refer to parameters HIGHSATURATION, LOWSATURATION, and NULL to override replacement of Valid output mosaic pixels.
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 SaturationLow SaturationNull Input Pixel Value TypeCurrent 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 SaturationLow SaturationNull Input Pixel Value TypeCurrent 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 Objects and Documents

Applications

History

Jim Mathews1992-01-01 Original version
Jeff Anderson2004-02-26 Converted to Isis 3.0
Jeff Anderson2004-07-28 Fixed bug caused by PVL refactor
Elizabeth Miller2005-11-15 Added appTest, and fixed fromlist filter
Elizabeth Miller2006-05-18 Depricated CubeProjection and ProjectionManager to ProjectionFactory
Elizabeth Miller2006-08-03 Added user entered range and helper button
Elizabeth Miller2006-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 Crosby2007-02-28 Added an exception that reports which input cube is causing a problem while mosaicking.
Sean Crosby2007-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 Crosby2007-03-20 Corrected bug in determining if an image fits into the output mosaic
Sean Crosby2007-03-20 Fixed one of the application tests
Stuart Sides2007-04-16 Fixed bug where input cubes where incorrectly not processed.
Steven Lambright2008-05-13 This program now utilizes ProcessMapMosaic
Sharmila Prasad2009-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 Prasad2011-01-19 Added "AVERAGE" priority where the mosaic will be average of valid input and mosaic pixels.
Sharmila Prasad2011-01-24 Option to match DEM and also added new group "mosaic" to hold ShapeModel attributes for the mosaic
Sharmila Prasad2011-09-07 Fixed bug #0000390 - tracking should continue even if the first image does not map onto the mosaic
Sharmila Prasad2011-10-25 Fixed bug #0000464 - add optional list TOLIST containing all the files names that were added onto the mosaic.
Sharmila Prasad2011-11-07 Updated documentation for Average priority. Fixes #553
Steven Lambright and Stuart Sides2012-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 Oyama2012-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. Cook2012-12-10 Changed to use TProjection instead of Projection. References #775
Debbie A. Cook2013-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
Jeannie Backer, Tammy Becker, and Kimberly Oyama2014-04-07 Updated user documentation. Fixes #1617. Fixes #1620. References #1623. References #1550.

Parameter Groups

Files

Name Description
FROMLIST List of cubes to mosaic
MOSAIC Mosaic output cube
TOLIST List of images successfully added to the mosaic
PRIORITYThe priority of output pixel placement

Band Priority

Name Description
TYPEIndicate the Band Name or Number to be used for comparison
NUMBEREnter the Band Number
KEYNAMEEnter the Keyword NAME as it appears in the BandBin Group
KEYVALUEEnter the keyword value associated with the "KEYNAME"
CRITERIAThe criteria (Lesser or Greater) of pixel placement in a priority band

Ground Range

Name Description
GRANGEGround Range Options
MINLATMinimum Latitude
MAXLATMaximum Latitude
MINLONMinimum Longitude
MAXLONMaximum Longitude

Options

Name Description
TRACK Track the filenames for each mosaic pixel
MATCHBANDBINInput and mosaic BandBin Groups must match
MATCHDEMEnforce DEM Match
HIGHSATURATIONForce input High (Instrument and Representation) values
LOWSATURATIONForce input Low (Instrument and Representation) values
NULLForce input NULL values
X

Files: FROMLIST

Description

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 longtiude extents of each input file may vary.

Type filename
File Mode input
Filter *.txt *.lis *.lst
Close Window
X

Files: MOSAIC

Description

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.

Type cube
File Mode output
Filter *.cub
Close Window
X

Files: TOLIST

Description

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.

Type filename
File Mode output
Internal Default None
Filter *.lis
Close Window
X

Files: PRIORITY

Description

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
BENEATHInput 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 says 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
AVERAGEAverage 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.

Exclusions

  • TYPE
  • CRITERIA
  • NUMBER
  • KEYNAME
  • KEYVALUE
  • TRACK
Close Window
X

Band Priority: TYPE

Description

This option allows you to select the method to specify the band to use for the pixel comparison.

Type string
Default BANDNUMBER
Option List:
Option Brief Description
BANDNUMBERBand Number You can enter the band number to use in the pixel comparison. Refer to the parameter NUMBER.

Exclusions

  • KEYNAME
  • KEYVALUE

Inclusions

  • NUMBER
KEYWORDKeyword NAME in "BandBin" Group You can select the Keyword name and value that correspond to the priority band Refer to the parameters KEYNAME and KEYVALUE.

Exclusions

  • NUMBER

Inclusions

  • KEYNAME
  • KEYVALUE
Close Window
X

Band Priority: NUMBER

Description

This is the band number selected for the pixel comparison

Type integer
Default 1
Close Window
X

Band Priority: KEYNAME

Description

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".

Type string
Default OriginalBand
Close Window
X

Band Priority: KEYVALUE

Description

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.

Type string
Default 1
Close Window
X

Band Priority: CRITERIA

Description

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
LESSERThe 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.
GREATERThe 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.
Close Window
X

Ground Range: GRANGE

Description

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
AUTOAutomatically 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
USERUser Entered Range The program will apply the ground range values you entered for the mosaic.

Inclusions

  • MINLAT
  • MAXLAT
  • MINLON
  • MAXLON
Close Window
X

Ground Range: MINLAT

Description

The minimum latitude value boundary extent for the output mosaic.

Type double
Close Window
X

Ground Range: MAXLAT

Description

The maximum latitude value boundary extent for the output mosaic.

Type double
Close Window
X

Ground Range: MINLON

Description

The minimum longitude value boundary extent for the output mosaic.

Type double
Close Window
X

Ground Range: MAXLON

Description

The maximum longitude value bounary extent for the output mosaic.

Type double
Close Window
X

Options: TRACK

Description

The Track feature creates a band in the output mosaic file containing the index values for every pixel in the output mosaic. The Track-band can only be used appropriately through the QVIEW-AdvancedTracking tool. As the user interactively pans across the displayed mosaic band (Band1), for every mosaic pixel location QVIEW-AdvancedTracking will report the source cube filename that was input to automos. The Track-band cannot be used outside the QVIEW-AdvancedTracking tool. 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 file (byte) size of the mosaic is increased due to the track-band.

A table, called InputImages, containing the names of the images used in the mosaic will be added to the cube when TRACK=TRUE.

WARNING: If Tracking is turned on in a mosaic, any subsequent applications that modify "dn" values will corrupt the track-band, for instance the application reduce.

Type boolean
Default FALSE
Close Window
X

Options: MATCHBANDBIN

Description

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.

Type boolean
Default TRUE
Close Window
X

Options: MATCHDEM

Description

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 it's value will be propogated to the 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.

Type boolean
Default FALSE
Close Window
X

Options: HIGHSATURATION

Description

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.

Type boolean
Default FALSE
Close Window
X

Options: LOWSATURATION

Description

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.

Type boolean
Default FALSE
Close Window
X

Options: NULL

Description

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.

Type boolean
Default FALSE
Close Window

Example 1

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 mosaiced 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 left alone 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.

Command Line

automos fromlist=example.lis mosaic=exampleMosaic.cub priority=band number=2
An example of how to run this program from the command line.

GUI Screenshot

Example of GUI

Example GUI

An example of how to run this program using the GUI.

Input Images

Input image 1

First image in list

Parameter Name: FROMLIST

This is a side-by-side display of the two bands of the first input cube. You can see the colorful special pixels in each band.

Input image 2

Input image for mask

Parameter Name: FROMLIST

This is a side-by-side display of the two bands of the second input cube. You can see the colorful special pixels in each band.

Output Image

Output image of resulting mosaic.

Output mosaic

Parameter Name: MOSAIC

This is a side-by-side display of the two bands of the resulting mosaic.