This method has been deprecated. Use ENVISubsetRaster for spatial and spectral subsetting. Use ENVIROIMaskRaster for applying ROI information to a raster.

The Subset function method returns an ENVIRaster object that is a spatial and/or spectral subset of the original raster.

Syntax

Result = ENVIRaster.Subset([, Keywords=value])

Return Value

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

Arguments

None

Keywords

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

BANDS

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]).

ERROR

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.

ROI

Set this keyword to an ENVIROI object. When this keyword is set, the returned ENVIRaster will contain information on which pixels are inside or outside of the ENVIROI object. To get this information, use the PIXEL_STATE keyword with ENVIRaster::GetData or ENVIRasterIterator::GetData.

SPATIALREF

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

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 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, MapX, MapY
SpatialRef.ConvertLonLatToMap, LowerRightLon, LowerRightLat, MapX2, MapY2
 
; Define the geographic subset
Subset = Raster.Subset(SPATIALREF=SpatialRef, $
  SUB_RECT=[MapX, MapY2, MapX2, MapY])

Version History

ENVI 5.1

Introduced
ENVI 5.2 Deprecated

See Also

ENVIRaster, ENVIRaster::GetData, ENVIRaster::Save, ENVIRaster::Export, ENVIROI