automos

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

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

Type	filename
File Mode	input
Filter	*.txt *.lis *.lst

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

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

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 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. Exclusions TYPE CRITERIA NUMBER KEYNAME KEYVALUE TRACK

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 BANDNUMBER Band Number You can enter the band number to use in the pixel comparison. Refer to the parameter NUMBER. Exclusions KEYNAME KEYVALUE Inclusions NUMBER KEYWORD Keyword 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

Description

This is the band number selected for the pixel comparison

Type	integer
Default	1

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

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

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

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 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. Inclusions MINLAT MAXLAT MINLON MAXLON

Description

The minimum latitude value boundary extent for the output mosaic.

Type	double

Description

The maximum latitude value boundary extent for the output mosaic.

Type	double
Greater Than	MINLAT

Description

The minimum longitude value boundary extent for the output mosaic.

Type	double

Description

The maximum longitude value boundary extent for the output mosaic.

Type	double
Greater Than	MINLON

Description

The Track feature creates a separate tracking cube containing the index values for the source of every pixel in the output mosaic. The tracking cube can only be used appropriately through the QVIEW-AdvancedTracking tool. As the user pans across the displayed mosaic, for every mosaic pixel location QVIEW-AdvancedTracking will interactively report the filename, the serial number and the index of the input cube that was input to 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.

Type	boolean
Default	FALSE

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

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

Type	boolean
Default	FALSE

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

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

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

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.

automos fromlist=example.lis mosaic=exampleMosaic.cub priority=band number=2

Example of GUI

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

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 of resulting mosaic.

Output mosaic Parameter Name: MOSAIC This is a side-by-side display of the two bands of the resulting mosaic.