Modifying iTool Data

Every visualization displayed in an iTool represents some data. The visualization's data may have been supplied in the form of IDL variables, as when creating a visualization with a routine like IPLOT, or the data may have been created interactively, as when drawing a shape annotation on top of an existing visualization. In all cases, the data used by the iTools system to create the visualization is stored and managed by the iTools Data Manager — the data is not available in the IDL context, nor does it appear in the IDL Workbench's Variables view.

The iTools procedural interface provides two routines for working with visualization data: IGETDATA and IPUTDATA. The IGETDATA routine allows you to retrieve data associated with a visualization from the iTools Data Manager into IDL's context, where you can act on it using IDL commands. Similarly, the IPUTDATA routine allows you to replace the data used by an iTool visualization with data from IDL's context.

Changing a Visualization's Data

Use the IPUTDATA routine to replace data used to create an iTool visualization with new data available in the current execution context. To replace a data variable, you will need:

The iTool identifier of the visualization whose data you want to replace, or a string that will allow the IGETID function to find the identifier

Copies of all of the variables used by the visualization

For example, suppose you have created a plot with a text annotation:

; Create some data
xdata = FINDGEN(200)
ydata1 = SIN(data1*2*!PI/25.0)*EXP(-0.01*data1)
; Create the plot
IPLOT, xdata, ydata1, TITLE='My Plot'

Now suppose you want to change the value of the dependent variable, leaving everything else about your plot unchanged:

ydata2 = SIN(data1*2*!PI/25.0)*EXP(0.01*data1)
IPUTDATA, 'plot', xdata, ydata2
ISETCURRENT, /SHOW

In this example, we pass the string `plot' to the IPUTDATA procedure to represent the iTool identifier of the plot visualization. Within the IPUTDATA routine, the string is passed to the IGETID function, which uses it to locate the full identifier for the plot line. (See Understanding iTool Identifiers and IGETID for more on IGETID.) Note that although we are only changing the value of the second data variable (replacing ydata1 with ydata2), we pass the same number of data arguments we used when initially creating the plot.

Retrieving a Visualization's Data

Use the IGETDATA routine to extract the data from an iTool visualization and place it in an ordinary IDL variable.

Why retrieve the data from the iTool visualization? You might assume that, having created the visualization in the first place, you already have the data available to you in IDL variables. While this is often the case, there are times when you may not have access to variables that represent the data that underlies the visualization. For example:

If you have restored an .isv file you received from a colleague, you will not have IDL variables containing the data used to create the iTool visualization.

If you have applied iTool operations that modify the data interactively, by selecting items from the iTools Operations menu, then the data that underlies the visualization has been modified, and no longer matches the IDL variables used to create the visualization.

If you have interactively created annotations in the iTool window, no IDL variables containing the data on which the annotations are based were created.

To extract a data variable from an iTool visualization, you will need:

The iTool identifier of the visualization whose data you want to retrieve, or a string that will allow the IGETID function to find the identifier.

For example, suppose you have created a surface visualization with the following command:

ISURFACE, HANNING(300,300)*300
ITEXT, 'My Surface', 0.5, 0.9, ALIGNMENT=0.5

Since the parameter passed to the ISURFACE procedure is itself an IDL expression, there is no IDL variable containing the result of the HANNING function created in the IDL context. You could use IGETDATA to retrieve the data and save it in an IDL variable:

IGETDATA, 'surface', surf_data
HELP, surf_data

IDL prints

SURF_DATA       FLOAT     = Array[300, 300]

Similarly, you could retrieve the text data:

IGETDATA, 'text', text_data
PRINT, text_data

IDL Prints:

My Surface