BuildMetaspatialRaster Task

This task constructs an ENVIRaster from an array of non-overlapping and non-gapping source rasters that have the same spatial dimensions. The individual rasters are tiled into one virtual raster.

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

The virtual raster associated with this task is ENVIMetaspatialRaster.

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. Update the file references in the example with the correct locations.

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

; Get the task from the catalog of ENVITasks

Task = ENVITask('BuildMetaspatialRaster')

; Define inputs

Task.INPUT_RASTERS = SourceRasters

; 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)

View1.Zoom, /FULL_EXTENT

Syntax

Result = ENVITask('BuildMetaspatialRaster')

Input parameters (Set, Get): DATA_IGNORE_VALUE, INPUT_RASTERS, OUTPUT_RASTER_URI, SPATIAL_REFERENCE

Output parameters (Get only): OUTPUT_RASTER

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

Input Parameters

DATA_IGNORE_VALUE (optional)

Specify a unique data value for pixels in the output raster that have a non-zero pixel state value. Pixels from empty tiles will have a non-zero pixel state value.

INPUT_RASTERS (required)

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

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

OUTPUT_RASTER_URI (optional)

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

If you set this parameter to an asterisk symbol (*), the output raster will be virtual and not written to disk.
If you do not specify this parameter, or set it to an exclamation symbol (!), a temporary file will be created.
If you set it to the hash symbol (#), ENVI creates a file in the temporary directory, but this file will not be deleted when ENVI closes.

SPATIAL_REFERENCE (optional)

Set this parameter to an ENVIStandardRasterSpatialRef, ENVIPseudoRasterSpatialRef, or ENVIRPCRasterSpatialRef object to be used by OUTPUT_RASTER. If this is not specified, then the SPATIALREF parameter of the first raster in the INPUT_RASTERS array will be used, if possible. If that raster is a NullObject, or if it does not have a SPATIALREF value, then OUTPUT_RASTER will not have any spatial reference associated with it.