Hide menu
Scene managment
This page describes functionality that is part of Visualization Toolkit add-on, which is licensed separately from the base CAD Exchanger SDK.

ModelPrs_Scene encapsulates a scene, connects with a viewport, and manages object display and interactive selection. One viewport only can be attached to a scene.

Adding and removing scene nodes

Once a scene graph has been constructed (see sdk_vis_scene_graph_creating) its top node can be added to a scene as a new root:

ModelPrs_SceneNode aRootNode = ...;
ModelPrs_Scene aScene;
aScene.AddRoot (aRootNode);

A root node can be removed from the scene using ModelPrs_Scene::RemoveRoot().

Update the scene

To enforce visual update of the scene in the attached viewport, the ModelPrs_Scene::Update() method must be called.

Updating the scene can be time-consuming and therefore should be delayed until changes to the underlying scene node’s data have been applied. For instance, the following example demonstrates multiple geometrical changes and single scene update:

ModelPrs_SceneNode aRootNode;
aRootNode.SetDisplayMode (ModelPrs_DM_Shaded);
ModelPrs_Scene aScene;
aScene.AddRoot (aRootNode);
aRootNode.AddChildNode (aFirstNode);
aRootNode.AddChildNode (aSecondNode);
aFirstNode.SetGeometry (...);
aFirstNode.SetSelectionMode (ModelPrs_SM_Shape);
aSecondNode.SetGeometry (...);
aSecondNode.SetAppearance (ModelData_Appearance(...));
aScene.Update(); // multiple changes but one update

Displaying scene nodes

An object on a scene can be displayed in various display modes, for instance:

  • Wireframe
  • Shading
  • Shading with boundaries
  • Shading with surface boundaries
Wireframe display mode
Shaded display mode
Mixed display mode (Shaded with boundaries & Wireframe)

A display mode can be defined per each scene node using ModelPrs_SceneNode::SetDisplayMode(). See also Node attributes inheritance to check how distinct display modes apply in the scene graph.

The following code snippet demonstrates how to create a mixed shading and wireframe display modes:

ModelPrs_SceneNode aRoot;
ModelPrs_SceneNodeFactory aFactory;
auto aFirstNode = aFactory.Create (aFirstBody);
aRoot.AddChildNode (aFirstNode);
auto aSecondNode = aFactory.Create (aSecondBody);
aRoot.AddChildNode (aSecondNode);
aRoot.SetDisplayMode (ModelPrs_DM_Shaded);
aFirstNode.SetDisplayMode (ModelPrs_DM_Wireframe);
// aSecondNode inherits parent's display mode - ModelPrs_DM_Shaded

Hidding scene nodes

A hidden scene node (but not removed from the scene) can be either fully hidden or displayed as semi-transparent:

Ghost hidden visibility mode
Hidden visibility mode

This behavior is controlled with ModelPrs_SceneNode::SetVisibilityMode().

Hover and selection

Objects are selected upon mouse clicks (tap events on touch screens) or via ModelPrs_SelectionManager interface. Upon selection selected objects are highlighted on a screen. Selection on entire 3D scene can be enabled/disabled using the SetSelectionEnabled() of the viewport.

Selection manager and selection events observer

The scene provides ModelPrs_SelectionManager object to handle and to manage selection. To handle selection events a subclass of ModelPrs_SelectionChangesObserver must be defined with the redefined ModelPrs_SelectionChangesObserver::SelectionChangedByScene() and ModelPrs_SelectionChangesObserver::SelectionChangedByManager() methods and registered in the manager as follows:

class CustomSelectionChangesObserver : public ModelPrs_SelectionChangesObserver
void SelectionChangedByScene (const ModelPrs_Selection& theCurrent,
const ModelPrs_Selection& theSelected,
const ModelPrs_Selection& theDeselected) override
// Your code here.
void SelectionChangedByManager (const ModelPrs_Selection& theCurrent,
const ModelPrs_Selection& theSelected,
const ModelPrs_Selection& theDeselected) override
// Your code here.
CustomSelectionChangesObserver anObserver;
ModelPrs_Scene aScene;
aScene.SelectionManager().Register (anObserver);

The manager will notify about selection events using a call-back mechanism (your observer object).

The difference between SelectionChangedByScene() and SelectionChangedByManager() methods is that the first is invoked when the selection event source is a mouse click in the viewport and the second is invoked when you change the selection using ModelPrs_SelectionManager methods.

To manage selection in your code you can use Select(), Deselect() and DeselectAll() methods of ModelPrs_SelectionManager.

Selection object

A selection object encapsulates the scene node which has been selected/deselected and additionally in the case of B-Rep representation, the B-Rep subshapes. To access this data a subclass of ModelPrs_SelectionVisitor must be sent to selection's Accept() method:

class CustomSelectionVisitor : public ModelPrs_SelectionVisitor
void Visit (const ModelPrs_SceneNode& theNode) override
// the node itself is selected
void Visit (const ModelPrs_SceneNode& theNode, const std::vector<ModelData_Shape>& theShapes)
// subshapes of the node are selected
class CustomSelectionChangesObserver : public ModelPrs_SelectionChangesObserver
void SelectionChangedByScene (const ModelPrs_Selection& /*theCurrent*/,
const ModelPrs_Selection& theSelected,
const ModelPrs_Selection& /*theDeselected*/) override
theSelected.Accept (myVisitor);
void SelectionChangedByManager (const ModelPrs_Selection& /*theCurrent*/,
const ModelPrs_Selection& theSelected,
const ModelPrs_Selection& /*theDeselected*/) override
theSelected.Accept (myVisitor);
CustomSelectionVisitor myVisitor;

Refer to Selection Handling Example

Selection modes

A selection mode is represented by ModelPrs_SelectionMode enumeration and can be specified for each scene node with ModelPrs_SceneNode::SetSelectionMode(). For instance:

ModelPrs_SceneNode aRootNode = ...;
aRootNode.SetSelectionMode (ModelPrs_SM_Face);

ModelPrs_SelectionMode enumeration values are represented with binary flags and thus selection modes can be combined with each other as follows:

ModelPrs_SceneNode aNode;
aNode.SetSelectonMode (ModelPrs_SM_Vertex | ModelPrs_SM_Edge); // activate selection of vertices and edges

Values from ModelPrs_SM_Vertex to ModelPrs_SM_Solid apply for B-Rep representations only (and are ignored for polygonal representations):

ModelData_BRepRepresentation aBRep = ...;
ModelData_Body aBody = ...;
ModelData_PolyVertexSet aPVS = ...;
ModelPrs_SceneNode aRoot;
aRoot.SetSelectionMode (ModelPrs_SM_Face);
ModelPrs_SceneNodeFactroy aFactory;
aRoot.AddChildNode (aFactory.Create (aBRep));
aRoot.AddChildNode (aFactory.Create (aBody));
aRoot.AddChildNode (aFactory.Create (aPVS)); // no active selection - ModelPrs_SM_Face doesn't apply for PVS
See also
Topological Shapes

When combining selection modes of the same dimension, the value representing a finer type will dominate. For instance, when combining edge and wire selection the former will dominate (because any wire consists of edges).

ModelPrs_SceneNode aNode;
aNode.SetSelectionMode (ModelPrs_SM_Wire | ModelPrs_SM_Edge); // edge selection mode will dominate

The following list explains dominating modes in such combinations:

  • ModelPrs_SM_Solid dominate when combined with ModelPrs_SM_Node (whenever the node has a solid inside);
  • ModelPrs_SM_Shell dominate when combined with ModelPrs_SM_Node or ModelPrs_SM_Solid;
  • ModelPrs_SM_Face dominate when combined with ModelPrs_SM_Node, ModelPrs_SM_Shell or ModelPrs_SM_Solid;
  • ModelPrs_SM_Edge dominate when combined with ModelPrs_SM_Wire.

Selection filters

When selecting B-Rep edges and faces, additional filters can be specified in order to restrict selection to specific geometries. For instance, to restrict selection of faces lying on planar surfaces (such as real planes or planar NURBS-surfaces), the following filter can be specified:

ModelPrs_Scene aScene;
aScene.SelectionManager().SetFilter (ModelPrs_SFT_PlanarFaceFilter);

ModelPrs_SelectionFilterType enumeration values are represented by binary flags and thus several filters can be combined. The following example demonstrates how to limit selection to circular edges or surfaces of revolution (e.g. cylinders or cones):

ModelPrs_Scene aScene;
aScene.SelectionManager().SetFilter (ModelPrs_SFT_CircleEdgeFilter | ModelPrs_SFT_RevolFaceFilter);
See also

Selection filters are useful when you interact with the scene to create Measurements.

Refer to Measurements Example


A 3D viewport can support hover - highlighting a selectable object when mouse coursor moves over it. This behavior is controlled with the method SetHighlightingEnabled() of a respective viewport.

Future versions of CAD Exchanger SDK will enable support of user-defined callbacks which will be invoked upon hover detection similar to selection callbacks. Currently no callbacks are supported.
Selects B-Rep faces in a node. *.
Definition: ModelPrs_SelectionMode.hxx:34
Selects B-Rep edges in a node. *.
Definition: ModelPrs_SelectionMode.hxx:36
Shaded display mode.
Definition: ModelPrs_DisplayMode.hxx:31
Selects B-Rep wires in a node. *.
Definition: ModelPrs_SelectionMode.hxx:35
Defines a filter accepting faces with plane-like surfaces.
Definition: ModelPrs_SelectionFilterType.hxx:28
Defines a filter accepting faces with revolution surfaces.
Definition: ModelPrs_SelectionFilterType.hxx:29
Selects B-Rep vertexes in a node. *.
Definition: ModelPrs_SelectionMode.hxx:37
Defines a filter accepting edges with circle-like curves.
Definition: ModelPrs_SelectionFilterType.hxx:27
Wireframe display mode.
Definition: ModelPrs_DisplayMode.hxx:30