Styling in the Anatomy Plugin

CSS-like styling of objects in the Anatomy plugin.

Collaboration diagram for Styling in the Anatomy Plugin:

CSS-like styling of objects in the Anatomy plugin.

Overview

In order to support consistent styling of objects (Meshes, Pointclouds, Keypoints, etc...) independent of the algorithms that created them, the Anatomy plugin provides a CSS-like styling mechanism. Lists of styles can be attached to AnatomicalStructureCollection objects in the ASCDisplayOptions class. These styles ultimately determine how the objects are visualized. We strive to follow the syntax and terminology of CSS closely, while making some simplifications and adaptations to fit the needs of the Anatomy plugin. Thus, we refer to the parameters that define the style of an object as "properties", the property-value pairs as "declarations", and the rules that match objects to styles as "selectors". Additional modifiers to selectors are refered to as "pseudo-classes" as in CSS.

using namespace AnatomyPlugin;
AnatomicalStructureCollection& asc = ...
ASCDisplayOptions& opts = asc.components().getOrCreate<ASCDisplayOptions>();
StyleSheet& myStyleSheet = opts.getOrAppendStyleSheet("My Style Sheet"); // Append new style sheet with the given name
 
// Style all Graphs and Splines are visualized in a projective way over an x-ray with the CT plugin (see ASCProjectionController).
std::optional<Selector> graphsSelector = "Graphs:projective, Splines:projective"_sel;
myStyleSheet.appendOrModify(graphsSelector.value(), [](Properties &declaration)
{
      declaration.setParam(StyleProperty::AlphaLine, "-50%"); // Make lines less opaque than what was defined by previous styles
});
 
// Style all Meshes that are part of AnatomicalStructure objects with identifier "ImFusion.Liver"
// and have key "ImFusion.Tumor" when they are visualized in a projective way over an x-ray with the CT plugin.
std::optional<Selector> tumorSelector = "Meshes#ImFusion.Liver/ImFusion.Tumor:projective"_sel;
myStyleSheet.appendOrModify(tumorSelector.value(), [](Properties &declaration)
{
      declaration.setParam(StyleProperty::VisibilityOutline, true); // Show the outline visualization
      declaration.setParam(StyleProperty::ColorOutline, "red"); // Set the outline color of the Meshes to red
      declaration.setParam(StyleProperty::OutlineWidth, 3); // Make the outline width 3 pixels
      declaration.setParam(StyleProperty::VisibilitySurface, false); // Hide the surface visualization
      declaration.setParam(StyleProperty::VisibilityWireframe, false); // Hide the wireframe visualization
});

In the above example, we append a new style sheet to the list of given styles. This style sheet contains two style rules comprising:

• A Selector, that determines when the style should be applied
• A Declaration, that is a Properties instance which contains the property-value pairs that define the style.

A style "cascade" is applied to each object, which means that styles are applied in a specific order, with later declarations overriding or modifying earlier ones. Thus, the order of the styles is crucial both in terms of how individual style rules are ordered in a style sheet, and how style sheets are ordered. Whether or not a style is applied to an object depends on whether the object in the given context matches the style's selector. If a selector does not match an object, the style rule it is part of does not affect how the object is visualized.

Selectors

Selectors are used to match styles to objects. The easiest way to create a Selector is to use operator""_sel as above, but selectors can also be created programmatically using the Selector class. A Selector is an OR-combination of SelectorElem objects. Such SelectorElem objects can match:

• A specific content type, e.g. "Meshes", "Graphs", "Splines", etc. (see ContentType). The syntax here is e.g. "Meshes". A content type is always required, otherwise "*" should be used.
• Optionally, a specific identifier, e.g. "ImFusion.Liver", "ImFusion.Tumor" (see AnatomicalStructure::identifier()). The syntax here is e.g. "#ImFusion.Liver".
• Optionally, a specific key, e.g. "ImFusion.Tumor" (see KeyValueStore). The syntax here is "/ImFusion.Tumor".
• Optionally, individual parameters in the AnatomicalStructure::attributes() properties instance. The syntax here is e.g. "[hidden="true"]".
• Optionally, individual parameters in the KeyValueStore::Entry::attributes() properties instance. The syntax here is e.g. "[[hidden="true"]]".
• Optionally, various pseudo-classes that match objects based on their properties, e.g. ":projective", ":focus", ":selected", etc.

Any subset of the above can be combined with logical AND into a SelectorElem. We do not support more complex selectors (such as AND-combinations of arbitrary Selector objects).

Example of a rather complex AnatomyPlugin::SelectorElem:

"Meshes#ImFusion.Liver[myspecialattribute="true"]:focus"

This matches Meshes that are contained in an AnatomicalStructure with identifier "ImFusion.Liver" and have myspecialattribute=true and the state of their AnatomicalStructureCollection::selection() is such that their AnatomicalStructure is the focus element.

Declarations

Declarations are used to define the style of objects. They are a collection of property-value pairs, where the properties are defined in the StyleProperty namespace.

Colors

Colors can be specified in various formats, including:

• As a std::string param: named colors, e.g. "red", "blue", "green", etc.
• As a std::string param: hexadecimal colors with either 6 (rgb) or 8 (rgba) values, e.g. "#FF0000" for red, "#00FF00" for green, etc.
• As ImFusion::vec3 / ImFusion::vec4 values from code.

Numerical Values

Numerical values can either be absolute (e.g. "5.2") or relative (e.g. "-50%"). Relative values only take effect if a previous style has defined the same property.

Cascading

The StyleRule::combine() function is used to combine an ordered list of declarations. Generally, the last declaration for a property wins, but there are some exceptions:

• Relative values are always combined with the previous value, e.g. if the previous value was 5 and the new value is -50%, the final value will be 2.5.
• The Color property sets all of the color properties (Color, ColorOutline, ColorWireframe ...). The Alpha and Visibility properties work analogously.
• The values of all "color" properties are converted to type ImFusion::vec4
• The "alpha" properties do not end up in the final properties, but are multiplied onto the fourth corresponding color component after the style cascade.

To maintain compatibility with previous versions of the Anatomy plugin, the "allow_object_attributes_override" property has been introduced. If this property is true at the end of the style cascade, selected properties from AnatomicalStructure::attributes() - most notably "color" - will override values set by the styles. To disable this behavior, set the AllowObjectAttributesOverride property to false in the last style rule of the style cascade.

Default Style Sheets

The Anatomy plugin comes with default style sheets that define the default styles for all objects. These style sheets are applied in the beginning of the style cascade, and can thus be overridden by later style sheets. They can be modified for debugging purposes, but in production code the recommended way to change the default styles is to append a new style sheet.

Graphically Modifying Styles

The "Inspect Style Sheets" algorithm in the Anatomy plugin allows you to inspect and modify existing style rules for AnatomicalStructureCollection objects.

Note

This algorithm is meant for debugging and testing purposes only. Defining and modifying your own style sheets has to be done pure programmatically.

Compatibility with previous versions of the ASCDisplayOptions

The existing parameters in the ASCDisplayOptions have been kept. However, these no longer drive visualization directly; modifying them modifies the default values in the default style sheet.