The following examples demonstrate how to query the IDL Task Engine for task information and run a custom IDL Task.

For command-line arguments and options see IDL Task Engine.

Query the IDLTask Catalog

Use QueryTaskCatalog Task to get a list of available IDLTasks. The following steps show how to use this task with the IDLTaskEngine executable:

  1. Start a terminal window.
  2. Create a scratch directory with write permissions in the terminal window, where any temporary output can be written. Change to that directory:
    3. mkdir sandbox
    cd sandbox
  3. Run the QueryTaskCatalog task from IDLTask on a single line. Use the example below to run with PRO code. To run with a SAVE file, omit ‑‑compile from the command:

    4. Bash shell:

    echo '{"taskName":"QueryTaskCatalog"}' | InstallDir/bin/idltaskengine ‑‑compile

    Windows terminal:

    echo {"taskName":"QueryTaskCatalog"} | "InstallDir\bin\bin.x86_64\idltaskengine.bat" ‑‑compile

Query a Task for its Parameters

Once you have selected a specific task of interest, use QueryTask Task to get information about its input and output parameters. The following steps show how to use QueryTask task with the IDLTaskEngine executable:

  1. Start a terminal window.
  2. Create a scratch directory with write permissions in a terminal window, where any temporary output can be written. Change to that directory:
    3. mkdir sandbox
    cd sandbox
  3. Run the QueryTask task from IDLTaskEngine on a single line. Use the example below to run with PRO code. To run with a SAVE file, omit ‑‑compile from the command:

    4. Bash shell:

    echo '{"taskName":"QueryTask","inputParameters":{"Task_Name":"QueryTaskCatalog"}}' | InstallDir/bin/idltaskengine ‑‑compile

    Windows terminal:

    echo {"taskName":"QueryTask","inputParameters":{"Task_Name":"QueryTaskCatalog"}} | "InstallDir\bin\bin.x86_64\idltaskengine.bat" ‑‑compile
  4. To view an error generated during task execution, run the above command with a fake task name. Use the example below to run with PRO code. To run with a SAVE file, omit ‑‑compile from the command:

    5. Bash shell:

    echo '{"taskName":"QueryTask","inputParameters":{"Task_Name":"DoesNotExist"}}' | InstallDir/bin/idltaskengine ‑‑compile

    Windows terminal:

    echo {"taskName":"QueryTask","inputParameters":{"Task_Name":"DoesNotExist"}} | "InstallDir\bin\bin.x86_64\idltaskengine.bat" ‑‑compile

Run a Custom Task

The following example shows how to run a custom task with an image located in the IDL installation path.

  1. Start a terminal window.
  2. Create a scratch directory with write permissions named sandbox in the terminal window.
    3.     mkdir sandbox

  3. Copy the content below and save it to a file named ExampleThumbnail.task in the sandbox directory in a text editor. This task file describes the task and it's parameters.

      {
        "name": "ExampleThumbnail",
        "base_class": "IDLTaskFromProcedure",
        "routine": "ExampleThumbnail",
        "display_name": "Example Thumbnail",
        "description": "This task creates a thumbnail from an input image.",
        "schema": "idltask_1.1",
        "revision": "1.0",
        "parameters": [
        {
          "name": "INPUT_IMAGE",
          "display_name": "Input Image",
          "type": "STRING",
          "direction": "input",
          "required": true,
          "description": "A filename to an image to create a thumbnail."
        },
        {
          "name": "WIDTH",
          "display_name": "Width",
          "type": "INT",
          "direction": "input",
          "required": false,
          "description": "The width and height of the output thumbnail image in pixels.",
          "default":32
        },
        {
          "name": "OUTPUT_THUMBNAIL",
          "display_name": "Output Thumbnail",
          "type": "STRING",
          "direction": "output",
          "required": true,
          "description": "The output bitmap file of the thumbnail."
        }
        ]
      }

  4. Copy the below content and save it to a file named examplethumbnail.pro in the sandbox directory in IDLDE. This routine uses the Image function in a buffer to save out a thumbnail of the input image.

    pro ExampleThumbnail, INPUT_IMAGE=inputImage, OUTPUT_THUMBNAIL=outputThumbnailFile, WIDTH=width
      compile_opt idl2
       
      ON_ERROR, 2
       
      if (~file_test(inputImage, /REGULAR)) then begin
        message, 'Input file not found.', /NONAME
      endif
       
      cd, CURRENT=current
      dotIndex = inputImage.LastIndexOf('.')
      baseName = File_BaseName(inputImage.Remove(dotIndex) + '_thumbnail.bmp')
      outputThumbnailFile = FilePath(baseName, ROOT_DIR=current)
       
      i=image(inputImage, DIMENSIONS=[640,640], MARGIN=0, ASPECT_RATIO=0, /BUFFER)
      i.save, outputThumbnailFile, BORDER=0, WIDTH=width
    end
  5. Change to the sandbox directory in the terminal window, where the output will be written. 
    6. cd sandbox
  6. Create a thumbnail.json file in the scratch directory with the following JSON code in a text editor.

    7. Tip: On Windows systems, update the URL key to "InstallDir\\examples\\data\\boulder.tif", where xx is the IDL version.

    {
      "taskName": "ExampleThumbnail",
      "inputParameters": {
        "INPUT_IMAGE": "InstallDir/examples/data/boulder.tif"
      }
    }
  7. Run the ExampleThumbnail task from the IDLTaskEngine executable using the newly created file. Use the example below to run with PRO code. To run with a SAVE file, omit ‑‑compile from the command:

    8. Bash shell:

    InstallDir/bin/idltaskengine ‑‑compile < thumbnail.json

    Windows terminal:

    "InstallDir\bin\bin.x86_64\idltaskengine.bat" ‑‑compile < thumbnail.json
  8. To output a thumbnail with a larger width, update the thumbnail.json file as follows.

    9. Tip: On Windows systems, update the URL key to "InstallDir\\examples\\data\\boulder.tif", where xx is the IDL version. 

    {
      "taskName": "ExampleThumbnail",
      "inputParameters": {
        "INPUT_IMAGE": "InstallDir/examples/data/boulder.tif",
        "WIDTH":100
      }
    }
  9. Run the ExampleThumbnail task with the updated JSON input Thumbnail task. Notice that the generated thumbnail is larger since the width has doubled. Use the example below to run with PRO code. To run with a SAVE file, omit ‑‑compile from the command.

    10. Bash shell:

    InstallDir/bin/idltaskengine ‑‑compile < thumbnail.json

    Windows terminal:

    "InstallDir\bin\bin.x86_64\idltaskengine" ‑‑compile < thumbnail.json