Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

ISIS Documentation

ringsautomos

Create a mosaic using a list of map projected cubes

This program uses a text-based list of cubes, all in the same map projection and equivalent projection parameters (PixelResolution, CenterRingLongitude, etc), to generate a mosaic. By default, The program automatically determines the size of the mosaic by examining each cube. The user also has the option of entering their own ring radius and ring longitude range to use for the mosaic.

There are four different ways/priorities (ONTOP, BENEATH, BAND and AVERAGE) for how the input image can be placed on the mosaic. In case of special pixels and the special pixel flags being enabled, the details for each priority is described in the tables 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. The tracking cube will have the same base-name as the mosaic cube, but will end in "_tracking.cub", and must always reside in the same directory as the mosaic cube to be properly accessed. 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 ringsautomos 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 differently depending on the Priority options and whether you are using single- or multi-band cubes:

  • For single band cubes, you can specify PRIORITY as ONTOP and BENEATH.
  • For multiband cubes, you can use PRIORITY=BAND.
  • For multiband cubes, you can use PRIORITY=ONTOP only when the NULL, HIGHSATURATION and LOWSATURATION options are set to true.
  • This feature is NOT supported for any single- or multi-band cubes when using 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.

Tracking can be set at the time of Mosaic creation only and cannot be turned on after the mosaic is created. For multiband mosaics, if PRIORITY=ONTOP and all the Special Pixel flags are not set to true, or if PRIORITY=BENEATH, tracking will be turned off even if it was turned on while creating the mosaic. ONTOP priority places all the valid input pixels onto the mosaic unless the special pixel flags are turned on or if the mosaic has a NULL pixel. In a multi band scenario, a pixel origin within a particular line and sample will not be the same in all the different bands.

WARNING: If Tracking is turned on in a mosaic, any subsequent applications that modify DN values will corrupt the Tracking cube.

Priority BAND can track the origin for multiband input cubes. The input cube pixels will be placed in the output mosaic based on the "Lesser" or "Greater" criteria of a priority band defined by the user. Band can be implemented with the TYPE, BANDNUMBER or KEYWORD options.

  • If BANDNUMBER is chosen then the band number can be entered in the NUMBER field.
  • If KEYWORD is chosen then PVL key name and value from the BANDBIN group can be entered in the KEYNAME and KEYVALUE fields.

Multiband input example with BAND priority and example parameters:

  • BAND = Emission Angle band(EMA)
  • Input pixels = (30,30,30) in EMA Band for some sample and line
  • Corresponding pixels in the EMA band in the mosaic = (75, 75, 75)
  • Criteria = GREATER than

Expected Result:

    Since input pixels are not GREATER than corresponding mosaic pixels, then the input pixels are not copied to the mosaic, so also the corresponding pixels in all the other bands in the input. Hence the origin for those pixels remains unchanged.

Given this same example with CRITERIA=LESSER than:

    All corresponding pixels in all the input bands will be copied to the mosaic and the origin for those pixels is the current input cube.

MATCHBANDIN, if set, requires the specified input bands to match the mosaic bands and the bands can be anywhere in the mosaic but must be contiguous for multi-band. If MATCHBANDIN is not set then any input image can be placed on the mosaic within its boundaries.

HIGHSATURATION, LOWSATURATION and NULL options, if set, will cause the the input pixels with these values to be copied to the mosaic for ONTOP and BAND priorities regardless of the CRITERIA for the BAND priority. These options are not supported for BENEATH priority.

Currently Tracking can be viewed in the Advanced Tool Tracking option of the qview application. Following are the Tracking info:

Index: Zero based and is in the order in which the image was placed on the mosaic. No origin is represented as -1.

FileName: File name of input image

Serial Number: Serial Number of the input image

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

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 Changed to work for ringplane projections and renamed to ringsautomos. Also fixed type in BANDNUMBER parameter default. References #775
Jeannie Backer2013-03-12 Added appTests. Test coverage appears low (52% scope, 54% line, 50% function), however these tests cover 100% in all three categories for the code that does not apply to the GUI helper methods.
Summer Stapleton2018-08-13 Updated documentation to reflect new handling of tracking capabilities with an external tracking cube and to be more consistent with other mosaicking program documentation as well as clarify why special pixel flags are required when priority=ontop for multiband mosaics. References #2092

Parameters

Files

A list of map projected cubes to mosaic. The Mapping groups must match in order to mosaic the cubes.
Type filename
File Mode input
Filter *.txt *.lis *.lst

The mosaic cube which will have the input cube placed into it.
Type cube
File Mode output
Filter *.cub

This optional output list contains the names of all images that were added onto the mosaic.
Type filename
File Mode output
Internal Default None
Filter *.lis

This parameter is used to select one of four ways to mosaic the pixels in areas of overlap.
Type string
Default ONTOP
Option List:
Option Brief Description
ONTOP Input cube will be placed on top of the mosaic An input pixel will always be copied onto a NULL mosaic pixel. Valid input pixel will also be copied onto the mosaic. Special input pixel will be copied onto the mosaic only if the special pixel flags are set.

Exclusions

  • TYPE
  • CRITERIA
  • NUMBER
  • KEYNAME
  • KEYVALUE
BENEATHInput cube will be placed beneath the mosaic If the mosaic pixel is NULL, then the input pixel will be written onto the mosaic otherwise it remains unchanged.

Exclusions

  • TYPE
  • CRITERIA
  • NUMBER
  • KEYNAME
  • KEYVALUE
  • HIGHSATURATION
  • LOWSATURATION
  • NULL

Inclusions

  • TRACK
BANDInput pixel is placed on top of the mosaic based on the criteria in the selected band Input pixel is copied onto the mosaic if the mosaic pixel is NULL or if the chosen input pixel satisfies the criteria in comparison with the corresponding pixel in the mosaic. Special Input pixels are copied onto the mosaic if the special pixel flags are set.

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

The pixels in this band will be used for comparison between input image and the mosaic for a decision to be made in copying image into the mosaic.
Type string
Default BANDNUMBER
Option List:
Option Brief Description
BANDNUMBERBand Number Choose this option to enter the band number to be used for comparison. This band number will be compared with the band # in the OriginalBand.

Exclusions

  • KEYNAME
  • KEYVALUE

Inclusions

  • NUMBER
KEYWORDPVL Keyword in "BandBin" group Choose this option to enter Keyword from the "BandBin" group of the PVL

Exclusions

  • NUMBER

Inclusions

  • KEYNAME
  • KEYVALUE

The band number should match that in the "OriginalBand" of "BandBin" Group
Type integer
Default 1

The entered key name must match the key name in the "BandBin"
Type string
Default OriginalBand

This value must match the value associated with the key name entered in the KEYNAME
Type string
Default 1

This parameter is used to select one of two ways to mosaic the pixels in areas of overlap when doing by band comparison.
Type string
Default LESSER
Option List:
Option Brief Description
LESSERInput pixel LESSER than the corresponding pixel in the mosaic If the dn value of a pixel in the input cube is lesser than the corresponding pixel in the mosaic in the chosen band, then the input cube pixel will replace the corresponding pixel for all the bands in the mosaic.
GREATERInput pixel GREATER than the corresponding pixel in the mosaic If the dn value of a pixel in the input cube is greater than the corresponding pixel in the mosaic in the chosen band, then the input cube pixel will replace the corresponding pixel for all the bands in the mosaic.

Ground Range

The ground range can either be calculated automatically or entered by the user. If the USER option is selected, values must be entered for the MINRINGRAD, MAXRINGRAD, MINRINGLON, and MAXRINGLON parameters. AUTO is the default for this parameter.
Type string
Default AUTO
Option List:
Option Brief Description
AUTOAutomatically Calculate Range The program will automatically calculate the groundrange for the mosaic by examining all the cubes in the FROMLIST. This is the default option.

Exclusions

  • MINRINGRAD
  • MAXRINGRAD
  • MINRINGLON
  • MAXRINGLON
USERUser Entered Range The program will use the user entered ground range values for the mosaic.

Inclusions

  • MINRINGRAD
  • MAXRINGRAD
  • MINRINGLON
  • MAXRINGLON

The minimum ring radius value to use in the mosaic.
Type double

The maximum ring radius value to use in the mosaic.
Type double

The minimum ring longitude value to use in the mosaic.
Type double

The maximum ring longitude value to use in the mosaic.
Type double

Options

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 ringsautomos 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

This option causes the application to fail if the input bandbin group does not match the mosaic bandbin group.
Type boolean
Default TRUE

This option causes the application to fail if the input DEM shapemodel does not match the mosaic's' shapemodel.
Type boolean
Default FALSE

This option causes High Saturation values (both Instrument and Representation) in the input image to be automatically copied to the mosaic irrespective of the priority
Type boolean
Default FALSE

This option causes Low Saturation values (both Instrument and Representation) in the input image to be automatically copied to the mosaic irrespective of the priority
Type boolean
Default FALSE

This option causes NULL values in the input image to be automatically copied to the mosaic irrespective of the priority
Type boolean
Default FALSE