What is the iTools Procedural Interface?

IDL's iTools were designed to provide an easy way to create and interactively modify sophisticated data visualizations. Because the tools were meant for interactive use, the facilities for modifying existing visualizations were limited to interactive, mouse-and-keyboard-based workflows. If you wanted to control an iTool programmatically, you needed to use the object-oriented iTools framework, as described in iTool Programming.

The iTools procedural interface, introduced in IDL 7.1, allows you to perform many of the actions that were originally only available interactively via calls to procedure-oriented IDL routines — that is, directly from the IDL command line, or in procedural .pro code, without the need to use the object-oriented iTools framework.

Quick Example

The following provides a very brief example that illustrates how you might use the iTools procedural interface to create and annotate an image visualization:

; Open an image file and visualize it with IIMAGE
IOPEN, FILEPATH('africavlc.png', $
   SUBDIRECTORY=['examples', 'data']), /VISUALIZE

; Add a text annotation for desert areas
ITEXT, 'Desert', -0.2, 0.45, /NORMAL
ISETPROPERTY, 'text 0', COLOR=[155,0,0]

; Add a text annotation for savanna areas
ITEXT, 'Savanna', 0, -0.3, /NORMAL
ISETPROPERTY, 'text 1', COLOR=[155,100,0]

; Increase the size of both text annotations
ISETPROPERTY, 'text*', FONT_SIZE=24

Note
In this example, we call the ISETPROPERTY routine with simple strings rather than full iTool identifiers to specify the visualization elements whose properties we want to modify. See Understanding iTool Identifiers and IGETID for more on this technique.

Limitations of the Procedural Interface

While you can manipulate many aspects of an existing iTool, not every action you can perform interactively (by using the mouse and selecting menus) is exposed via the iTools procedural interface. For example, the routines in the procedural interface do not provide mechanisms to:

Routines in the iTools Procedural Interface

The following routines comprise the iTools procedural interface:

ICONTOUR

Creates an iTool to display contour data.

ICONVERTCOORD

Converts between DATA, DEVICE, and NORMAL iTool coordinate systems.

IDELETE

Deletes a tool in the IDL Intelligent Tools system. (Note that this routine was previously named ITDELETE.)

IELLIPSE

Creates an ellipse annotation in an existing iTool.

IGETCURRENT

Retrieves the iTool identifier of the current tool in the IDL Intelligent Tools system.

IGETDATA

Retrieves data from a specified iTools visualization.

IGETID

Retrieves the full iTool object identifier string for an iTool visualization item based on a portion of the identifier.

IGETPROPERTY

Retrieves a property value from an iTools visualization.

IIMAGE

Creates an iTool to display image data.

IMAP

Creates an iTool to display map data.

IOPEN

Opens a file, reads data from the file, and adds one or more variables containing the data to IDL's current scope.

IPLOT

Creates an iTool to display plot data.

IPOLYGON

Creates a polygon annotation in an existing iTool.

IPOLYLINE

Creates a line annotation in an existing iTool.

IPUTDATA

Replaces the data on a specified iTools visualization without changing other properties of the visualization.

IREGISTER

Registers iTool object classes or other iTool functionality with the IDL Intelligent Tools system. (Note that this routine was previously named ITREGISTER.)

IRESET

Resets the IDL iTools session. (Note that this routine was previously named ITRESET.)

IRESOLVE

Resolves all IDL code within the iTools directory, as well as all other IDL code required for the iTools framework. (Note that this routine was previously named ITRESOLVE.)

IROTATE

Rotates an iTools visualization.

ISAVE

Saves the contents of the current iTool as an image file.

ISCALE

Scales an iTools visualization.

ISETCURRENT

Sets the current tool in the IDL Intelligent Tools system. (Note that this routine was previously named ITCURRENT.)

ISETPROPERTY

Sets a property on one or more iTools visualizations.

ISURFACE

Creates an iTool to display surface data.

ITEXT

Creates a text annotation in an existing iTool.

ITRANSLATE

Translates an iTools visualization.

IVECTOR

Creates an iTool to display vector data.

IVOLUME

Creates an iTool to display volume data.

IZOOM

Changes the zoom factor on an iTools visualization.

For information on controlling iTools programmatically using the object-oriented iTools framework, rather than using the procedural interface described in this chapter, see Controlling iTools from the IDL Command Line (iTool Developer's Guide).