ENVIMetaspectralRaster

This function constructs an ENVIRaster from a stack of source rasters with the same spatial dimensions. Metaspectral rasters often combine bands from different rasters into a single file.

The input rasters must have the same number of rows and columns.
The input rasters can have different pixel sizes.
The input rasters do not need to be georeferenced, but you can georeference the resulting metaspectral raster using the SPATIALREF keyword.
The input rasters can be of different interleave types, but the resulting metaspectral raster will be BSQ.
The input rasters can be of different data types, but the resulting metaspectral raster will be cast to the highest data type out of all the rasters. Complex and non-complex data cannot be mixed.
Use ENVILayerStackRaster to create a georeferenced layer stack. A layer stack is similar to a metaspectral raster except that the source rasters are regridded to a common spatial grid.
See Working with Metaspectral Datasets in the ENVI API for guidelines on using Landsat and ASTER imagery.

This task is different than ENVILayerStackRaster, where the input rasters can have different numbers of rows and columns and they will be reprojected and regridded to a common spatial grid.

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

Example

This example creates a raster that includes seven multispectral bands from the Landsat-8 OLI sensor and two thermal bands from its TIRS sensor. Update the file location with your own directory and data file. After running this example, open the Data Manager to see the full band list.

; Start the application

e = ENVI()

; Select a Landsat-8 metadata file

File = 'LC80410302013229LGN00_MTL.txt'

Raster = e.OpenRaster(File)

; Landsat-8 data are stored in a 5-element

; array. Multispectral bands are stored in the

; first array element. Thermal bands are stored

; in the fourth array element.

OLIBands = Raster[0]

TIRBands = Raster[3]

; Create a metaspectral raster

MSRaster = ENVIMetaspectralRaster([OLIBands,TIRBands])

; Get the collection of data objects currently available in the Data Manager

DataColl = e.Data

; Add the output to the Data Manager

DataColl.Add, MSRaster

; Display the band-stacked raster

View = e.GetView()

Layer = View.CreateLayer(MSRaster)

View.Zoom, /FULL_EXTENT

See More Examples for other common uses for metaspectral rasters.

Syntax

Result = ENVIMetaspectralRaster(Input_Rasters [, Keywords=value])

Return Value

This routine returns a reference to an ENVIRaster.

Arguments

Input_Rasters

Specify an array of input ENVIRasters.

Methods

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

Dehydrate

Hydrate

Keywords

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.

NAME

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. If this keyword is not specified, then the first valid SPATIALREF property found in the Input_Rasters array will be used.

More Examples

Combine bands from different rasters

This example creates one raster that consists of Band 2 from a 1985 Landsat TM image and Band 2 from a 2005 TM image. The result is called a band stack. Both source images have the same number of rows and columns; they are also in the same coordinate system and have the same pixel size (30 m).

The example uses sample images that are available from our ENVI Tutorials web page. Click the Landsat Case Studies link to download the .zip file to your machine, then unzip the files. Update the file location with your own directory.

; Start the application

e = ENVI()

; Select a Landsat TM scene from 1985

File1 = 'LasVegasTM5May1985.dat'

Raster1 = e.OpenRaster(File1)

; Select a Landsat TM scene from 2005

File2 = 'LasVegasTM5May2005.dat'

Raster2 = e.OpenRaster(File2)

; Get the red band (2) from the 1985 scene.

; Bands are zero-based.

RedRaster1 = ENVISubsetRaster(Raster1, BANDS=1)

; Get the red band (2) from the 2005 scene.

RedRaster2 = ENVISubsetRaster(Raster2, BANDS=1)

; Get the spatial reference of the 1985 scene.

SpatialRef=RedRaster1.SPATIALREF

; Create a raster that includes both bands

BandStack = ENVIMetaspectralRaster([RedRaster1, RedRaster2], $

  SPATIALREF=SpatialRef)

; Display the two bands in different views

View = e.GetView()

Layer1 = View.CreateLayer(BandStack, BANDS=[0])

Layer1.QUICK_STRETCH='linear 2%'

View2 = e.CreateView()

Layer2 = View2.CreateLayer(BandStack, BANDS=[1])

Layer2.QUICK_STRETCH='linear 2%'

View.Zoom, /FULL_EXTENT

View2.Zoom, /FULL_EXTENT

Version History

ENVI 5.2	Introduced
ENVI 5.3.1	Documented the dehydrated form of this virtual raster
ENVI 5.3.2	Removed layer stacking code example; use ENVILayerStackRaster now for layer stacking.
ENVI 5.4	Added Dehydrate and Hydrate methods; added NAME keyword

API Version

4.2