Welcome to the Harris Geospatial documentation center. Here you will find reference guides and help documents.


  >  Docs Center  >  ENVI API  >  Processing  >  Data Processing using ENVITask

Data Processing using ENVITask

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 or Run GSF 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 ENVIISODATAClassificationTask 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 ENVIISODATAClassificationTask:

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:

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 ENVIExportRasterToENVITask 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



© 2019 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us