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.

; 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 properties (Set, Get): DATA_IGNORE_VALUE, INPUT_RASTERS, OUTPUT_RASTER_URI, SPATIAL_REFERENCE

Output properties (Get only): OUTPUT_RASTER

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

Methods

This task inherits the following methods from ENVITask:

Properties

This task inherits the following properties from ENVITask:

COMMUTE_ON_DOWNSAMPLE

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

This is a reference to the output raster of filetype ENVI.

OUTPUT_RASTER_URI (optional)

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

If you set this property to an asterisk symbol (*), the output raster will be virtual and not written to disk.
If you do not specify this property, or set it to an exclamation symbol (!), a temporary file will be created.

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

Version History

ENVI 5.2. 1

Introduced

ENVI 5.5

OUTPUT_RASTER_URI now supports '*', which allows OUTPUT_RASTER to be virtual output.

INPUT_RASTERS allows NullObject values in array of ENVIRasters.

Add DATA_IGNORE_VALUE, so that exported raster will have correct pixel state.

API Version

4.2