The features described in this topic are obsolete
and should not be used in new IDL code.

LIVE_SURFACE

The LIVE_SURFACE procedure creates an interactive plotting environment for multiple surfaces. Because the interactive environment requires extra system resources, this routine is most suitable for relatively small data sets. If you find that performance does not meet your expectations, consider using the Direct Graphics SURFACE routine or the Object Graphics IDLgrSurface class directly.

After LIVE_SURFACE has been executed, you can double-click on a section of the surface to display a properties dialog. A set of buttons in the upper left corner of the image window allows you to print, undo the last operation, redo the last "undone" operation, copy, draw a line, draw a rectangle, or add text.

Figure 2-4: LIVE_SURFACE Properties Dialog

You can control your LIVE window after it is created using any of several auxiliary routines. See LIVE_Tools for an explanation.

Syntax

LIVE_SURFACE, Data, Data2,... [, /BUFFER] [, DIMENSIONS=[width, height]{normal units}] [, /DOUBLE] [, DRAW_DIMENSIONS=[width, height]{devive units}] [, ERROR=variable] [, /INDEXED_COLOR] [, INSTANCING={-1 | 0 | 1}] [, LOCATION=[x, y]{normal units}] [, /MANAGE_STYLE] [, NAME=structure] [, /NO_DRAW] [, /NO_SELECTION] [, /NO_STATUS] [, /NO_TOOLBAR] [, PARENT_BASE=widget_id | , TLB_LOCATION=[Xoffset, Yoffset]{device units}] [, PREFERENCE_FILE=filename{full path}] [, REFERENCE_OUT=variable] [, RENDERER={0 | 1}] [, REPLACE={structure | {0 | 1 | 2 | 3 | 4}}] [, STYLE=name_or_reference] [, TEMPLATE_FILE=filename] [, TITLE=string] [, WINDOW_IN=string] [, {X | Y}INDEPENDENT=vector] [, {/X | /Y}LOG] [, {X | Y}RANGE=[min, max]{data units}] [, {X | Y}_TICKNAME=array]

Arguments

Data

A vector of data. Up to 25 of these arguments may be specified. If any of the data is stored in IDL variables of type DOUBLE, LIVE_SURFACE uses double-precision to store the data and to draw the result.

Keywords

BUFFER

Set this keyword to bypass the creation of a LIVE window and send the visualization to an offscreen buffer. The WINDOW field of the reference structure returned by the REFERENCE_OUT keyword will contain the name of the buffer.

DIMENSIONS

Set this keyword to a two-element, floating-point vector of the form [width, height] specifying the dimensions of the visualization in normalized coordinates. The default is [1.0, 1.0].

DOUBLE

Set this keyword to force LIVE_SURFACE to use double-precision to draw the result. This has the same effect as specifying data in the Data argument using IDL variables of type DOUBLE.

DRAW_DIMENSIONS

Set this keyword equal to a vector of the form [width, height] representing the desired size of the LIVE tools draw widget (in pixels). The default is [452, 452].

Note
This default value may be different depending on previous template projects.

ERROR

Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI.

Note
If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed.

INDEXED_COLOR

If set, the indexed color mode will be used. The default is TrueColor. (See Using IDL for more information on color modes.)

INSTANCING

Set this keyword to 1 to instance drawing on, or 0 to turn it off. The default (-1) is to use instancing if and only if the "software renderer" is being used (see RENDERER). For more information, see "Instancing" in the Objects and Object Graphics manual.

LOCATION

Set this keyword to a two-element, floating-point vector of the form [X, Y] specifying the location of the visualization (relative to the lower left hand corner within the visualization window) in normalized coordinates. The default is [0.0, 0.0].

Note
LOCATION may be adjusted to take into account window decorations.

MANAGE_STYLE

Set this keyword to have the passed in style item destroyed when the LIVE tool window is destroyed. This keyword will have no effect if the STYLE keyword is not set to a style item.

NAME

Set this keyword to a structure containing suggested names for the data items to be created for this visualization. See the REPLACE keyword for details on how they will be used. The fields of the structure are as follows. (Any or all of the tags may be set.)

Table 2-35: Fields of the NAME keyword
Tag	Description
DATA	Dependent Data Name(s)
IX	Independent X Data Name
IY	Independent Y Data Name

The default for a field is to use the given variable name. If the variable does not have a name (i.e., is an expression), a default name is automatically generated. The dependent data names will be used in a round-robin fashion if more data than names are input.

NO_DRAW

Set this keyword to inhibit the visualization window from drawing. This is useful if multiple visualizations and/or annotations are being created via calls to other LIVE_Tools in order to reduce unwanted draws and help speed the display

NO_STATUS

Set this keyword to prevent the creation of the status bar.

NO_TOOLBAR

Set this keyword to prevent the creation of the toolbar.

PARENT_BASE

Set this keyword to the widget ID of an existing base widget to bypass the creation of a LIVE window and create the visualization within the specified base widget.

Note
The location of the draw widget is not settable. It is expected that the user who wishes to insert a tool into their own widget application will determine the setting from the parent base sent to the tool.

Note
LIVE_DESTROY on a window is recommended when using PARENT_BASE so that proper memory cleanup is done. Simply destroying the parent base is not sufficient.

Note
When specifying a PARENT_BASE, that parent base must be running in a non-blocking mode. Putting a LIVE tool into a realized base already controlled by XMANAGER will override the XMANAGER mode to /NO_BLOCK even if blocking had been in effect.

REFERENCE_OUT

Set this keyword to a variable to return a structure defining the names of the created items. The fields of the structure are shown in the following table.

Table 2-36: Fields of the LIVE_SURFACE Reference Structure
Tag	Description
WIN	Window Name
VIS	Visualization Name
GRAPHIC	Graphic Name(s)
XAXIS	X-Axis Name
YAXIS	Y-Axis Name
ZAXIS	Z-Axis Name
LEGEND	Legend Name
DATA	Dependent Data Name(s)
IX	Independent X Data Name
IY	Independent Y Data Name

RENDERER

Set this keyword to 1 to use the "software renderer", or 0 to use the "hardware renderer". The default (-1) is to use the setting in the IDL Workbench preferences; if the IDL Workbench is not running, however, the default is hardware rendering. For more information, see "Hardware vs. Software Rendering" in the Objects and Object Graphics manual.

REPLACE

Set this keyword to a structure containing tags as listed for the NAME keyword, with scalar values corresponding to the replacement options listed below. (Any or all of the tags may be set.) The replacement settings are used to determine what action to take when an item (such as data) being input would have the same name as one already existing in the given window or buffer (WINDOW_IN).

Table 2-37: REPLACE keyword Settings and Action Taken
Setting	Action Taken
0	New items will be given unique names.
1	Existing items will be replaced by new items (i.e., the old items will be deleted and new ones created).
2	User will be prompted for the action to take.
3	The values of existing items will be replaced. This will cause dynamic updating to occur for any current uses, e.g., a visualization would redraw to show the new value.
4	Default. Option 0 will be used for items that do not have names (e.g., data input as an expression rather than a named variable, with no name provided via the NAME keyword). Option 3 will be used for all named items.

STYLE

Set this keyword to either a string specifying a style name created with LIVE_STYLE.

TITLE

Set this keyword to a string specifying the title to give the main window. It must not already be in use. A default will be chosen if no title is specified.

TLB_LOCATION

Set this keyword to a two-element vector of the form [Xoffset, Yoffset] specifying the offset (in pixels) of the LIVE window from the upper left corner of the screen. This keyword has no effect if the PARENT_BASE keyword is set. The default is [0, 0].

WINDOW_IN

Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window or a LIVE tool buffer, in which to display the visualization. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. The default is to create a new window.

XINDEPENDENT

Set this keyword to a vector specifying X values for LIVE_SURFACE. The default is the data's index values.

Note
Only one independent vector is allowed; all dependent vectors will use the independent vector.

YINDEPENDENT

Set this keyword to a vector specifying Y values for LIVE_SURFACE. The default is the data's index values.

Note
Only one independent vector is allowed; all dependent vectors will use the independent vector.

XLOG

Set this keyword to make the X axis a log axis. The default is 0 (linear axis).

YLOG

Set this keyword to make the Y axis a log axis. The default is 0 (linear axis).

XRANGE

Set this keyword equal to a two-element array that defines the minimum and maximum values of the X axis range. The default equals the values computed from the data range.

YRANGE

Set this keyword equal to a two-element array that defines the minimum and maximum values of the Y axis range. The default equals the values computed from the data range.

X_TICKNAME

Set this keyword equal to an array of strings to be used to label the tick mark for the X axis. The default equals the values computed from the data range.

Y_TICKNAME

Set this keyword equal to an array of strings to be used to label the tick mark for the Yaxis. The default equals the values computed from the data range.

Examples

This example visualizes two surface representations. To manipulate any part of the surface, double click on surface to access a graphical user interface:

LIVE_SURFACE, tempData, pressureData 

Note

This is a "Live" situation. When data of the same name is used multiple times within the same window, it always represents the same internal data item. For example, if one does the following:
Y = indgen(10) 
LIVE_PLOT, Y, WINDOW_IN=w, DIMENSIONS=d, LOCATION=loc1 
Y = indgen(20) 
LIVE_PLOT, Y, WINDOW_IN=w, DIMENSIONS=d, LOCATION=loc2

The first plot will update to use the Y of the second plot when the second plot is drawn. If the user wants to display 2 "tweaks" of the same data, a different variable name must be used each time, or at least one should be an expression (thus not a named variable). For example:

LIVE_PLOT, Y1,... 
LIVE_PLOT, Y2,...

or;

LIVE_PLOT, Y,... 
LIVE_PLOT, myFunc(Y),...

In last example, the data of the second visualization will be given a default unique name since an expression rather than a named variable is input.

Note
The above shows the default behavior for naming and replacing data, which can be overridden using the NAME and REPLACE keywords.

Version History

Introduced: 5.0