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.

Bands are zero-based, so 0=Band 1, 1=Band 2, etc.
If you do not specify this keyword, all available bands will be used for processing.
The valid range of values is 0 to numBands-1.
Band indices cannot be repeated (for example, [0,0,1]).

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:

[x₁, y₁, x₂, y₂]

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

Value	Pixel coordinates	Geographic coordinates
x₁	First pixel of the columns dimension	Minimum value in the map x-dimension
y₁	First pixel of the rows dimension	Minimum value in the map y-dimension
x₂	Last pixel of the columns dimension	Maximum value in the map x-dimension
y₂	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 do not set the SPATIALREF keyword, then x and y refer to pixel coordinates. These are zero-based and must be integers.
If you set the SPATIALREF keyword, then x and y refer to map or geographic coordinates.
- They can be floating-point or integer values.
- They can be represented as map coordinates (x=eastings, y=northings) or geographic coordinates (x=longitude, y=latitude), depending on the spatial reference object used. The x,y coordinates must be in the same units (degrees, meters, feet, etc.) as the spatial reference object. See More Examples below.

If you do not specify this keyword, the entire raster will be used for processing.

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