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
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:
e = ENVI()
File = Filepath('qb_boulder_msi', Subdir=['data'], $
Root_Dir=e.Root_Dir)
Raster = e.OpenRaster(File)
Task = ENVITask('ISODATAClassification')
Task.INPUT_RASTER = Raster
To process a spatial subset of the original image (rasters only), you should define the subset before running most tasks:
e = ENVI()
File = Filepath('qb_boulder_msi', Subdir=['data'], $
Root_Dir=e.Root_Dir)
Raster = e.OpenRaster(File)
Subset = ENVISubsetRaster(Raster, Sub_Rect=[600,200,799,399])
Task = ENVITask('ISODATAClassification')
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:
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:
e = ENVI()
File = Filepath('qb_boulder_msi', Subdir=['data'], $
Root_Dir=e.Root_Dir)
Raster = e.OpenRaster(File)
Task = ENVITask('ISODATAClassification')
Task.INPUT_RASTER = Raster
Task.ITERATIONS = 6
Task.Execute
Or, define the properties along with the Execute statement if you prefer a more procedural approach:
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:
e = ENVI()
File = Filepath('qb_boulder_msi', Subdir=['data'], $
Root_Dir=e.Root_Dir)
Raster = e.OpenRaster(File)
Task = ENVITask('ISODATAClassification')
Task.INPUT_RASTER = Raster
Task.Execute
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:
e = ENVI()
File = Filepath('qb_boulder_msi', Subdir=['data'], $
Root_Dir=e.Root_Dir)
Raster = e.OpenRaster(File)
Task = ENVITask('DirectionalFilter')
Task.INPUT_RASTER = Raster
Task.KERNEL_SIZE = [3,5]
Task.ANGLE = 25.0
Task.OUTPUT_RASTER_URI = e.GetTemporaryFilename()
Task.Execute
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