Local Context removal

Local Context was an essential part of OCCT 3D Viewer (AIS_InteractiveContext) for a long time. The concept of Local Context is quite simple and powerful - differentiation of two Viewer states: Neutral Point where all model objects reside, and Local Context augmenting main model presentations with auxiliary ones, created temporarily for particular task in user interaction. Even more, OCCT allows creation of multiple Local Contexts, defining some sort of stack of contexts.

Local Context naturally fulfills requirements of application implementing a concept of nested operation, where each nested operation may create a set of new dialogs, adjust 3D Viewer with addition presentations (within Local Context), and turns back to original state (Neutral Point) at the end.

At the same time, modern applications can be organized in much more complicated way making simple concept of Local Context useless; in such case Local Context becomes a burden unnecessarily complicating overall 3D Viewer management.

In practice, most applications manage temporary objects and selection by their own, duplicating Local Context functionality. Application using Local Context should be extremely careful with its state to not ruin 3D Viewer content - a lot of application bugs are coming from incorrect usage of Local Context.

One of pitfalls of Local Context concept was bounding Local Selection with it, so that it was not possible activating Local Selection without opening Local Context. And while Local Context is a questionable feature, Local Selection is an essential functionality for any complex OCCT-based application. It allows selecting Shape parts of particular type (Vertices, Edges, Faces, Shells, Solids) or Mesh parts (Nodes, Elements).

Local Context removal

Thus we see that applications have to deal with Local Context just to be able to use Local Selection. This binding has been cut since OCCT 7.0.0 release, by possibility to activate Local Selection within Neutral Point. This made concept of Local Context within OCCT obsolete.

That is, Local Context functionality has been marked deprecated within OCCT 7.0.0 release. Applications now should activate Local Selection without opening Local Context, and manage 3D Viewer state manually. And now it is a time to completely remove this feature.

This important step would allow cleaning an over-complicated and confusing API of AIS_InteractiveContext class, removing a complex and fragile code of Local Context management (and thus, additional source of bugs) and, as result, making better API for applications.

The removal has been scheduled for OCCT 7.3.0 release - therefore, Local Context functionality will be removed from OCCT development branch soon after OCCT 7.2.0 release.

Porting application code

Since Local Context will be removed, application code using it should be ported. Within OCCT 7.2.0, all functions within AIS_InteractiveContext related to Local Context has been marked as Standard_DEPRECATED, so that compiler will point developers onto the places which should be updated. Most critical points are:

• Activation of Local Selection Application should activate Local Selection modes directly within Neutral Point. Selection mode 0 is (usually) reserved by Interactive Objects for detecting entire objects, while other numbers activate detection of sub-parts. The numbers depend on Interactive Object implementation; for instance, AIS_Shape::SelectionMode() returns a selection mode index for a sub-shape type (TopAbs_ShapeEnum) detection.
• Opening/Closing Local Context Application code should deactivate Local Selection modes and track temporary presentations manually.
• Iterating through Selected objects Application code should avoid using deprecated methods like InitCurrent()/MoreCurrent()/NextCurrent()/Current(). Instead, use methods InitSelected()/MoreSelected()/NextSelected()/SelectedOwner()/SelectedInteractive().
• Shapes, sub-shapes and Interactive Objects Application should avoid using AIS_InteractiveContext methods returning TopoDS_Shape (such as SelectedShape()/DetectedShape()). Instead use methods taking / returning one of two kinds of objects:
  • AIS_InteractiveObject - a presentation holding one or more model objects. Since single Interactive Object can represent more than one logical object (depending on application logic or activated Local Selection), this type should be used within basic operations only (displaying/erasing objects). Examples: AIS_Shape - a presentation holding TopoDS_Shape; MeshVS_Mesh - a presentation holding arbitrary mesh.
  • SelectMgr_EntityOwner - an object defining a selectable object. This can be entire presentation AIS_InteractiveObject or it’s part. SelectMgr_EntityOwner::Selectable() returns the originating AIS_InteractiveObject presentation. Examples: StdSelect_BRepOwner - an owner pointing to a TopoDS_Shape (either entire shape of AIS_Shape or it’s sub-shape); MeshVS_MeshOwner - an owner pointing to entire MeshVS_Mesh presentation; MeshVS_MeshEntityOwner - an owner pointing to MeshVS_Mesh part (mesh Node, Element).

Code sample

Example of code using deprecated functionality:

  Handle(AIS_InteractiveContext) theContext;

  // activate Local Selection (edges)
  theContext->OpenLocalContext (0);
  theContext->ActivateStandardMode (TopAbs_EDGE);

  // do some interactions

  // deactivate Local Selection
  theContext->CloseAllContexts (false);

Example of new code:

  Handle(AIS_InteractiveContext) theContext;

  // activate Local Selection (edges)
  theContext->Deactivate();
  theContext->Activate (AIS_Shape::SelectionMode (TopAbs_EDGE));

  // do some interactions

  // deactivate Local Selection
  theContext->Deactivate();
  theContext->Activate (0);