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
e = ENVI()
File = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $
SUBDIRECTORY = ['data'])
Raster = e.OpenRaster(file)
Subset = ENVISubsetRaster(Raster, SUB_RECT=[200,200,299,299], BANDS=0)
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.
REMOVE_BAD_BANDS (optional)
Set this property to remove any bands marked as 'bad bands' in the metadata.
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 t 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)
UpperLeftLat = 35.1
UpperLeftLon = -112.1
LowerRightLat = 34.7
LowerRightLon = -111.6
SpatialRef = Raster.SPATIALREF
SpatialRef.ConvertLonLatToMap, UpperLeftLon, UpperLeftLat, ULMapX, ULMapY
SpatialRef.ConvertLonLatToMap, LowerRightLon, LowerRightLat, LRMapX, LRMapY
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
|
ENVI 6.1 |
Added REMOVE_BAD_BANDS property |
API Version
4.3
See Also
ENVIRaster, GeographicSubsetRaster Task, SubsetRaster Task