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: