This function constructs an ENVIRaster from an array of source rasters that overlap or contain gaps in coverage. ENVIIrregularGridMetaspatialRaster crops or pads the source rasters to a standard tile size if needed, then it tiles them into one raster.

The most common use for this function is with QuickBird images in DigitalGlobe tiled format (*.til) that overlap in coverage. When you use File > Open to select a .til file in the user interface, ENVI automatically assembles the tiles to construct a virtual raster. However, the ENVIIrregularGridMetaspatialRaster function was designed to give ENVI programmers control over the offsets and tile sizes needed to construct a new raster from individual source rasters.

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


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

Each source raster overlaps the others. The metaspatial raster created in this example will have a fixed tile size of 512 x 512 pixels:

; Start the application
e = ENVI()
offsets = LonArr(2,2,2)
; Select input rasters
file1 = 'qb_boulder_msi1.dat'
raster1 = e.OpenRaster(file1)
offsets[0,0,0] = 0 ;column
offsets[0,0,1] = 0 ;row
file2 = 'qb_boulder_msi2.dat'
raster2 = e.OpenRaster(file2)
offsets[1,0,0] = 464 ;column
offsets[1,0,1] = 0 ;row
file3 = 'qb_boulder_msi3.dat'
raster3 = e.OpenRaster(file3)
offsets[0,1,0] = 10 ;column
offsets[0,1,1] = 399 ;row
file4 = 'qb_boulder_msi4.dat'
raster4 = e.OpenRaster(file4)
offsets[1,1,0] = 425 ;column
offsets[1,1,1] = 453 ;row
; Specify input arguments
inputRasters = [[raster1, raster2], [raster3, raster4]]
tileSize = [512,512]
; create the metaspatial raster
msRaster = ENVIIrregularGridMetaspatialRaster(inputRasters, $
  tileSize, offsets)
; Display the result
view = e.GetView()
layer = view.CreateLayer(msRaster)
view.Zoom, /FULL_EXTENT


Result = ENVIIrregularGridMetaspatialRaster(Input_Rasters, Tile_Size, Offsets [, 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:

  • Specify empty tiles with null objects by calling the IDL Obj_New routine instead of using ENVIRasters.
  • 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]]


Specify a 2D array indicating the desired size of each tile, in number of pixels. Use this convention: [xSize, ySize]. Each source raster will be cropped or padded with "no data" values to fit the tile size.


Offsets are zero-based pixel coordinates that represent the top-left corner of each raster with respect to the top-left corner of the metaspatial raster. Specify an m x n x 2 array of offsets corresponding to the m x n array of source rasters, along with a column and row offset for each array.

For example, the layout of source rasters in the code example above is specified with a 2 x 2 array:

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

Offsets is a 2 x 2 x 2 array in this case. To further illustrate this example, the offsets for the upper-right image (raster2) are as follows:

offsets[1,0,0] = 464
offsets[1,0,1] = 0


  • [1,0,0] is the array index for the column, and 464 is its offset value
  • [1,0,1] is the array index for the row, and 0 is its offset value.

This means that pixel location (464,0) in raster2 will be the upper-right corner of the associated tile in the virtual raster.


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, ENVIMetaspatialRaster, BuildMetaspatialRaster Task, BuildIrregularGridMetaspatialRaster Task