Creating iTool Annotations

The IELLIPSE, IPOLYGON, IPOLYLINE, and ITEXT routines allow you to programmatically create annotations in an existing iTool window.

What is an Annotation?

An annotation is a line, shape, or block of text that is created separately from an iTool visualization. For example, the arrow and words "Look Here" in the following image are annotations:

api_annotation1.gif

The above example is created by the following lines of IDL code:

; Open a data file
file = FILEPATH('muscle.jpg', SUBDIRECTORY = ['examples', 'data'])

; Create an iTool with the image data
IIMAGE, file, TITLE = 'Muscle Tissue'

; Create the arrow annotation on glass, using data coordinates
IPOLYLINE, [[260,50], [525,170]], /DATA, THICK=2, $
   COLOR=[255,0,0], ARROW_STYLE=2

; Create the text annotation on glass, using data coordinates
ITEXT, 'Look Here', 530, 170, /DATA, COLOR=[255,0,0]

Creating Annotations "On Glass"

By default, annotations are created in the iTools Annotation Layer. The annotation layer is a separate graphics hierarchy that overlays the visualization contained in the iTool; it is separate from the data area. Annotations of this type are commonly referred to as being "on glass," because changes to the visualization that underlies the annotation layer do not change the annotations.

To illustrate the nature of annotations created in the annotation layer, create the annotated iTool described in the previous section. First, click on the image to select it. Next, select the Rotate manipulator and rotate the image. Note that the annotations do not move with the image.

api_annotation2.gif

Creating Annotations that Coexist with Data

If your annotations are positioned with respect to specific data points in the visualization, you may want to create the annotations in the Visualization Layer rather than in the annotation layer. Annotations included in the visualization layer will be modified along with the visualization's data, if the data are transformed. To create annotations in the visualization layer rather than the annotation layer, use the VISUALIZATION keyword to the annotation routines. For example, the following lines of IDL code create the same display as the previous sections, but place the annotations in the visualization layer along with the image data:

; Open a data file
file = FILEPATH('muscle.jpg', SUBDIRECTORY = ['examples', 'data'])

; Create an iTool with the image data
IIMAGE, file, TITLE = 'Muscle Tissue'

; Create the arrow annotation in the visualization layer,
; using data coordinates
IPOLYLINE, [[260,50], [525,170]], /DATA, THICK=2, $
   COLOR=[255,0,0], ARROW_STYLE=2, /VISUALIZATION

; Create the text annotation in the visualization layer,
; using data coordinates
ITEXT, 'Look Here', 530, 170, /DATA, COLOR=[255,0,0], $

   /VISUALIZATION

To illustrate the nature of annotations created in the visualization layer, create a second annotated iTool using the above code. First, click on the image to select it. Next, select the Rotate manipulator and rotate the image. Note that the annotations now move with the image.

api_annotation3.gif

Coordinate Systems

The iTool procedural annotation routines allow you to specify the coordinates of annotations using three different coordinate systems: NORMAL, DEVICE, or DATA.

Normal Coordinates

The Normal coordinate system maps the iTools canvas (the white space into which visualizations and annotations are drawn) into the range [0,1], with the point [0,0] being the lower left-hand corner of the canvas.

The Normal coordinate system is the default coordinate system; if you do not specify any of the coordinate system keywords, the location values are interpreted as normal coordinates. To explicitly use the normal coordinate system, set the NORMAL keyword to the annotation routine.

For example, the following code creates an empty iTool window, draws a blue line from the top to the bottom of the screen approximately one third of the distance from the left edge, and draws a red "x" in the center of the screen:

IPLOT
IPOLYLINE, [[0.333, 0], [0.333, 1]], THICK=2, COLOR=[0,0,255]
ITEXT, 'x', 0.5, 0.5, COLOR=[255,0,0]

The Normal coordinate system is useful when you want to position an annotation relative to the iTool canvas, regardless of its size or shape.

Device Coordinates

The Device coordinate system maps the iTools canvas (the white space into which visualizations and annotations are drawn) into the range of pixels, with [0,0] being the lower left-hand pixel on the canvas. To use the device coordinate system, set the DEVICE keyword to the annotation routine.

For example, the following code creates an empty iTool window and draws a 50x50 pixel green square positioned 100 pixels from the left-hand side of the canvas and 100 pixels up from the bottom of the canvas:

IPLOT
IPOLYGON, [[100,100], [150,100], [150,150], [100,150]], /DEVICE, $
   COLOR=[50,255,50], FILL_COLOR=[50,255,50]

The Device coordinate system is useful when you want to position an annotation at an exact pixel location regardless of the size or shape of the iTool canvas.

Data Coordinates

The Data coordinate system corresponds to the range of values used by the data that created the iTool visualization being annotated. To use the data coordinate system, set the DATA keyword to the annotation routine.

For example, the following code annotates the maximum value of a plot line:

values = RANDOMU(seed, 10)*10
IPLOT, values
maxvalue = MAX(values, maxindex)
IPOLYLINE, [[maxindex, maxvalue], [maxindex+1, maxvalue+1]], $
/DATA, ARROW_STYLE=2
ITEXT, 'Maximum value', maxindex+1, maxvalue+1, /DATA

The Data coordinate system is useful when you want to position an annotation relative to a particular data value, wherever it may be displayed in the visualization.

Note
Using Data coordinates is not the same as inserting the annotation into the visualization's data space using the VISUALIZATION keyword. You can use data coordinates to position annotations in either the annotation layer or the visualization layer.

The following code illustrates the relative placement of annotations using the three different coordinate systems:

IPLOT, INDGEN(5)
ITEXT, 'x (Data)', 1, 1, /DATA
ITEXT, 'x (Device)', 1, 1, /DEVICE
ITEXT, 'x', 1, 1, /NORMAL, ALIGNMENT=1.0, UPDIR=[0.0, -1.0]
ITEXT, '(Normal)', 0.95, 0.95, /NORMAL, ALIGNMENT=1.0

Note that for the normal case, we must reverse the default text alignment and text direction in order to place the "x" at the coordinates [1, 1] — since alignment and direction are normally measured from the lower left corner of the text string, using the default alignment and text direction would place the "x" outside the visible window.