Skip to main content
Version: 4.x

Introduction

Reveal supports flexible styling of individual nodes (objects) in the 3D model. Styles can be compromised of several attributes to customize the visualization through the NodeAppearance-type:

FieldField typeDescription
colorTHREE.Color?Override color, e.g new THREE.Color(1, 0, 0) (red). All components set to zero means no override.
visibleboolean?When false, the node(s) will be invisible
renderInFrontboolean?When true, the node(s) are rendered in front of other geometry
renderGhostedboolean?When true, the node(s) are rendered in transparent gray
outlineColorNodeOutlineColor?Adds an outline to the objects from a set of predefined colors
prioritizedForLoadingHintnumber?Assigns a prioritization weight to this node collection, influencing load priority. See Prioritize nodes for loading.

These attributes can be combined to customize the look of nodes. For convinience, a set of default appearances are provided in the DefaultNodeAppearance-constant:

AppearanceDescription
DefaultNo overrides, use colors from the CAD model
GhostedRender node(s) 'ghosted', i.e. make them translucent gray
OutlinedOutline node(s) with a white outline
HiddenHide node(s)
InFrontRender node(s) in front of all other nodes
HighlightedHighlight the node(s). Combination of InFront, Outlined and a custom color

These "appearance profiles"/styles are assigned to one or more nodes defined by a NodeCollection-instance. A NodeCollection identifies 3D nodes by treeIndex. There are several implementations of NodeCollection:

Class
TreeIndexNodeCollectionA set of nodes defined by a list of tree indices. Can be updated with a new set of indices.
NodeIdNodeCollectionSimilar to TreeIndexNodeCollection, but useful when you have 'node IDs', not tree indices.
PropertyFilterNodeCollectionA set of nodes defined by a query to the 3D backend to find nodes that matches one or more properties/attributes.
SinglePropertyFilterNodeCollectionSimilar to PropertyFilterNodeCollection, but only matches one node property to many values (e.g. for looking up nodes with a list of IDs).
AssetNodeCollectionA set of nodes defined by asset mappings linking 3D nodes to assets.
InvertedNodeCollectionInverts the result of a node collection to match the opposite nodes (i.e. a NOT-operator).
UnionNodeCollectionCombines nodes from several node colletions by finding the set union.
InersectionNodeCollectionCombines nodes from several node colletions by finding the set intersection.
NodeCollectionAbstract base class for node collections. Extend to implement custom node collections.

It's also possible implement custom node collections. This can be useful for specialized queries or to load sets from custom data sources.

CogniteCadModel.assignStyledNodeCollection and unassignStyledNodeCollection is used to manage styled set associated with a model:

// import { TreeIndexNodeCollection, DefaultNodeAppearance, NumericRange } from '@cognite/reveal'

// you can start from binding styles to an empty set and populate it later
const myNodes = new TreeIndexNodeCollection();
model.assignStyledNodeCollection(myNodes, DefaultNodeAppearance.Highlighted);

// later you might want to update the set as user does something, for example, selects an asset
// note that other styling sets might have different API for updates, for example `executeFilter`
const nodeTreeIndex = 0;
const nodeSubtreeSize = 100000;
myNodes.updateSet(new IndexSet(new NumericRange(nodeTreeIndex, nodeSubtreeSize)));

// if you want to change appearance of your existing set you can assign a new style
model.assignStyledNodeCollection(myNodes, DefaultNodeAppearance.Ghosted);

// and when you don't need to style this set anymore, just remove it completely
model.unassignStyledNodeCollection(myNodes);

Styling is "additive", meaning that styles from multiple styled sets are accumulated per node, much like how multiple classes are combined when working with CSS. Styled sets are applied first-in first-out (FIFO) in the order the are added.

// import { TreeIndexNodeCollection, DefaultNodeAppearance, NumericRange } from '@cognite/reveal'

// you can start from binding styles to an empty set and populate it later
const set1 = new TreeIndexNodeCollection(NumericRange.createFromInterval(0, 100));
model.assignStyledNodeCollection(set1, { color: new THREE.Color(1, 0, 0) });
const set2 = new TreeIndexNodeCollection(NumericRange.createFromInterval(50, 150));
model.assignStyledNodeCollection(set2, { outlineColor: NodeOutlineColor.White });

// [0..49] will be colored red
// [50..100] will be colored red and have a white outline
// [101..150] will have the default color and a white outline
note

The API for styling nodes has changed substantially since Reveal 1.x and upgrading Reveal will require manual steps to implement styling.

Examples

To play around with the different styling options, we can use CogniteCadModel.setDefaultNodeAppearance. A few example styles are shown below.

Ghosted style

Live Editor

Highlighted

Live Editor

Outline and custom color

By creating custom styles you have a powerful tool to customize how the model looks.

Live Editor

Note that outlineColor restricts the choice of color to a predefined set. This is a restriction imposed to reduce storage space for outlines to only 3 bits. The choice of colors is:

enum NodeOutlineColor {
NoOutline = 0,
White = 1,
Black = 2,
Cyan = 3,
Blue = 4,
Green = 5,
Red = 6,
Orange = 7
}