0029545: Documentation, visualization.md - article incorrectly specifies that AIS_Con...
[occt.git] / dox / user_guides / visualization / visualization.md
Content-type: text/html OCCT Git - occt.git/blame - dox/user_guides/visualization/visualization.md


500 - Internal Server Error

Malformed UTF-8 character (fatal) at (eval 8) line 1, <$fd> line 3051.
CommitLineData
ba06f8bb 1Visualization {#occt_user_guides__visualization}
bf62b306 2========================
3@tableofcontents
72b7576f 4
bf62b306 5@section occt_visu_1 Introduction
72b7576f 6
7c42f3f4 7Visualization in Open CASCADE Technology is based on the separation of:
8 * on the one hand -- the data which stores the geometry and topology of the entities you want to display and select, and
9 * 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).
72b7576f 10
18006a0f 11Presentations are managed through the **Presentation** component, and selection through the **Selection** component.
72b7576f 12
7c42f3f4 13**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.
72b7576f 14
7c42f3f4 15*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.
72b7576f 16
7c42f3f4 17If, 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.
72b7576f 18
2683e647 19The the following packages are used to display 3D objects:
7c42f3f4 20 * *AIS*;
21 * *StdPrs*;
22 * *Prs3d*;
23 * *PrsMgr*;
24 * *V3d*;
4ee1bdf4 25 * *Graphic3d*.
72b7576f 26
18006a0f 27The packages used to display 3D objects are also applicable for visualization of 2D objects.
72b7576f 28
7c42f3f4 29The 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.
72b7576f 30
d6b4d3d0 31@figure{visualization_image003.png,"Key concepts and packages in visualization",400}
72b7576f 32
2683e647 33To answer different needs of CASCADE users, this User's Guide offers the following three paths in reading it.
7c42f3f4 34
35 * If the 3D services proposed in AIS meet your requirements, you need only read chapter 3 @ref occt_visu_3 "AIS: Application Interactive Services".
36 * 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.
37
e2ba9cb1 38For advanced information on visualization algorithms, see our <a href="http://www.opencascade.com/content/tutorial-learning">E-learning & Training</a> offerings.
72b7576f 39
7c42f3f4 40@section occt_visu_2 Fundamental Concepts
72b7576f 41
7c42f3f4 42@subsection occt_visu_2_1 Presentation
72b7576f 43
7c42f3f4 44In 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.
72b7576f 45
7c42f3f4 46@subsubsection occt_visu_2_1_1 Structure of the Presentation
72b7576f 47
2683e647 48Displaying an object on the screen involves three kinds of entities:
bf62b306 49 * a presentable object, the *AIS_InteractiveObject*
7c42f3f4 50 * a viewer
51 * an interactive context, the *AIS_InteractiveContext*.
52
53#### The presentable object
54
55The 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.
56
57Standard 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.
72b7576f 58
7c42f3f4 59Each object to be presented individually must be presentable or associated with a presentable object.
72b7576f 60
7c42f3f4 61#### The viewer
72b7576f 62
7c42f3f4 63The 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.
72b7576f 64
7c42f3f4 65#### The Interactive Context
72b7576f 66
7c42f3f4 67The 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.
72b7576f 68
bf62b306 69@subsubsection occt_visu_2_1_2 Presentation packages
72b7576f 70
7c42f3f4 71Presentation 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.
18006a0f 72
7c42f3f4 73* *AIS* package provides all classes to implement interactive objects (presentable and selectable entities).
74* *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*.
75* *StdPrs* package provides ready-to-use standard presentation algorithms for specific geometries: points, curves and shapes of the geometry and topology toolkits.
18006a0f 76* *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.
7c42f3f4 77* *V3d* package provides the services supported by the 3D viewer.
2683e647 78* *Graphic3d* package provides resources to create 3D graphic structures.
18006a0f 79* *Visual3d* package contains classes implementing commands for 3D viewer.
80* *DsgPrs* package provides tools for display of dimensions, relations and XYZ trihedrons.
72b7576f 81
7c42f3f4 82@subsubsection occt_visu_2_1_3 A Basic Example: How to display a 3D object
72b7576f 83
bf62b306 84~~~~~
7c42f3f4 85Handle(V3d_Viewer) theViewer;
86Handle(AIS_InteractiveContext) aContext = new AIS_InteractiveContext (theViewer);
bf62b306 87
7c42f3f4 88BRepPrimAPI_MakeWedge aWedgeMaker (theWedgeDX, theWedgeDY, theWedgeDZ, theWedgeLtx);
89TopoDS_Solid aShape = aWedgeMaker.Solid();
90Handle(AIS_Shape) aShapePrs = new AIS_Shape (aShape); // creation of the presentable object
91aContext->Display (aShapePrs); // display the presentable object in the 3d viewer
bf62b306 92~~~~~
dba69de2 93
7c42f3f4 94The 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.
72b7576f 95
d6b4d3d0 96@figure{visualization_image004.svg,"Processes involved in displaying a presentable shape",400}
72b7576f 97
7c42f3f4 98@subsection occt_visu_2_2 Selection
72b7576f 99
a7d4dd94 100Standard 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.
72b7576f 101
a7d4dd94 102There are 3 different selection types:
103 - **Point selection** -- allows picking and highlighting a single object (or its part) located under the mouse cursor;
104 - **Rectangle selection** -- allows picking objects or parts located under the rectangle defined by the start and end mouse cursor positions;
105 - **Polyline selection** -- allows picking objects or parts located under a user-defined non-self-intersecting polyline.
72b7576f 106
7c42f3f4 107For OCCT selection algorithm, all selectable objects are represented as a set of sensitive zones, called **sensitive entities**. When the mouse cursor moves in the view, the sensitive entities of each object are analyzed for collision.
72b7576f 108
a7d4dd94 109@subsubsection occt_visu_2_2_1 Terms and notions
72b7576f 110
a7d4dd94 111This section introduces basic terms and notions used throughout the algorithm description.
72b7576f 112
7c42f3f4 113#### Sensitive entity
72b7576f 114
a7d4dd94 115Sensitive entities in the same way as entity owners are links between objects and the selection mechanism.
72b7576f 116
a7d4dd94 117The 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.
72b7576f 118
d6b4d3d0 119@figure{visualization_image005.png,"Example of a shape divided into sensitive entities",400}
72b7576f 120
a7d4dd94 121Depending 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).
72b7576f 122
a7d4dd94 123Entities 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.
72b7576f 124
7c42f3f4 125#### Entity owner
72b7576f 126
a7d4dd94 127Each 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.
72b7576f 128
7c42f3f4 129#### Selection
72b7576f 130
7c42f3f4 131To simplify the handling of different selection modes of an object, sensitive entities linked to their owners are organized into sets, called **selections**.
a7d4dd94 132Each selection contains entities created for a certain mode along with the sensitivity and update states.
72b7576f 133
7c42f3f4 134#### Selectable object
72b7576f 135
a7d4dd94 136Selectable object stores information about all created selection modes and sensitive entities.
137
138All 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.
139
140For 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:
7c42f3f4 141 - 0 -- selection of entire object (AIS_Shape);
a7d4dd94 142 - 1 -- selection of the vertices;
143 - 2 -- selection of the edges;
144 - 3 -- selection of the wires;
145 - 4 -- selection of the faces;
146 - 5 -- selection of the shells;
147 - 6 -- selection of the constituent solids.
148
d6b4d3d0 149@figure{visualization_image006.png,"Hierarchy of references from sensitive entity to selectable object",400}
a7d4dd94 150
d6b4d3d0 151@figure{visualization_image007.png,"The principle of entities organization within the selectable object",400}
a7d4dd94 152
7c42f3f4 153#### Viewer selector
a7d4dd94 154
155For 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.
a7d4dd94 156The 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.
157
7c42f3f4 158#### Selection manager
a7d4dd94 159
160Selection 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.
161
d6b4d3d0 162@figure{visualization_image008.png,"The relations chain between viewer selector and selection manager",400}
a7d4dd94 163
164@subsubsection occt_visu_2_2_2 Algorithm
165
166All 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.
167
7c42f3f4 168#### Selection Frustum
a7d4dd94 169
170The first step of each run of selection algorithm is to build the selection frustum according to the currently activated selection type.
171
172For 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.
173
174The frustum length is limited by near and far view volume planes and each plane is built parallel to the corresponding view volume plane.
175
d6b4d3d0 176@figure{visualization_image009.png,"",400}
72b7576f 177
d6b4d3d0 178The image above shows the rectangular frustum: a) after mouse move or click, b) after applying the rectangular selection.
179
180@figure{visualization_image010.png,"",400}
181
182In 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.
72b7576f 183
7c42f3f4 184#### BVH trees
72b7576f 185
a7d4dd94 186To maintain selection mechanism at the viewer level, a speedup structure composed of 3 BVH trees is used.
72b7576f 187
7c42f3f4 188The 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 *AIS_InteractiveObject* 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.
72b7576f 189
a7d4dd94 190The 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.
72b7576f 191
a7d4dd94 192The 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.
72b7576f 193
d6b4d3d0 194@figure{visualization_image022.png,"Selection BVH tree hierarchy: from the biggest object-level (first) to the smallest complex entity level (third)",400}
72b7576f 195
7c42f3f4 196#### Stages of the algorithm
72b7576f 197
a7d4dd94 198The algorithm includes pre-processing and three main stages.
72b7576f 199
7c42f3f4 200##### Pre-processing
201
202Implies calculation of the selection frustum and its main characteristics.
72b7576f 203
7c42f3f4 204##### First stage -- traverse of the first level BVH tree
72b7576f 205
7c42f3f4 206After 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 *separating axis theorem (SAT)*. When the traversal 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 object.
207
208##### Second stage -- traversal of the second level BVH tree
72b7576f 209
a7d4dd94 210At this stage it is necessary to determine if there are candidates among all sensitive entities of one object.
72b7576f 211
a7d4dd94 212First 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:
213 - activation check - the entity may be inactive at the moment as it belongs to deactivated selection;
214 - 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.
72b7576f 215
a7d4dd94 216After these checks the algorithm passes to the last stage.
72b7576f 217
7c42f3f4 218##### Third stage -- overlap or inclusion test of a particular sensitive entity
18006a0f 219
a7d4dd94 220If 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.
72b7576f 221
a7d4dd94 222@subsubsection occt_visu_2_2_3 Packages and classes
72b7576f 223
7c42f3f4 224Selection is implemented as a combination of various algorithms divided among several packages -- *SelectBasics*, *Select3D*, *SelectMgr* and *StdSelect*.
18006a0f 225
7c42f3f4 226#### SelectBasics
18006a0f 227
7c42f3f4 228*SelectBasics* package contains basic classes and interfaces for selection. The most notable are:
229 - *SelectBasics_SensitiveEntity* -- the base definition of a sensitive entity;
230 - *SelectBasics_EntityOwner* -- the base definition of the an entity owner -- the link between the sensitive entity and the object to be selected;
231 - *SelectBasics_PickResult* -- the structure for storing quantitative results of detection procedure, for example, depth and distance to the center of geometry;
232 - *SelectBasics_SelectingVolumeManager* -- the interface for interaction with the current selection frustum.
18006a0f 233
7c42f3f4 234Each custom sensitive entity must inherit at least *SelectBasics_SensitiveEntity*.
18006a0f 235
7c42f3f4 236#### Select3D
18006a0f 237
7c42f3f4 238*Select3D* package provides a definition of standard sensitive entities, such as:
a7d4dd94 239 - box;
240 - circle;
241 - curve;
242 - face;
243 - group;
244 - point;
245 - segment;
246 - triangle;
247 - triangulation;
248 - wire.
18006a0f 249
7c42f3f4 250Each basic sensitive entity inherits *Select3D_SensitiveEntity*, which is a child class of *SelectBasics_SensitiveEntity*.
251The package also contains two auxiliary classes, *Select3D_SensitivePoly* and *Select3D_SensitiveSet*.
18006a0f 252
7c42f3f4 253*Select3D_SensitiveSet* -- 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.
72b7576f 254
7c42f3f4 255*Select3D_SensitivePoly* -- 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 *Select3D_SensitivePoly* must satisfy the terms of Separating Axis Theorem to use standard OCCT overlap detection methods.
18006a0f 256
7c42f3f4 257#### SelectMgr
18006a0f 258
7c42f3f4 259*SelectMgr* package is used to maintain the whole selection process. For this purpose, the package provides the following services:
a7d4dd94 260 - activation and deactivation of selection modes for all selectable objects;
261 - interfaces to compute selection mode of the object;
262 - definition of selection filter classes;
263 - keeping selection BVH data up-to-date.
18006a0f 264
a7d4dd94 265A brief description of the main classes:
7c42f3f4 266 - *SelectMgr_FrustumBase*, *SelectMgr_Frustum*, *SelectMgr_RectangularFrustum*, *SelectMgr_TriangluarFrustum* and *SelectMgr_TriangularFrustumSet* -- 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);
267 - *SelectMgr_SensitiveEntity*, *SelectMgr_Selection* and *SelectMgr_SensitiveEntitySet* -- store and handle sensitive entities; *SelectMgr_SensitiveEntitySet* implements a primitive set for the second level BVH tree;
268 - *SelectMgr_SelectableObject* and *SelectMgr_SelectableObjectSet* -- describe selectable objects. They also manage storage, calculation and removal of selections. *SelectMgr_SelectableObjectSet* implements a primitive set for the first level BVH tree;
269 - *SelectMgr_ViewerSelector* -- encapsulates all logics of the selection algorithm and implements the third level BVH tree traverse;
270 - *SelectMgr_SelectionManager* -- manages activation/deactivation, calculation and update of selections of every selectable object, and keeps BVH data up-to-date.
18006a0f 271
7c42f3f4 272#### StdSelect
a7d4dd94 273
7c42f3f4 274*StdSelect* package contains the implementation of some *SelectMgr* classes and tools for creation of selection structures. For example,
275 - *StdSelect_BRepOwner* -- defines an entity owner with a link to its topological shape and methods for highlighting;
276 - *StdSelect_BRepSelectionTool* -- contains algorithms for splitting standard AIS shapes into sensitive primitives;
277 - *StdSelect_ViewerSelector3d* -- an example of *SelectMgr_ViewerSelecor* implementation, which is used in a default OCCT selection mechanism;
278 - *StdSelect_FaceFilter*, *StdSelect_EdgeFilter* -- implementation of selection filters.
a7d4dd94 279
280@subsubsection occt_visu_2_2_4 Examples of usage
281
7c42f3f4 282The first code snippet illustrates the implementation of *SelectMgr_SelectableObject::ComputeSelection()* method in a custom interactive object. The method is used for computation of user-defined selection modes.
a7d4dd94 283Let us assume it is required to make a box selectable in two modes -- the whole shape (mode 0) and each of its edges (mode 1).
a7d4dd94 284To 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.
a7d4dd94 285To 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.
18006a0f 286
287~~~~
7c42f3f4 288void InteractiveBox::ComputeSelection (const Handle(SelectMgr_Selection)& theSel,
18006a0f 289 const Standard_Integer theMode)
290{
a7d4dd94 291 switch (theMode)
18006a0f 292 {
7c42f3f4 293 case 0: // creation of face sensitives for selection of the whole box
18006a0f 294 {
7c42f3f4 295 Handle(SelectMgr_EntityOwner) anOwner = new SelectMgr_EntityOwner (this, 5);
296 for (Standard_Integer aFaceIter = 1; aFaceIter <= myNbFaces; ++aFaceIter)
297 {
298 Select3D_TypeOfSensitivity aSensType = myIsInterior;
299 theSel->Add (new Select3D_SensitiveFace (anOwner, myFaces[aFaceIter]->PointArray(), aSensType));
300 }
301 break;
18006a0f 302 }
7c42f3f4 303 case 1: // creation of edge sensitives for selection of box edges only
18006a0f 304 {
7c42f3f4 305 for (Standard_Integer anEdgeIter = 1; anEdgeIter <= 12; ++anEdgeIter)
306 {
307 // 1 owner per edge, where 6 is a priority of the sensitive
308 Handle(MySelection_EdgeOwner) anOwner = new MySelection_EdgeOwner (this, anEdgeIter, 6);
309 theSel->Add (new Select3D_SensitiveSegment (anOwner, myFirstPnt[anEdgeIter]), myLastPnt[anEdgeIter]));
310 }
311 break;
18006a0f 312 }
313 }
314}
18006a0f 315~~~~
316
7c42f3f4 317The algorithms for creating selection structures store sensitive primitives in *SelectMgr_Selection* instance. Each *SelectMgr_Selection* sequence in the list of selections of the object must correspond to a particular selection mode.
318To describe the decomposition of the object into selectable primitives, a set of ready-made sensitive entities is supplied in *Select3D* package. Custom sensitive primitives can be defined through inheritance from *SelectBasics_SensitiveEntity*.
319To make custom interactive objects selectable or customize selection modes of existing objects, the entity owners must be defined. They must inherit *SelectMgr_EntityOwner* interface.
a7d4dd94 320
7c42f3f4 321Selection structures for any interactive object are created in *SelectMgr_SelectableObject::ComputeSelection()* method.
322The example below shows how computation of different selection modes of the topological shape can be done using standard OCCT mechanisms, implemented in *StdSelect_BRepSelectionTool*.
18006a0f 323
324~~~~
a7d4dd94 325 void MyInteractiveObject::ComputeSelection (const Handle(SelectMgr_Selection)& theSelection,
326 const Standard_Integer theMode)
18006a0f 327 {
328 switch (theMode)
329 {
7c42f3f4 330 case 0: StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_SHAPE); break;
331 case 1: StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_VERTEX); break;
332 case 2: StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_EDGE); break;
333 case 3: StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_WIRE); break;
334 case 4: StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_FACE); break;
18006a0f 335 }
336 }
337~~~~
338
7c42f3f4 339The *StdSelect_BRepSelectionTool* 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 *TopoDS_Shape*.
18006a0f 340
341The 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:
342
7c42f3f4 343 - each entity owner has to maintain its own *Prs3d_Presentation* object, that results in a considerable memory overhead;
344 - drawing selected owners one by one is not efficient from the visualization point of view.
72b7576f 345
a7d4dd94 346Therefore, 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.
18006a0f 347
7c42f3f4 348On the basis of *SelectMgr_EntityOwner::IsAutoHilight()* return value, *AIS_InteractiveContext* object either uses the traditional way of highlighting (in case if *IsAutoHilight()* returns TRUE) or groups such owners according to their selectable objects and finally calls *SelectMgr_SelectableObject::HilightSelected()* or *SelectMgr_SelectableObject::ClearSelected()*, passing a group of owners as an argument.
18006a0f 349
7c42f3f4 350Hence, an application can derive its own interactive object and redefine virtual methods *HilightSelected()*, *ClearSelected()* and *HilightOwnerWithColor()* from *SelectMgr_SelectableObject*. *SelectMgr_SelectableObject::GetHilightPresentation* and *SelectMgr_SelectableObject::GetSelectPresentation* methods can be used to optimize filling of selection and highlight presentations according to the user's needs.
351The *AIS_InteractiveContext::HighlightSelected()* method can be used for efficient redrawing of the selection presentation for a given interactive object from an application code.
72b7576f 352
7c42f3f4 353After all the necessary sensitive entities are computed and packed in *SelectMgr_Selection* instance with the corresponding owners in a redefinition of *SelectMgr_SelectableObject::ComputeSelection()* method, it is necessary to register the prepared selection in *SelectMgr_SelectionManager* through the following steps:
354 - if there was no *AIS_InteractiveContext* opened, create an interactive context and display the selectable object in it;
355 - load the selectable object to the selection manager of the interactive context using *AIS_InteractiveContext::Load()* method. If the selection mode passed as a parameter to this method is not equal to -1, *ComputeSelection()* for this selection mode will be called;
356 - activate or deactivate the defined selection mode using *AIS_InteractiveContext::Activate()* or *AIS_InteractiveContext::Deactivate()* methods.
72b7576f 357
7c42f3f4 358After 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.
72b7576f 359
a7d4dd94 360The code snippet below illustrates the above steps. It also contains the code to start the detection procedure and parse the results of selection.
72b7576f 361
a7d4dd94 362~~~~~
a7d4dd94 363// Suppose there is an instance of class InteractiveBox from the previous sample.
364// It contains an implementation of method InteractiveBox::ComputeSelection() for selection
365// modes 0 (whole box must be selected) and 1 (edge of the box must be selectable)
7c42f3f4 366Handle(InteractiveBox) theBox;
367Handle(AIS_InteractiveContext) theContext;
a7d4dd94 368// To prevent automatic activation of the default selection mode
7c42f3f4 369theContext->SetAutoActivateSelection (false);
370theContext->Display (theBox, false);
a7d4dd94 371
372// Load a box to the selection manager without computation of any selection mode
7c42f3f4 373theContext->Load (theBox, -1, true);
a7d4dd94 374// Activate edge selection
7c42f3f4 375theContext->Activate (theBox, 1);
a7d4dd94 376
7c42f3f4 377// Run the detection mechanism for activated entities in the current mouse coordinates and in the current view.
378// Detected owners will be highlighted with context highlight color
379theContext->MoveTo (aXMousePos, aYMousePos, myView);
a7d4dd94 380// Select the detected owners
7c42f3f4 381theContext->Select();
a7d4dd94 382// Iterate through the selected owners
7c42f3f4 383for (theContext->InitSelected(); theContext->MoreSelected() && !aHasSelected; theContext->NextSelected())
a7d4dd94 384{
7c42f3f4 385 Handle(AIS_InteractiveObject) anIO = theContext->SelectedInteractive();
a7d4dd94 386}
72b7576f 387
a7d4dd94 388// deactivate all selection modes for aBox1
7c42f3f4 389theContext->Deactivate (aBox1);
bf62b306 390~~~~~
72b7576f 391
a7d4dd94 392It is also important to know, that there are 2 types of detection implemented for rectangular selection in OCCT:
393 - <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;
394 - <b>overlap</b> detection. In this case the sensitive primitive is considered detected when it is partially overlapped by the selection rectangle.
72b7576f 395
a7d4dd94 396The standard OCCT selection mechanism uses inclusion detection by default. To change this, use the following code:
72b7576f 397
a7d4dd94 398~~~~~
7c42f3f4 399// Assume there is a created interactive context
400const Handle(AIS_InteractiveContext) theContext;
a7d4dd94 401// Retrieve the current viewer selector
7c42f3f4 402const Handle(StdSelect_ViewerSelector3d)& aMainSelector = theContext->MainSelector();
a7d4dd94 403// Set the flag to allow overlap detection
7c42f3f4 404aMainSelector->AllowOverlapDetection (true);
a7d4dd94 405~~~~~
72b7576f 406
7c42f3f4 407@section occt_visu_3 Application Interactive Services
408@subsection occt_visu_3_1 Introduction
72b7576f 409
7c42f3f4 410Application Interactive Services allow managing presentations and dynamic selection in a viewer in a simple and transparent manner.
411The central entity for management of visualization and selections is the **Interactive Context**. It is connected to the main viewer.
72b7576f 412
7c42f3f4 413Interactive context by default starts at **Neutral Point** with each selectable object picked as a whole, but the user might activate **Local Selection** for specific objects to make selectable parts of the objects.
414Local/global selection is managed by a list of selection modes activated for each displayed object with 0 (default selection mode) usually meaning Global (entire object) selection.
72b7576f 415
7c42f3f4 416**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.
72b7576f 417
7c42f3f4 418An 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.
419When an Interactive Object is visualized, the required graphic attributes are taken from its own **Drawer** (*Prs3d_Drawer*) if it has the required custom attributes or otherwise from the context drawer.
72b7576f 420
d6b4d3d0 421@figure{visualization_image017.png,"",360}
72b7576f 422
7c42f3f4 423It 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 only within at the Neutral Point, others only within Local Selection. It is possible to program custom filters and load them into the interactive context.
72b7576f 424
bf62b306 425@subsection occt_visu_3_2 Interactive objects
72b7576f 426
18006a0f 427Entities 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.
428
bf62b306 429@subsubsection occt_visu_3_2_1 Presentations
72b7576f 430
7c42f3f4 431An interactive object can have as many presentations as its creator wants to give it.
4323D presentations are managed by **Presentation Manager** (*PrsMgr_PresentationManager*). As this is transparent in AIS, the user does not have to worry about it.
72b7576f 433
7c42f3f4 434A presentation is identified by an index (*Display Mode*) and by the reference to the Presentation Manager, which it depends on.
435By convention, the default mode of representation for the Interactive Object has index 0.
72b7576f 436
d6b4d3d0 437@figure{visualization_image018.png,"",360}
72b7576f 438
7c42f3f4 439Calculation 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.
72b7576f 440
7c42f3f4 441If you are creating your own type of interactive object, you must implement the Compute function in one of the following ways:
72b7576f 442
bf62b306 443#### For 3D:
72b7576f 444
bf62b306 445~~~~~
7c42f3f4 446void PackageName_ClassName::Compute (const Handle(PrsMgr_PresentationManager3d)& thePresentationManager,
447 const Handle(Prs3d_Presentation)& thePresentation,
448 const Standard_Integer theMode);
bf62b306 449~~~~~
72b7576f 450
7c42f3f4 451#### For hidden line removal (HLR) mode in 3D:
bf62b306 452~~~~~
7c42f3f4 453void PackageName_ClassName::Compute (const Handle(Prs3d_Projector)& theProjector,
454 const Handle(Prs3d_Presentation)& thePresentation);
bf62b306 455~~~~~
72b7576f 456
bf62b306 457@subsubsection occt_visu_3_2_2 Hidden Line Removal
72b7576f 458
7c42f3f4 459The 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.
72b7576f 460
7c42f3f4 461By convention, the Interactive Object accepts or rejects the representation of HLR mode. It is possible to make this declaration in one of two ways:
72b7576f 462
7c42f3f4 463* Initially by using one of the values of the enumeration *PrsMgr_TypeOfPresentation*:
bf62b306 464 * *PrsMgr_TOP_AllView*,
465 * *PrsMgr_TOP_ProjectorDependant*
72b7576f 466
7c42f3f4 467* Later by using the function *PrsMgr_PresentableObject::SetTypeOfPresentation*
72b7576f 468
7c42f3f4 469*AIS_Shape* class is an example of an interactive object that supports HLR representation.
470The type of the HLR algorithm is stored in *Prs3d_Drawer* of the shape. It is a value of the *Prs3d_TypeOfHLR* enumeration and can be set to:
471 * *Prs3d_TOH_PolyAlgo* for a polygonal algorithm based on the shape's triangulation;
472 * *Prs3d_TOH_Algo* for an exact algorithm that works with the shape's real geometry;
473 * *Prs3d_TOH_NotSet* if the type of algorithm is not set for the given interactive object instance.
72b7576f 474
7c42f3f4 475The type of the HLR algorithm used for *AIS_Shape* can be changed by calling the *AIS_Shape::SetTypeOfHLR()* method.
476The current HLR algorithm type can be obtained using *AIS_Shape::TypeOfHLR()* method is to be used.
72b7576f 477
7c42f3f4 478These 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*.
479So 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.
72b7576f 480
bf62b306 481@subsubsection occt_visu_3_2_3 Presentation modes
72b7576f 482
7c42f3f4 483There are four types of interactive objects in AIS:
484 * the "construction element" or Datum,
485 * the Relation (dimensions and constraints)
486 * the Object
487 * the None type (when the object is of an unknown type).
72b7576f 488
7c42f3f4 489Inside 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:
490 * *AIS_InteractiveObject::Type*
491 * *AIS_InteractiveObject::Signature*.
72b7576f 492
7c42f3f4 493**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").
72b7576f 494
7c42f3f4 495The 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.
496Consequently, to get information about this class it is necessary to use virtual function *AIS_InteractiveObject::AcceptDisplayMode*.
72b7576f 497
bf62b306 498#### Display Mode
72b7576f 499
bf62b306 500The 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.
72b7576f 501
bf62b306 502#### Highlight Mode
72b7576f 503
7c42f3f4 504At dynamic detection, the presentation echoed by the Interactive Context, is by default the presentation already on the screen.
72b7576f 505
7c42f3f4 506The 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.
72b7576f 507
7c42f3f4 508Note 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).
72b7576f 509
7c42f3f4 510For 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.
72b7576f 511
bf62b306 512#### Infinite Status
7c42f3f4 513
514If 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.
515
516Let us take for example the class called *IShape* representing an interactive object:
517
518~~~~~
519myPk_IShape::myPK_IShape (const TopoDS_Shape& theShape, PrsMgr_TypeOfPresentation theType)
520: AIS_InteractiveObject (theType), myShape (theShape) { SetHilightMode (0); }
521
522void myPk_IShape::Compute (const Handle(PrsMgr_PresentationManager3d)& thePrsMgr,
523 const Handle(Prs3d_Presentation)& thePrs,
524 const Standard_Integer theMode)
525{
526 switch (theMode)
527 {
528 // algo for calculation of wireframe presentation
529 case 0: StdPrs_WFDeflectionShape::Add (thePrs, myShape, myDrawer); return;
530 // algo for calculation of shading presentation
531 case 1: StdPrs_ShadedShape::Add (thePrs, myShape, myDrawer); return;
532 }
533}
534
535void myPk_IShape::Compute (const Handle(Prs3d_Projector)& theProjector,
536 const Handle(Prs3d_Presentation)& thePrs)
537{
538 // Hidden line mode calculation algorithm
539 StdPrs_HLRPolyShape::Add (thePrs, myShape, myDrawer, theProjector);
bf62b306 540}
541~~~~~
72b7576f 542
7c42f3f4 543@subsubsection occt_visu_3_2_4 Selection
72b7576f 544
7c42f3f4 545An interactive object can have an indefinite number of selection modes, each representing a "decomposition" into sensitive primitives. Each primitive has an **Owner** (*SelectMgr_EntityOwner*) which allows identifying the exact interactive object or shape which has been detected (see @ref occt_visu_2_2 "Selection" chapter).
72b7576f 546
7c42f3f4 547The set of sensitive primitives, which correspond to a given mode, is stocked in a **Selection** (*SelectMgr_Selection*).
72b7576f 548
7c42f3f4 549Each 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 *SelectMgr_SelectableObject::setGlobalSelMode()*.
72b7576f 550
ebcbd824 551The 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*.
a7d4dd94 552A detailed explanation of the mechanism and the manner of implementing this function has been given in @ref occt_visu_2_2 "Selection" chapter.
72b7576f 553
a7d4dd94 554There 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*.
2683e647 555
bf62b306 556@subsubsection occt_visu_3_2_5 Graphic attributes
72b7576f 557
7c42f3f4 558Graphic attributes manager, or *Prs3d_Drawer*, stores graphic attributes for specific interactive objects and for interactive objects controlled by interactive context.
18006a0f 559
560Initially, all drawer attributes are filled out with the predefined values which will define the default 3D object appearance.
18006a0f 561When 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.
562
563Keep in mind the following points concerning graphic attributes:
7c42f3f4 564 * Each interactive object can have its own visualization attributes.
565 * 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.)
566 * 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.
72b7576f 567
7c42f3f4 568@figure{visualization_image020.svg,"Redefinition of virtual functions for changes in AIS_Shape and AIS_TextLabel.",360}
72b7576f 569
7c42f3f4 570The following virtual functions provide settings for color, width, material and transparency:
571 * *AIS_InteractiveObject::UnsetColor*
572 * *AIS_InteractiveObject::SetWidth*
573 * *AIS_InteractiveObject::UnsetWidth*
574 * *AIS_InteractiveObject::SetMaterial*
575 * *AIS_InteractiveObject::UnsetMaterial*
576 * *AIS_InteractiveObject::SetTransparency*
577 * *AIS_InteractiveObject::UnsetTransparency*
72b7576f 578
7c42f3f4 579These methods can be used as a shortcut assigning properties in common way, but result might be not available.
580Some interactive objects might not implement these methods at all or implement only a sub-set of them.
581Direct modification of *Prs3d_Drawer* properties returned by *AIS_InteractiveObject::Attributes* can be used for more precise and predictable configuration.
72b7576f 582
7c42f3f4 583It is important to know which functions may imply the recalculation of presentations of the object.
584If the presentation mode of an interactive object is to be updated, a flag from *PrsMgr_PresentableObject* indicates this.
585The mode can be updated using the functions *Display* and *Redisplay* in *AIS_InteractiveContext*.
72b7576f 586
7c42f3f4 587@subsubsection occt_visu_3_2_6 Complementary Services
72b7576f 588
7c42f3f4 589When you use complementary services for interactive objects, pay special attention to the cases mentioned below.
72b7576f 590
bf62b306 591#### Change the location of an interactive object
72b7576f 592
7c42f3f4 593The following functions allow "moving" the representation and selection of Interactive Objects in a view without recalculation (and modification of the original shape).
594 * *AIS_InteractiveContext::SetLocation*
595 * *AIS_InteractiveContext::ResetLocation*
596 * *AIS_InteractiveContext::HasLocation*
597 * *AIS_InteractiveContext::Location*
72b7576f 598
7c42f3f4 599#### Connect an interactive object to an applicative entity
72b7576f 600
7c42f3f4 601Each Interactive Object has functions that allow attributing it an *Owner* in form of a *Transient*.
602 * *AIS_InteractiveObject::SetOwner*
603 * *AIS_InteractiveObject::HasOwner*
604 * *AIS_InteractiveObject::Owner*
72b7576f 605
7c42f3f4 606An interactive object can therefore be associated or not with an applicative entity, without affecting its behavior.
72b7576f 607
7c42f3f4 608**NOTE:** Don't be confused by owners of another kind - *SelectBasics_EntityOwner* used for identifying selectable parts of the object or object itself.
72b7576f 609
7c42f3f4 610#### Resolving coincident topology
72b7576f 611
7c42f3f4 612Due 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.
72b7576f 613
7c42f3f4 614To 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.
72b7576f 615
7c42f3f4 616The methods *AIS_InteractiveObject::SetPolygonOffsets* and *AIS_InteractiveContext::SetPolygonOffsets* allow setting up the polygon offsets.
ebcbd824 617
618@subsubsection occt_visu_3_2_7 Object hierarchy
619
620Each *PrsMgr_PresentableObject* has a list of objects called *myChildren*.
621Any transformation of *PrsMgr_PresentableObject* is also applied to its children. This hierarchy does not propagate to *Graphic3d* level and below.
622
623*PrsMgr_PresentableObject* sends its combined (according to the hierarchy) transformation down to *Graphic3d_Structure*.
ebcbd824 624The materials of structures are not affected by the hierarchy.
625
626Object hierarchy can be controlled by the following API calls:
7c42f3f4 627* *PrsMgr_PresentableObject::AddChild*;
628* *PrsMgr_PresentableObject::RemoveChild*.
ebcbd824 629
630@subsubsection occt_visu_3_2_8 Instancing
631
632The conception of instancing operates the object hierarchy as follows:
7c42f3f4 633* Instances are represented by separated *AIS* objects.
634* Instances do not compute any presentations.
ebcbd824 635
636Classes *AIS_ConnectedInteractive* and *AIS_MultipleConnectedInteractive* are used to implement this conception.
637
49225e2f 638*AIS_ConnectedInteractive* is an object instance, which reuses the geometry of the connected object but has its own transformation and visibility flag. This connection is propagated down to *OpenGl* level, namely to *OpenGl_Structure*. *OpenGl_Structure* can be connected only to a single other structure.
ebcbd824 639
7c42f3f4 640*AIS_ConnectedInteractive* can be referenced to any *AIS_InteractiveObject* in general. When it is referenced to another *AIS_ConnectedInteractive*, it just copies the reference.
ebcbd824 641
642*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.
643
644All *AIS_MultipleConnectedInteractive* are able to have child assemblies. Deep copy of object instances tree is performed if one assembly is attached to another.
645
646Note 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.
647
648Instances can be controlled by the following DRAW commands:
7c42f3f4 649* *vconnect* : Creates and displays *AIS_MultipleConnectedInteractive* object from input objects and location.
650* *vconnectto* : Makes an instance of object with the given position.
651* *vdisconnect* : Disconnects all objects from an assembly or disconnects an object by name or number.
652* *vaddconnected* : Adds an object to the assembly.
653* *vlistconnected* : Lists objects in the assembly.
ebcbd824 654
655Have a look at the examples below:
656~~~~~
657pload ALL
658vinit
659psphere s 1
660vdisplay s
661vconnectto s2 3 0 0 s # make instance
662vfit
663~~~~~
664
665See how proxy *OpenGl_Structure* is used to represent instance:
666
d6b4d3d0 667@figure{/user_guides/visualization/images/visualization_image029.png,"",240}
ebcbd824 668
669The original object does not have to be displayed in order to make instance. Also selection handles transformations of instances correctly:
670
671~~~~~
672pload ALL
673vinit
674psphere s 1
675psphere p 0.5
676vdisplay s # p is not displayed
677vsetloc s -2 0 0
678vconnect x 3 0 0 s p # make assembly
679vfit
680~~~~~
681
d6b4d3d0 682@figure{/user_guides/visualization/images/visualization_image030.png,"",420}
ebcbd824 683
684Here is the example of a more complex hierarchy involving sub-assemblies:
685
686~~~~~
687pload ALL
688vinit
689box b 1 1 1
690psphere s 0.5
691vdisplay b s
692vsetlocation s 0 2.5 0
693box d 0.5 0.5 3
694box d2 0.5 3 0.5
695vdisplay d d2
696
697vconnectto b1 -2 0 0 b
698vconnect z 2 0 0 b s
699vconnect z2 4 0 0 d d2
700vconnect z3 6 0 0 z z2
701vfit
702~~~~~
703
7c42f3f4 704@subsection occt_visu_3_3 Interactive Context
ebcbd824 705
7c42f3f4 706@subsubsection occt_visu_3_3_1 Rules
72b7576f 707
7c42f3f4 708The 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.
72b7576f 709
7c42f3f4 710There 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.
72b7576f 711
bf62b306 712~~~~~
7c42f3f4 713Handle(AIS_Shape) aShapePrs = new AIS_Shape (theShape);
714myIntContext->Display (aShapePrs, AIS_Shaded, 0, false, aShapePrs->AcceptShapeDecomposition());
715myIntContext->SetColor(aShapePrs, Quantity_NOC_RED);
bf62b306 716~~~~~
72b7576f 717
7c42f3f4 718You can also write
72b7576f 719
bf62b306 720~~~~~
7c42f3f4 721Handle(AIS_Shape) aShapePrs = new AIS_Shape (theShape);
722aShapePrs->SetColor (Quantity_NOC_RED);
723aShapePrs->SetDisplayMode (AIS_Shaded);
724myIntContext->Display (aShapePrs);
bf62b306 725~~~~~
72b7576f 726
7c42f3f4 727@subsubsection occt_visu_3_3_2 Groups of functions
72b7576f 728
7c42f3f4 729**Neutral Point** and **Local Selection** constitute the two operating modes or states of the **Interactive Context**, which is the central entity which pilots visualizations and selections.
730The **Neutral Point**, which is the default mode, allows easily visualizing and selecting interactive objects, which have been loaded into the context.
731Activating **Local Selection** for specific Objects allows selecting of their sub-parts.
72b7576f 732
7c42f3f4 733@subsubsection occt_visu_3_3_3 Management of the Interactive Context
18006a0f 734
735An 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.
7c42f3f4 736When an interactive object is visualized, the required graphic attributes are first taken from the object's own *Drawer* if it exists, or from the context drawer if otherwise.
18006a0f 737
7c42f3f4 738The following adjustable settings allow personalizing the behavior of presentations and selections:
739 * Default Drawer, containing all the color and line attributes which can be used by interactive objects, which do not have their own attributes.
740 * Default Visualization Mode for interactive objects. By default: *mode 0*;
741 * Highlight color of entities detected by mouse movement. By default: *Quantity_NOC_CYAN1*;
742 * Pre-selection color. By default: *Quantity_NOC_GREEN*;
743 * Selection color (when you click on a detected object). By default: *Quantity_NOC_GRAY80*;
72b7576f 744
7c42f3f4 745All of these settings can be modified by functions proper to the Context.
746When 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.
18006a0f 747
7c42f3f4 748Let us examine the case of two interactive objects: *theObj1* and *theObj2*:
72b7576f 749
bf62b306 750~~~~~
7c42f3f4 751theCtx->Display (theObj1, false);
752theCtx->Display (theObj2, true); // TRUE for viewer update
753theCtx->SetDisplayMode (theObj1, 3, false);
754theCtx->SetDisplayMode (2, true);
755// theObj2 is visualised in mode 2 (if it accepts this mode)
756// theObj1 stays visualised in its mode 3
bf62b306 757~~~~~
72b7576f 758
7c42f3f4 759*PresentationManager* and *Selector3D*, which manage the presentation and selection of present interactive objects, are associated to the main Viewer.
72b7576f 760
7c42f3f4 761@subsection occt_visu_3_4 Local Selection
72b7576f 762
7c42f3f4 763@subsubsection occt_visu_3_4_1 Selection Modes
72b7576f 764
7c42f3f4 765The Local Selection is defined by index (Selection Mode). The Selection Modes implemented by a specific interactive object and their meaning should be checked within the documentation of this class.
766See, for example, *MeshVS_SelectionModeFlags* for *MeshVS_Mesh* object.
72b7576f 767
7c42f3f4 768The interactive object, which is used the most by applications, is *AIS_Shape*. Consequently, there are standard functions, which allow you to easily prepare selection operations on the constituent elements of shapes (selection of vertices, edges, faces, etc.). The Selection Mode for a specific shape type (*TopAbs_ShapeEnum*) is returned by method *AIS_Shape::SelectionMode()*.
72b7576f 769
7c42f3f4 770The function *AIS_InteractiveObject::Display* (without argument taking Selection Mode) activates the object's default Selection Mode.
771The functions *AIS_InteractiveContext::Activate* and *AIS_InteractiveContext::Deactivate* activate and deactivate specific Selection Mode.
72b7576f 772
7c42f3f4 773More than one Selection Mode can be activated at the same time (but default 0 mode for selecting entire object is exclusive - it cannot be combined with others).
774The list of active modes can be retrieved using function *AIS_InteractiveContext::ActivatedModes*.
72b7576f 775
7c42f3f4 776@subsubsection occt_visu_3_4_2 Filters
bf62b306 777
7c42f3f4 778To define an environment of dynamic detection, you can use standard filter classes or create your own.
779A filter questions the owner of the sensitive primitive to determine if it has the desired qualities. If it answers positively, it is kept. If not, it is rejected.
bf62b306 780
7c42f3f4 781The root class of objects is *SelectMgr_Filter*. The principle behind it is straightforward: a filter tests to see whether the owners (*SelectMgr_EntityOwner*) detected in mouse position by selector answer *OK*. If so, it is kept, otherwise it is rejected.
782You can create a custom class of filter objects by implementing the deferred function *SelectMgr_Filter::IsOk()*.
72b7576f 783
7c42f3f4 784In *SelectMgr*, there are also Composition filters (AND Filters, OR Filters), which allow combining several filters. In Interactive Context, all filters that you add are stored in an OR filter (which answers *OK* if at least one filter answers *OK*).
72b7576f 785
7c42f3f4 786There are Standard filters, which have already been implemented in several packages:
787 * *StdSelect_EdgeFilter* -- for edges, such as lines and circles;
788 * *StdSelect_FaceFilter* -- for faces, such as planes, cylinders and spheres;
789 * *StdSelect_ShapeTypeFilter* -- for shape types, such as compounds, solids, shells and wires;
790 * *AIS_TypeFilter* -- for types of interactive objects;
791 * *AIS_SignatureFilter* -- for types and signatures of interactive objects;
792 * *AIS_AttributeFilter* -- for attributes of Interactive Objects, such as color and width.
72b7576f 793
7c42f3f4 794There are several functions to manipulate filters:
795* *AIS_InteractiveContext::AddFilter* adds a filter passed as an argument.
796* *AIS_InteractiveContext::RemoveFilter* removes a filter passed as an argument.
797* *AIS_InteractiveContext::RemoveFilters* removes all present filters.
798* *AIS_InteractiveContext::Filters* gets the list of filters active in a context.
72b7576f 799
7c42f3f4 800#### Example
72b7576f 801
bf62b306 802~~~~~
7c42f3f4 803// shading visualization mode, no specific mode, authorization for decomposition into sub-shapes
804const TopoDS_Shape theShape;
805Handle(AIS_Shape) aShapePrs = new AIS_Shape (theShape);
806myContext->Display (aShapePrs, AIS_Shaded, -1, true, true);
72b7576f 807
7c42f3f4 808// activates decomposition of shapes into faces
809const int aSubShapeSelMode = AIS_Shape::SelectionMode (TopAbs_Face);
810myContext->Activate (aShapePrs, aSubShapeSelMode);
72b7576f 811
7c42f3f4 812Handle(StdSelect_FaceFilter) aFil1 = new StdSelect_FaceFilter (StdSelect_Revol);
813Handle(StdSelect_FaceFilter) aFil2 = new StdSelect_FaceFilter (StdSelect_Plane);
814myContext->AddFilter (aFil1);
815myContext->AddFilter (aFil2);
72b7576f 816
7c42f3f4 817// only faces of revolution or planar faces will be selected
818myContext->MoveTo (thePixelX, thePixelY, myView);
bf62b306 819~~~~~
72b7576f 820
7c42f3f4 821@subsubsection occt_visu_3_4_6 Selection
72b7576f 822
7c42f3f4 823Dynamic detection and selection are put into effect in a straightforward way. There are only a few conventions and functions to be familiar with:
824 * *AIS_InteractiveContext::MoveTo* -- passes mouse position to Interactive Context selectors.
825 * *AIS_InteractiveContext::Select* -- stores what has been detected at the last *MoveTo*. Replaces the previously selected object. Empties the stack if nothing has been detected at the last move.
826 * *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.
827 * *AIS_InteractiveContext::Select* -- selects everything found in the surrounding area.
828 * *AIS_InteractiveContext::ShiftSelect* -- selects what was not previously in the list of selected, deselects those already present.
bf62b306 829
7c42f3f4 830Highlighting of detected and selected entities is automatically managed by the Interactive Context. The Highlight colors are those dealt with above. You can nonetheless disconnect this automatic mode if you want to manage this part yourself:
bf62b306 831~~~~~
7c42f3f4 832 AIS_InteractiveContext::SetAutomaticHilight
833 AIS_InteractiveContext::AutomaticHilight
bf62b306 834~~~~~
72b7576f 835
7c42f3f4 836You can question the Interactive context by moving the mouse. The following functions can be used:
837 * *AIS_InteractiveContext::HasDetected* -- checks if there is a detected entity;
838 * *AIS_InteractiveContext::DetectedOwner* -- returns the (currently highlighted) detected entity.
bf62b306 839
7c42f3f4 840After using the *Select* and *ShiftSelect* functions, you can explore the list of selections. The following functions can be used:
841 * *AIS_InteractiveContext::InitSelected* -- initializes an iterator;
842 * *AIS_InteractiveContext::MoreSelected* -- checks if the iterator is valid;
843 * *AIS_InteractiveContext::NextSelected* -- moves the iterator to the next position;
844 * *AIS_InteractiveContext::SelectedOwner* -- returns an entity at the current iterator position.
72b7576f 845
7c42f3f4 846The owner object *SelectMgr_EntityOwner* is a key object identifying selectable entitiy in the viewer (returned by methods *AIS_InteractiveContext::DetectedOwner* and *AIS_InteractiveContext::SelectedOwner*).
847The Interactive Object itself can be retrieved by method *SelectMgr_EntityOwner::Selectable*, while identifying sub-part depends on type of Interactive Object.
848In case of *AIS_Shape*, the (sub)shape is returned by method *StdSelect_BRepOwner::Shape*.
72b7576f 849
7c42f3f4 850#### Example
bf62b306 851~~~~~
7c42f3f4 852for (myAISCtx->InitSelected(); myAISCtx->MoreSelected(); myAISCtx->NextSelected())
bf62b306 853{
7c42f3f4 854 Handle(SelectMgr_EntityOwner) anOwner = myAISCtx->SelectedOwner();
855 Handle(AIS_InteractiveObject) anObj = Handle(AIS_InteractiveObject)::DownCast (anOwner->Selectable());
856 if (Handle(StdSelect_BRepOwner) aBRepOwner = Handle(StdSelect_BRepOwner)::DownCast (anOwner))
857 {
858 // to be able to use the picked shape
859 TopoDS_Shape aShape = aBRepOwner->Shape();
860 }
bf62b306 861}
862~~~~~
72b7576f 863
7c42f3f4 864@subsection occt_visu_3_5 Standard Interactive Object Classes
72b7576f 865
18006a0f 866Interactive Objects are selectable and viewable objects connecting graphic representation and the underlying reference geometry.
867
868They are divided into four types:
3f812249 869 * the **Datum** -- a construction geometric element;
870 * the **Relation** -- a constraint on the interactive shape and the corresponding reference geometry;
871 * the **Object** -- a topological shape or connection between shapes;
872 * **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.
18006a0f 873
874Inside 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*).
7c42f3f4 875If you want to give a particular type and signature to your interactive object, you must redefine the two virtual methods: *Type* and *Signature*.
18006a0f 876
877@subsubsection occt_visu_3_5_1 Datum
878
879The **Datum** groups together the construction elements such as lines, circles, points, trihedrons, plane trihedrons, planes and axes.
7c42f3f4 880
881*AIS_Point, AIS_Axis, AIS_Line, AIS_Circle, AIS_Plane* and *AIS_Trihedron* have four selection modes:
882 * mode 0 : selection of a trihedron;
883 * mode 1 : selection of the origin of the trihedron;
884 * mode 2 : selection of the axes;
885 * mode 3 : selection of the planes XOY, YOZ, XOZ.
886
887when you activate one of modes: 1 2 3 4, you pick AIS objects of type:
888 * *AIS_Point*;
889 * *AIS_Axis* (and information on the type of axis);
890 * *AIS_Plane* (and information on the type of plane).
891
892*AIS_PlaneTrihedron* offers three selection modes:
893 * mode 0 : selection of the whole trihedron;
894 * mode 1 : selection of the origin of the trihedron;
3f812249 895 * mode 2 : selection of the axes -- same remarks as for the Trihedron.
72b7576f 896
7c42f3f4 897For 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.
e5bd0d98 898
18006a0f 899@subsubsection occt_visu_3_5_2 Object
900
901The **Object** type includes topological shapes, and connections between shapes.
e5bd0d98 902
7c42f3f4 903*AIS_Shape* has two visualization modes:
904 * mode 0 : Line (default mode)
905 * mode 1 : Shading (depending on the type of shape)
72b7576f 906
7c42f3f4 907*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.
908*AIS_MultipleConnectedInteractive* is an object connected to a list of interactive objects (which can also be Connected objects. It does not require memory-hungry presentation calculations).
72b7576f 909
7c42f3f4 910*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.
18006a0f 911
912The class *AIS_ColoredShape* allows using custom colors and line widths for *TopoDS_Shape* objects and their sub-shapes.
913
914~~~~~
915 AIS_ColoredShape aColoredShape = new AIS_ColoredShape (theShape);
916
917 // setup color of entire shape
7c42f3f4 918 aColoredShape->SetColor (Quantity_NOC_RED);
18006a0f 919
920 // setup line width of entire shape
921 aColoredShape->SetWidth (1.0);
922
923 // set transparency value
924 aColoredShape->SetTransparency (0.5);
925
926 // customize color of specified sub-shape
7c42f3f4 927 aColoredShape->SetCustomColor (theSubShape, Quantity_NOC_BLUE1);
18006a0f 928
929 // customize line width of specified sub-shape
930 aColoredShape->SetCustomWidth (theSubShape, 0.25);
931~~~~~
932
933The 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.
934- The type of point marker used to draw points can be specified as a presentation aspect.
935- The presentation provides selection by a bounding box of the visualized set of points. It supports two display / highlighting modes: points or bounding box.
936
d6b4d3d0 937@figure{point_cloud.png,"A random colored cloud of points",240}
18006a0f 938
939Example:
940~~~~~
941Handle(Graphic3d_ArrayOfPoints) aPoints = new Graphic3d_ArrayOfPoints (2000, Standard_True);
942aPoints->AddVertex (gp_Pnt(-40.0, -40.0, -40.0), Quantity_Color (Quantity_NOC_BLUE1));
943aPoints->AddVertex (gp_Pnt (40.0, 40.0, 40.0), Quantity_Color (Quantity_NOC_BLUE2));
944
945Handle(AIS_PointCloud) aPntCloud = new AIS_PointCloud();
946aPntCloud->SetPoints (aPoints);
947~~~~~
948
949The draw command *vpointcloud* builds a cloud of points from shape triangulation.
950This command can also draw a sphere surface or a volume with a large amount of points (more than one million).
951
bf62b306 952@subsubsection occt_visu_3_5_3 Relations
18006a0f 953
954The **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.
955
956The following relations are provided by *AIS*:
bf62b306 957 * *AIS_ConcentricRelation*
958 * *AIS_FixRelation*
959 * *AIS_IdenticRelation*
960 * *AIS_ParallelRelation*
961 * *AIS_PerpendicularRelation*
962 * *AIS_Relation*
963 * *AIS_SymmetricRelation*
964 * *AIS_TangentRelation*
72b7576f 965
7c42f3f4 966The list of relations is not exhaustive.
72b7576f 967
bf62b306 968@subsubsection occt_visu_3_5_4 Dimensions
7c42f3f4 969 * *AIS_AngleDimension*
970 * *AIS_Chamf3dDimension*
971 * *AIS_DiameterDimension*
bf62b306 972 * *AIS_DimensionOwner*
973 * *AIS_LengthDimension*
974 * *AIS_OffsetDimension*
975 * *AIS_RadiusDimension*
72b7576f 976
7c42f3f4 977@subsubsection occt_visu_3_5_5 MeshVS_Mesh
72b7576f 978
7c42f3f4 979*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.
72b7576f 980
7c42f3f4 981However, 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.
72b7576f 982
7c42f3f4 983The 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.
72b7576f 984
7c42f3f4 985You can add/remove builders using the following methods:
bf62b306 986~~~~~
7c42f3f4 987 MeshVS_Mesh::AddBuilder (const Handle(MeshVS_PrsBuilder)& theBuilder, Standard_Boolean theToTreatAsHilighter);
988 MeshVS_Mesh::RemoveBuilder (const Standard_Integer theIndex);
989 MeshVS_Mesh::RemoveBuilderById (const Standard_Integer theId);
bf62b306 990~~~~~
72b7576f 991
7c42f3f4 992There 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:
bf62b306 993~~~~~
994 MeshVS_DMF_WireFrame
995 MeshVS_DMF_Shading
996 MeshVS_DMF_Shrink
7c42f3f4 997~~~~~
72b7576f 998
7c42f3f4 999It is also possible to display deformed mesh in wireframe, shading or shrink modes usung:
1000~~~~~
1001 MeshVS_DMF_DeformedPrsWireFrame
1002 MeshVS_DMF_DeformedPrsShading
1003 MeshVS_DMF_DeformedPrsShrink
bf62b306 1004~~~~~
72b7576f 1005
7c42f3f4 1006The following methods represent different kinds of data:
bf62b306 1007~~~~~
7c42f3f4 1008 MeshVS_DMF_VectorDataPrs
bf62b306 1009 MeshVS_DMF_NodalColorDataPrs
1010 MeshVS_DMF_ElementalColorDataPrs
1011 MeshVS_DMF_TextDataPrs
1012 MeshVS_DMF_EntitiesWithData
7c42f3f4 1013~~~~~
bf62b306 1014
7c42f3f4 1015The following methods provide selection and highlighting:
bf62b306 1016~~~~~
1017 MeshVS_DMF_SelectionPrs
1018 MeshVS_DMF_HilightPrs
7c42f3f4 1019~~~~~
72b7576f 1020
7c42f3f4 1021*MeshVS_DMF_User* is a user-defined mode.
72b7576f 1022
7c42f3f4 1023These values will be used by the presentation builder.
1024There is also a set of selection modes flags that can be grouped in a combination of bits:
bf62b306 1025 * *MeshVS_SMF_0D*
1026 * *MeshVS_SMF_Link*
1027 * *MeshVS_SMF_Face*
1028 * *MeshVS_SMF_Volume*
7c42f3f4 1029 * *MeshVS_SMF_Element* -- groups *0D, Link, Face* and *Volume* as a bit mask;
bf62b306 1030 * *MeshVS_SMF_Node*
7c42f3f4 1031 * *MeshVS_SMF_All* -- groups *Element* and *Node* as a bit mask;
bf62b306 1032 * *MeshVS_SMF_Mesh*
1033 * *MeshVS_SMF_Group*
1034
7c42f3f4 1035Such an object, for example, can be used for displaying the object and stored in the STL file format:
72b7576f 1036
bf62b306 1037~~~~~
1038// read the data and create a data source
4178b353 1039Handle(Poly_Triangulation) aSTLMesh = RWStl::ReadFile (aFileName);
1040Handle(XSDRAWSTLVRML_DataSource) aDataSource = new XSDRAWSTLVRML_DataSource (aSTLMesh);
72b7576f 1041
7c42f3f4 1042// create mesh
1043Handle(MeshVS_Mesh) aMeshPrs = new MeshVS();
1044aMeshPrs->SetDataSource (aDataSource);
72b7576f 1045
bf62b306 1046// use default presentation builder
7c42f3f4 1047Handle(MeshVS_MeshPrsBuilder) aBuilder = new MeshVS_MeshPrsBuilder (aMeshPrs);
1048aMeshPrs->AddBuilder (aBuilder, true);
bf62b306 1049~~~~~
72b7576f 1050
7c42f3f4 1051*MeshVS_NodalColorPrsBuilder* allows representing a mesh with a color scaled texture mapped on it.
1052To do this you should define a color map for the color scale, pass this map to the presentation builder, and define an appropriate value in the range of 0.0 - 1.0 for every node.
1053The following example demonstrates how you can do this (check if the view has been set up to display textures):
bf62b306 1054
1055~~~~~
1056// assign nodal builder to the mesh
7c42f3f4 1057Handle(MeshVS_NodalColorPrsBuilder) aBuilder = new MeshVS_NodalColorPrsBuilder (theMeshPrs, MeshVS_DMF_NodalColorDataPrs | MeshVS_DMF_OCCMask);
1058aBuilder->UseTexture (true);
bf62b306 1059
1060// prepare color map
7c42f3f4 1061Aspect_SequenceOfColor aColorMap;
1062aColorMap.Append (Quantity_NOC_RED);
1063aColorMap.Append (Quantity_NOC_BLUE1);
bf62b306 1064
1065// assign color scale map values (0..1) to nodes
7c42f3f4 1066TColStd_DataMapOfIntegerReal aScaleMap;
2683e647 1067...
bf62b306 1068// iterate through the nodes and add an node id and an appropriate value to the map
7c42f3f4 1069aScaleMap.Bind (anId, aValue);
1070
bf62b306 1071// pass color map and color scale values to the builder
7c42f3f4 1072aBuilder->SetColorMap (aColorMap);
1073aBuilder->SetInvalidColor (Quantity_NOC_BLACK);
1074aBuilder->SetTextureCoords (aScaleMap);
1075aMesh->AddBuilder (aBuilder, true);
bf62b306 1076~~~~~
72b7576f 1077
7c42f3f4 1078@subsection occt_visu_3_6 Dynamic Selection
72b7576f 1079
7c42f3f4 1080The dynamic selection represents the topological shape, which you want to select, by decomposition of *sensitive primitives* -- 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.
72b7576f 1081
a7d4dd94 1082For more details on the algorithm and examples of usage, please, refer to @ref occt_visu_2_2 "Selection" chapter.
72b7576f 1083
bf62b306 1084@section occt_visu_4 3D Presentations
72b7576f 1085
7c42f3f4 1086@subsection occt_visu_4_1 Glossary of 3D terms
72b7576f 1087
7c42f3f4 1088* **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.
3f812249 1089* **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.
1090* **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.
7c42f3f4 1091* **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.
1092* **View** -- is defined by a view orientation, a view mapping, and a context view.
3f812249 1093* **Viewer** -- manages a set of views.
1094* **View orientation** -- defines the manner in which the observer looks at the scene in terms of View Reference Coordinates.
1095* **View mapping** -- defines the transformation from View Reference Coordinates to the Normalized Projection Coordinates. This follows the Phigs scheme.
1096* **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.
72b7576f 1097
18006a0f 1098@subsection occt_visu_4_2 Graphic primitives
72b7576f 1099
18006a0f 1100The *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.
72b7576f 1101
7c42f3f4 1102Graphic structures can be:
1103 * Displayed,
1104 * Highlighted,
1105 * Erased,
1106 * Transformed,
18006a0f 1107 * Connected to form a tree hierarchy of structures, created by transformations.
7c42f3f4 1108
1109There are classes for:
1110 * Visual attributes for lines, faces, markers, text, materials,
1111 * Vectors and vertices,
1112 * Graphic objects, groups, and structures.
72b7576f 1113
18006a0f 1114@subsubsection occt_visu_4_2_2 Structure hierarchies
bf62b306 1115
18006a0f 1116The 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.
1117
1118@subsubsection occt_visu_4_2_3 Graphic primitives
7c42f3f4 1119* **Markers**
1120 * Have one or more vertices,
1121 * Have a type, a scale factor, and a color,
1122 * Have a size, shape, and orientation independent of transformations.
1123* **Triangulation**
1124 * Have at least three vertices,
1125 * Have nodal normals defined for shading,
1126 * Have interior attributes -- style, color, front and back material, texture and reflection ratio,
1127* **Polylines** or **Segments**
1128 * Have two or more vertices,
1129 * Have the following attributes -- type, width scale factor, color.
1130* **Text**
1131 * Has geometric and non-geometric attributes,
1132 * Geometric attributes -- character height, character up vector, text path, horizontal and vertical alignment, orientation, three-dimensional position, zoomable flag
1133 * Non-geometric attributes -- text font, character spacing, character expansion factor, color.
1134
1135@subsubsection occt_visu_4_2_4 Primitive arrays
1136
1137The different types of primitives could be presented with the following primitive arrays:
bf62b306 1138 * *Graphic3d_ArrayOfPoints,*
bf62b306 1139 * *Graphic3d_ArrayOfPolylines,*
bf62b306 1140 * *Graphic3d_ArrayOfSegments,*
1141 * *Graphic3d_ArrayOfTriangleFans,*
1142 * *Graphic3d_ArrayOfTriangles,*
1143 * *Graphic3d_ArrayOfTriangleStrips.*
1144
7c42f3f4 1145The *Graphic3d_ArrayOfPrimitives* is a base class for these primitive arrays.
1146Method set *Graphic3d_ArrayOfPrimitives::AddVertex* allows adding vertices to the primitive array with their attributes (color, normal, texture coordinates).
1147You can also modify the values assigned to the vertex or query these values by the vertex index.
bf62b306 1148
7c42f3f4 1149The following example shows how to define an array of points:
72b7576f 1150
bf62b306 1151~~~~~
1152// create an array
7c42f3f4 1153Handle(Graphic3d_ArrayOfPoints) anArray = new Graphic3d_ArrayOfPoints (theVerticiesMaxCount);
bf62b306 1154
1155// add vertices to the array
7c42f3f4 1156anArray->AddVertex (10.0, 10.0, 10.0);
1157anArray->AddVertex (0.0, 10.0, 10.0);
72b7576f 1158
bf62b306 1159// add the array to the structure
7c42f3f4 1160Handle(Graphic3d_Group) aGroup = thePrs->NewGroup();
1161aGroup->AddPrimitiveArray (anArray);
1162aGroup->SetGroupPrimitivesAspect (myDrawer->PointAspect()->Aspect());
bf62b306 1163~~~~~
72b7576f 1164
7c42f3f4 1165If the primitives share the same vertices (polygons, triangles, etc.) then you can define them as indices of the vertices array.
1166The method *Graphic3d_ArrayOfPrimitives::AddEdge* allows defining the primitives by indices. This method adds an "edge" in the range *[1, VertexNumber()]* in the array.
1167It is also possible to query the vertex defined by an edge using method *Graphic3d_ArrayOfPrimitives::Edge*.
72b7576f 1168
7c42f3f4 1169The following example shows how to define an array of triangles:
72b7576f 1170
bf62b306 1171~~~~~
1172// create an array
7c42f3f4 1173Standard_Boolean hasNormals = false;
1174Standard_Boolean hasColors = false;
1175Standard_Boolean hasTextureCrds = false;
1176Handle(Graphic3d_ArrayOfTriangles) anArray = new Graphic3d_ArrayOfTriangles (theVerticesMaxCount, theEdgesMaxCount, hasNormals, hasColors, hasTextureCrds);
bf62b306 1177// add vertices to the array
7c42f3f4 1178anArray->AddVertex (-1.0, 0.0, 0.0); // vertex 1
1179anArray->AddVertex ( 1.0, 0.0, 0.0); // vertex 2
1180anArray->AddVertex ( 0.0, 1.0, 0.0); // vertex 3
1181anArray->AddVertex ( 0.0,-1.0, 0.0); // vertex 4
bf62b306 1182
1183// add edges to the array
7c42f3f4 1184anArray->AddEdge (1); // first triangle
1185anArray->AddEdge (2);
1186anArray->AddEdge (3);
1187anArray->AddEdge (1); // second triangle
1188anArray->AddEdge (2);
1189anArray->AddEdge (4);
bf62b306 1190
1191// add the array to the structure
7c42f3f4 1192Handle(Graphic3d_Group) aGroup = thePrs->NewGroup();
1193aGroup->AddPrimitiveArray (anArray);
1194aGroup->SetGroupPrimitivesAspect (myDrawer->ShadingAspect()->Aspect());
bf62b306 1195~~~~~
1196
18006a0f 1197@subsubsection occt_visu_4_2_5 Text primitive
72b7576f 1198
7c42f3f4 1199TKOpenGL toolkit renders text labels using texture fonts. *Graphic3d* text primitives have the following features:
1200 * fixed size (non-zoomable) or zoomable,
72b7576f 1201 * can be rotated to any angle in the view plane,
1202 * support unicode charset.
1203
7c42f3f4 1204The text attributes for the group could be defined with the *Graphic3d_AspectText3d* attributes group.
1205To add any text to the graphic structure you can use the following methods:
1206~~~~~
1207void Graphic3d_Group::Text (const Standard_CString theText,
1208 const Graphic3d_Vertex& thePoint,
1209 const Standard_Real theHeight,
1210 const Quantity_PlaneAngle theAngle,
1211 const Graphic3d_TextPath theTp,
1212 const Graphic3d_HorizontalTextAlignment theHta,
1213 const Graphic3d_VerticalTextAlignment theVta,
1214 const Standard_Boolean theToEvalMinMax);
1215~~~~~
1216*theText* parameter is the text string, *thePoint* is the three-dimensional position of the text, *theHeight* is the text height, *theAngle* 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).
1217*theTp* parameter defines the text path, *theHta* is the horizontal alignment of the text, *theVta* is the vertical alignment of the text.
1218You can pass FALSE as *theToEvalMinMax* if you do not want the graphic3d structure boundaries to be affected by the text position.
1219
1220**Note** that the text orientation angle can be defined by *Graphic3d_AspectText3d* attributes.
1221~~~~~
1222void Graphic3d_Group::Text (const Standard_CString theText,
1223 const Graphic3d_Vertex& thePoint,
1224 const Standard_Real theHeight,
1225 const Standard_Boolean theToEvalMinMax);
1226void Graphic3d_Group::Text (const TCcollection_ExtendedString& theText,
1227 const Graphic3d_Vertex& thePoint,
1228 const Standard_Real theHeight,
1229 const Quantity_PlaneAngle theAngle,
1230 const Graphic3d_TextPath theTp,
1231 const Graphic3d_HorizontalTextAlignment theHta,
1232 const Graphic3d_VerticalTextAlignment theVta,
1233 const Standard_Boolean theToEvalMinMax);
1234void Graphic3d_Group::Text (const TCcollection_ExtendedString& theText,
1235 const Graphic3d_Vertex& thePoint,
1236 const Standard_Real theHeight,
1237 const Standard_Boolean theToEvalMinMax);
bf62b306 1238~~~~~
72b7576f 1239
bf62b306 1240See the example:
1241~~~~~
1242// get the group
7c42f3f4 1243Handle(Graphic3d_Group) aGroup = thePrs->NewGroup();
72b7576f 1244
7c42f3f4 1245// change the text aspect
1246Handle(Graphic3d_AspectText3d) aTextAspect = new Graphic3d_AspectText3d();
1247aTextAspect->SetTextZoomable (true);
1248aTextAspect->SetTextAngle (45.0);
1249aGroup->SetPrimitivesAspect (aTextAspect);
72b7576f 1250
7c42f3f4 1251// add a text primitive to the structure
1252Graphic3d_Vertex aPoint (1, 1, 1);
1253aGroup->Text (Standard_CString ("Text"), aPoint, 16.0);
bf62b306 1254~~~~~
1255
18006a0f 1256@subsubsection occt_visu_4_2_6 Materials
1257
1258A *Graphic3d_MaterialAspect* is defined by:
1259 * Transparency;
3f812249 1260 * Diffuse reflection -- a component of the object color;
18006a0f 1261 * Ambient reflection;
3f812249 1262 * Specular reflection -- a component of the color of the light source;
18006a0f 1263 * Refraction index.
1264
1265The following items are required to determine the three colors of reflection:
1266 * Color;
1267 * Coefficient of diffuse reflection;
1268 * Coefficient of ambient reflection;
1269 * Coefficient of specular reflection.
1270
1271@subsubsection occt_visu_4_2_7 Textures
1272
1273A *texture* is defined by a name.
1274Three types of texture are available:
1275 * 1D;
1276 * 2D;
1277 * Environment mapping.
1278
1279@subsubsection occt_visu_4_2_8 Shaders
1280
7c42f3f4 1281OCCT visualization core supports GLSL shaders. Shaders can be assigned to a generic presentation by its drawer attributes (Graphic3d aspects). To enable custom shader for a specific AIS_Shape in your application, the following API functions can be used:
18006a0f 1282
1283~~~~~
1284// Create shader program
1285Handle(Graphic3d_ShaderProgram) aProgram = new Graphic3d_ShaderProgram();
1286
1287// Attach vertex shader
7c42f3f4 1288aProgram->AttachShader (Graphic3d_ShaderObject::CreateFromFile (Graphic3d_TOS_VERTEX, "<Path to VS>"));
18006a0f 1289
1290// Attach fragment shader
7c42f3f4 1291aProgram->AttachShader (Graphic3d_ShaderObject::CreateFromFile (Graphic3d_TOS_FRAGMENT, "<Path to FS>"));
18006a0f 1292
1293// Set values for custom uniform variables (if they are)
7c42f3f4 1294aProgram->PushVariable ("MyColor", Graphic3d_Vec3 (0.0f, 1.0f, 0.0f));
18006a0f 1295
7c42f3f4 1296// Set aspect property for specific AIS_Shape
18006a0f 1297theAISShape->Attributes()->ShadingAspect()->Aspect()->SetShaderProgram (aProgram);
1298~~~~~
72b7576f 1299
18006a0f 1300@subsection occt_visu_4_3 Graphic attributes
72b7576f 1301
18006a0f 1302@subsubsection occt_visu_4_3_1 Aspect package overview
72b7576f 1303
18006a0f 1304The *Aspect* package provides classes for the graphic elements in the viewer:
1305 * Groups of graphic attributes;
1306 * Edges, lines, background;
1307 * Window;
1308 * Driver;
1309 * Enumerations for many of the above.
72b7576f 1310
18006a0f 1311@subsection occt_visu_4_4 3D view facilities
72b7576f 1312
18006a0f 1313@subsubsection occt_visu_4_4_1 Overview
72b7576f 1314
7c42f3f4 1315The *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.
72b7576f 1316
7c42f3f4 1317A 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.
bf62b306 1318
7c42f3f4 1319The *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:
1320 * Default parameters of the viewer,
1321 * Views (orthographic, perspective),
1322 * Lighting (positional, directional, ambient, spot, headlight),
89a929ea 1323 * Clipping planes,
7c42f3f4 1324 * Instantiated sequences of views, planes, light sources, graphic structures, and picks,
1325 * Various package methods.
72b7576f 1326
18006a0f 1327@subsubsection occt_visu_4_4_2 A programming example
72b7576f 1328
cfece3ef 1329This sample TEST program for the *V3d* Package uses primary packages *Xw* and *Graphic3d* and secondary packages *Visual3d, Aspect, Quantity* and *math*.
1330
1331~~~~~
7c42f3f4 1332// create a default display connection
cfece3ef 1333Handle(Aspect_DisplayConnection) aDispConnection = new Aspect_DisplayConnection();
7c42f3f4 1334// create a Graphic Driver
cfece3ef 1335Handle(OpenGl_GraphicDriver) aGraphicDriver = new OpenGl_GraphicDriver (aDispConnection);
7c42f3f4 1336// create a Viewer to this Driver
cfece3ef 1337Handle(V3d_Viewer) VM = new V3d_Viewer (aGraphicDriver);
1338VM->SetDefaultBackgroundColor (Quantity_NOC_DARKVIOLET);
1339VM->SetDefaultViewProj (V3d_Xpos);
1340// Create a structure in this Viewer
1341Handle(Graphic3d_Structure) aStruct = new Graphic3d_Structure (VM->Viewer());
1342
1343// Type of structure
1344aStruct->SetVisual (Graphic3d_TOS_SHADING);
4ee1bdf4 1345
1346// Create a group of primitives in this structure
cfece3ef 1347Handle(Graphic3d_Group) aPrsGroup = new Graphic3d_Group (aStruct);
72b7576f 1348
cfece3ef 1349// Fill this group with one quad of size 100
1350Handle(Graphic3d_ArrayOfTriangleStrips) aTriangles = new Graphic3d_ArrayOfTriangleStrips (4);
1351aTriangles->AddVertex (-100./2., -100./2., 0.0);
1352aTriangles->AddVertex (-100./2., 100./2., 0.0);
1353aTriangles->AddVertex ( 100./2., -100./2., 0.0);
1354aTriangles->AddVertex ( 100./2., 100./2., 0.0);
7c42f3f4 1355aPrsGroup->AddPrimitiveArray (aTriangles);
1356aPrsGroup->SetGroupPrimitivesAspect (new Graphic3d_AspectFillArea3d());
72b7576f 1357
7c42f3f4 1358// Create Ambient and Infinite Lights in this Viewer
cfece3ef 1359Handle(V3d_AmbientLight) aLight1 = new V3d_AmbientLight (VM, Quantity_NOC_GRAY50);
1360Handle(V3d_DirectionalLight) aLight2 = new V3d_DirectionalLight (VM, V3d_XnegYnegZneg, Quantity_NOC_WHITE);
72b7576f 1361
4ee1bdf4 1362// Create a 3D quality Window with the same DisplayConnection
cfece3ef 1363Handle(Xw_Window) aWindow = new Xw_Window (aDispConnection, "Test V3d", 0.5, 0.5, 0.5, 0.5);
72b7576f 1364
cfece3ef 1365// Map this Window to this screen
1366aWindow->Map();
72b7576f 1367
4ee1bdf4 1368// Create a Perspective View in this Viewer
cfece3ef 1369Handle(V3d_View) aView = new V3d_View (VM);
18006a0f 1370aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Perspective);
1371// Associate this View with the Window
cfece3ef 1372aView ->SetWindow (aWindow);
18006a0f 1373// Display ALL structures in this View
1374VM->Viewer()->Display();
1375// Finally update the Visualization in this View
1376aView->Update();
18006a0f 1377// Fit view to object size
1378V->FitAll();
1379~~~~~
72b7576f 1380
18006a0f 1381@subsubsection occt_visu_4_4_3 Define viewing parameters
72b7576f 1382
7c42f3f4 1383View 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:
72b7576f 1384
3f812249 1385* **Eye** -- defines the observer (camera) position. Make sure the Eye point never gets between the Front and Back clipping planes.
72b7576f 1386
3f812249 1387* **Center** -- defines the origin of View Reference Coordinates (where camera is aimed at).
72b7576f 1388
3f812249 1389* **Direction** -- defines the direction of camera view (from the Eye to the Center).
72b7576f 1390
3f812249 1391* **Distance** -- defines the distance between the Eye and the Center.
72b7576f 1392
3f812249 1393* **Front** Plane -- defines the position of the front clipping plane in View Reference Coordinates system.
72b7576f 1394
3f812249 1395* **Back** Plane -- defines the position of the back clipping plane in View Reference Coordinates system.
72b7576f 1396
3f812249 1397* **ZNear** -- defines the distance between the Eye and the Front plane.
72b7576f 1398
3f812249 1399* **ZFar** -- defines the distance between the Eye and the Back plane.
dba69de2 1400
18006a0f 1401Most 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:
72b7576f 1402
18006a0f 1403Example:
1404~~~~~
1405// rotate camera by X axis on 30.0 degrees
1406gp_Trsf aTrsf;
1407aTrsf.SetRotation (gp_Ax1 (gp_Pnt (0.0, 0.0, 0.0), gp_Dir (1.0, 0.0, 0.0)), 30.0);
1408aView->Camera()->Transform (aTrsf);
1409~~~~~
72b7576f 1410
18006a0f 1411@subsubsection occt_visu_4_4_4 Orthographic Projection
1412
d6b4d3d0 1413@figure{view_frustum.png,"Perspective and orthographic projection",420}
72b7576f 1414
18006a0f 1415The following code configures the camera for orthographic rendering:
72b7576f 1416
bf62b306 1417~~~~~
18006a0f 1418// Create an orthographic View in this Viewer
1419Handle(V3d_View) aView = new V3d_View (VM);
1420aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Orthographic);
1421// update the Visualization in this View
1422aView->Update();
1423~~~~~
72b7576f 1424
18006a0f 1425@subsubsection occt_visu_4_4_5 Perspective Projection
72b7576f 1426
3f812249 1427