Custom Tasks

Custom Tasks Tutorial

This topic describes how application developers can create custom data-processing tasks using IDL and ENVI application programming interface (API) code. ENVI already provides many API routines to perform data-processing tasks. See Data Processing Using ENVITasks and ENVITask for a list of available tasks. However, you can write custom tasks using task templates that define the input and output parameters required for data processing. You can write a custom task once and run it on desktop or enterprise environments using the ENVI Task Engine.

Benefits of Using ENVITask

Writing custom tasks using the ENVITask framework provides the following benefits:

• Parameters are automatically validated for correctness. For example, you do not have to add error-handling code to the task to ensure the end user specifies a valid ENVIRaster object as input.
• The ENVI Modeler automatically recognizes all ENVITasks and lets you use them as building blocks for creating custom workflows.
• Temporary filenames are created if the end user does not set the URI parameter (property) for the task. ENVI will clean up the temporary output upon exit so that your system's temporary directory will not fill up with unwanted data.
• Tasks include a dynamic user interface that allows end users to enter parameters and to run the task using a dialog. See ENVIUI::SelectTaskParameters for details.
• For tasks that wrap an IDL program, you do not have to update any code to rename keywords or to map values to user-friendly strings.
• For tools that are based on ENVITasks, you can run the tools in the background by selecting Run Task in the Background in the task dialog. See ENVI Servers. This allows you to continue working in ENVI while concurrent tasks are running.
• You can run tasks through any command-line interface via stdio. See ENVI Task Engine for details.

Getting Started

Here are the general steps for writing a custom task.

See Custom Tasks Tutorial for an example.

1. Write an IDL procedure that contains the data-processing steps. It should have keywords that define inputs and outputs.
2. Create a task template that maps the keywords in your procedure to task parameters. Save the task file with a .task extension. Task templates consist of JSON-formatted text that defines the input and output parameters required for data processing. See the following topics for more information:
   • Task Schema History
   • Task Templates
   • Sample Task Template
3. Deploy the task files to your system.
4. Write an IDL program to run the custom task.

At this point, you can run the custom task from the IDL/ENVI command line using the following pattern. This example only has one parameter, which is the input raster.

IDL> e = ENVI()

ENVI> task = ENVITask('MyCustomTask')

ENVI> task.INPUT_RASTER = 'C:\MyData\MyRaster.dat'

ENVI> task.Execute

To save the result to disk:

ENVI> outURI = 'C:\MyData\OutputRaster.dat'

ENVI> outRaster = Task.OUTPUT_RASTER

ENVI> outRaster.Export, outURI, 'ENVI'

In most cases, however, you will want to run the custom task using the ENVI application. Follow these additional steps:

1. Create a dynamic user interface (UI) that lets users enter required and optional parameters to run the task. Use the ENVIUI::SelectTaskParameters method to create the dynamic UI.
2. Optional: Create a style sheet that will render UI elements such as color pickers or ROI file selection tools. Creating a style sheet gives you more control in designing an effective UI.
3. Optional: Deploy the custom task as an extension to the ENVI Toolbox. See Custom Tasks Tutorial for an example.
4. Optional: If you or other users will run the custom task from the ENVI application only (without IDL), you must create an IDL save file (.sav) for the programs you wrote in Steps 1 and 4 above. See Custom Tasks Tutorial for an example.

Here are some tips for creating custom tasks:

• Parameter names should be consistent among different tasks; ideally, they should have the same names as in your IDL procedure.
• We recommend that you do not add spatial or spectral subsetting as parameters to custom tasks; instead, subset your data using ENVISubsetRaster. If your custom task includes a dynamic UI with a file selection dialog, you can prevent end users from subsetting raster data by setting the DISABLE_SUBRECT and DISABLE_BANDS keywords on the ENVIRaster_UI class.
• You can add progress bars to custom tasks. See Messaging for more information.
• Instead of using ENVITaskFromProcedure as the base class for custom tasks, you can write a custom base class. See Custom Task Base Classes for reasons why you would consider this.