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.


This example creates a metaspatial raster from four source rasters. The source files are available on the ENVI Resource DVD (in the APIGriddingExamples folder) or from the ENVI Tutorials web page. Click the "ENVI Tutorial Data" hyperlink. Copy the images to your local drive.

; 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


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.



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


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




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.


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


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


See Also

ENVIRaster, BuildMetaspatialRaster Task, ENVIIrregularGridMetaspatialRaster, BuildIrregularGridMetaspatialRaster Task