Pseudo-coloring of surfaces and volumes is one of ParaView’s primary methods of displaying data. ParaView’s color legend provides an important link between color and data values, and is a critical component of many visualizations. Over the years, ParaView’s color legend features have expanded to cover numerous usage scenarios, including annotating specific values with text, showing the color assigned to NaN values, showing categorical colors, and controlling different elements of the color legend such as font size and style.
The color legend’s versatility unfortunately came with a somewhat complex implementation. The previous implementation made it challenging to debug when problems arose and difficult to augment when new features were needed. For ParaView 5.4, we have added a new color legend implementation that resolves a number of existing bugs and paves the way to make adding features easier in the future.
The new color legend has some key differences from its older counterpart.
Nicer automatic labels
One of the complaints with the previous color legend involved the numbers chosen for labels. These numbers were chosen by subdividing the numeric range assigned to the color legend into evenly spaced intervals. Not infrequently, seemingly odd choices of scalar values that required a large number of decimal places would be chosen for labels. In the new color legend we use the same algorithm used by ParaView’s 2D charts to compute “nice” label values that have a more compact representation based on multiples of 2, 5 or 10.
You will also notice that the title placement has changed for vertically oriented color legends. Instead of having a horizontal orientation that can potentially use up a lot of horizontal and vertical space, the title is rotated to be vertically aligned with the length of the color legend.
Another key difference with labels in the new color legend is that the number of labels is determined automatically by how many nice numbers fit within the span of the long dimension of the legend. In the prior implementation, one could specify a maximum number of labels, but this property was really just a suggestion that did not always work out in a satisfactory way. Note that if you are not satisfied with the automatic labels in the new color legend, you can exercise total control of the labeled values with the feature described in the next section.
Label with specific values
A new feature in the color legend enables one to specify the exact labels displayed by the color legend. When enabled, the automatically computed label values will be replaced with the requested labels. This gives total control over the label values that are displayed.
Out-of-range colors are now displayed
The Above Range and Below Range colors can be assigned to all values that fall either above or below the numeric range assigned to the color legend. Colors for these values were not displayed in the color legend in the previous version. They are presented in the new version as color swatches at either end of the color bar. The NaN color swatch remains available in the new color legend.
Improved annotation layout
The new color legend continues to support annotations that are useful for labeling special values with arbitrary text. There were certain configurations where the annotation text was laid out in unexpected ways in the old color legend; the new legend improves on the layout.
More precise font control
In the previous color legend, the displayed font size was indirectly related to the specified font size. The size of the color legend affected the scaling of the requested font size which often lead to a disconnect between the font size that was requested and the font size that was displayed on the screen. The new color legend respects the requested font size regardless of the size of the color legend.
More precise color bar thickness control
Like font size, the thickness of the color bar (the smaller dimension) was controlled by an aspect ratio that related the length and thickness of the scalar bar. The thickness would change size if the scalar bar length was changed. In the new color legend, the color bar thickness is specified in terms of points, much like how font sizes are specified. Some examples below show the relation between scalar bar thickness and font size.
Setting color legend position
While the new color legend supports interactive dragging to position it in any location on the screen, a new Window Location property lets you specify one of six predefined window locations: Lower Left Corner, Lower Right Corner, Lower Center, Upper Left Corner, Upper Right Corner, and Upper Center. When one of these window locations is chosen, the color legend will stay anchored to it such that all parts of the color legend are guaranteed to be visible. A seventh option, Any Location, enables the color legend to be dragged to any position on the screen. This option is automatically set when interaction with the color legend occurs.
Though the presentation of the new color legend has changed, most of the existing color legend properties have been preserved. Two exceptions are:
- AspectRatio – controls the thickness of the color bar
- Point2 – which controls the length of the color legend
Backwards compatibility handling for Python scripts written in earlier versions of ParaView will ensure that these properties continue to work as expected in ParaView 5.4.
We hope you enjoy using the new color legend coming to ParaView 5.4.0. Please let us know if you have any problems using it and how we might improve backwards compatibility with existing ParaView state files and Python scripts.