ParaView/Users Guide/Annotation

Annotation

In ParaView, there are several ways to annotate the data to better understand or explain it. Several of the annotations can be interactively placed in the 3D scene. The parameters of the annotations are controlled using traditional user interface elements. Some types of annotation are discussed in other parts of this book. See section Error: Reference source not found for information about labeling points or cells in a data set. See sections Error: Reference source not found and Error: Reference source not found for a discussion of plotting.

Scalar Bar

The most straightforward way to display a scalar bar (or color legend) in the active 3D view is to use the color legend visibility button on the Active Variables Control toolbar. When the data set selected in the Pipeline Browser is being colored by a variable (i.e., something other than Solid Color is selected in the Color by menu on the Display tab), this button is active. Clicking it toggles the visibility (in the selected 3D view) of a scalar bar showing the mapping from data values to colors for that variable.

The interface for changing the color mapping and properties of the scalar bar is accessible from the Display tab of the Object Inspector. Pressing the Edit Color Map button displays the interface for manipulating the color map and scalar bar as shown below. For instructions on displaying the Edit Color Map button, see section Error: Reference source not found, Error: Reference source not found.

Figure 1. Color Map Controls

At the top of the Color Scale tab of the Color Scale Editor dialog is an editor for mapping scalar values to colors (for surface rendering) and also to opacity (for volume rendering). The scalar range of this color map editor is shown below the Automatically Rescale to Fit Data Range check box. The leftmost sphere corresponds to the minimum scalar value, and the rightmost one corresponds to the maximum. Any interior nodes correspond to values between these two extremes. New nodes may be added to the color editor by left-clicking in the editor; this determines the scalar value associated with the node, but that value may be changed by typing a new value in the Scalar Value text box below the color map editor or by clicking and dragging a node. (The scalar value for a particular node may not be changed such that it is less than that for a node left of it or greater than that for a node right of it.) When volume rendering, the vertical height of a node indicates its opacity. For surface rendering, opacity is determined for an entire data set, not based on the underlying scalar values.

When a node in the color map editor is clicked, it becomes highlighted (i.e., drawn larger than the other spheres in the editor). In the example above, the second node from the left has been selected. Clicking again on the selected node displays a color chooser from which you may select a new color for the node. Pressing the ‘d’ or Delete key while a node is selected removes that node from the editor. Only the endpoint nodes may not be deleted.

Below the color map editor (or transfer function editor, for volume rendering) is a set of three text boxes for changing the scalar value, opacity, and scale associated with a given node. Only the scalar value is associated with surface rendering. The scalar values at the endpoints may only be changed if the Automatically Rescale to Fit Data Range check box (discussed later in this section) is unmarked. When volume rendering, you may also specify the opacity and scale per node in the editor. In volume rendering, the opacity is accumulated as you step through the volume being rendered. The Scale value determines the unit distance over which the opacity is accumulated.

The controls below the set of three text boxes specify the color space and any color map preset you wish to save or use. The color spaces available are RGB (red, green, blue), HSV (hue, saturation, value), Wrapped HSV, and CIELAB (a more perceptually linear color space). The color space determines how the colors are interpolated between specified values; the colors at the color map (or transfer function) editor nodes will remain the same regardless of the color space chosen. If wrapped HSV is used, the interpolation will use the shortest path in hue, even going through the value hue = 0. For non-wrapped HSV, the hue interpolation will not pass through 0. (A hue of zero sets the color to red.)

In addition to choosing the color space and modifying the color map / transfer function nodes, you may also create and load preset color scales. (When volume rendering, only the color map is stored; the scalar-to-opacity mapping is not.) To store your current settings as a preset, click the Save button. In the dialog box that appears, you may enter a name for your new preset. By default, the scalar values from the data array being used are stored in the preset. If you wish these values to be normalized between 0 and 1, press the Normalize button.

Figure 2. Dialog for choosing color scale presets.

Any presets you save, in addition to the default ones provided by ParaView, are available by pressing the Choose Preset button, causing the dialog shown below to be displayed. Selecting a preset and clicking OK causes the current color map to be set to the chosen preset. Any user-defined presets may be normalized (as discussed above) or removed from the list of presets entirely using the Normalize and Remove buttons, respectively. (The default presets are already normalized and may not be removed from the application.)

Any of the color scale presets may be exported to a file using the Export button in the above dialog. The resulting file(s) may then be copied to another computer for use with ParaView on a different machine. In order to load presets that are stored in such files, press the Import button on the above dialog, and navigate to the desired color preset file.

If the current data set is colored by an array of vectors, the Component menu will be enabled. It determines whether the data is colored by a single vector component (X, Y, or Z) or by the vector’s Magnitude (the default). If the data is colored by a single-component (scalar) array, then the Component menu is disabled.

If Use Logarithmic Scale is checked, then instead of the scalar values in the data array being used directly to determine the colors, the base-10 logarithm of the data array values is computed, and the resulting value is used for extracting a color from the color map. If the data array contains values for which a logarithm would produce invalid results (i.e., any values less than or equal to 0), the range for the color map is changed to [0, 10] so that the logarithm produces valid results.

By default, any data attribute that has been used to color a data set currently loaded in ParaView whose name and number of components match that of the array selected in the Color by menu contributes to the range of the color map. To change this behavior, first uncheck the Automatically Rescale to Fit Data Range check box. (This ensures that the range of the color map is not reset when the range of the data attribute changes.) The minimum and maximum values of the color map can be overridden by pressing the Rescale Range button, entering different Minimum and Maximum values in the dialog that appears, and pressing Rescale; this rescales all the nodes in the color map so that the scalar values lie at the same normalized positions. Alternatively, you may modify the scalar values of any node (including the endpoints if Automatically Rescale to Fit Data Range is off) by clicking a node to highlight it and typing a new value in the Scalar Value entry box. By changing the minimum and maximum color map values, it is possible to manually specify what range of data values the color map will cover. Pressing the Rescale to Data Range button on the Color Scale tab of the Color Scale Editor sets the range to cover only the current data set.

If Use Discrete Colors is checked, the Resolution slider at the bottom of the dialog specifies the number of colors to in the color map. The scale ranges from 2 to 256 (the default). The fewer the number of colors, the larger the range each color covers. This is useful if the data attribute has a small number of distinct values or if larger ranges of the array values should be mapped to the same color.

Figure 3. Scalar Bar controls

On the Color Legend tab, there are several different parameters available to you. First is the Show Color Legend check box which toggles the visibility of the scalar bar (color legend) in the 3D view. This has the same effect as using the color legend visibility [[Image:]] button on the Active Variable Controls toolbar. Below the Show Color Legend check button are the controls for displaying the title and labels on the scalar bar. In the Title section, the Text entry box specifies the label that appears above the scalar bar. It defaults to the name of the array used for coloring the data set. If the current data set is being colored by a vector array, the value of the second entry box defaults to specifying how the color is determined from the vector (i.e., X, Y, Z, or Magnitude). The entry box labeled Labels contains formatting text specifying the form of the scalar bar labels (numbers). The format specification used is the same as that used by the printf function in C++.

Below each of the Title and Labels entry boxes are controls for determining how the title and labels will be drawn in the display area. The leftmost control is a menu for choosing the font; the available fonts are Ariel (the default), Courier, and Times. Next are three formatting attribute buttons controlling whether the text is boldfaced, italicized, or shadowed, respectively. The next interface control is a spin box for controlling the text’s opacity. It ranges from 0 (transparent) to 1 (opaque).

At the bottom of this tab is a Number of Labels spin box. This determines how many scalar-value labels will be shown alongside the scalar bar.

When the scalar bar is displayed in the 3D scene, it can be positioned and resized interactively, similar to interacting with 3D widgets. (See section Error: Reference source not found.) Clicking and dragging the scalar bar with the left mouse button repositions it in the display area. If the scalar bar begins to move beyond the left or right side of the display area, it is reoriented vertically. It is reoriented in a horizontal direction if it is moving off-screen at the top or bottom of the display area. The scalar bar can be resized by left-clicking and dragging any of its sides or corners.

Figure 4. Scalar Bar displaying X-component of Normals

Orientation Axes

When interacting with data in ParaView, it can be difficult to determine how the data set is oriented in 3D. To remedy this problem, a marker showing labeled 3D axes (i.e., orientation axes) can be displayed. The orientation of the axes matches that of the data, and the axes reorient themselves as the camera is rotated about the 3D scene. (See section Error: Reference source not found, Error: Reference source not found.)

Figure 5. 3D Orientation Axes

The user interface controls for the orientation axes are located in the Annotation section of the View Settings dialog (View menu, View Settings) for the 3D view. The check box beside the Orientation Axes label toggles the visibility of the orientation axes. The Interactive check box controls whether the orientation axes can be repositioned and resized through mouse interaction, similar to interacting with 3D widgets. (See section Error: Reference source not found.) Left-clicking and dragging the orientation axes repositions them in the 3D view. When the orientation axes are in interactive mode, a bounding rectangle (outline) is displayed around the axes when the mouse moves over them. Left-clicking and dragging on the edges of this outline resizes the orientation axes. From the Set Outline Color button (enabled when Interactive is checked), you can change the color used for displaying the bounding rectangle. This is useful for making the outline more visible if its current color is similar to the color of the background or any object behind the outline (if the orientation axes are placed in front of a data set). The orientation axes are always drawn in front of any data set occupying the same portion of the 3D view. The Axis Label Color button allows you to change the color of the labels for the three axes. The reasons for changing the color of the axis labels are similar to those for changing the outline color.

Figure 6. User interface controls for orientation axes (in 3D view’s view settings dialog)

Text Display

Often users want to display additional text in the 3D view (e.g., when generating a still image or an animation). In ParaView, there are a variety of ways to do this, all through the use of sources and filters. The Text source displays 2D text in the 3D scene, the 3D Text source does the same for 3D text, and the Annotate Time filter shows the current time using a text annotation in the 3D view.

Text Source

The Text source allows you display arbitrary 2D text in a 3D view. It is available from the Sources menu. On its Properties tab, enter whatever text you wish to be displayed in the Text entry area, and press the Apply button.

Once the text has been added to the 3D view, you can reposition it within the view by left-clicking and dragging the text. (A bounding box will be displayed around the text.) By default, the text is displayed in the lower left corner of the 3D view.

The Display tab in the Object Inspector for the Text source is different than for most other sources and filters displayed in the 3D view. Specific controls are given for positioning the text and setting various font properties.

Figure 7. Display tab for the Text source

The first check box, Show Text, toggles the visibility of the text in the 3D view. This corresponds to the eye icon in the Pipeline Browser for this source. The Interactive check box below it determines whether the text may be interactively repositioned by clicking and dragging in the 3D view.

The Text Property section of the Display tab allows you to specify various parameters relating to the font used for displaying the text. The Font Size spin box determines how large the letters in the text will be. The Font menu determines which font type will be used: Ariel, Courier, or Times. The three buttons beside this menu indicate whether the text will be drawn boldfaced, italicized, and/or using shadows. The Align menu specifies whether the text will be left-, center-, or right-aligned within its bounds box. The Opacity spin box determines how opaque the text appears. An opacity value of 0 corresponds to completely transparent text, while an opacity value of 1 means completely opaque text. The Color button beside the Opacity spin box allows you to choose a color for the text.

The Text Position of the Display tab is used for specifying exactly where in the 3D view the text appears. If Use Window Location is unchecked, then the Lower Left Corner section is active. The two spin boxes provided determine the X and Y coordinates of the lower left corner of the bounding box of the text, specified in normalized coordinates (starting from the lower left corner of the view).

If Use Window Location is checked, then the six buttons in that section of the interface become available. They allow you to choose various locations within the view for anchoring the text. Using the top row of buttons, you may place the text in the upper left corner, in the top center of the view, or in the upper right corner, respectively. The bottom row of button behaves similarly for the bottom portion of the 3D view.

3D Text Source

Whereas the Text source (described above) positions text in 2D, overlaying the 3D scene, the 3D Text source places text in the 3D scene. The text is affected by rotation, panning, and zooming as is any other object in the 3D scene. The Display tab for sources of this type is the same as for any other reader, source, or filter displaying data in a 3D view.

Annotate Time Filter

The Annotate Time filter is useful for labeling a time-varying data set or animation with ParaView’s current time in a 3D view. It is drawn as a 2D label, similar to the output of the Text source. The Properties tab for this filter provides a single text box labeled Format. From this text box, you may specify a format string (printf style) indicating how the label will appear in the scene. As with the output of the Text source, this label may be interactively repositioned in the scene. The Display tab for this source is the same as the one for the Text source; it is described earlier in this section.

[[Image:]] Figure 8. Using the Annotate Time filter to display the current time in a time-varying data set