BuildMosaicRaster Task

This task builds a mosaic raster based on a set of input rasters.

The virtual raster associated with this task is ENVIMosaicRaster.

See the Before You Begin section of the Seamless Mosaic help topic for tips on acceptable input formats, preprocessing steps, and working with hyperspectral images.

If you use the Export method to save a multi-band mosaic to disk, the output mosaic will have a band-interleaved-by-pixel (BIP) format. This ensures optimal performance during the export step.

Example

The example uses sample images that available from our ENVI Tutorials web page. Click the Mosaic link to download the .zip file to your achine, then unzip the files. Update the file location with your own directory.

; Start the application

e = ENVI()

; Open two aerial photos

File1 = '2002apr01.dat'

Raster1 = e.OpenRaster(File1)

File2 = '2004apr13_warp.dat'

Raster2 = e.OpenRaster(File2)

; Get the catalog of ENVITasks

Task = ENVITask('BuildMosaicRaster')

; Define inputs

Task.INPUT_RASTERS = [Raster1, Raster2]

Task.COLOR_MATCHING_ACTIONS = ['Reference', 'Adjust']

Task.COLOR_MATCHING_METHOD = 'Histogram Matching'

Task.COLOR_MATCHING_STATISTICS = 'Entire Scene'

Task.FEATHERING_METHOD = 'Edge'

Task.FEATHERING_DISTANCE = 15

Task.DATA_IGNORE_VALUE = 0

; Run the task

Task.Execute

; Get the collection of data objects currently available in the Data Manager

DataColl = e.Data

; Add the output to the Data Manager

DataColl.Add, Task.OUTPUT_RASTER

; Display the result

View = e.GetView()

Layer = View.CreateLayer(Task.OUTPUT_RASTER)

View.Zoom, /FULL_EXTENT

Syntax

Result = ENVITask('BuildMosaicRaster')

Input properties (Set, Get): COLOR_MATCHING_ACTIONS, COLOR_MATCHING_METHOD, COLOR_MATCHING_STATISTICS, DATA_IGNORE_VALUE, FEATHERING_DISTANCE, FEATHERING_METHOD, INPUT_RASTERS, OUTPUT_RASTER_URI, SEAMLINE_METHOD

Output properties (Get only): OUTPUT_RASTER

Properties marked as "Set" are those that you can set to specific values. You can also retrieve their current values any time. Properties marked as "Get" are those whose values you can retrieve but not set.

Methods

This task inherits the following methods from ENVITask:

Properties

This task inherits the following properties from ENVITask:

COMMUTE_ON_DOWNSAMPLE

COLOR_MATCHING_ACTIONS (optional)

Set this property to an array of strings that indicates how each element of the INPUT_RASTERS array should be treated with regard to color matching: as a reference image, an adjusted image, or no color matching. The number of elements in this array must match the number of input scenes in the INPUT_RASTERS array. Valid strings are as follows; these are not case-sensitive.

By default, the first scene in the INPUT_RASTERS array is set to the reference image. All other images are set to Adjust.

Adjust: Scenes that will be color-matched to the scene marked as Reference.
None: Scenes that will not be color-matched.
Reference: The scene whose statistics form the basis of color matching for all scenes marked as Adjust. You must set one, and only one, scene to Reference.

Suppose that you define an array of input scenes as follows:

scenes = [raster1, raster2, raster3, raster4]

If you want raster2 to be the reference image, set this property as follows:

Task.COLOR_MATCHING_ACTIONS = ['Adjust', 'Reference', 'Adjust', 'Adjust']

COLOR_MATCHING_METHOD (optional)

Set this property to a string that indicates the color matching method to perform.

Histogram Matching: Map discrete grayscale levels from the histogram of the adjusted scenes to the corresponding grayscale levels in the reference scene. This helps to minimize the tonal differences across multiple scenes.
None (default): Do not perform color matching.

COLOR_MATCHING_STATISTICS (optional)

Set this property to one of the following strings indicating what parts of the reference and adjusted images are used to compute statistics for color matching, if COLOR_MATCHING_METHOD is set to Histogram Matching.

Overlapping Area (default): Compute statistics from areas where the reference image overlaps with adjusted images. If there is at least 10% overlap between scenes, histogram matching based on statistics from overlapping areas performs better than statistics from the entire scene. If there are no overlapping regions, then this property will be set to Entire Scene.
Entire Scene: Compute statistics from the entire image.

DATA_IGNORE_VALUE (optional)

Set this property to a pixel value that will be used to fill areas where no valid data appear in the output raster. The following rules apply:

The value must be within the range of the input scenes' data type (e.g., floating-point, byte, integer, etc.)
For scenes that are in ENVI raster format: if all scenes have the same data ignore value defined in their associated headers, that value will be the default output data ignore value.
For mosaics exported to ENVI raster format, the data ignore value is written to the data ignore value field in the associated header file. If you do not set a data ignore value, this field will not be added to the header file.
When the input scenes have a floating-point or double-precision floating-point data type, be sure to specify a double-precision value (for example, 100D).

You can set the data ignore value to an NaN (not a number) value as follows:

Task.DATA_IGNORE_VALUE = !VALUES.F_NAN

FEATHERING_DISTANCE (optional)

Set this property to an array of integers indicating the number of pixels used for edge or seamline feathering for each INPUT_RASTER. The number of elements in this array must match the number of input scenes in the INPUT_RASTER array. Set values to 1 or greater.

FEATHERING_METHOD (optional)

Set this property to one of the following strings that indicates the feathering method to use:

None: (default) No feathering.
Edge: Edge feathering blends the pixels inside of each footprint boundary with underlying scenes that are within the FEATHERING_DISTANCE value that you set.
Seamline: Seamline feathering blends the pixels on both sides of an auto-generated seamline with the underlying scenes.

If you set this property to a value other than None, you must also specify FEATHERING_DISTANCE. If you set this property to Seamline, you must also set the SEAMLINE_METHOD property.

INPUT_RASTERS (required)

Specify an array of rasters to mosaic.

OUTPUT_RASTER

This is a reference to the output raster of filetype ENVI.

If you use the Export method to save a multi-band mosaic to disk, the output mosaic will have a band-interleaved-by-pixel (BIP) interleave format. This ensures optimal performance during the export step.

OUTPUT_RASTER_URI (optional)

Specify a string with the fully qualified filename and path to export the associated OUTPUT_RASTER.

If you set this property to an asterisk symbol (*), the output raster will be virtual and not written to disk.
If you do not specify this property, or set it to an exclamation symbol (!), a temporary file will be created.

RESAMPLING (optional)

Specify the resampling method:

Nearest Neighbor: (default) Uses the nearest pixel without any interpolation to create the image.
Bilinear: Performs a linear interpolation using four pixels to resample the image.
Cubic: Uses 16 pixels to approximate the sinc function using cubic polynomials to resample the image. Cubic convolution resampling is significantly slower than the other methods.

SEAMLINE_METHOD (optional)

Set this property to a string that indicates the method used to automatically generate seamlines:

Geometry: Seamline generation that is based on the use of seamline networks by area Voroni diagrams with overlap (Pan et al., 2009). See Add Seamlines for more information.
None: (default) No seamline generation.

If SEAMLINE_METHOD is set to Geometry, then FEATHERING_METHOD must be set to Seamline.

Reference: Pan, J., M. Wang, D. Li, and J. Li. "Automatic Generation of Seamline Network Using the Area Voronoi Diagram with Overlap." IEEE Transactions on Geoscience and Remote Sensing 47, No. 6 (2009): 1737-174.

Version History

ENVI 5.3	Introduced
ENVI 5.4. 1	Renamed the BACKGROUND property to DATA_IGNORE_VALUE
ENVI 5.5	OUTPUT_RASTER_URI now supports '*', which allows OUTPUT_RASTER to be virtual output.

API Version

4.2