Scene management

Table of Contents

• Adding and removing scene nodes
• Update the scene
• Displaying scene nodes
• Hidding scene nodes
• Hover and selection
  • Selection manager and selection events observer
  • Selection object
  • Selection modes
  • Selection filters
  • Hover

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 Creating a scene graph) its top node can be added to a scene as a new root:

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

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
{
public:
    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
{
public:
    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
{
public:
    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);
    }
private:
    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

ModelPrs_SelectionFilterType

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

Refer to Measurements Example

Hover

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.

Note

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.