* on the other hand -- its **presentation** (what you see when an object is displayed in a scene) and **selection** (possibility to choose the whole object or its sub-parts interactively to apply application-defined operations to the selected entities).
**Application Interactive Services** (AIS) provides the means to create links between an application GUI viewer and the packages, which are used to manage selection and presentation, which makes management of these functionalities in 3D more intuitive and consequently, more transparent.
*AIS* uses the notion of the *interactive object*, a displayable and selectable entity, which represents an element from the application data. As a result, in 3D, you, the user, have no need to be familiar with any functions underlying AIS unless you want to create your own interactive objects or selection filters.
If, however, you require types of interactive objects and filters other than those provided, you will need to know the mechanics of presentable and selectable objects, specifically how to implement their virtual functions. To do this requires familiarity with such fundamental concepts as the sensitive primitive and the presentable object.
The figure below presents a schematic overview of the relations between the key concepts and packages in visualization. Naturally, "Geometry & Topology" is just an example of application data that can be handled by *AIS*, and application-specific interactive objects can deal with any kind of data.
* If you need more detail, for example, a selection filter on another type of entity -- you should read chapter 2 @ref occt_visu_2 "Fundamental Concepts", chapter 3 @ref occt_visu_3 "AIS: Application Interactive Services", and 4 @ref occt_visu_4 "3D Presentations". You may want to begin with the chapter presenting AIS.
For advanced information on visualization algorithms, see our <a href="http://www.opencascade.com/content/tutorial-learning">E-learning & Training</a> offerings.
In Open CASCADE Technology, presentation services are separated from the data, which they represent, which is generated by applicative algorithms. This division allows you to modify a geometric or topological algorithm and its resulting objects without modifying the visualization services.
The purpose of a presentable object is to provide the graphical representation of an object in the form of *Graphic3d* structure. On the first display request, it creates this structure by calling the appropriate algorithm and retaining this framework for further display.
Standard presentation algorithms are provided in the *StdPrs* and *Prs3d* packages. You can, however, write specific presentation algorithms of your own, provided that they create presentations made of structures from the *Graphic3d* packages. You can also create several presentations of a single presentable object: one for each visualization mode supported by your application.
The viewer allows interactively manipulating views of the object. When you zoom, translate or rotate a view, the viewer operates on the graphic structure created by the presentable object and not on the data model of the application. Creating Graphic3d structures in your presentation algorithms allows you to use the 3D viewers provided in Open CASCADE Technology for 3D visualisation.
The interactive context controls the entire presentation process from a common high-level API. When the application requests the display of an object, the interactive context requests the graphic structure from the presentable object and sends it to the viewer for displaying.
Presentation involves at least the *AIS, PrsMgr, StdPrs* and *V3d* packages. Additional packages, such as *Prs3d* and *Graphic3d* may be used if you need to implement your own presentation algorithms.
* *PrsMgr* package provides low level services and is only to be used when you do not want to use the services provided by AIS. It contains all classes needed to implement the presentation process: abstract classes *Presentation* and *PresentableObject* and concrete class *PresentationManager3d*.
* *StdPrs* package provides ready-to-use standard presentation algorithms for specific geometries: points, curves and shapes of the geometry and topology toolkits.
* *Prs3d* package provides generic presentation algorithms such as wireframe, shading and hidden line removal associated with a *Drawer* class, which controls the attributes of the presentation to be created in terms of color, line type, thickness, etc.
The shape is created using the *BRepPrimAPI_MakeWedge* command. An *AIS_Shape* is then created from the shape. When calling the *Display* command, the interactive context calls the Compute method of the presentable object to calculate the presentation data and transfer it to the viewer. See figure below.
Standard OCCT selection algorithm is represented by 2 parts: dynamic and static. Dynamic selection causes objects to be automatically highlighted as the mouse cursor moves over them. Static selection allows to pick particular object (or objects) for further processing.
For OCCT selection algorithm, all selectable objects are represented as a set of sensitive zones, called <b>sensitive entities</b>. When the mouse cursor moves in the view, the sensitive entities of each object are analyzed for collision.
The purpose of entities is to define what parts of the object will be selectable in particular. Thus, any object that is meant to be selectable must be split into sensitive entities (one or several). For instance, to apply face selection to an object it is necessary to explode it into faces and use them for creation of a sensitive entity set.
Depending on the user's needs, sensitive entities may be atomic (point or edge) or complex. Complex entities contain many sub-elements that can be handled by detection mechanism in a similar way (for example, a polyline stored as a set of line segments or a triangulation).
Entities are used as internal units of the selection algorithm and do not contain any topological data, hence they have a link to an upper-level interface that maintains topology-specific methods.
Each sensitive entity stores a reference to its owner, which is a class connecting the entity and the corresponding selectable object. Besides, owners can store any additional information, for example, the topological shape of the sensitive entity, highlight colors and methods, or if the entity is selected or not.
To simplify the handling of different selection modes of an object, sensitive entities linked to its owners are organized into sets, called **selections**.
All successors of a selectable object must implement the method that splits its presentation into sensitive entities according to the given mode. The computed entities are arranged in one selection and added to the list of all selections of this object. No selection will be removed from the list until the object is deleted permanently.
For all standard OCCT shapes, zero mode is supposed to select the whole object (but it may be redefined easily in the custom object). For example, the standard OCCT selection mechanism and *AIS_Shape* determine the following modes:
For each OCCT viewer there is a **Viewer selector** class instance. It provides a high-level API for the whole selection algorithm and encapsulates the processing of objects and sensitive entities for each mouse pick.
The viewer selector maintains activation and deactivation of selection modes, launches the algorithm, which detects candidate entities to be picked, and stores its results, as well as implements an interface for keeping selection structures up-to-date.
Selection manager is a high-level API to manipulate selection of all displayed objects. It handles all viewer selectors, activates and deactivates selection modes for the objects in all or particular selectors, manages computation and update of selections for each object. Moreover, it keeps selection structures updated taking into account applied changes.
All three types of OCCT selection are implemented as a single concept, based on the search for overlap between frustum and sensitive entity through 3-level BVH tree traversal.
For the point or the rectangular selection the base of the frustum is a rectangle built in conformity with the pixel tolerance or the dimensions of a user-defined area, respectively. For the polyline selection, the polygon defined by the constructed line is triangulated and each triangle is used as the base for its own frustum. Thus, this type of selection uses a set of triangular frustums for overlap detection.
In the image above triangular frustum is set: a) by a user-defined polyline, b) by triangulation of the polygon based on the given polyline, c) by a triangular frustum based on one of the triangles.
The first level tree is constructed of axis-aligned bounding boxes of each selectable object. Hence, the root of this tree contains the combination of all selectable boundaries even if they have no currently activated selections. Objects are added during the display of <i>AIS_InteractiveObject</i> and will be removed from this tree only when the object is destroyed. The 1st level BVH tree is build on demand simultaneously with the first run of the selection algorithm.
The second level BVH tree consists of all sensitive entities of one selectable object. The 2nd level trees are built automatically when the default mode is activated and rebuilt whenever a new selection mode is calculated for the first time.
The third level BVH tree is used for complex sensitive entities that contain many elements: for example, triangulations, wires with many segments, point sets, etc. It is built on demand for sensitive entities with under 800K sub-elements.
@figure{visualization_image022.png,"Selection BVH tree hierarchy: from the biggest object-level (first) to the smallest complex entity level (third)",400}
After successful building of the selection frustum, the algorithm starts traversal of the object-level BVH tree. The nodes containing axis-aligned bounding boxes are tested for overlap with the selection frustum following the terms of <i>separating axis theorem (SAT)</i>. When the traverse goes down to the leaf node, it means that a candidate object with possibly overlapping sensitive entities has been found. If no such objects have been detected, the algorithm stops and it is assumed that no object needs to be selected. Otherwise it passes to the next stage to process the entities of the found selectable.
First of all, at this stage the algorithm checks if there is any transformation applied for the current object. If it has its own location, then the correspondingly transformed frustum will be used for further calculations. At the next step the nodes of the second level BVH tree of the given object are visited to search for overlapping leaves. If no such leafs have been found, the algorithm returns to the second stage. Otherwise it starts processing the found entities by performing the following checks:
- tolerance check - current selection frustum may be too large for further checks as it is always built with the maximum tolerance among all activated entities. Thus, at this step the frustum may be scaled.
If the entity is atomic, a simple SAT test is performed. In case of a complex entity, the third level BVH tree is traversed. The quantitative characteristics (like depth, distance to the center of geometry) of matched sensitive entities is analyzed and clipping planes are applied (if they have been set). The result of detection is stored and the algorithm returns to the second stage.
Selection is implemented as a combination of various algorithms divided among several packages -- <i>SelectBasics</i>, <i>Select3D</i>, <i>SelectMgr</i> and <i>StdSelect</i>.
- <i>SelectBasics_EntityOwner</i> -- the base definition of the an entity owner -- the link between the sensitive entity and the object to be selected;
- <i>SelectBasics_PickResult</i> -- the structure for storing quantitative results of detection procedure, for example, depth and distance to the center of geometry;
<i>Select3D_SensitivePoly</i> -- describes an arbitrary point set and implements basic functions for selection. It is important to know that this class does not perform any internal data checks. Hence, custom implementations of sensitive entity inherited from <i>Select3D_SensitivePoly</i> must satisfy the terms of Separating Axis Theorem to use standard OCCT overlap detection methods.
<i>Select3D_SensitiveSet</i> -- a base class for all complex sensitive entities that require the third level BVH usage. It implements traverse of the tree and defines an interface for the methods that check sub-entities.
- <i>SelectMgr_FrustumBase</i>, <i>SelectMgr_Frustum</i>, <i>SelectMgr_RectangularFrustum</i>, <i>SelectMgr_TriangluarFrustum</i> and <i>SelectMgr_TriangularFrustumSet</i> -- interfaces and implementations of selecting frustums, these classes implement different SAT tests for overlap and inclusion detection. They also contain methods to measure characteristics of detected entities (depth, distance to center of geometry);
- <i>SelectMgr_SensitiveEntity</i>, <i>SelectMgr_Selection</i> and <i>SelectMgr_SensitiveEntitySet</i> -- store and handle sensitive entities; <i>SelectMgr_SensitiveEntitySet</i> implements a primitive set for the second level BVH tree;
- <i>SelectMgr_SelectableObject</i> and <i>SelectMgr_SelectableObjectSet</i> -- describe selectable objects. They also manage storage, calculation and removal of selections. <i>SelectMgr_SelectableObjectSet</i> implements a primitive set for the first level BVH tree;
- <i>SelectMgr_SelectionManager</i> -- manages activation/deactivation, calculation and update of selections of every selectable object, and keeps BVH data up-to-date.
- <i>StdSelect_ViewerSelector3d</i> -- an example of <i>SelectMgr_ViewerSelecor</i> implementation, which is used in a default OCCT selection mechanism;
The first code snippet illustrates the implementation of <i>SelectMgr_SelectableObject::ComputeSelection()</i> method in a custom interactive object. The method is used for computation of user-defined selection modes.
To select the whole box, the application can create a sensitive primitive for each face of the interactive object. In this case, all primitives share the same owner -- the box itself.
To select box's edge, the application must create one sensitive primitive per edge. Here all sensitive entities cannot share the owner since different geometric primitives must be highlighted as the result of selection procedure.
The algorithms for creating selection structures store sensitive primitives in <i>SelectMgr_Selection</i> instance. Each <i>SelectMgr_Selection</i> sequence in the list of selections of the object must correspond to a particular selection mode.
To describe the decomposition of the object into selectable primitives, a set of ready-made sensitive entities is supplied in <i>Select3D</i> package. Custom sensitive primitives can be defined through inheritance from <i>SelectBasics_SensitiveEntity</i>.
To make custom interactive objects selectable or customize selection modes of existing objects, the entity owners must be defined. They must inherit <i>SelectMgr_EntityOwner</i> interface.
The example below shows how computation of different selection modes of the topological shape can be done using standard OCCT mechanisms, implemented in <i>StdSelect_BRepSelectionTool</i>.
The <i>StdSelect_BRepSelectionTool</i> class provides a high level API for computing sensitive entities of the given type (for example, face, vertex, edge, wire and others) using topological data from the given <i>TopoDS_Shape</i>.
The traditional way of highlighting selected entity owners adopted by Open CASCADE Technology assumes that each entity owner highlights itself on its own. This approach has two drawbacks:
Therefore, to overcome these limitations, OCCT has an alternative way to implement the highlighting of a selected presentation. Using this approach, the interactive object itself will be responsible for the highlighting, not the entity owner.
On the basis of <i>SelectMgr_EntityOwner::IsAutoHilight()</i> return value, <i>AIS_LocalContext</i> object either uses the traditional way of highlighting (in case if <i>IsAutoHilight()</i> returns true) or groups such owners according to their selectable objects and finally calls <i> SelectMgr_SelectableObject::HilightSelected()</i> or <i>SelectMgr_SelectableObject::ClearSelected()</i>, passing a group of owners as an argument.
Hence, an application can derive its own interactive object and redefine virtual methods <i>HilightSelected()</i>, <i>ClearSelected()</i> and <i>HilightOwnerWithColor()</i> from <i>SelectMgr_SelectableObject</i>. <i>SelectMgr_SelectableObject::GetHilightPresentation</i> and <i>SelectMgr_SelectableObject::GetSelectPresentation</i> methods can be used to optimize filling of selection and highlight presentations according to the user's needs.
The <i>AIS_InteractiveContext::HighlightSelected()</i> method can be used for efficient redrawing of the selection presentation for a given interactive object from an application code.
After all the necessary sensitive entities are computed and packed in <i>SelectMgr_Selection</i> instance with the corresponding owners in a redefinition of <i>SelectMgr_SelectableObject::ComputeSelection()</i> method, it is necessary to register the prepared selection in <i>SelectMgr_SelectionManager</i> through the following steps:
- load the selectable object to the selection manager of the interactive context using <i>AIS_InteractiveContext::Load()</i> method. If the selection mode passed as a parameter to this method is not equal to -1, <i>ComputeSelection()</i> for this selection mode will be called;
- activate or deactivate the defined selection mode using <i>AIS_InteractiveContext::Activate()</i> or <i>AIS_InteractiveContext::Deactivate()</i> methods.
After these steps, the selection manager of the created interactive context will contain the given object and its selection entities, and they will be involved in the detection procedure.
- <b>inclusive</b> detection. In this case the sensitive primitive is considered detected only when all its points are included in the area defined by the selection rectangle;
The central entity for management of visualization and selections is the **Interactive Context**. It is connected to the main viewer (and if need be, the trash bin viewer). It has two operating modes: the Neutral Point and the local visualization and selection context.
the neutral point. It is possible to choose the interactive objects, which you want to act on, the selection modes, which you want to activate, and the temporary visualizations, which you will execute.
**Interactive Objects** are the entities, which are visualized and selected. You can use classes of standard interactive objects for which all necessary functions have already been programmed, or you can implement your own classes of interactive objects, by respecting a certain number of rules and conventions described below.
An Interactive Object is a "virtual" entity, which can be presented and selected. An Interactive Object can have a certain number of specific graphic attributes, such as visualization mode, color and material.
When an Interactive Object is visualized, the required graphic attributes are taken from its own **Drawer** if it has the required custom attributes or otherwise from the context drawer.
It can be necessary to filter the entities to be selected. Consequently there are **Filter** entities, which allow refining the dynamic detection context. Some of these filters can be used at the Neutral Point, others only in an open local context. It is possible to program custom filters and load them into the interactive context.
Entities which are visualized and selected in the AIS viewer are objects. They connect the underlying reference geometry of a model to its graphic representation in *AIS*. You can use the predefined OCCT classes of standard interactive objects, for which all necessary functions have already been programmed, or, if you are an advanced user, you can implement your own classes of interactive objects.
Calculation of different presentations of an interactive object is done by the *Compute* functions inheriting from *PrsMgr_ PresentableObject::Compute* functions. They are automatically called by *PresentationManager* at a visualization or an update request.
The view can have two states: the normal mode or the computed mode (Hidden Line Removal mode). When the latter is active, the view looks for all presentations displayed in the normal mode, which have been signalled as accepting HLR mode. An internal mechanism allows calling the interactive object's own *Compute*, that is projector function.
These methods get the value from the drawer of *AIS_Shape*. If the HLR algorithm type in the *AIS_Drawer* is set to *Prs3d_TOH_NotSet*, the *AIS_Drawer* gets the value from the default drawer of *AIS_InteractiveContext*.
So it is possible to change the default HLR algorithm used by all newly displayed interactive objects. The value of the HLR algorithm type stored in the context drawer can be *Prs3d_TOH_Algo* or *Prs3d_TOH_PolyAlgo*. The polygonal algorithm is the default one.
Inside these categories, additional characterization is available by means of a signature (an index.) By default, the interactive object has a NONE type and a signature of 0 (equivalent to NONE.) If you want to give a particular type and signature to your interactive object, you must redefine two virtual functions:
**Note** that some signatures are already used by "standard" objects provided in AIS (see the @ref occt_visu_3_5 "List of Standard Interactive Object Classes".
The interactive context can have a default mode of representation for the set of interactive objects. This mode may not be accepted by a given class of objects.
The functions *AIS_InteractiveContext::SetDisplayMode* and *AIS_InteractiveContext::UnsetDisplayMode* allow setting a custom display mode for an objects, which can be different from that proposed by the interactive context.
The functions *AIS_InteractiveObject::SetHilightMode* and *AIS_InteractiveObject::UnSetHilightMode* allow specifying the display mode used for highlighting (so called highlight mode), which is valid independently from the active representation of the object. It makes no difference whether this choice is temporary or definitive.
Note that the same presentation (and consequently the same highlight mode) is used for highlighting *detected* objects and for highlighting *selected* objects, the latter being drawn with a special *selection color* (refer to the section related to *Interactive Context* services).
For example, you want to systematically highlight the wireframe presentation of a shape - non regarding if it is visualized in wireframe presentation or with shading. Thus, you set the highlight mode to *0* in the constructor of the interactive object. Do not forget to implement this representation mode in the *Compute* functions.
If you do not want an object to be affected by a *FitAll* view, you must declare it infinite; you can cancel its "infinite" status using *AIS_InteractiveObject::SetInfiniteState* and *AIS_InteractiveObject::IsInfinite* functions.
An interactive object can have an indefinite number of selection modes, each representing a "decomposition" into sensitive primitives. Each primitive has an <i>owner</i> (*SelectMgr_EntityOwner*) which allows identifying the exact interactive object or shape which has been detected (see @ref occt_visu_2_2 "Selection" chapter).
Each selection mode is identified by an index. By convention, the default selection mode that allows us to grasp the interactive object in its entirety is mode *0*. However, it can be modified in the custom interactive objects using method <i>SelectMgr_SelectableObject::setGlobalSelMode()</i>.
The calculation of selection primitives (or sensitive entities) is done in a virtual function *ComputeSelection*. It should be implemented for each type of interactive object that is assumed to have different selection modes using the function *AIS_InteractiveObject::ComputeSelection*.
There are some examples of selection mode calculation for the most widely used interactive object in OCCT -- *AIS_Shape* (selection by vertex, by edges, etc). To create new classes of interactive objects with the same selection behavior as *AIS_Shape* -- such as vertices and edges -- you must redefine the virtual function *AIS_InteractiveObject::AcceptShapeDecomposition*.
You also can temporarily change the priority of some interactive objects for selection of the global mode to facilitate their graphic detection using the following functions:
Graphic attributes manager, or *AIS Drawer*, stores graphic attributes for specific interactive objects and for interactive objects controlled by interactive context.
When an interactive object is visualized, the required graphic attributes are first taken from its own drawer if one exists, or from the context drawer if no specific drawer for that type of object exists.
* The set of graphic attributes of an interactive object is stocked in an *AIS_Drawer*, which is only a *Prs3d_Drawer* with the possibility of a link to another drawer
* By default, the interactive object takes the graphic attributes of the context in which it is visualized (visualization mode, deflection values for the calculation of presentations, number of isoparameters, color, type of line, material, etc.)
* In the *AIS_InteractiveObject* abstract class, standard attributes including color, line thickness, material, and transparency have been privileged. Consequently, there is a certain number of virtual functions, which allow acting on these attributes. Each new class of interactive object can redefine these functions and change the behavior of the class.
Due to the fact that the accuracy of three-dimensional graphics coordinates has a finite resolution the elements of topological objects can coincide producing the effect of "popping" some elements one over another.
To the problem when the elements of two or more Interactive Objects are coincident you can apply the polygon offset. It is a sort of graphics computational offset, or depth buffer offset, that allows you to arrange elements (by modifying their depth value) without changing their coordinates. The graphical elements that accept this kind of offsets are solid polygons or displayed as boundary lines and points. The polygons could be displayed as lines or points by setting the appropriate interior style.
The combination of these elements defines the polygon display modes that will use the given offsets. You can switch off the polygon offsets by passing *Aspect_POM_Off*. Passing *Aspect_POM_None* allows changing the *aFactor* and *aUnits* values without changing the mode. If *aMode* is different from *Aspect_POM_Off*, the *aFactor* and *aUnits* arguments are used by the graphics renderer to calculate the depth offset value:
*AIS_ConnectedInteractive* is an object instance, which reuses the geometry of the connected object but has its own transformation, material, visibility flag, etc. This connection is propagated down to *OpenGl* level, namely to *OpenGl_Structure*. *OpenGl_Structure* can be connected only to a single other structure.
*AIS_ConnectedInteractive* can be referenced to any *AIS_Interactive* object in general. When it is referenced to another *AIS_ConnectedInteractive*, it just copies the reference.
*AIS_MultipleConnectedInteractive* represents an assembly, which does not have its own presentation. The assemblies are able to participate in the object hierarchy and are intended to handle a grouped set of instanced objects. It behaves as a single object in terms of selection. It applies high level transformation to all sub-elements since it is located above in the hierarchy.
All *AIS_MultipleConnectedInteractive* are able to have child assemblies. Deep copy of object instances tree is performed if one assembly is attached to another.
Note that *AIS_ConnectedInteractive* cannot reference *AIS_MultipleConnectedInteractive*. *AIS_ConnectedInteractive* copies sensitive entities of the origin object for selection, unlike *AIS_MultipleConnectedInteractive* that re-uses the entities of the origin object.
The Interactive Context allows managing in a transparent way the graphic and **selectable** behavior of interactive objects in one or more viewers. Most functions which allow modifying the attributes of interactive objects, and which were presented in the preceding chapter, will be looked at again here.
There is one essential rule to follow: the modification of an interactive object, which is already known by the Context, must be done using Context functions. You can only directly call the functions available for an interactive object if it has not been loaded into an Interactive Context.
**Neutral Point** and **Local Context** constitute the two operating modes or states of the **Interactive Context**, which is the central entity which pilots visualizations and selections.
The **Neutral Point**, which is the default mode, allows easily visualizing and selecting interactive objects, which have been loaded into the context. Opening **Local contexts** allows preparing and using a temporary selection environment without disturbing the neutral point.
A set of functions allows choosing the interactive objects which you want to act on, the selection modes which you want to activate, and the temporary visualizations which you will execute. When the operation is finished, you close the current local context and return to the state in which you were before opening it (neutral point or previous local context).
Some functions can only be used in open Local Context; others in closed local context; others do not have the same behavior in one state as in the other.
An interactive object can have a certain number of specific graphic attributes, such as visualization mode, color, and material. Correspondingly, the interactive context has a set of graphic attributes, the *Drawer*, which is valid by default for the objects it controls.
When an interactive object is visualized, the required graphic attributes are first taken from the object's own <i>Drawer</i> if one exists, or from the context drawer for the others.
When you change a graphic attribute pertaining to the Context (visualization mode, for example), all interactive objects, which do not have the corresponding appropriate attribute, are updated.
*PresentationManager3D* and *Selector3D*, which manage the presentation and selection of present interactive objects, are associated to the main Viewer. The same is true of the optional Collector.
* Opening a local context allows preparing an environment for temporary presentations and selections, which will disappear once the local context is closed.
The interactive object, which is used the most by applications, is *AIS_Shape*. Consequently, standard functions are available which allow you to easily prepare selection operations on the constituent elements of shapes (selection of vertices, edges, faces etc) in an open local context. The selection modes specific to "Shape" type objects are called **Standard Activation Mode**. These modes are only taken into account in open local context and only act on interactive objects which have redefined the virtual function *AcceptShapeDecomposition()* so that it returns *TRUE*.
* Objects, which are temporarily in a local context, are not recognized by other local contexts a priori. Only objects visualized in Neutral Point are recognized by all local contexts.
The specific modes of selection only concern the interactive objects, which are present in the Main Viewer. In the Collector, you can only locate interactive objects, which answer positively to the positioned filters when a local context is open, however, they are never decomposed in standard mode.
* *UseDisplayedObjects*: allows loading the interactive objects visualized at Neutral Point in the opened local context. If *FALSE*, the local context is empty after being opened. If *TRUE*, the objects at Neutral Point are modified by their default selection mode.
* *AllowShapeDecomposition*: *AIS_Shape* allows or prevents decomposition in standard shape location mode of objects at Neutral Point, which are type-privileged (see @ref occt_visu_3_2_4 "Selection" chapter). This Flag is only taken into account when *UseDisplayedObjects* is *TRUE*.
* *AcceptEraseOfObjects*: authorizes other local contexts to erase the interactive objects present in this context. This option is rarely used. The last option has no current use.
When the index is not specified in the first function, the current Context is closed. This option can be dangerous, as other Interactive Functions can open local contexts without necessarily warning the user. For greater security, you have to close the context with the index given on opening.
To get the index of the current context, use function *AIS_InteractiveContext::IndexOfCurrentLocal*. It allows closing all open local contexts at one go. In this case, you find yourself directly at Neutral Point.
When you close a local context, all temporary interactive objects are deleted, all selection modes concerning the context are canceled, and all content filters are emptied.
You must distinguish between the **Neutral Point** and the **Open Local Context** states. Although the majority of visualization functions can be used in both situations, their behavior is different.
Neutral Point should be used to visualize the interactive objects, which represent and select an applicative entity. Visualization and Erasing orders are straightforward:
* The first *Display* function among the two ones available in *InteractiveContext* visualizes the object in its default mode (set with help of SetDisplayMode() method of InteractiveObject prior to Display() call), or in the default context mode, if applicable. If it has neither, the function displays it in 0 presentation mode. The object's default selection mode is automatically activated (0 mode by convention).
* Activating the displayed object by default can be turned off with help of *SetAutoActivateSelection()* method. This might be efficient if you are not interested in selection immediately after displaying an object.
* The second *Display* function should only be used in Neutral Point to visualize a supplementary mode for the object, which you can erase by *EraseMode (...)*. You activate the selection mode. This is passed as an argument. By convention, if you do not want to activate a selection mode, you must set the *SelectionMode* argument to -1. This function is especially interesting in open local context, as we will see below.
* In Neutral Point, it is not advisable to activate other selection modes than the default selection one. It is preferable to open a local context in order to activate particular selection modes.
* When you call *Erase(Interactive object)* function, the *PutIncollector* argument, which is *FALSE* by default, allows you to visualize the object directly in the Collector and makes it selectable (by activation of 0 mode). You can nonetheless block its passage through the Collector by changing the value of this option. In this case, the object is present in the Interactive Context, but is not seen anywhere.
* *Erase()* with *putInCollector = Standard_True* might be slow as it recomputes the object presentation in the Collector. Set *putInCollector* to *Standard_False* if you simply want to hide the object's presentation temporarily.
* Visualization attributes and graphic behavior can be modified through a set of functions similar to those for the interactive object (color, thickness of line, material, transparency, locations, etc.) The context then manages immediate and deferred updates.
* Call *Remove()* method of *InteractiveContext* as soon as the interactive object is no longer needed and you want to destroy it.. Otherwise, references to *InteractiveObject* are kept by *InteractiveContext*, and the *Object* is not destroyed, which results in memory leaks. In general, if the presentation of an interactive object can be computed quickly, it is recommended to *Remove()* it instead of using *Erase()* method.
The function *AIS_InteractiveObject::Display* automatically activates the object's default selection mode. When you only want to visualize an Interactive Object in open Context, you must call the function *AIS_InteractiveContext::Display*.
This activates the corresponding selection mode for all objects in Local Context, which accept decomposition into sub-shapes. Every new Object which has been loaded into the interactive context and which meets the decomposition criteria is automatically activated according to these modes.
If you have opened a local context by loading an object with the default options <i>(AllowShapeDecomposition = Standard_True)</i>, all objects of the "Shape" type are also activated with the same modes. You can change the state of these "Standard" objects by using *SetShapeDecomposition(Status)*.
This function allows loading an Interactive Object whether it is visualized or not with a given selection mode, and/or with the necessary decomposition option. If *AllowDecomp=TRUE* and obviously, if the interactive object is of the "Shape" type, these "standard" selection modes will be automatically activated as a function of the modes present in the Local Context.
A filter questions the owner of the sensitive primitive in local context to determine if it has the desired qualities. If it answers positively, it is kept. If not, it is rejected.
The root class of objects is *SelectMgr_Filter*. The principle behind it is straightforward: a filter tests to see whether the owners <i>(SelectMgr_EntityOwner)</i> detected in mouse position by the Local context selector answer *OK*. If so, it is kept, otherwise it is rejected.
In *SelectMgr*, there are also Composition filters (AND Filters, OR Filters), which allow combining several filters. In InteractiveContext , all filters that you add are stocked in an OR filter (which answers *OK* if at least one filter answers *OK*).
As there are specific behaviors on shapes, each new *Filter* class must, if necessary, redefine *AIS_LocalContext::ActsOn* function, which informs the Local Context if it acts on specific types of sub-shapes. By default, this function answers *FALSE*.
Only type filters are activated in Neutral Point to make it possible to identify a specific type of visualized object. For filters to come into play, one or more object selection modes must be activated.
Dynamic detection and selection are put into effect in a straightforward way. There are only a few conventions and functions to be familiar with. The functions are the same in neutral point and in open local context:
* *AIS_InteractiveContext::Select* -- stocks what has been detected on the last *MoveTo*. Replaces the previously selected object. Empties the stack if nothing has been detected at the last move
* *AIS_InteractiveContext::ShiftSelect* -- if the object detected at the last move was not already selected, it is added to the list of the selected objects. If not, it is withdrawn. Nothing happens if you click on an empty area.
Highlighting of detected and selected entities is automatically managed by the Interactive Context, whether you are in neutral point or Local Context. The Highlight colors are those dealt with above. You can nonetheless disconnect this automatic mode if you want to manage this part yourself :
If there is no open local context, the objects selected are called **current objects**. If there is a local context, they are called **selected objects**. Iterators allow entities to be recovered in either case. A set of functions allows manipulating the objects, which have been placed in these different lists.
When a Local Context is open, you can select entities other than interactive objects (vertices, edges etc.) from decompositions in standard modes, or from activation in specific modes on specific interactive objects. Only interactive objects are stocked in the list of selected objects.
After using the *Select* and *ShiftSelect* functions in Neutral Point, you can explore the list of selections, referred to as current objects in this context. The following functions can be used:
You have to ask whether you have selected a shape or an interactive object before you can recover the entity in the Local Context or in the iteration loop. If you have selected a Shape from *TopoDS* on decomposition in standard mode, the *Interactive()* function returns the interactive object, which provided the selected shape. Other functions allow you to manipulate the content of Selected or Current Objects:
* *AIS_InteractiveContext::SetSelectedCurrent* takes the list of selected objects from a local context and puts it into the list of current objects in Neutral Point;
* *AIS_InteractiveContext::KeepTemporary* transfers the characteristics of the interactive object seen in its local context (visualization mode, etc.) to the neutral point. When the local context is closed, the object does not disappear.
You can also want to use function *AIS_InteractiveContext::ClearLocalContext* to modify in a general way the state of the local context before continuing a selection (emptying objects, removing filters, standard activation modes).
When you want to work on one type of entity, you should open a local context with the option *UseDisplayedObjects* set to FALSE. Some functions which allow you to recover the visualized interactive objects, which have a given Type, and Signature from the "Neutral Point" are:
* The Interactive Objects visualized at Neutral Point are activated with their default selection mode. You must deactivate those, which you do not want to use.
* The "temporary" Interactive Objects present in the Local Contexts are not automatically taken into account. You have to load them manually if you want to use them.
It is useful to create an **interactive editor**, to which you pass the Interactive Context. This allow setting up different contexts of selection/presentation according to the operation, which you want to perform.
* **None** -- a token, that instead of eliminating the object, tells the application to look further until it finds an acceptable object definition in its generation.
Inside these categories, there is a possibility of additional characterization by means of a signature. The signature provides an index to the further characterization. By default, the **Interactive Object** has a *None* type and a signature of 0 (equivalent to *None*).
If you want to give a particular type and signature to your interactive object, you must redefine the two virtual methods: <i>Type</i> and <i>Signature</i>.
For the presentation of planes and trihedra, the default length unit is millimeter and the default value for the representation of axes is 10. To modify these dimensions, you must temporarily recover the object **Drawer**. From it, take the *DatumAspect()* and change the value *FirstAxisLength*. Finally, recalculate the presentation.
* *AIS_ConnectedInteractive* is an Interactive Object connecting to another interactive object reference, and located elsewhere in the viewer makes it possible not to calculate presentation and selection, but to deduce them from your object reference.
* *AIS_MultipleConnectedInteractive* is an object connected to a list of interactive objects (which can also be Connected objects. It does not require memory hungry calculations of presentation)
* *AIS_TexturedShape* is an Interactive Object that supports texture mapping. It is constructed as a usual AIS_Shape, but has additional methods that allow to map a texture on it.
* *MeshVS_Mesh* is an Interactive Object that represents meshes, it has a data source that provides geometrical information (nodes, elements) and can be built up from the source data with a custom presentation builder.
The presentation class *AIS_PointCloud* can be used for efficient drawing of large arbitrary sets of colored points. It uses *Graphic3d_ArrayOfPoints* to pass point data into OpenGl graphic driver to draw a set points as an array of "point sprites". The point data is packed into vertex buffer object for performance.
- The presentation provides selection by a bounding box of the visualized set of points. It supports two display / highlighting modes: points or bounding box.
The **Relation** is made up of constraints on one or more interactive shapes and the corresponding reference geometry. For example, you might want to constrain two edges in a parallel relation. This constraint is considered as an object in its own right, and is shown as a sensitive primitive. This takes the graphic form of a perpendicular arrow marked with the || symbol and lying between the two edges.
*MeshVS_Mesh* is an Interactive Object that represents meshes. This object differs from the *AIS_Shape* as its geometrical data is supported by the data source *MeshVS_DataSource* that describes nodes and elements of the object. As a result, you can provide your own data source.
However, the *DataSource* does not provide any information on attributes, for example nodal colors, but you can apply them in a special way -- by choosing the appropriate presentation builder.
The presentations of *MeshVS_Mesh* are built with the presentation builders *MeshVS_PrsBuilder*. You can choose between the builders to represent the object in a different way. Moreover, you can redefine the base builder class and provide your own presentation builder.
There is a set of reserved display and highlighting mode flags for *MeshVS_Mesh*. Mode value is a number of bits that allows selecting additional display parameters and combining the following mode flags, which allow displaying mesh in wireframe, shading and shrink modes:
The dynamic selection represents the topological shape, which you want to select, by decomposition of <i>sensitive primitives</i> -- the sub-parts of the shape that will be detected and highlighted. The sets of these primitives are handled by the powerful three-level BVH tree selection algorithm.
* **Anti-aliasing** This mode attempts to improve the screen resolution by drawing lines and curves in a mixture of colors so that to the human eye the line or curve is smooth. The quality of the result is linked to the quality of the algorithm used by the workstation hardware.
* **Group** -- a set of primitives and attributes on those primitives. Primitives and attributes may be added to a group but cannot be removed from it, unless erased globally. A group can have a pick identity.
* **Light** There are five kinds of light source -- ambient, headlight, directional, positional and spot. The light is only activated in a shading context in a view.
* **Primitive** -- a drawable element. It has a definition in 3D space. Primitives can either be lines, faces, text, or markers. Once displayed markers and text remain the same size. Lines and faces can be modified e.g. zoomed. Primitives must be stored in a group.
* **Structure** -- manages a set of groups. The groups are mutually exclusive. A structure can be edited, adding or removing groups. A structure can reference other structures to form a hierarchy. It has a default (identity) transformation and other transformations may be applied to it (rotation, translation, scale, etc). It has no default attributes for the primitive lines, faces, markers, and text. Attributes may be set in a structure but they are overridden by the attributes in each group. Each structure has a display priority associated with it, which rules the order in which it is redrawn in a 3D viewer. If the visualization mode is incompatible with the view it is not displayed in that view, e.g. a shading-only object is not visualized in a wireframe view.
* **View mapping** -- defines the transformation from View Reference Coordinates to the Normalized Projection Coordinates. This follows the Phigs scheme.
* **Z-Buffering** -- a form of hidden surface removal in shading mode only. This is always active for a view in the shading mode. It cannot be suppressed.
The *Graphic3d* package is used to create 3D graphic objects in a 3D viewer. These objects called **structures** are made up of groups of primitives and attributes, such as polylines, planar polygons with or without holes, text and markers, and attributes, such as color, transparency, reflection, line type, line width, and text font. A group is the smallest editable element of a structure. A transformation can be applied to a structure. Structures can be connected to form a tree of structures, composed by transformations. Structures are globally manipulated by the viewer.
The root is the top of a structure hierarchy or structure network. The attributes of a parent structure are passed to its descendants. The attributes of the descendant structures do not affect the parent. Recursive structure networks are not supported.
* Geometric attributes -- character height, character up vector, text path, horizontal and vertical alignment, orientation, three-dimensional position, zoomable flag
Primitive arrays are a more efficient approach to describe and display the primitives from the aspects of memory usage and graphical performance. The key feature of the primitive arrays is that the primitive data is not duplicated. For example, two polygons could share the same vertices, so it is more efficient to keep the vertices in a single array and specify the polygon vertices with indices of this array. In addition to such kind of memory savings, the OpenGl graphics driver provides the Vertex Buffer Objects (VBO). VBO is a sort of video memory storage that can be allocated to hold the primitive arrays, thus making the display operations more efficient and releasing the RAM memory.
The Vertex Buffer Objects are enabled by default, but VBOs availability depends on the implementation of OpenGl. If the VBOs are unavailable or there is not enough video memory to store the primitive arrays, the RAM memory will be used to store the arrays.
The Vertex Buffer Objects can be disabled at the application level. You can use the method *Graphic3d_GraphicDriver::EnableVBO (const Standard_Boolean status)* to enable/disable VBOs:
**Note** that the use of Vertex Buffer Objects requires the application level primitive data provided by the *Graphic3d_ArrayOfPrimitives* to be transferred to the video memory. *TKOpenGl* transfers the data and releases the *Graphic3d_ArrayOfPrimitives* internal pointers to the primitive data. Thus it might be necessary to pay attention to such kind of behaviour, as the pointers could be modified (nullified) by the *TKOpenGl*.
These methods take vertex coordinates as an argument and allow you to define the color, the normal and the texture coordinates assigned to the vertex. The return value is the actual number of vertices in the array.
The method *Graphic3d_ArrayOfPrimitives::AddEdge* allows defining the primitives by indices. This method adds an "edge" in the range <i> [1, VertexNumber() ] </i> in the array.
If the primitive array presents primitives built from sequential sets of vertices, for example polygons, then you can specify the bounds, or the number of vertices for each primitive. You can use the method *Graphic3d_ArrayOfPrimitives::AddBound* to define the bounds and the color for each bound. This method returns the actual number of bounds.
The OpenGl graphics driver uses advanced text rendering powered by FTGL library. This library provides vector text rendering, as a result the text can be rotated and zoomed without quality loss.
*AText* parameter is the text string, *APoint* is the three-dimensional position of the text, *AHeight* is the text height, *AAngle* is the orientation of the text (at the moment, this parameter has no effect, but you can specify the text orientation through the *Graphic3d_AspectText3d* attributes).
OCCT visualization core supports GLSL shaders. Currently OCCT supports only vertex and fragment GLSL shader. Shaders can be assigned to a generic presentation by its drawer attributes (Graphic3d aspects). To enable custom shader for a specific AISShape in your application, the following API functions are used:
The *V3d* package provides the resources to define a 3D viewer and the views attached to this viewer (orthographic, perspective). This package provides the commands to manipulate the graphic scene of any 3D object visualized in a view on screen.
A set of high-level commands allows the separate manipulation of parameters and the result of a projection (Rotations, Zoom, Panning, etc.) as well as the visualization attributes (Mode, Lighting, Clipping, etc.) in any particular view.
The *V3d* package is basically a set of tools directed by commands from the viewer front-end. This tool set contains methods for creating and editing classes of the viewer such as:
This sample TEST program for the *V3d* Package uses primary packages *Xw* and *Graphic3d* and secondary packages *Visual3d, Aspect, Quantity* and *math*.
View projection and orientation in OCCT *v3d* view are driven by camera. The camera calculates and supplies projection and view orientation matrices for rendering by OpenGL. The allows to the user to control all projection parameters. The camera is defined by the following properties:
Most common view manipulations (panning, zooming, rotation) are implemented as convenience methods of *V3d_View* class, however *Graphic3d_Camera* class can also be used directly by application developers:
projects / occt.git / blame