A few months ago I wrote about ENVITask,
the new API for analysis in ENVI 5.1. Anyone who has looked at this API will
notice that it the task objects do not contain parameters for spatial or spectral
subsetting like ENVI_DOIT does with POS and DIMS. Adding these parameters to
every task causes unnecessary internal complication, and isn't needed due to
our "raster is a raster" philosophy. If you only want to run a task
on a subset of the raster, it's up to you to perform the subsetting before
invoking the task. This is accomplished with the ENVIRaster::Subset() method,
which returns a new ENVIRaster object that provides access to only that subset.
As the docs describe, there are three forms of subsetting
that can be performed:
- spatial subsetting using SUB_RECT
- spectral subsetting using BANDS
- pixel masking using ROI
You can use any or all of these keywords together, though if
you specify by SUB_RECT and ROI the spatial subsetting is performed first, then
the ROI masking is done.
Spatial subsetting is performed using the SUB_RECT keyword, which
is expressed in pixel coordinates as an array [ leftCol, topRow, rightCol,
bottomRow ]. These values will be clamped to the raster if you specify
negative values or values too large.
Spectral subsetting is performed using the BANDS keyword,
which is either a scalar band index or an array or band indices. These indices
are 0-based, and can't be repeated, but the order of them is significant and
can be used for band reordering. So setting BANDS=[0,1,2] will give you a
different output raster than BANDS=[2,1,0]. Out of range band indices will
throw an error.
Pixel masking using an ENVIROI is performed using the ROI
keyword, which is set to the ENVIROI object reference. This won't change the
spatial or spectral extents of the raster, but it will mask out any pixels that
aren't inside the ROI. If you're writing your own extensions or processing
scripts, you have to use the PIXELSTATE keyword when you call
ENVIRaster::GetData()
or ENVIRasterIterator::GetData().
As the documentation of these two methods explains, this keyword will be set to
a byte array of the same dimensions as the data, which uses a bitmask to tell
you whether each pixel is valid or not and why not. For most purposes, the
only question is whether the PIXELSTATE value is 0 or not, where 0 means valid
and any non-zero value means invalid.
Here is an example that loads a Quickbird mosaic, chips out
a small spatial subset with only the visible bands and calibrates it to a radiance
image, and then loads the resulting output in a raster layer to compare to the
original raster:
; load the raster
nv = ENVI()
inputFile = Dialog_Pickfile(TITLE='Select a file to calibrate')
oRaster = nv.OpenRaster(inputFile)
; display the raster in view
oView = nv.GetView()
oLayer1 = oView.CreateLayer(oRaster)
; subset the raster for task processing
subRect = [700, 900, 1000, 1300]
bands = [0, 1, 2]
oInput = oRaster.Subset(SUB_RECT=subRect, BANDS=bands)
; load the enviTask
oTask = enviTask('RadiometricCalibration')
; Set parameters
oTask.INPUT_RASTER = oInput
oTask.CALIBRATION_TYPE = 0 ; Radiance
oTask.OUTPUT_DATA_TYPE = 4 ; Float
; run the task
oTask.Execute
; display the results
oLayer2 = oView.CreateLayer(oTask.Output_Raster)
A screen shot of this code shows the results:
