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:

bil

bip

bsq

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 or bil
• [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 [x₁, y₁, x₂, y₂], where:

x₁ = First pixel of the columns dimension

y₁ = First pixel of the rows dimension

x₂ = Last pixel of the columns dimension

y₂ = 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

API Version

4.2

See Also

ENVIRaster, ENVIRaster::SetData, ENVISubsetRaster, ENVI::OpenRaster