ENVIMosaicRaster

This is a reference to a mosaic raster, which covers the spatial extent of multiple rasters (also called scenes).

The result is a virtual raster, which has some additional considerations with regard to methods and properties. See Virtual Rasters for more information, including how they differ from ENVITasks.

The equivalent task is BuildMosaicRaster.

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 are available from our ENVI Tutorials web page. Click the Mosaic link to download the .zip file to your machine, 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)

; Create a mosaic

mosaicRaster = ENVIMosaicRaster([Raster1, Raster2], $

  COLOR_MATCHING_ACTIONS = ['Reference', 'Adjust'], $

  COLOR_MATCHING_METHOD = 'Histogram Matching', $

  COLOR_MATCHING_STATS = 'Entire Scene', $

  FEATHERING_METHOD = 'Edge', $

  FEATHERING_DISTANCE = 15, $

  DATA_IGNORE_VALUE = 0)

; Display the result

View = e.GetView()

Layer = View.CreateLayer(mosaicRaster)

View.Zoom, /FULL_EXTENT

Syntax

Result = ENVIMosaicRaster(Scenes [, Properties=value] [, Keywords=value])

Return Value

This function returns a reference to an ENVIMosaicRaster.

Arguments

Scenes

An array of ENVIRasters that comprise the mosaic raster. This argument can be configured after creation with the SCENES property.

Each scene must have the same number of bands and the same data type.
The Seamless Mosaic tool accepts complex data as input. If a complex function exists, ENVI converts the data to a single-precision (floating-point) or double-precision data type before mosaicking the data. If a complex function does not exist, ENVI uses the Power function to convert complex data for mosaicking.
If floating-point or double-precision floating-point images have pixel values of NaN (not a number) or Inf (infinity), those pixels are ignored when computing footprints and statistics for color correction.

Methods

This virtual raster inherits methods and properties from ENVIRaster; however the following methods will override the ENVIRaster methods:

Dehydrate

Hydrate

ENVIMosaicRaster inherits the following methods from ENVIRaster:

CreatePyramid (not used with ENVIMosaicRaster)

CreateTileIterator

Export

GetData

Save (not used with ENVIMosaicRaster)

SetData

SetTile

WriteMetadata

The following method is unique to ENVIMosaicRaster:

SaveSeamPolygons

Here are some items to note about methods:

Since a mosaic raster is a read-only object, you cannot write to ENVIMosaicRaster using the SetData and SetTile methods.
ENVIDataCollection will not return an ENVIMosaicRaster until you export the mosaic.

Properties

A mosaic raster is a raster object, so it inherits all properties from ENVIRaster. For ENVIMosaicRaster, the PYRAMID_EXISTS property always returns 0 (FALSE) and the READ_ONLY property always returns 1 (TRUE) since a mosaic raster is a read-only object.

The following properties are unique to ENVIMosaicRaster:

COLOR_MATCHING_METHOD (Get, Set)

Set this property to a string that indicates the color matching method to perform. Strings are not case-sensitive.

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

If you set this property to a value other than 'none', you must also set the COLOR_MATCHING_ACTIONS keyword.

COLOR_MATCHING_ACTIONS (Get, Set)

Set COLOR_MATCHING_ACTIONS to an array of strings that indicates how each element of the Scenes 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 Scenes array. Valid strings are as follows; these are not case-sensitive.

By default, the first scene in the Scenes array is set to the reference image.

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:

mosaicRaster = ENVIMosaicRaster([raster1, raster2, raster3, raster4])

By default, raster1 is the reference image and the COLOR_MATCHING_ACTIONS array will be set to the following:

COLOR_MATCHING_ACTIONS = ['reference', 'adjust', 'adjust', 'adjust']

To change the logic so that raster4 has no color correction and raster3 is the reference image, set COLOR_MATCHING_ACTIONS as follows:

mosaicRaster = ENVIMosaicRaster([raster1, raster2, raster3, raster4], $

   RESAMPLING = 'Bilinear', $

  COLOR_MATCHING_ACTIONS = ['adjust', 'adjust', 'reference', 'none'], $

   COLOR_MATCHING_METHOD = 'histogram matching', $

   COLOR_MATCHING_STATS = 'overlapping area')

Or, set it once the property has been initialized:

mosaicRaster = ENVIMosaicRaster([raster1, raster2, raster3, raster4], $

   RESAMPLING = 'Bilinear', $

   COLOR_MATCHING_METHOD = 'histogram matching', $

   COLOR_MATCHING_STATS = 'overlapping area')

mosaicRaster.COLOR_MATCHING_ACTIONS = ['adjust', 'adjust', 'reference', 'none']

The number of elements in the COLOR_MATCHING_ACTIONS array will automatically adjust to match the number of elements in the Scenes argument if you delete or re-order any scenes. If you do this, you should query the COLOR_MATCHING_ACTIONS property as follows:

PRINT, mosaicRaster.COLOR_MATCHING_ACTIONS

Then further modify the property's contents if needed.

COLOR_MATCHING_STATS (Get, Set)

If you set the COLOR_MATCHING_METHOD property to a value other than 'none', then set COLOR_MATCHING_STATS to a string that indicates what parts of the reference and adjusted images are used to compute statistics for color matching. Strings are not case sensitive.

entire scene: Compute statistics from the entire image.
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'.

DATA_IGNORE_VALUE (Get, Set)

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:

mosaicRaster = ENVIMosaicRaster([raster1, raster2], $

DATA_IGNORE_VALUE=!VALUES.F_NAN)

FEATHERING_DISTANCE (Get, Set)

Set this property to the number of pixels used for edge or seamline feathering. See Set the Feathering Distance in the Seamless Mosaic help topic for illustrations.

If you set FEATHERING_METHOD to 'edge', the feathering distance is the number of pixels that the top-most scene will be blended along its edge with underlying scenes.
If you set FEATHERING_METHOD to 'seamline' and SEAMLINE_METHOD to 'geometry', the feathering distance is the total number of pixels that will be blended across a seamline. For example, if FEATHERING_DISTANCE=10, each side of the auto-generated seamline will be blended by five pixels with underlying scenes.
The default value is !NULL, which means no feathering will be applied.
Set this keyword to an integer value of 1 or greater, while setting the FEATHERING_METHOD keyword to 'edge' or 'seamline'.
The number of pixels you specify is for the output mosaic, not the input scenes.
You can specify a single value, which will apply to all scenes. Or, specify an array of values for each scene as defined in the Scenes argument. The number of elements must match that of the Scenes argument.

FEATHERING_METHOD (Get, Set)

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

edge: Edge feathering blends the pixels inside of each footprint boundary with underlying scenes that are within the FEATHERING_DISTANCE value that you set. If you generated any seamlines by setting SEAMLINE_METHOD to 'geometry', the 'edge' setting is ignored.
none: (default) No feathering.
seamline: Seamline feathering blends the pixels on both sides of an auto-generated seamline (when the SEAMLINE_METHOD property is set to 'geometry') with the underlying scenes.

RESAMPLING (Get, Set)

Set this property to one of the following strings to indicate the resampling method used when creating the output mosaic:

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.

SCENES (Init)

Set this property to an array of ENVIRasters that comprise the mosaic raster. Each file must have the same number of bands and the same data type. You must define at least one raster with the SCENES property to create the mosaic. Input files can be georeferenced to different coordinate systems; the first scene in the SCENES array defines the output projection for the mosaic raster.

SEAM_POLYGONS (Get, Set)

Set this property to an ENVIVector object containing seam polygons that you want to restore. The seam polygons must be exported from either of the following:

Clicking the Save Seam Polygons button in the Seamless Mosaic tool
Invoking the SaveSeamPolygon method to ENVIMosaicRaster.

Before restoring seam polygons, ensure that the same scenes used to create the polygons are defined with the Scenes argument. They do not necessarily have to be in the same order as they were when the seam polygons were exported.

First, open the vector file of the seam polygons. For example:

vector = e.OpenVector('C:\Data\MySeamPolygons.shp')

Then restore the seam polygons in the ENVIMosaicRaster call. For example:

mosaicRaster = ENVIMosaicRaster([raster1, raster2], SEAM_POLYGONS=vector)

If you set this property, then the SEAMLINE_METHOD property will be ignored.

SEAMLINE_METHOD (Get, Set)

Set this property to one of the following strings to indicate the method used to automatically generate seamlines:

geometry: An automated seamline generation method that is based on the use of seamline networks formed by area Voronoi diagrams with overlap (Pan et al., 2009). The Voronoi edge lies in the overlapping part between adjacent areas. Auto seamline generation creates effective mosaic polygons that define the pixels of each input image used for the final mosaic. See Add Seamlines for more information.
None: (default) No seamline generation.

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.

Keywords

Keywords are applied only during the initial creation of the object.

ERROR

Set this keyword to a named variable that will contain any error message issued during execution of this routine. If no error occurs, the ERROR variable will be set to a null string (''). If an error occurs and the routine is a function, then the function result will be undefined.

When this keyword is not set and an error occurs, ENVI returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine. See IDL Help for more information on !ERROR_STATE and CATCH.

See Manage Errors for more information on error handling in ENVI programming.

NAME

Specify a string that identifies the raster.

Version History

ENVI 5.1	Introduced
ENVI 5.3.1	Added Dehydrate method
ENVI 5.4	Added Hydrate method; added NAME keyword
ENVI 5.4.1	Renamed the BACKGROUND keyword to DATA_IGNORE_VALUE

API Version

4.2