ENVITask

The ENVITask function accepts a task name and returns an object reference to the task.

To write a custom task, see Custom Tasks and ENVITaskFromProcedure.

ENVITasks can run asynchronously. See ENVIAsyncSpawnTaskJob.

Example

Example code is available in each of the ENVITask topics.

Syntax

Result = ENVITask(GSF_URL [, ERROR=variable])

Or:

Result = ENVITask('TaskURI' [, ERROR=variable])

Or:

Result = ENVITask('TaskName' [, ERROR=variable])

Return Value

The ENVITask function returns a reference to an ENVITask object. Use the returned reference to set parameters and execute the task by changing properties or calling methods.

Arguments

GSF_URL

Specify a URL to a Geospatial Services Framework (GSF) endpoint, for example:

http://server:port/ese/services/ENVI/ENVIApplyGainOffsetTask

TaskURI

Specify a string with the full path and filename to a .task file on disk. This option is useful if you are developing and testing a custom task but have not yet deployed it to the appropriate location yet.

TaskName

Specify a string with the name of the task to perform. To see the full list of available tasks in ENVI, type the following at the command line after starting ENVI:

taskNames = e.TASK_NAMES

print, taskNames

Methods

Properties

Properties marked as (Init) can be set during the initial creation of the object. Properties marked as (Get) can be retrieved. Properties marked as (Set) can be set after initial creation.

ABORTED (Get)

A boolean that returns true if the task was aborted. Not all tasks support aborting; in these cases the property always returns false.

COMMUTE_ON_DOWNSAMPLE (Get, Init)

A string that defines whether the result of running the ENVITask first, then down-sampling the output raster, matches the result of down-sampling the input raster(s) first before running the ENVITask.

An ENVITask developer can use the scripts provided in More Examples below to determine the COMMUTE_ON_DOWNSAMPLE property value when creating an ENVITask.

Valid values are:

Yes: Downsample the input raster(s) first, and then run the task. The resulting output raster matches the result if the task is run first, then downsample the output raster.

Approximate: The two results look close to each other, but do not exactly match.

No: The two results are significantly different.

Unknown: The property value is unknown.

COMMUTE_ON_SUBSET (Get, Init)

A string that defines whether the result of running the ENVITask first, then subsetting the output raster, matches the result of subsetting the input raster(s) first before running the ENVITask.

An ENVITask developer can use the scripts provided in More Examples below to determine the COMMUTE_ON_SUBSET property value when creating an ENVITask.

Valid values are:

Yes: Subset the input raster(s) first, and then run the task. The resulting output raster matches the result if the task is run first, then subset the output raster.
Approximate: The two results look close to each other, but do not exactly match.
No: The two results are significantly different.
Unknown: The property value is unknown.

DESCRIPTION (Get, Init)

Text describing the task.

DISPLAY_NAME (Get, Init)

The name of the task as it appears in the user interface.

NAME (Get, Init)

The name of the task.

REVISION (Get, Init)

A string with the semantic revision number of the task. As the task definition evolves over time, the changes will affect how the revision number is incremented, according to semantic versioning rules.

SOURCE_URI (Get, Init)

The path and filename of the .task file that defines the task. If the task was created programmatically using OBJ_NEW, then SOURCE_URI will be an empty string.

TAGS (Get, Init)

A scalar string or an array of strings that help categorize the task. It can be empty with a value of !NULL.

Keywords

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.

More Examples

Downsample

The spectral index task shown in the next two examples performs a pixel-independent operation on the input raster. The two results match exactly and the COMMUTE_ON_DOWNSAMPLE property value of the spectral index task is Yes.

Example 1: Downsample Input Raster First, then Run Task

; Start the application

e = ENVI()

; Select input data

file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $

  SUBDIRECTORY = ['data'])

raster = e.OpenRaster(file)

; Downsample the input raster

scale = 2.0

DownSampleRaster = ENVIResampleRaster(Raster, PIXEL_SCALE=scale, $

  METHOD='Nearest Neighbor')

; Get the Spectral Index task from the catalog of ENVITasks

Task = ENVITask('SpectralIndex')

; Define the inputs

Task.INDEX = 'Normalized Difference Vegetation Index'

Task.INPUT_RASTER = DownSampleRaster

; Define outputs

Task.OUTPUT_RASTER_URI = e.GetTemporaryFilename()

; Execute the task

Task.Execute

; Get the collection of data objects currently available in the Data Manager

DataColl = e.Data

; Add the output to the Data Manager

DataColl.Add, Task.Output_Raster

; Display the result

View1 = e.GetView()

Layer1 = View1.CreateLayer(Task.Output_Raster)

Example 2: Run Task First, then Downsample Output Raster

; Start the application

e = ENVI()

; Select input data

file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $

  SUBDIRECTORY = ['data'])

raster = e.OpenRaster(file)

; Get the Spectral Index task from the catalog of ENVITasks

Task = ENVITask('SpectralIndex')

; Define the inputs

Task.INDEX = 'Normalized Difference Vegetation Index'

Task.INPUT_RASTER = Raster

; Define outputs

Task.OUTPUT_RASTER_URI = e.GetTemporaryFilename()

; Execute the task

Task.Execute

; Get the output raster

OutRaster = Task.Output_Raster

; Downsample the output raster

scale = 2.0

OutDownSampleRaster = ENVIResampleRaster(OutRaster, PIXEL_SCALE=scale, $

  METHOD='Nearest Neighbor')

; Get the collection of data objects currently available in the Data Manager

DataColl = e.Data

; Add the output to the Data Manager

DataColl.Add, OutDownSampleRaster

; Display the result

View1 = e.GetView()

Layer1 = View1.CreateLayer(OutDownSampleRaster)

Subset

The ClassificationAggregation task shown in the next two examples aggregates smaller class regions to a larger, adjacent region as part of the classification cleanup. The two results look close to each other, but do not exactly match at the image border. The COMMUTE_ON_SUBSET property value of the classification aggregation task is Approximate.

Example 1: Subset Input Raster First, then Run Task

; Start the application

e = ENVI()

; Select input data

file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $

  SUBDIRECTORY = ['data'])

raster = e.OpenRaster(file)

; Create a classification ENVIRaster

; Get the task from the catalog of ENVITasks

Task = ENVITask('ISODATAClassification')

; Define inputs

Task.INPUT_RASTER = Raster

; Define outputs

Task.OUTPUT_RASTER_URI = e.GetTemporaryFilename()

; Run the task

Task.Execute

; Get the output classification raster

classificationRaster = Task.OUTPUT_RASTER

; Subset the classificaiton raster

Subrect = [50, 100, 249, 279]

SubsetRaster = classificationRaster.Subset(SUB_RECT=Subrect)

; Get the classification aggregation task from the catalog of ENVITasks

AggregationTask=ENVITask('ClassificationAggregation')

; Define inputs

AggregationTask.INPUT_RASTER = SubsetRaster

; Define outputs

AggregationTask.OUTPUT_RASTER_URI = e.GetTemporaryFilename()

; Run the task

AggregationTask.Execute

; Get the collection of data objects currently available in the Data Manager

DataColl = e.Data

; Add the output to the Data Manager

DataColl.Add, AggregationTask.OUTPUT_RASTER

; Display the result

View1 = e.GetView()

Layer1 = View1.CreateLayer(AggregationTask.OUTPUT_RASTER)

Example 2: Run Task First, then Subset Output Raster

; Start the application

e = ENVI()

; Select input data

file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $

  SUBDIRECTORY = ['data'])

raster = e.OpenRaster(file)

; Create a classification ENVIRaster

; Get the task from the catalog of ENVITasks

Task = ENVITask('ISODATAClassification')

; Define inputs

Task.INPUT_RASTER = Raster

; Define outputs

Task.OUTPUT_RASTER_URI = e.GetTemporaryFilename()

; Run the task

Task.Execute

; Get the output classification raster

classificationRaster = Task.OUTPUT_RASTER

; Get the classification aggregation task from the catalog of ENVITasks

AggregationTask = ENVITask('ClassificationAggregation')

; Define inputs

AggregationTask.INPUT_RASTER = classificationRaster

; Define outputs

AggregationTask.OUTPUT_RASTER_URI = e.GetTemporaryFilename()

; Run the task

AggregationTask.Execute

; Subset the output raster

Subrect = [50, 100, 249, 279]

OutSubsetRaster = AggregationTask.OUTPUT_RASTER.Subset(SUB_RECT=Subrect)

; Get the collection of data objects currently available in the Data Manager

DataColl = e.Data

; Add the output to the Data Manager

DataColl.Add, OutSubsetRaster

; Display the result

View1 = e.GetView()

Layer1 = View1.CreateLayer(OutSubsetRaster)

Version History

ENVI 5.1	Introduced
ENVI 5.2	Added DISPLAY_NAME property. Added COMMUTE_ON_DOWNSAMPLE and COMMUTE_ON_SUBSET properties.
ENVI 5.3	Added ABORTED property.
ENVI 5.3. 2	Added AddParameter and RemoveParameter methods.
ENVI 5.4	Deprecated IGNORE_VALIDATE property and Validate method.
ENVI 5.5	Added Hydrate method; added ability to specify a Geospatial Services Framework (GSF) endpoint URL as input.
ENVI 5.5.1	Added TAGS and SOURCE_URI properties.

API Version

4.2