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

mapmos

Create a mosaic using map projected cubes

This program allows the user to create a mosaic using a map projected cube (Level2). A mosaic can be created from an initial cube or the input cube can be placed in a pre-existing mosaic.

REQUIREMENT: The input cube must be map projected (Level2). The input cube is 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.

If a new mosaic is to be created, it must be initalized with an input cube and CREATE=YES. The default size of the output mosaic will be the SAME latitude and longitude extents of the input file. The size of the output mosaic can be entered by the user through any or all four boundary parameters: MINLAT, MAXLAT, MINLON, MAXLON. The input cube also establishes the number of bands and BandBin Group of the output mosaic. If there is a list of input cubes to mosaic together, refer to the similar application called automos.

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

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

Refer to automos for additional information and examples.

Categories

Related Applications to Previous Versions of ISIS

This program replaces the following application existing in previous versions of ISIS:
  • mosaic

Related Objects and Documents

Applications

History

Eric Eliason1986-01-02 Original version
Jeff Anderson2004-02-24 Converted to Isis 3.0
Jeff Anderson2004-02-26 Modified to not propagate input labels to the output mosaic
Jeff Anderson2005-11-15 Fixed bug with mapping groups not properly initialized or copied
Jacob Danton2005-12-05 Added appTest
Elizabeth Miller2006-05-18 Depricated CubeProjection and ProjectionManager to ProjectionFactory
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.
Steven Lambright2008-05-13 This program now utilizes ProcessMapMosaic
Christopher Austin2008-09-19 If the given cube falls outside the provided the mosaic, it will now be logged. (Removed some unused header files.)
Christopher Austin2008-12-11 Changed the parameters SLAT, ELAT, SLON, ELON to MINLAT, MAXLAT, MINLON, MAXLON in correlation with automos.
Sharmila Prasad2009-10-15 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 Prasad2010-10-27 Process Input File Attributes
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-11-07 Updated documentation for Average priority. Fixes #553.
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. References #976.
Kimberly Oyama2013-04-15 Made the default for the TYPE parameter BANDNUMBER because, when running the GUI and PRIORITY=BAND, a blank "TYPE=" was added to the command line string. This no longer occurs, there is either no TYPE parameter or it is set to "TYPE=BANDNUMBER". Fixes #1549.
Kimberly Oyama2014-02-14 Removed the requirement that all four lat/lon extents be entered by the user. The user can now enter as little as none if the input cube Mapping group has the extents. However, if the input cube is missing any of the extents, the user must enter them. If any of the extents are missing, an error will be thrown. Fixes #1550.
Kimberly Oyama and Tammy Becker2014-04-05 Updated Documentation. Updated unit test for priority=band. Fixes #1620. References #1623. References #1550.
Summer Stapleton2018-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

Parameters

Files

This cube will be placed in 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

The output 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 the latitude and longitude range parameters must be entered.
Type cube
File Mode output
Filter *.cub

This parameter determines how the pixels from the input cube will be placed in the mosaic.
Type string
Default ONTOP
Option List:
Option Brief Description
ONTOP Input cube will be 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 will be 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
BAND Input pixel is placed based on the CRITERIA parameter 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

  • TYPE
  • CRITERIA
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

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.

Exclusions

  • KEYNAME
  • KEYVALUE

Inclusions

  • NUMBER
KEYWORD PVL Keyword in "BandBin" group Selecting this option allows you to enter the Keyword name and value corresponding to the band to use in the pixel comparison.

Exclusions

  • NUMBER

Inclusions

  • KEYNAME
  • KEYVALUE

This is the number of the band to use for the pixel comparison.
Type integer
Default 1

This is the keyword string. The entered keyword name must match the name in the BandBin group in the image labels.
Type string
Default OriginalBand

This value must match the value associated with the KEYNAME parameter.
Type string
Default 1

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.

Initialization

Select this parameter if the mosaic does not already exist.
Type boolean
Default NO
Inclusions
  • MINLAT
  • MAXLAT
  • MINLON
  • MAXLON
  • TRACK

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 mapmos 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 parameter specifies the minimum latitude of the mosaic.
Type double
Internal Default Use Map Value
Minimum -90.0 (inclusive)

This parameter specifies the maximum latitude of the mosaic.
Type double
Internal Default Use Map Value
Maximum 90.0 (inclusive)
Greater Than MINLAT

This parameter specifies the minimum longitude of the mosaic.
Type double
Internal Default Use Map Value

This parameter specifies the maximum longitude of the mosaic.
Type double
Internal Default Use Map Value
Greater Than MINLON

Options

This option causes the application to fail if the input BandBin Group keywords do not match the mosaic BandBin Group.
Type boolean
Default TRUE

This option causes the application to fail if the input DEM shapemodel file does not match the filename value in the output mosaic ShapeModel.
Type boolean
Default FALSE

This option causes an input High 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

This option causes input NULL pixel values to replace the output mosaic pixel regardless of the priority set or the original value of the mosaic pixel.
Type boolean
Default FALSE

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