Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


Harris Geospatial / Docs Center / Using IDL / Custom IDL Tasks

IDL

Custom IDL Tasks

Custom IDL Tasks

This topic describes how to create custom IDL Tasks. The IDLTask function is the core of this capability. It provides one entry point for end users to create and execute an instance of the custom code.

See the following topics to learn more:

Benefits of Using IDLTask


IDL Tasks are an object-oriented API to encapsulate IDL procedures.

IDL Tasks provide the following to users:

  • One entry point for users through IDLTask function.
  • Stores all input and output in the IDLTask object for easy access.
  • Discover available tasks through IDLQueryTaskCatalogTask.
  • Provides introspection to learn about the input parameters and their requirements.
  • Provides validation of input for expected data types, available choices, ranges, and any additional constraints a task has defined.

IDL Tasks provide the following to developers:

  • Create new procedures and allow IDLTask to validate inputs instead of having to write additional code in the routine.
  • Allows wrapping existing libraries as IDL Tasks by simply creating a task file (*.task) that maps to library routines.
  • Provides information on each parameter on direction, expected data types, available choices, ranges, and more.
  • IDL Tasks can be executed from other programming languages; see IDL Task Engine for details.
  • If you have an application using the IDL Task Engine and want task information, use IDLQueryTaskTask and IDLQueryAllTasksTask.

See Custom Tasks for details on creating tasks.

Your First Custom IDL Task


This example shows how to create a custom task that returns the sum of two numbers:

  1. Create a scratch directory with write permissions to place the example files into, then add the scratch directory to the IDL Path.
  2. Copy the content below and save it to a file named addition.pro in the scratch directory:
  3.   pro addition, A=a, B=b, C=c
        compile_opt idl2
        c = a + b
      end
  4. Copy the JSON content below and save it in a file named addition.task in the scratch directory:
  5. {
      "name": "addition",
      "description": "Returns the sum of a and b.",
      "base_class": "IDLTaskFromProcedure",
      "routine": "addition",
      "schema": "idltask_1.0",
      "parameters": [
        {
          "name": "A",
          "type": "INT",
          "direction": "input",
          "required": true,
          "test_exact": true
        },
        {
          "name": "B",
          "type": "INT",
          "direction": "input",
          "required": true,
          "test_exact": true
        },
        {
          "name": "C",
          "type": "INT",
          "direction": "output",
          "required": true
        }
      ]
    }
  6. Run the custom task using the IDLTask function at the IDL Console:
  7.   task = IDLTask('addition')
      task.A = 2
      task.B = 2
      task.Execute
      print, 'The sum is:', task.C
  8. The IDLTask stores the inputs. If you want to update just one input and rerun, use:
  9.   task.B = 8
      task.Execute
      print, 'The sum is:', task.C
  10. If you look at the addition.task file, you will notice that for the input parameters of A and B, the test_exact key is set to true. Setting test_exact to true prevents non-integer floating point values as input. Run the following at the IDL Console and note that an error is generated:
  task = IDLTask('addition')
  task.A = 2.5

QUERY_IMAGE as a Custom IDL Task


This example shows how to wrap the QUERY_IMAGE routine into a custom task:

  1. Create a scratch directory with write permissions to place the example files into, then add the scratch directory to the IDL Path.
  2. IDL Task supports execution of a procedure with keywords. QUERY_IMAGE is a function with an argument. To support QUERY_IMAGE you build a thin procedure that wraps QUERY_IMAGE. Copy the content below and save it to a file named myqueryimage.pro in the scratch directory.
  3.   pro myqueryimage, FILENAME=filename, $
        SUPPORTED=supported, $
        _REF_EXTRA=extra
         
        compile_opt idl2
         
        supported = Query_Image(filename, $
          _STRICT_EXTRA=extra)
           
      end
  4. Copy the JSON content below and save it in a file named myqueryimage.task in the scratch directory:
  5. {
      "name": "MyQueryImage",
      "description": "Returns information about an image format file.",
      "base_class": "IDLTaskFromProcedure",
      "routine": "myqueryimage",
      "schema": "idltask_1.0",
      "parameters": [
        {
          "name": "FILENAME",
          "type": "STRING",
          "direction": "input",
          "required": true
        },
        {
          "name": "SUPPORTED",
          "type": "BOOLEAN",
          "direction": "output"
        },
        {
          "name": "CHANNELS",
          "type": "LONG",
          "direction": "output"
        },
        {
          "name": "DIMENSIONS",
          "type": "LONGARRAY",
          "dimensions": [2], 
          "direction": "output"
        },
        {
          "name": "PALETTE_EXISTS",
          "keyword": "HAS_PALETTE",
          "type": "BOOLEAN",
          "direction": "output"
        },
        {
          "name": "FORMAT",
          "keyword": "TYPE",
          "type": "STRING",
          "direction": "output"
        }
      ]
    }
  6. Review the parameter definition for DIMENSIONS below. QUERY_IMAGE returns an array containing 2 elements for the DIMENSIONS keyword. To expose that keyword for the task you define the parameter keys of type equal to LONGARRAY and dimensions of [2].
  7.     {
          "name": "DIMENSIONS",
          "type": "LONGARRAY",
          "dimensions": [2], 
          "direction": "output"
        }
  8. Review the parameter definition for FORMAT below. QUERY_IMAGE used TYPE as the keyword. For the task, we exposed the parameter name as FORMAT to help in clarification to users. IDL Task Parameter definition allows remapping of old keywords to new keywords by defining the parameter key of keyword and the parameter key of name. If the parameter definition did not have the keyword key, then it is implied that the name key is used as the keyword name when calling the routine.
  9.     {
          "name": "FORMAT",
          "keyword": "TYPE",
          "type": "STRING",
          "direction": "output"
        }
  10. Run the custom task using the IDLTask function at the IDL Console:
  11.   task = IDLTask('myqueryimage')
      task.FILENAME = FILEPATH('rose.jpg', SUBDIR=['examples','data'])
      task.Execute
      print, 'The format is '+task.FORMAT+' with dimensions of:'
      print, task.DIMENSIONS
  12. Run the task against multiple files. Copy the content below and save it to a file named runmyqueryimagetask.pro in the scratch directory:
  13.   pro runMyQueryImageTask
        compile_opt idl2
         
        ; Define a data directory to search for data files
        dataDir = FilePath('', SUBDIR=['examples','data'])
        dataFiles = File_Search(dataDir,'*')
         
        ; Create an instance of MyQueryImage task
        task = IDLTask('MyQueryImage')
         
        ; Run MyQueryImage task against all files in the data directory
        ; to see which ones contain a PALETTE
        print,'Data files that contain palettes that '+$
          'can be read by QUERY_IMAGE:'
        foreach file, dataFiles do begin
          ; Update the FILENAME parameter on the task to the new file
          task.FILENAME = file
           
          ; Execute the task with each file
          task.Execute
           
          ; Check if supported and has a palette. 
          ; Print if the file has a palette
          if (task.SUPPORTED && task.PALETTE_EXISTS) then $
           print, task.FILENAME
        endforeach
         
        print,''
         
        ; Run MyQueryImage task against all files in data directory
        ; to see which ones are of JPEG format
        format = 'JPEG'
        print,'Data files that are of '+format+' format:'
        foreach file, dataFiles do begin
          ; Update the FILENAME parameter on the task to the new file
          task.FILENAME = file
           
          ; Execute the task with each file
          task.Execute
           
          ; Check if format looking for and print if it is
          if (task.FORMAT eq format) then $
           print, task.FILENAME
        endforeach
      end

Task Definitions


Task definitions consist of a HASH of key-value pairs that define the task and its parameters. A task definition can be stored to disk as JSON-formatted text file with an extension of .task.

This section describes the keys in a task definition.

Task Keys

This table describes the keys that provide an overview of the task. Refer to IDLTask for additional details.

Key

Required

Description

name

Yes, if storing the task definition to disk

A string with the name of the task. This name is used when calling the IDLTask function to create an instance of the task. The name of the task file must match the value of this key and must be a valid IDL variable name.

base_class

Yes

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

schema

Yes

A string containing the schema of the task definition. The schema is: idltask_1.0 . IDL will support this schema in future releases if a new schema is introduced.
routine

Yes, when used with IDLTaskFromProcedure

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

display_name

No

A string with the name of the task for display purposes. Spaces and special characters are allowed.

description

No

A string with a description of the task.

parameters

No

A LIST of HASHs of key/value pairs, described in the Parameter Keys table below.

Parameter Keys

This table describes the keys that belong to the parameters group in a task definition; these are repeated for each parameter. Depending on the parameter type, there can be additional keys. Refer to the IDLParameter* topics to find out specific information about a given parameter. The mapping of the parameter properties to the task definition is 1:1, if the parameter property name is TEST_EXACT then the task definition key is test_exact.

Key

Required

Description

name

Yes

The name of the parameter as it appears to the end user. This key must be a valid IDL variable name.

type

Yes

A scalar string indicating the parameter type to use on creating an instance of the task.

Basic scalar data type string values are:

BYTE, INT, UINT, LONG, ULONG, LONG64,ULONG64, FLOAT, DOUBLE, COMPLEX, DCOMPLEX, STRING, BOOLEAN, LIST, HASH, DICTIONARY, ORDEREDHASH

Basic array data types must include the dimensions key and type string values are:

BYTEARRAY, INTARRAY, UINTARRAY, LONGARRAY, ULONGARRAY, LONG64ARRAY,ULONG64ARRAY, FLOATARRAY, DOUBLEARRAY, COMPLEXARRAY, DCOMPLEXARRAY, STRINGARRAY, BOOLEANARRAY,

The type key value can be set to a class name to indicate that the user must provide an object of the given class name.

dimensions

No

A scalar string specifying the required dimensions for a parameter, if type specified is an *ARRAY type.

If the number of elements in any dimension does not matter, then use an asterisk ('*') for that dimension.

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

No

The internal keyword that the parameter should map to when invoking the routine. If it is the same as the name key, then you do not need to create this key.
display_name

No

A string with the name of the parameter for display purposes. Spaces and special characters are allowed.

description

No

A string with a description of the parameter.
direction

No

Specify if the parameter is input or output. If this key is not set, then direction defaults to input.

required

No

A boolean value that indicates whether the parameter is required or not. The default is false, which allows the parameter to be optional.

default

No

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

hidden

No

A boolean value that indicates whether the parameter is visible to the user or not. The default is false, which means the user can see it and set its value. Set this key to true if you want to prevent the user from seeing the parameter or changing its value. You must also set the default key to the desired value.

additional keys

No

Depending on the parameter there may be additional keys available to define. For example for a type set to STRING, there is fold_case and choice_list. You could use the QueryProperty static method on the given parameter class to discover the available keys:

IDL>print, IDLParameterString.QueryProperty()



© 2017 Exelis Visual Information Solutions, Inc. |  Legal
My Account    |    Buy    |    Contact Us