ENVIRaster::GetData
This method returns the raster data (either all of the data or a subset).
Example
; Launch the application and open a file
e = ENVI()
file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $
SUBDIRECTORY = ['data'])
raster = e.OpenRaster(file)
; Get the first band with a subset, refactoring the
; size in the x and y direction
data = raster.GetData(BANDS=[0], SUB_RECT=[100,449,550,899])
; Create a new raster of the subsetted data
newfile = e.GetTemporaryFilename()
new_raster = ENVIRaster(data, URI=newfile)
new_raster.Save
; Display the subset
view=e.GetView()
layer=view.CreateLayer(new_raster)
See More Examples.
Syntax
Result = ENVIRaster.GetData([, Keywords=value])
Return Value
This method returns an array of data values specified by the keywords below. If you do not specify any keywords, this method returns the entire data set at full resolution with the interleave defined by the data source.
Keywords
Keywords are applied only during the initial creation of the object.
BANDS
An array of integer indices that define the spectral subset to be returned. The indices are sequential and zero-based (Band 1 = 0, Band 2 = 1, etc.) By default, all bands will be returned.
If the ENVIRaster contains complex data, the BANDS keyword applies only to complex bands, not including the bands containing the real and imaginary components. For instance, for two complex bands, you would set BANDS=[0,1]
, not BANDS=[0,3]
.
COMPLEX_FUNCTION
If the ENVIRaster contains complex data:
Calling ENVIRaster::GetData with the COMPLEX_FUNCTION keyword returns the raster data after the complex function is applied. The band values will be of type FLOAT or DOUBLE (FLOAT if the data is single-precision complex and DOUBLE if it is double-precision complex). If the raster does not contain complex data, setting this keyword causes an error.
Calling ENVIRaster::GetData without the COMPLEX_FUNCTION keyword returns the raw complex data directly from the file as either COMPLEX (6) or DCOMPLEX (9) data. This data type corresponds to the raster's DATA_TYPE property.
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.
INTERLEAVE
By default, when the INTERLEAVE keyword is not set, the returned raster has the same interleave as the source ENVIRaster.
You can optionally set the INTERLEAVE keyword to a string specifying the desired interleave of the returned data:
String | Interleave | Data Array |
---|---|---|
bil |
Band interleaved by line |
[ncolumns, nbands, nrows] |
bip |
Band interleaved by pixel |
[nbands, ncolumns, nrows] |
bsq |
Band sequential |
[ncolumns, nrows, nbands] |
INTERPOLATION
Set this keyword to 'nearest neighbor'
or 'pixel aggregate'
to indicate the preferred resampling method. The default value is 'nearest neighbor'
. This keyword has no effect if XFACTOR or YFACTOR is not set.
PIXEL_STATE
Set this keyword to a named variable that contains a byte array indicating the state of every pixel returned. The returned values are the sum of the bit values of the accumulated pixel states for every pixel returned.
PIXEL_STATE has three bits of information to determine if you want to use the corresponding pixel value in calculation:
- 1: No Data (Data Ignore Value, NaN, Inf for floating point rasters)
- 2: Mask
- 4: Outside of ROI
The PIXEL_STATE value for a pixel could be any combination of the above bits:
- 0 = Good Pixel
- 1 = No Data
- 2 = Mask
- 3 = No Data + Mask
- 4 = Outside of ROI
- 5 = No Data + Outside of ROI
- 6 = Mask + Outside of ROI
- 7 = No Data + Mask + Outside of ROI
See Raster Pixel State for more details.
If you set the XFACTOR or YFACTOR keywords, no PIXEL_STATE value will be returned.
ROI
Set this keyword to an ENVIROI object to get the data values of the pixels contained in the region of interest (ROI) associated with the input ENVIRaster. If you set this keyword, you cannot set the SUB_RECT, XFACTOR, YFACTOR, or INTERPOLATION keywords because those are meant for rectangular subsets of data.
When you set the ROI keyword, the GetData method returns a 2D array with the following:
- [nPixels, nBands] when INTERLEAVE is
bsq
orbil
- [nBands, nPixels] when INTERLEAVE is
bip
Where nPixels is the number of raster pixels that the ROI contains. This is the same number of pixels you would get from calling the ENVIROI::PixelAddresses method. The pixel addresses will be the same too.
See More Examples below for a code example that uses the ROI keyword.
Note: Big ROIs will return a large amount of data. To avoid returning too much data in a single read, see the second code example in How do I process the pixels within an ROI? for an alternative way to extract ROI data.
SUB_RECT
Set this keyword to a four-element array expressing the spatial range (in pixels) of the data. The array is of the form [x1, y1, x2, y2], where:
x1 = First pixel of the columns dimension
y1 = First pixel of the rows dimension
x2 = Last pixel of the columns dimension
y2 = Last pixel of the rows dimension
Pixel coordinates are zero-based.
If you want to use a subset of the input data for image processing, consider using the ENVISubsetRaster function instead.
XFACTOR
Set this keyword to a floating-point value less than or equal to 1.0, indicating the scale factor in the x direction when retrieving the data.
YFACTOR
Set this keyword to a floating-point value less than or equal to 1.0, indicating the scale factor in the y direction when retrieving the data.
More Examples
The following example prints the mean value for each ROI (for each band) associated with an input raster:
PRO GetROIExample
COMPILE_OPT IDL2
; Start the application
e = ENVI(/HEADLESS)
; Open an input raster
file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $
SUBDIRECTORY = ['data'])
raster = e.OpenRaster(file)
; Open an ROI file
file = FILEPATH('qb_boulder_roi.xml', ROOT_DIR=e.ROOT_DIR, $
SUBDIRECTORY = ['data'])
rois = e.OpenRoi(file)
FOREACH roi, rois DO BEGIN
pixelData = raster.GetData(ROI=roi)
meanValue = Total(pixelData,1) / roi.PixelCount(raster)
Print,'Roi: ' + roi.Name
Print,'Mean = ', meanValue
ENDFOREACH
END
Version History
ENVI 5 |
Introduced |
ENVI 5.1 |
Added PIXEL_STATE keyword |
ENVI 5.5 |
Added ROI keyword |
API Version
4.2
See Also
ENVIRaster, ENVIRaster::SetData, ENVISubsetRaster, ENVI::OpenRaster