ENVISubsetRaster

This function constructs an ENVIRaster from a source raster that has been spatially and/or spectrally subsetted.

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

Example

; Launch the application

e = ENVI()

 

; Open a file

File = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $

SUBDIRECTORY = ['data'])

Raster = e.OpenRaster(file)

 

; Create a spatial subset of 100 samples x 100 lines

; and a spectral subset of Band 1.

Subset = ENVISubsetRaster(Raster, SUB_RECT=[200,200,299,299], BANDS=0)

 

; Display the original and subsetted raster

; as two layers in the same view

View = e.GetView()

Layer1 = view.CreateLayer(raster)

Layer2 = view.CreateLayer(subset)

See More Examples.

Syntax

Result = ENVISubsetRaster(Input_Raster [, Keywords=value])

Return Value

This method returns an ENVIRaster that is a spatial and/or spectral subset of an original raster file.

Arguments

Input_Raster

Specify the input ENVIRaster.

Methods

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

Dehydrate

Hydrate

Keywords

Keywords are applied only during the initial creation of the object.

BANDS (optional)

Set this keyword to an array of band indices, indicating the specific bands (a spectral subset) to process.

Applying a spectral subset before running spectral processing and analysis tools (for example, FLAASH and QUAC atmospheric correction or ACE target detection) can significantly change the processing results since the pixel spectral information changes after subsetting. If the raster has a bad bands list defined, you should exclude those bad bands in subsequent processing and analysis.

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 ENVIGLTRasterSpatialRef, ENVIPseudoRasterSpatialRef, ENVIRPCRasterSpatialRef, or ENVIStandardRasterSpatialRef object, indicating the spatial reference of the spatial subset. You must also set the SUB_RECT keyword. If you set the SPATIALREF keyword, the SUB_RECT array values are treated as geographic coordinates in the specified spatial reference, instead of pixel coordinates.

SUB_RECT (optional)

Set this keyword to a four-element array expressing the spatial range of the raster data. The array is of the form:

[x1, y1, x2, y2]

The following table defines the x and y values of the SUB_RECT array:

Value

Pixel coordinates

Geographic coordinates

x1

First pixel of the columns dimension

Minimum value in the map x-dimension

y1

First pixel of the rows dimension

Minimum value in the map y-dimension

x2

Last pixel of the columns dimension

Maximum value in the map x-dimension

y2

Last pixel of the rows dimension

Maximum value in the map y-dimension

The array values differ, depending on whether or not the SPATIALREF keyword is also set.

If you set the SPATIALREF keyword, the geographic extent of SUB_RECT is determined by transforming all four coordinates from the spatial reference defined by SPATIALREF into the spatial reference of the subset. This is followed by a reprojection into pixel coordinates. The reprojection may result in a rotated rectangle or trapezoid. In this case, the subset will be a rectangle that encompasses the extent of the input subset, as the following figure shows:

More Examples

Suppose that you have an image that is a UTM projection, with coordinates in eastings and northings (in meters). You want to define a spatial subset based on known latitude and longitude coordinates (in degrees). Because the spatial reference of the source image uses map coordinates, then the SUB_RECT value must also use map coordinates. You can use the ConvertLonLatToMap method to convert the geographic coordinates to map coordinates as follows. Be sure to arrange the minimum and maximum x,y values in the correct order.

Raster = e.OpenRaster(File)

 

; This is the area of interest:

UpperLeftLat = 35.1

UpperLeftLon = -112.1

LowerRightLat = 34.7

LowerRightLon = -111.6

 

; Get the spatial reference of the raster

SpatialRef = Raster.SPATIALREF

 

; Convert from Lon/Lat to MapX/MayY

SpatialRef.ConvertLonLatToMap, UpperLeftLon, UpperLeftLat, ULMapX, ULMapY

SpatialRef.ConvertLonLatToMap, LowerRightLon, LowerRightLat, LRMapX, LRMapY

 

; Define the geographic subset

Subset = ENVISubsetRaster(Raster, SPATIALREF=SpatialRef, $

SUB_RECT=[ULMapX, LRMapY, LRMapX, ULMapY])

Version History

ENVI 5.2

Introduced

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

4.2

See Also

ENVIRaster, GeographicSubsetRaster Task, SubsetRaster Task