Data Processing using ENVITasks

ENVI provides many data-processing routines that are ready to use in your ENVI API script. See the ENVITask topic for a list of available routines. You can also run ENVITasks interactively using the Run Task tool.

This topic describes the use of ENVITasks in the ENVI API. See the following sections for details on the different steps involved in running a data-processing task:

• Discover what tasks are available
• Define input properties
• Validate the task
• Run the task
• Create output

Discover What Tasks are Available

See the ENVITask help topic for a list of available data-processing tasks including classification, radiometric calibration, RPC orthorectification, and image transforms. More tasks are continually added over time. To print a list of task names, type the following at the IDL command line:

IDL> e = ENVI()

ENVI> e.Task_Names

Use a string from the resulting list to create an instance of a task, for example:

ENVI> Task = ENVITask('ISODATAClassification')

Print the task variable to learn what that task does:

ENVI> Task

IDL prints a description of the task, along with definitions of each property.

ENVIISODATACLASSIFICATIONTASK <600185>

NAME = 'ISODATAClassification'

DISPLAY_NAME = 'ISODATA Classification'

DESCRIPTION = 'This task clusters pixels in a dataset based on statistics only, without requiring you to define training classes.'

COMMUTE_ON_DOWNSAMPLE = 'Unknown'

COMMUTE_ON_SUBSET = 'Unknown'

ROUTINE = 'ISODATA'

 

CHANGE_THRESHOLD_PERCENT

  DESCRIPTION = 'The change threshold percentage that determines when to complete the classification. When the percentage of pixels that change classes during an iteration is less than the threshold value, the classification completes.'

  VALUE = 2.0000000

  DIRECTION = 'INPUT'

Define Input Properties

Properties (also called parameters) tell the task what to do with the input data. The best way to learn the properties for a task is to consult its ENVI Help topic. An example is the ISODATAClassification Task topic.

Printing a task is another quick way to list all of the properties that are defined for that task. An example is the NUMBER_OF_CLASSES property to the ISODATAClassification task:

NUMBER_OF_CLASSES

DESCRIPTION = 'The requested number of classes to generate.'

VALUE = 5

DIRECTION = 'INPUT'

VALUE = 5

CHOICE_LIST = !NULL

REQUIRED = 0

NAME = 'NUMBER_OF_CLASSES'

DEFAULT = 5

VALUE = 5

• The DESCRIPTION field defines the property.
• The VALUE field lists the currently defined value. This is the only part of a property that you can edit (or set).
• The DIRECTION field indicates if the property is used for input or output.
• The CHOICE_LIST field lists the valid options to choose from, if the property has a limited number of choices.
• The REQUIRED field is 1 if the property is required to run the task, or 0 if it is optional.
• The NAME field is the valid string to use when referring to the property in subsequent steps.
• The DEFAULT field lists the default value if the property is optional. This value will be used unless you set a different value.

To list the properties of a task without all of the details, type the following at the ENVI command line:

ENVI> Task.ParameterNames()

You can create a variable for an individual property once you know its name:

ENVI> Parameter = Task.Parameter('Iterations')

The next section discusses input properties in more detail.

Input Data

Most tasks have an INPUT_RASTER or INPUT_VECTOR property, depending on whether the task is designed for image or vector processing. These properties are required for the task to run. You need to pass the ENVIRaster or ENVIVector object to the task:

; Start the application

e = ENVI()

 

; Open an input file

File = Filepath('qb_boulder_msi', Subdir=['data'], $
  Root_Dir=e.Root_Dir)

Raster = e.OpenRaster(File)

 

; Get the task from the catalog of ENVITasks

Task = ENVITask('ISODATAClassification')

 

; Define inputs

Task.INPUT_RASTER = Raster

To process a spatial subset of the original image (rasters only), you should define the subset before running most tasks:

; Start the application

e = ENVI()

 

; Open an input file

File = Filepath('qb_boulder_msi', Subdir=['data'], $
  Root_Dir=e.Root_Dir)

Raster = e.OpenRaster(File)

 

; Process a spatial subset

Subset = ENVISubsetRaster(Raster, Sub_Rect=[600,200,799,399])

 

; Get the task from the catalog of ENVITasks

Task = ENVITask('ISODATAClassification')

 

; Define inputs

Task.INPUT_RASTER = Subset

Exceptions include tasks for supervised classification. In these cases, you may have training regions throughout the entire input image that you want to include in training statistics used for classification:

• MahalanobisClassification
• MaximumLikelihoodClassification
• MinimumDistanceClassification
• SpectralAngleMapperClassification

Processing

Most data-processing tasks have additional properties that are unique to that task. ISODATA classification, for example, needs to know the number of output classes that you want to define.

If a property is marked as "optional," you do not have to explicitly define it if you want to use the default value. Here is an example of querying the current value of the ITERATIONS property:

ENVI> Task.ITERATIONS

IDL prints:

10

If you want to use the default value of 10, you do not need to set the ITERATIONS property. To change the value, define it as follows

Task.ITERATIONS = 15

The next section describes how to ensure that values you defined for the input properties are valid.

Validate Tasks

Once you set a property on a task, ENVI immediately checks the property to ensure it is valid. Here is an example of defining an incorrect input raster for a task at the ENVI command line:

ENVI> Task.INPUT_RASTER = WrongRaster

% Variable is undefined: <No name>.

% Execution halted at: $MAIN$

If the property is within a script (versus executing it at the command line), ENVI will issue the error message when you run the script. The task will not run.

Run Tasks

Use the Execute method to run the task. You can define the required properties before executing the task:

; Start the application

e = ENVI()

 

; Open an input file

File = Filepath('qb_boulder_msi', Subdir=['data'], $
  Root_Dir=e.Root_Dir)

Raster = e.OpenRaster(File)

 

; Get the task from the catalog of ENVITasks

Task = ENVITask('ISODATAClassification')

 

; Define inputs

Task.INPUT_RASTER = Raster

Task.ITERATIONS = 6

 

; Run the task

Task.Execute

Or, define the properties along with the Execute statement if you prefer a more procedural approach:

; Run the task

Task.Execute, INPUT_RASTER=Raster, ITERATIONS=6

Create Output

Option 1

To write the output of a task to disk, set the OUTPUT_RASTER_URI property to a string with the full path and filename:

Task.OUTPUT_RASTER_URI = 'C:\MyData\OutputRaster.dat'

If you only want the output for the current ENVI session, ENVITask will automatically create a temporary filename if you do not set the OUTPUT_RASTER_URI property. The temporary file is deleted once you close the ENVI session.

After running a task, you can retrieve the output for later use in that session using the OUTPUT_RASTER property:

; Start the application

e = ENVI()

 

; Open an input file

File = Filepath('qb_boulder_msi', Subdir=['data'], $
  Root_Dir=e.Root_Dir)

Raster = e.OpenRaster(File)

 

; Get the task from the catalog of ENVITasks

Task = ENVITask('ISODATAClassification')

 

; Define inputs

Task.INPUT_RASTER = Raster

 

; Run the task

Task.Execute

 

; Get the output raster

Task.OUTPUT_RASTER

Option 2

You can also use the ExportRasterToENVI task to save the output of a task to an ENVI-format raster on disk. The following example applies a directional filter to an input raster, then saves the result to an ENVI-format file:

; Start the application

e = ENVI()

 

; Open an input file

File = Filepath('qb_boulder_msi', Subdir=['data'], $

  Root_Dir=e.Root_Dir)

Raster = e.OpenRaster(File)

 

; Get the task from the catalog of ENVITasks

Task = ENVITask('DirectionalFilter')

 

; Define inputs

Task.INPUT_RASTER = Raster

Task.KERNEL_SIZE = [3,5]

Task.ANGLE = 25.0

 

; Define output location

Task.OUTPUT_RASTER_URI = e.GetTemporaryFilename()

 

; Run the task

Task.Execute

 

; Save the result to an ENVI-format file

exportTask = ENVITask('ExportRasterToENVI')

exportTask.INPUT_RASTER = Task.OUTPUT_RASTER

exportTask.OUTPUT_URI = e.GetTemporaryFilename()

exportTask.Execute

Display Options

To display output immediately after running a task, create a view and layer as follows:

View = e.GetView()

Layer = View.CreateLayer(Task.OUTPUT_RASTER)

See the ENVIView help topic for methods you can use to zoom, rotate, pan, and perform other view operations on the data.

Adding the output to the Data Manager allows the data object to persist throughout the ENVI session. If you have a script that runs an interactive session of ENVI (but does not close it), the object will be available for use even after the script ends. If you close ENVI, the Data Manager closes the relevant files and cleans up object references. Use the following code to add the output to the Data Manager:

e.Data.Add, Task.OUTPUT_RASTER