ENVIMetaspatialRaster

This function constructs an ENVIRaster from an array of non-overlapping and non-gapping source rasters that have the same spatial dimensions. ENVIMetaspatialRaster tiles the individual rasters into one raster.

If source rasters need to be cropped or padded to fit into a standard tile size, use the ENVIIrregularGridMetaspatialRaster routine instead.

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

Example

This example creates a metaspatial raster from four source rasters. The source files are available from our ENVI Tutorials web page. Click the API Gridding Examples link to download the .zip file to your machine, then unzip the files.

; Start the application

e = ENVI()

; Select input files.

ULFile = 'qb_boulder_msi_UpperLeft.dat'

ULRaster = e.OpenRaster(ULFile)

URFile = 'qb_boulder_msi_UpperRight.dat'

URRaster = e.OpenRaster(URFile)

LLFile = 'qb_boulder_msi_LowerLeft.dat'

LLRaster = e.OpenRaster(LLFile)

LRFile = 'qb_boulder_msi_LowerRight.dat'

LRRaster = e.OpenRaster(LRFile)

SourceRasters = [[ULRaster, URRaster], [LLRaster, LRRaster]]

; Create a metaspatial raster

MSRaster = ENVIMetaspatialRaster(SourceRasters)

; Display the result

view = e.GetView()

layer = view.CreateLayer(MSRaster)

view.Zoom, /FULL_EXTENT

Syntax

Result = ENVIMetaspatialRaster(Input_Rasters [, Keywords=value])

Return Value

This routine returns a reference to an ENVIRaster. The returned raster will be cast to the highest data type among all the source rasters.

Arguments

Input_Rasters

Specify a 2D array of input ENVIRasters. The following rules apply:

Source rasters must have the same number of bands and the same spatial dimensions. One exception is that the outside edges can be shorter than the rest as long as all rasters in the entire row or column are equal in size.
Specify empty tiles with null objects by calling the IDL Obj_New routine instead of using ENVIRasters.
Padded and empty tiles will have PIXEL_STATE set to 2 (No Data). The pixel data will be invalid in these areas. If you need to export the raster to disk, provide a data ignore value.
Metadata values are passed from the source rasters to the virtual raster only if the values are the same in all source rasters.
Source rasters do not need to be georeferenced. If the top-left tile contains a spatial reference, that reference will be used for the virtual raster. You can override the spatial reference by using the SPATIALREF keyword.
The order of the array elements determines the layout of the tiles in the metaspatial raster. Here are some examples:

SourceRasters = [raster1, raster2, raster3, raster4]

SourceRasters = [[raster1, raster2], [raster3, raster4]]

[[raster1], [raster2], [raster3], [raster4]]

Methods

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

Dehydrate

Hydrate

Keywords

ERROR (optional)

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.

SPATIALREF (optional)

Set this keyword to an ENVIStandardRasterSpatialRef, ENVIPseudoRasterSpatialRef, or ENVIRPCRasterSpatialRef object to be used by the output raster mosaic. If this keyword is not specified, then the SPATIALREF property of the upper left corner raster will be used, if possible. If the upper left corner raster is a NullObject, or if it does not have a SPATIALREF value, then the output raster will not have any spatial reference associated with it.

Version History

ENVI 5.2.1	Introduced
ENVI 5.3.1	Documented the dehydrated form of this virtual raster
ENVI 5.4	Added Dehydrate and Hydrate methods; added NAME keyword

API Version

4.2