This topic describes the fields (also called keys) in a task template for use with ENVI 5.4.

Task Keys

The following table describes the keys that provide an overview of the task. The envitask_3.0 schema simplifies this table, as the JSON keys have the same names as the ENVITask properties. The "Mapping" field lists the ENVITask property that corresponds to the key.

Key

Required

Description

Mapping

name

Yes

A string with the name of the task, excluding the prefix ENVI and the suffix Task.

NAME

base_class

Yes

A string with the name of the class to use; the most common is ENVITaskFromProcedure.

Use ENVIMetatask if you are creating a metatask. See Metatasks for details.

Use ENVIAbortableTaskFromProcedure to allow your custom task to have a progress dialog with an option to cancel the process. See Messaging for details.

You can also write your own base class to simplify the process of writing custom tasks that use a common set of parameters and application behavior. See Custom Base Classes for more information.

 

routine

Yes

The routine that is called when Task.Execute is invoked.

ROUTINE

display_name

No

A string with the name of the task as it appears to the end user. Spaces and special characters are allowed. This key is used by tasks that display a dynamic user interface for entering parameters. See ENVIUI::SelectTaskParameters for details.

DISPLAY_NAME

description

Yes

A string with a description of the task.

DESCRIPTION

commute_on_downsample

No

A string that indicates if raster processing is affected by downsampling before program execution. A value of Yes indicates that the raster can be downsampled before execution, yielding the same result as downsampling the output raster. A value of No means that downsampling the raster before execution will yield different results than downsampling the results from the original raster.

This key is used by the dynamic task UI to determine Preview accuracy.

COMMUTE_ON_DOWNSAMPLE

commute_on_subset

No

A string that indicates if raster processing is affected by subsetting before program execution. For example, your algorithm may rely on statistics of the entire dataset to get accurate results. A value of Yes indicates that the raster can be subsetted before execution. A value of No means that the raster should not be subsetted before execution.

This key is used by the dynamic task UI to determine Preview accuracy.

COMMUTE_ON_SUBSET

schema

Yes

A string listing the version of ENVITask JSON schema that was used to write this task. Currently the only valid value is envitask_3.0.

 

parameters

No

A container of key/value pairs, described in the Parameter Keys section next.

 

Parameter Keys

The following table describes the keys that belong to the parameters group in a task template; these are repeated for each parameter. The "Mapping to ENVITaskParameter" field lists the keys' corresponding property names in ENVITaskParameter.

Key

Required

Description

Mapping to ENVITaskParameter

name

Yes

The name of the parameter as it appears to the end user.

NAME

keyword

No

The internal keyword that the parameter should map to. If it is the same as the NAME key, then you do not need to set keyword.

 

display_name

No

The name of the task as it appears to the end user. This key is used by tasks that display a dynamic user interface for entering parameters. See ENVIUI::SelectTaskParameters for details.

DISPLAY_NAME

type

Yes

A scalar string with one of the following:

  • IDL data type: Byte, Int, Long, Float, Double, Complex, String, DComplex, UInt, ULong, Long64, or ULong64
  • The required class for the parameter (for example, ENVIRaster, ENVIVector, or ENVIROI)
  • Boolean type (Bool)
  • ENVIURI: Indicates that a string is required that references a local or remote file source.
  • List (scalar only; no arrays)
  • OrderedList (scalar only; no arrays)
  • Hash (scalar only; no arrays)
  • OrderedHash (scalar only; no arrays)

If a specified data type requires more than one scalar, use the dimensions parameter below to indicate the array dimensions. Append Array to the data type; for example, floatArray.

TYPE

dimensions

No

Specify the array dimensions if the type parameter requires more than one scalar.

  • Example of a three-element array declaration: 
    "type": "floatArray",
    "dimensions": "[3]"
  • Example of a 1D array with any number of elements: 
    "type": "intArray",
    "dimensions": "[*]"
  • Example of a 2D array with any number of columns or rows: 
    "type": "intArray",
    "dimensions": "[*,*]"
  • Example of a 2D array with a specific number of elements: 
    "type": "byteArray",
    "dimensions": "[3,256]"
  • Example of a 2D array with any number of columns and 3 rows: 
    "type": "intArray",
    "dimensions": "[*,3]"

DIMENSIONS

direction

Yes

Specify if the parameter is input or output.

Note: If you are using an older version of ENVI where the task template specifies the version key (instead of schema), be aware of the differences in output behavior: ENVI automatically creates an OUTPUT_RASTER_URI property if you define the OUTPUT_RASTER property of an ENVIRaster and you set the direction parameter to output.

DIRECTION

required

No

Set this key to true or false (default) to indicate if it is required for the task to execute or not.

REQUIRED

description

Yes

A description of the parameter.

DESCRIPTION

choice_list

No

A string array that lists the possible values for the property. Any IDL data type is supported. You can also map from user-friendly strings to an internal lookup table of values if desired.

This property is not present for all values of TYPE. Use QueryProperty to learn if it is available.

CHOICE_LIST

default

No

The default value of the parameter if the end user does not provide a value.

DEFAULT

min

No

A value that is greater than or equal to the minimum value allowed for the parameter.

This property is not present for all values of TYPE. Use QueryProperty to learn if it is available.

MIN

max

No

A value that is less than or equal to the maximum value allowed for the parameter.

This property is not present for all values of TYPE. Use QueryProperty to learn if it is available.

MAX

hidden

No

Set this key to true if the parameter is required for the task but you do not want to expose it to the end user. You must also set the default key to the desired value for the parameter to be set internally.

 

Revision History

This section summarizes the updates to task templates, compared to the previous release:

  • The version key was renamed to schema. It is a required key with a default value of envitask_3.0. You can still specify version, but its value must be 5.3.2 or earlier.
  • Task and parameter key names are lower-case and use underscores to separate multiple words.
  • The routine task key is required.
  • The description task key is required.
  • The dataType parameter key was renamed to type. It now accepts lists, ordered lists, hashes, and ordered hashes. See the type description above for details.
  • The dimensions key was introduced. Use this key to specify the array dimensions if the type parameter requires more than one scalar. See the dimensions description above for details.
  • The parameterType key was replaced with the required key. The valid values are true or false.
  • The defaultValue key was renamed to default.

See Also

Task Schema History, Sample Task Template, Custom Tasks