Chapter 1. Data Explorer Tools

Partial Table-of-Contents

Data Explorer tools (i.e., tool modules) perform a variety of functions to generate visual images. In the VPE window, their icons can be used as "building blocks" to create visual program networks, from which images are generated in the Image window. They can also be invoked from script-language programs or from the command line (when Data Explorer is in "script mode"). And they can be grouped together in macros for greater efficiency.

Many modules are accessible through both the graphical user interface and the scripting language. Some, however, are available only through the user interface: the Interactors, the Color Editor, Image, Pick, Probe, Receiver, and Transmitter. Most have default values for parameter inputs, values that are (as much as possible) appropriate for the data involved. These defaults enable the new user to begin visualizing data with only a few connections and to customize a visualization program one step at a time.

Tools are divided into the categories listed in the tool palette of the VPE window:

• Annotation
• DXLink
• Debugging
• Flow Control
• Import and Export
• Interactor
• Interface Control
• Realization
• Rendering
• Special
• Structuring
• Transformation
• Windows
• {ALL} (an alphabetic listing of all the tools).

The directory /usr/local/dx/samples/programs contains visual program examples that use these tools, along with a subdirectory (.../SIMPLE) of simpler examples. Use the Open file-selection dialog box to call up either directory (adding "/*.net" to the directory name when you enter it in the Filter text field). For a description of a visual program, either highlight the program name in the Files list of the dialog box and click on the Comments pushbutton or select the Application Comment option of the Help pull-down menu (after the visual program is loaded).

The directory /usr/local/dx/samples/scripts contains script examples for all of the modules. Descriptions are included as comments in the script files themselves.

The rest of this chapter summarizes the tool categories and the tools they contain. The order in which they appear is the same as that displayed in the palettes of the VPE window. For detailed descriptions of individual tools, see Chapter 2. "Functional Modules".

Note: Two modules that appear in Chapter 2. "Functional Modules" are available only in script mode and so are not listed in any of the Visual Program Editor categories:

Executive	Executes an executive command (see Executive).
KeyIn	Waits for input from the system prompt in the window from which you invoked Data Explorer (see KeyIn).

1.1 Tool Categories

Annotation

These tools add various kinds of information to a visualization.

AutoAxes	Creates an axes box for a specified data set, using a specified camera. The camera is required so that the AutoAxes module can determine how to position the axes box and labels.
AutoGlyph	Produces glyphs (a representational figure, such as an arrow) for every data value in an input Field. The size and type of glyph are based on the data it receives.
Caption	Creates a caption for an image. The caption position specified in pixel- or viewport-relative coordinates. Captions always remain aligned to the screen.
ColorBar	Creates a color bar to be displayed on the screen. It accepts a color map as input.
Format	Creates a string from numeric values. For example, you can create the string "Isosurface value = 23.4", where 23.4 is the output of an Interactor.
Glyph	Produces glyphs for every data value in an input Field. This module allows more precise control of glyph size than AutoGlyph does.
Legend	Produces a legend which associates a string with a color.
Parse	Separates a string into its component parts (e.g., the string "data = 3.7" into "data", "=", and the floating point value "3.7").
Plot	Creates a 2-dimensional plot from a line. You can specify: customized labels for the axes; axes limits; y-axes on the left and right sides of the plot; and logarithmic or linear axes.
Ribbon	Produces a ribbon of specified width from an input line. If a "normals" component is present on the line (e.g., if the curl option was used to create a streamline or streakline), the twist of the ribbon will correspond to the direction of the "normals."
Text	Produces text that appears in the "space" occupied by the image. That is, unlike Caption, this module specifies the text position and size in the same coordinates as the data.
Tube	Produces a tube of specified diameter and number of sides from an input line. If a "normals" component is present on the line (e.g., if the curl option was used to create a streamline or streakline), the twist of the tube will correspond to the direction of the "normals."

DXLink

These tools are used to control Data Explorer from a separate program.

Note: According to UNIX alphabetical convention, capital letters precede lower case. Thus DXLink precedes Debugging in the category pallet of the VPE, and the DXLink routines precede Direction in the tools pallet and in the routine descriptions in Chapter 2. "Functional Modules".

DXLInput	Enables a remote DXLink application to set a parameter value in a visual program.
DXLInputNamed	Enables a remote DXLink application to set a parameter value in a visual program, but also allows the name of the variable to be set via a wire into the DXLInputNamed tool.
DXLOutput	Sends a value to a remote application.

Debugging

These tools facilitate the analysis of a program's execution.

Describe	Presents information about any Data Explorer object in the Message window.
Echo	Echoes a message. It can also print simple Array Objects (e.g., output of the Statistics module). In the user interface this output appears in the Message window.
Message	Displays a message to the user, either in the Message window or in a pop-up dialog box.
Print	Prints information about an Object (e.g. a Field or a Camera). You can specify the level of detail. In the user interface the output appears in the Message window.
System	Allows you to execute arbitrary operating-system commands.
Trace	Enables the tracing of time spent in a module, tracing of memory, or the use of debugging flags or user-written modules.
Usage	Prints the amount of memory currently being used by Data Explorer.
Verify	Checks an Object for internal consistency.
VisualObject	Creates a renderable object representing an object's hierarchy.

Flow Control

These tools control the flow of execution in a visual program.

For additional information, see Chapter 4. "Data Explorer Execution Model" in IBM Visualization Data Explorer User's Guide.

Done	Specifies whether an executing loop should terminate.
Execute	Allows the user to change the execution state of a visual program without using the Execute pull-down menu in the user interface.
First	Indicates whether the current iteration of the loop is the first.
ForEachMember	Initiates a loop for each member of a group or item in an array.
ForEachN	Iterates through a specified set of integers.
GetGlobal	Retrieves an object from the cache. Maintains state between executions.
GetLocal	Retrieves an object from the cache.
Route	Routes an Object through selector-specified output paths.
SetGlobal	Places an object in the cache. Maintains state between executions.
SetLocal	Places an object in the cache.
Switch	Switches the output between a list of inputs.

Import and Export

The first two tools listed, along with ReadImage and WriteImage, are concerned with the flow of data into and out of a visual program. The others typically process data immediately after it has been imported.

Export	Exports Objects created in Data Explorer to an external data file (in Data Explorer file format).
Import	Brings data into Data Explorer from a specified file. If the file contains more than one variable or contains multiple frames of data, portions of the data can be specified for importation. Supported formats are native Data Explorer format, CDF, netCDF, HDF, and General Array format.
ImportSpreadsheet	Brings data into Data Explorer from spreadsheet, or tabular, data file.
Include	Includes (or excludes) points based on their data values (e.g., removing all points with data values greater than 9.3). It can also be used to remove data marked as invalid.
Partition	Subdivides data to take advantage of parallelism for Data Explorer SMP. You can control the level of subdivision.
ReadImage	Reads an image from an external file.
Reduce	Reduces the resolution of a data set, filtering and resampling the set at a lower resolution.
Refine	Increases the number of samples in a data set. This module interpolates data values or colors at the new positions from the data or color values at the original positions. It can also convert connections from quads or faces to triangles, and from cubes to tetrahedra.
Slab	Takes a positional subset of a data set with regular connections (cubes, quads, and lines). You can specify along which axis to take the subset, where the slab should begin, and how thick the slab is to be. The module performs no interpolation.
Slice	Takes a positional subset of a data set with regular connections, like the Slab module. However, unlike the Slab module, it creates output with a dimensionality 1 less than the dimensionality of the input. For example, you can import a data set as a 4-dimensional grid, with the fourth dimension representing time. You can then use the Slice module to create 3-dimensional slices of the data set.
Stack	Stacks a series of n-dimensional Fields to form a single (n+1)-dimensional Field. This module can also be used to increase the dimensionality of a single Field.
Transpose	Transposes the positions of a Field. For example, it can interchange the x and y axes.
WriteImage	Writes an image to an external file in a specified format. The same functionality is provided by the SaveImage option of the File pull-down menu of the Image window.

Interactor

These tools provide interactive control of inputs to other modules in visual programs. They can be used only with the user interface.

For additional information, see 7.1 , "Using Control Panels and Interactors" in IBM Visualization Data Explorer User's Guide. Interactors are named after the type of data they control:

FileSelector	Presents a standard Motif file-selector dialog box. The output is a file name.
Integer	Presents a stepper, slider, dial, or text interactor. The output is a whole number.
IntegerList	Presents a scrolled-list or text interactor. The output is a list of integers.
Reset	Presents a toggle button. The output is one value the first time it is run, and a different value on subsequent runs until the toggle is selected again.
Scalar	Presents a stepper, slider, dial, or text interactor. The output is a real number.
ScalarList	Presents a stepper, slider, dial, or text interactor. The output is list of scalar values.
Selector	Presents an option menu, a set of radio buttons, or a toggle button. The outputs are a value and a string, representing a choice from a selection.
SelectorList	Presents a selection list. The output is a list of values and a list of strings, representing a choice of one or more from many.
String	Presents a text interactor. The output is a text string.
StringList	Presents a scrolled-text list. The output is a list of strings.
Toggle	Presents a toggle button. The output is one of two values (set or unset).
Value	Presents a text interactor. The output is a value (scalar, vector, tensor, or matrix).
ValueList	Presents a scrolled list or text interactor. The output is a value list.
Vector	Presents a stepper or text interactor. The output is a vector.
VectorList	Presents a scrolled-list or text interactor. The output is a vector list.

Interface Control

These tools are used to control Data Explorer tools from within a visual program.

ManageColormapEditor	Allows colormap editors to be opened and closed from within a visual program.
ManageControlPanel	Allows control panels to be opened and closed from within a visual program.
ManageImageWindow	Allows image windows to be opened and closed from within a visual program.
ManageSequencer	Determines whether the Sequence control panel is displayed or not.

Realization

These tools create structures for rendering and display (e.g., bands, triangle connections, isosurfaces, and boundary boxes).

AutoGrid	Maps a set of scattered points onto a grid. The grid will be created automatically by Data Explorer.
Band	Divides a Field into bands based on given division values.
Connect	Creates triangle connections for a Field of scattered positions.
Construct	Constructs an arbitrary Field. You can specify the origin, the deltas, the counts in each dimension, and the data. You can also use Construct to create a Field containing a "positions" component with given position values (e.g., the output of the ProbeList tool).
Enumerate	Generates a numeric list.
Grid	Produces a set of points on a grid. You can construct rectangles, ellipses, lines, crosshairs, and bricks. You can specify the size of the object and the number of points in the grid.
Isolate	Shrinks the connections elements of a Field so that they can be individually seen.
Isosurface	Creates surfaces or lines of constant value. For volumetric inputs, it creates isosurfaces; for surface inputs, contour lines. Use the ClipPlane module to display the interior of an isosurface.
MapToPlane	Maps a 3-dimensional data Field onto an arbitrary plane. You can specify a point and a normal to define the plane.
Regrid	Maps a set of scattered points onto a specified grid.
RubberSheet	Deforms a surface field (composed of triangles, quads, or lines) by an amount proportional to the data value at each point. You can use the Normals or FaceNormals module to add shading before rendering.
Sample	Produces a set of points in an arbitrary field. For example, you can produce a set of approximately evenly spaced samples on an isosurface.
ShowBoundary	Creates a renderable object that is the boundary of a volumetric field.
ShowBox	Creates a set of renderable lines that represent the bounding box of a field.
ShowConnections	Creates a set of renderable lines that represent the connections of elements in a field.
ShowPositions	Creates a set of renderable points that represent the positions of a field.
Streakline	Computes a line that traces the path of a particle through a changing vector field. The data input to the module is a vector field series, or a single field that is a member of a vector field series. You can control the starting points of the streaklines, and can optionally provide a curl field to produce twist on any ribbons or tubes constructed from the streakline.
Streamline	Computes a line that traces the path of a particle through a constant vector field. The data input to the module is a vector field. You can control the starting points of the streamlines, and can optionally provide a curl field to produce twist on any ribbons or tubes constructed from the streamline.

Rendering

These tools create a displayable image from a renderable object or modify the visual characteristics of the object(s) being displayed. For example, Normals and FaceNormals could be used to add shading to a geometrical structure created with RubberSheet (Realization category), while Light and AmbientLight could be used to change its default lighting.

AmbientLight	Produces an ambient light. You can specify the color of the light. Ambient lights illuminate a surface equally, regardless of direction, so an object illuminated only with ambient light is not shaded. Note that it is not necessary to specify an ambient light, because a small amount of ambient light is built into the object model. However, explicitly specified lighting overrides the default lighting.
Arrange	Creates a single image from a collection of images. You can specify how many images to put in a row.
AutoCamera	This module produces an appropriate camera as input to the Render or Display module. Specifying a "look-from" direction changes this default camera. The width of the image in model units (orthographic projection) or the field of view (perspective projection), or the image size and aspect ratio can also be changed.
Camera	Produces a camera for input to the Render or Display module. You can specify the "look-to" point, the "look-from" point, the width of the image in units corresponding to those in the data, the image size, and the aspect ratio. Camera differs from AutoCamera in that it specifies a "look from" a point instead of a direction.
ClipBox	Clips an object using a box. You can specify the box explicitly, as the two corners defining a box, or it can be the bounding box of an object. The module renders only that part of the object inside the box. The Render, Display, or Image tool actually performs the clipping.
ClipPlane	Clips an object by a plane. The user specifies the plane with a point and a normal. The side of the plane the normal projects into is the side that will be clipped (i.e., not displayed). The Render, Display, or Image tool performs the clipping.
Display	Renders and/or displays an image to the screen. If a camera is not provided, the Display module expects the first input to be an image (e.g., the output of Render or Arrange).
FaceNormals	Computes normals on a surface. When you use the FaceNormals module, each face of the surface is flat-shaded.
Image	This tool renders and displays an image to the screen. It performs like the AutoCamera and Display modules combined. Using the Image tool to render an image enables many direct interactors that are not available when using AutoCamera and Display. These options are available in the View Control option of the Options pull-down menu in the Image window. For example, see "Controlling the Image: View Control..." in IBM Visualization Data Explorer User's Guide. The Image tool is available only in the graphical user interface.
Light	Produces a distant point light. You can specify the direction and color of the light. Note that it is not necessary to specify a light, because there is a default light built into the object model; however, explicitly specified lighting overrides the default lighting.
Normals	Computes point or face normals for shading a surface. For example, you can use this module to produce shading on rubbersheets and boundaries. However, shading on an isosurface is smoother if you use the gradient shading options built into the Isosurface module.
Overlay	Overlays two images. The result is a new image that can be displayed using the Display module. The new image is a pixel-by-pixel sum of the two images, where 1 - blend attenuates the base-image pixels, and blend attenuates the overlay-image pixels, (blend is a value between 0 and 1). You can also perform chromakeying by specifying blend as an RGB color or as a string specifying a color.
Render	Renders an object and creates an image. The object can be any combination of volumes, surfaces, lines, and points, and you can clip the object. You need to provide a camera to the Render module to specify the viewing direction.
Reorient	Rotates or inverts an image or a group of images.
Rotate	Rotates an object around specified axes. The Render, Display, or Image tool actually performs the rotation.
Scale	Changes an object's dimensions along the x, y, and z axes. The scaling is actually performed in the Render, Display, or Image tool.
ScaleScreen	Scales all screen objects (typically captions and color bars) by a specified amount.
Shade	Allows you to specify object-shading parameters such as specularity.
Transform	Moves, rotates, and resizes an object. The Render, Display, or Image tool actually performs the translation.
Translate	Moves an object along the x, y, and z axes. The Render, Display, or Image tool actually performs the translation.
UpdateCamera	Makes specified alterations to the input camera.

Special

Tools in this category can be used in visual programs for a variety of purposes.

Note: For details, see the sections of the IBM Visualization Data Explorer User's Guide referred to in the following list.

Colormap	Presents an interactor tool for creating color maps.
Input	Defines an input to a macro. See 7.2 , "Creating and Using Macros" for information.
Output	Defines an output of a macro. See 7.2 , "Creating and Using Macros" for information.
Pick	Allows the user to pick objects in a scene using the mouse. See "Using Pick" for information.
Probe	Allows the user to pick an xyz point in a scene using the mouse. See "Using Probes (Cursors)" for information.
ProbeList	Allows the user to pick multiple xyz points in a scene using the mouse. See "Using Probes (Cursors)" for information.
Receiver	Receives the output of a transmitter for "wireless" connections. See "Using Transmitters and Receivers" for information.
Sequencer	Allows animation of a visual program. See "Using the Sequencer" in IBM Visualization Data Explorer User's Guide for information.
Transmitter	Outputs an Object for "wireless" connections. See "Using Transmitters and Receivers" for information.

Structuring

These tools manipulate Data Explorer data structures. Their functions include the creation of hierarchies, selection of elements in a hierarchy, allowing operations on components other than "data," manipulation of Field or Group components, and determining which branches of a visual program are to be executed.

Append	Adds Objects as members to an existing Group.
Attribute	Extracts an attribute from an Object.
ChangeGroupMember	Inserts, renames, or deletes a member of an existing Group.
ChangeGroupType	Changes the type of a Group.
Collect	Collects Objects into a Group. For example, you can use Collect to collect a streamline, an isosurface, and a light. You can then pass the collection to the Image tool.
CollectMultiGrid	Collects Objects into a Multigrid (a Group that will be treated as a single data Object).
CollectNamed	Collects Objects into a Group (like Collect) but allows each Object in the Group to be given a name.
CollectSeries	Collects Objects into a Series. You give each element of the series a series position (e.g., a time tag).
CopyContainer	Copies the top container Object.
Extract	Extracts a component from a Field (e.g., the "colors" component).
Inquire	Returns information about the input Object (e.g., data type, number of elements, etc.).
List	Concatenates several items into a single list.
Mark	Marks a specified component in a Field as the data component. Many modules operate only on the "data" component. Thus the Mark module allows modules to operate on components other than data (e.g., "positions" or "colors"). If a "data" component already exists, it is preserved in a "saved data" component. You can restore it by using the Unmark module.
Options	Associates attributes with an Object. For example, plotting options such as marker type can be specified by adding attributes to the line.
Remove	Removes a specified component from a Field.
Rename	Renames a component in a Field. For example, you could rename the "colors" component to "front colors" to get only front-facing colors. You should be aware that component names have special meanings to modules using them. See Chapter 3. "Understanding the Data Model" in IBM Visualization Data Explorer User's Guide.
Replace	Replaces a component in one Field with a component from another, or with an input Array.
Select	Selects members out of a Group or elements from a list. two isosurfaces, a streamline, and a mapped plane. You could then use the selector input to the module to choose which of these is the output of the module.
Unmark	Undoes the action of the Mark module. It moves the "data" component back to the component you specify, and the "saved data" component is restored to the "data" component.

Transformation

These tools generally modify or add to components of the input Field without changing its underlying positions and connections. For example, AutoColor creates a "colors" component based on the data values of a Field and Compute performs a mathematical operation on the "data" component of a Field.

AutoColor	Automatically colors a data Field. By default, the minimum data value is blue, the maximum data value is red, and data values between are blue to red through cyan, green, and yellow. You can control what subset of the data range to color and what portion of the color wheel to use. You can also control the opacity of the object and the intensity of the colors. AutoColor also chooses appropriate colors and opacities for volume rendering.
AutoGrayScale	Automatically colors a data field using a gray scale.
Categorize	Categorizes data, creating an integer data component along with a lookup table into which the integers reference.
CategoryStatistics	Performs various statistics such as minimum, maximum, number of items, etc., on categorical data.
Color	Allows you more control over the coloring of an object than is possible with AutoColor. You can specify a string representing a color (e.g., "spring green"), an RGB color, or a color map (from the Colormap Editor, for example) to be applied to a data Field. You can also use the Color module to make objects (e.g., isosurfaces) translucent.
Compute	Performs point-by-point arithmetic on a Field or Fields. For example, it can add the "data" component of one Field to the tangent of the "data" component of another Field. You can also use the Compute module to select components from a vector data Field; construct a vector "data" component from a set of scalar input data Fields; or perform conditional operations.
Compute2	Differs from Compute in allowing the expression to be passed in by means of an input tab (e.g., from a Selector interactor).
Convert	Converts between hue, saturation, and value color space and red, green, and blue color space. You can convert either a single vector, a list of vectors, or a color map.
DFT	Performs a discrete Fourier transformation on a 2- or 3-dimensional field.
Direction	Converts azimuth, elevation, and distance to Cartesian coordinates (x, y, and z), which are useful for specifying camera viewing directions and for specifying ClipPlane or MapToPlane normal directions.
DivCurl	Computes the divergence and the curl of a vector field.
Equalize	Applies histogram equalization to a field.
FFT	Performs a fast Fourier transformation on a 2- or 3-dimensional field.
Filter	Filters a Field. You can specify a name describing a filter (e.g., "laplacian") or a filter matrix explicitly.
Gradient	Computes the gradient of a scalar Field.
Histogram	Computes a histogram and the median of an input data Field. You can then use Plot to visualize the result as a 2-dimensional graph.
Lookup	Uses one object to look up the value of another object in a field.
Map	Maps Fields onto one another. For example, you can map a data Field onto an isosurface or onto a tube that has been formed from a streamline.
Measure	Performs measurements (e.g., surface area or volume) on a data Object.
Morph	Applies a binary morphological operator, such as erode or dilate.
Post	Changes the dependency of data (and other components) between positions and connections.
QuantizeImage	Converts an image from a format containing (potentially) as many colors as pixels to a quantized image with a color map with a user-specified number of colors between 8 and 256.
Sort	Sorts a list or Field based on values in the data component.
Statistics	Computes the statistics of a Field: the mean, standard deviation, variance, minimum, and maximum. You can use these statistics as input for other modules, or print them using the Echo or Print modules.

Windows