User's Reference - Data Explorer Tools

## Chapter 1. Data Explorer Tools

Partial Table-of-Contents

- 1.1 Tool Categories
- Annotation
- DXLink
- Debugging
- Flow Control
- Import and Export
- Interactor
- Interface Control
- Realization
- Rendering
- Special
- Structuring
- Transformation
- Windows

  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

  These tools create or supervise image windows.

  ReadImageWindow | reads back an image (pixels) from an Image or Display window, for both hardware and software rendered images.
  SuperviseState | watches for and acts on mouse and keyboard events in a Display window, based on user-defined callbacks.
  SuperviseWindow | creates a window which will be monitored by SuperviseState.

  [ OpenDX Home at IBM | OpenDX.org ]