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
See also ENVITasks by Category.
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
See Also
ENVITask::Parameter, ENVITaskFromProcedure, ENVIAsyncSpawnTaskJob, QueryAllTasks Task, QueryTaskCatalog Task, QueryTask Task, RunTask Task