BuildIrregularGridMetaspatialRaster Task

This task constructs an ENVIRaster from an array of source rasters that overlap or contain gaps in coverage. The individual rasters are tiled into one virtual 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 BuildIrregularGridMetaspatialRaster task was designed to give ENVI programmers control over the offsets and tile sizes needed to construct a virtual raster from individual source rasters.

The virtual raster associated with this task is ENVIIrregularGridMetaspatialRaster.

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.

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

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

tileSize = [512,512]

; Get the task from the catalog of ENVITasks

Task = ENVITask('BuildIrregularGridMetaspatialRaster')

; Define inputs

Task.INPUT_RASTERS = sourceRasters

Task.OFFSETS = offsets

Task.TILE_SIZE = tileSize

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

View.Zoom, /FULL_EXTENT

Syntax

Result = ENVITask('BuildIrregularGridMetaspatialRaster')

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 that may contain overlaps and gaps. Each tile of the output raster will be cropped or padded to fit the tile size. The following rules apply:

Source rasters must have the same number of bands.
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]]

OFFSETS (required)

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

Where:

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

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.

TILE_SIZE (required)

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.

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