name

Yes

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

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.

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.

description

Yes

A string with a description of the task.

revision

No

A string with the semantic revision number of the task. Semantic versioning provides a quick way to extract information about a new task release using a convention of X.Y.Z, where:

• X represents the major version. An incremented value indicates that task additions and updates are not backward-compatible.
• Y represents the minor version. An incremented value indicates that task additions and updates are backward-compatible.
• Z represents the patch number. An incremented value indicates bug fixes that do not affect the task.

The revision key is for development purposes only. The revision number does not affect which task file is loaded. Whichever task file is found first will be used. If revision is not set, it will default to a value of 1.0.0.

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 result in different results than downsampling the results from the original raster.

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

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.

schema

Yes

A string listing the version of ENVITask JSON schema that was used to write this task. The valid values are envitask_3.3, envitask_3.2, envitask_3.1, or envitask_3.0.

tags

No

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

parameters

No

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

name

Yes

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

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.

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, ENVIROI, or ENVIMetataskDAG).
• Boolean type (Bool)
• ENVIURI: Indicates that a uniform resource indicator (URI) is required. For a local file, specify a scalar string that is a fully qualified file path. For a remote file, specify a string with the direct URL of the dataset.
• ENVIVirtualizableURI: A string that references a filename or folder to use, or that virtual output was requested
• 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.

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]"

direction

Yes

Specify if the parameter is input or output.

Note: Older versions of ENVI use a different task schema; for example:

     "version": "5.x",

In these cases, ENVI automatically creates an OUTPUT_RASTER_URI property if youy define the OUTPUT_RASTER property of an ENVIRaster and set the direction parameter to output.

required

No

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

description

Yes

A description of the parameter.

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.

default

No

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

auto_extension

No

This property only applies when:

• The type key is set to ENVIURI or ENVIURIArray, and:
• The direction key is set to input, and one of the following conditions:
  • The required is set to true, or:
  • The required key is set to false and the user sets VALUE to an asterisk (*).

Set this property to a scalar string to use as a file extension for input ENVIURI parameters where VALUE=!NULL. When the parent ENVITask is executed, input ENVIURI parameters without a value can be populated by values generated by ENVI::GetTemporaryFilename. If this property is not set, or if it is set to !NULL, then no filenames will be generated and the task will likely fail. An empty string value will generate filenames without an extension.

is_temporary

No

This property only applies when:

• The type key is set to ENVIURI or ENVIURIArray, and
• The direction key is set to input, and
• The auto_extension key is not !NULL

Set this property to true to indicate if input ENVIURI parameters with filenames automatically generated by the ENVITask framework will be deleted when ENVI closes.

When the parent ENVITask is executed, input ENVIURI parameters that had VALUE=!NULL and had their values populated according to the auto_extension property can be marked for deletion when ENVI closes.

is_directory

No

Set this property to true to indicate if the VALUE of an ENVIURI parameter should be treated as a directory or a URI to a file. When the parent ENVITask is executed and the VALUE property is set to !NULL and the is_directory key is set to true, then a subdirectory will be created under the ENVI Output Directory preference location. The base name will consist of the parameter's NAME, and the parameter's VALUE will be set to that new directory.

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.

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.

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.

uri_param

No

This property only applies when:

• The type key is set to a supported scalar or array data type that has an associated URI-based ENVIParameter* class. This includes ENVIConfusionMatrix, ENVIGCPSet, ENVIPointCloud (scalar only), ENVIPointCloudQuery (scalar only), ENVIRaster, ENVIRasterSeries, ENVIROI, ENVISpectralLibrary, ENVITiePointSet, and ENVIVector.
• The direction key is set to output.

Set this key to a parameter name (in the same task) that it is associated with. That other parameter must adhere to the following constraints:

• The type key is set to ENVIURI if the parameter is a scalar type, or ENVIURIArray if the parameter is an array type.
• The dimensions key must match the parameter's dimension key if this is an array type.
• The direction key is set to input.

For example, the uri_param key for OUTPUT_RASTER below is set to OUTPUT_URI, which is the name of the associated input parameter of type ENVIURI. That input parameter specifies what file to use to export the raster.

{

  "name": "OUTPUT_RASTER",

  "display_name": "Output Raster",

  "type": "ENVIRASTER",

  "direction": "output",

  "required": true,

  "uri_param": "OUTPUT_URI",

  "description": "This is a reference to the output raster."

},

{

  "name": "OUTPUT_URI",

  "display_name": "Output Raster URI",

  "type": "ENVIURI",

  "direction": "input",

  "required": false,

  "description": "Specify a string with the fully-qualified path and filename for OUTPUT_RASTER."

  "fold_case": true,

  "auto_extension": ".dat",

  "is_temporary": true

}