0027750: Visualization, V3d_View - remove unused functionality ZClipping and ZCueing
[occt.git] / dox / user_guides / visualization / visualization.md
ba06f8bb 1Visualization {#occt_user_guides__visualization}
bf62b306 2========================
72b7576f 4
bf62b306 5@section occt_visu_1 Introduction
72b7576f 6
2683e647 7Visualization in Open CASCADE Technology is based on the separation of:
3f812249 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
18006a0f 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
18006a0f 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
bf62b306 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:
4ee1bdf4 20 * *AIS*;
21 * *StdPrs*;
22 * *Prs3d*;
23 * *PrsMgr*;
24 * *V3d*;
25 * *Graphic3d*.
72b7576f 26
18006a0f 27The packages used to display 3D objects are also applicable for visualization of 2D objects.
72b7576f 28
bf62b306 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
bf62b306 31@image html visualization_image003.png "Key concepts and packages in visualization"
32@image latex visualization_image003.png "Key concepts and packages in visualization"
72b7576f 33
2683e647 34To answer different needs of CASCADE users, this User's Guide offers the following three paths in reading it.
67d7f07f 36 * If the 3D services proposed in AIS meet your requirements, you need only read chapter 3 @ref occt_visu_3 "AIS: Application Interactive Services".
3f812249 37 * 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.
e2ba9cb1 38
39For advanced information on visualization algorithms, see our <a href="http://www.opencascade.com/content/tutorial-learning">E-learning & Training</a> offerings.
72b7576f 40
2683e647 41@section occt_visu_2 Fundamental Concepts
72b7576f 42
bf62b306 43@subsection occt_visu_2_1 Presentation
72b7576f 44
bf62b306 45In 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 46
bf62b306 47@subsubsection occt_visu_2_1_1 Structure of the Presentation
72b7576f 48
2683e647 49Displaying an object on the screen involves three kinds of entities:
bf62b306 50 * a presentable object, the *AIS_InteractiveObject*
72b7576f 51 * a viewer
52 * an interactive context, the *AIS_InteractiveContext*.
18006a0f 54<h4>The presentable object</h4>
bf62b306 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.
72b7576f 56
bf62b306 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
bf62b306 59Each object to be presented individually must be presentable or associated with a presentable object.
72b7576f 60
bf62b306 61<h4>The viewer </h4>
18006a0f 62The 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 63
bf62b306 64<h4>The Interactive Context </h4>
65The 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 66
bf62b306 67@subsubsection occt_visu_2_1_2 Presentation packages
72b7576f 68
18006a0f 69Presentation 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.
bf62b306 71* *AIS* package provides all classes to implement interactive objects (presentable and selectable entities).
18006a0f 72* *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*.
73* *StdPrs* package provides ready-to-use standard presentation algorithms for specific geometries: points, curves and shapes of the geometry and topology toolkits.
74* *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.
75* *V3d* package provides the services supported by the 3D viewer.
2683e647 76* *Graphic3d* package provides resources to create 3D graphic structures.
18006a0f 77* *Visual3d* package contains classes implementing commands for 3D viewer.
78* *DsgPrs* package provides tools for display of dimensions, relations and XYZ trihedrons.
72b7576f 79
bf62b306 80@subsubsection occt_visu_2_1_3 A Basic Example: How to display a 3D object
72b7576f 81
bf62b306 82~~~~~
2683e647 83Void Standard_Real dx = ...; //Parameters
84Void Standard_Real dy = ...; //to build a wedge
85Void Standard_Real dz = ...;
bf62b306 86Void Standard_Real ltx = ...;
88Handle(V3d_Viewer)aViewer = ...;
90aContext = new AIS_InteractiveContext(aViewer);
92BRepPrimAPI_MakeWedge w(dx, dy, dz, ltx);
93TopoDS_Solid & = w.Solid();
94Handle(AIS_Shape) anAis = new AIS_Shape(S);
95//creation of the presentable object
4ee1bdf4 96aContext -> Display(anAis);
bf62b306 97//Display the presentable object in the 3d viewer.
dba69de2 99
bf62b306 100The 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 101
290f0085 102@image html visualization_image004.svg "Processes involved in displaying a presentable shape"
103@image latex visualization_image004.svg "Processes involved in displaying a presentable shape"
72b7576f 104
bf62b306 105@subsection occt_visu_2_2 Selection
72b7576f 106
a7d4dd94 107Standard 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 108
a7d4dd94 109There are 3 different selection types:
110 - **Point selection** -- allows picking and highlighting a single object (or its part) located under the mouse cursor;
111 - **Rectangle selection** -- allows picking objects or parts located under the rectangle defined by the start and end mouse cursor positions;
112 - **Polyline selection** -- allows picking objects or parts located under a user-defined non-self-intersecting polyline.
72b7576f 113
a7d4dd94 114For OCCT selection algorithm, all selectable objects are represented as a set of sensitive zones, called <b>sensitive entities</b>. When the mouse cursor moves in the view, the sensitive entities of each object are analyzed for collision.
72b7576f 115
a7d4dd94 116@subsubsection occt_visu_2_2_1 Terms and notions
72b7576f 117
a7d4dd94 118This section introduces basic terms and notions used throughout the algorithm description.
72b7576f 119
a7d4dd94 120<h4>Sensitive entity</h4>
72b7576f 121
a7d4dd94 122Sensitive entities in the same way as entity owners are links between objects and the selection mechanism.
72b7576f 123
a7d4dd94 124The 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 125
a7d4dd94 126@image html visualization_image005.png "Example of a shape divided into sensitive entities"
127@image latex visualization_image005.png "Example of a shape divided into sensitive entities"
72b7576f 128
a7d4dd94 129Depending 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 130
a7d4dd94 131Entities 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 132
a7d4dd94 133<h4>Entity owner</h4>
72b7576f 134
a7d4dd94 135Each 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 136
a7d4dd94 137<h4>Selection</h4>
72b7576f 138
a7d4dd94 139To simplify the handling of different selection modes of an object, sensitive entities linked to its owners are organized into sets, called **selections**.
72b7576f 140
a7d4dd94 141Each selection contains entities created for a certain mode along with the sensitivity and update states.
72b7576f 142
a7d4dd94 143<h4>Selectable object</h4>
72b7576f 144
a7d4dd94 145Selectable object stores information about all created selection modes and sensitive entities.
147All 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.
149For 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:
150 - 0 -- selection of the *AIS_Shape*;
151 - 1 -- selection of the vertices;
152 - 2 -- selection of the edges;
153 - 3 -- selection of the wires;
154 - 4 -- selection of the faces;
155 - 5 -- selection of the shells;
156 - 6 -- selection of the constituent solids.
158@image html visualization_image006.png "Hierarchy of references from sensitive entity to selectable object"
159@image latex visualization_image006.png "Hierarchy of references from sensitive entity to selectable object"
161@image html visualization_image007.png "The principle of entities organization within the selectable object"
162@image latex visualization_image007.png "The principle of entities organization within the selectable object"
164<h4>Viewer selector</h4>
166For 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.
168The 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.
170<h4>Selection manager</h4>
172Selection 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.
174@image html visualization_image008.png "The relations chain between viewer selector and selection manager"
175@image latex visualization_image008.png "The relations chain between viewer selector and selection manager"
177@subsubsection occt_visu_2_2_2 Algorithm
179All 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.
181<h4>Selection Frustum</h4>
183The first step of each run of selection algorithm is to build the selection frustum according to the currently activated selection type.
185For 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.
187The frustum length is limited by near and far view volume planes and each plane is built parallel to the corresponding view volume plane.
189@image html visualization_image009.png "Rectangular frustum: a) after mouse move or click, b) after applying the rectangular selection"
190@image latex visualization_image009.png "Rectangular frustum: a) after mouse move or click, b) after applying the rectangular selection"
72b7576f 191
a7d4dd94 192@image html visualization_image010.png "Triangular frustum set: a) user-defined polyline, b) triangulation of the polygon based on the given polyline, c) triangular frustum based on one of the triangles"
193@image latex visualization_image010.png "Triangular frustum set: a) user-defined polyline, b) triangulation of the polygon based on the given polyline, c) triangular frustum based on one of the triangles"
72b7576f 194
a7d4dd94 195<h4>BVH trees</h4>
72b7576f 196
a7d4dd94 197To maintain selection mechanism at the viewer level, a speedup structure composed of 3 BVH trees is used.
72b7576f 198
a7d4dd94 199The first level tree is constructed of axis-aligned bounding boxes of each selectable object. Hence, the root of this tree contains the combination of all selectable boundaries even if they have no currently activated selections. Objects are added during the display of <i>AIS_InteractiveObject</i> and will be removed from this tree only when the object is destroyed. The 1st level BVH tree is build on demand simultaneously with the first run of the selection algorithm.
72b7576f 200
a7d4dd94 201The 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 202
a7d4dd94 203The 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 204
a7d4dd94 205@image html visualization_image022.png "Selection BVH tree hierarchy: from the biggest object-level (first) to the smallest complex entity level (third)"
206@image latex visualization_image022.png "Selection BVH tree hierarchy: from the biggest object-level (first) to the smallest complex entity level (third)"
72b7576f 207
a7d4dd94 208<h4>Stages of the algorithm</h4>
72b7576f 209
a7d4dd94 210The algorithm includes pre-processing and three main stages.
72b7576f 211
a7d4dd94 212* **Pre-processing** -- implies calculation of the selection frustum and its main characteristics.
213* **First stage** -- traverse of the first level BVH tree.
72b7576f 214
a7d4dd94 215After successful building of the selection frustum, the algorithm starts traversal of the object-level BVH tree. The nodes containing axis-aligned bounding boxes are tested for overlap with the selection frustum following the terms of <i>separating axis theorem (SAT)</i>. When the traverse goes down to the leaf node, it means that a candidate object with possibly overlapping sensitive entities has been found. If no such objects have been detected, the algorithm stops and it is assumed that no object needs to be selected. Otherwise it passes to the next stage to process the entities of the found selectable.
72b7576f 216
a7d4dd94 217* **Second stage** -- traverse of the second level BVH tree
72b7576f 218
a7d4dd94 219At this stage it is necessary to determine if there are candidates among all sensitive entities of one object.
72b7576f 220
a7d4dd94 221First 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:
222 - activation check - the entity may be inactive at the moment as it belongs to deactivated selection;
223 - 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 224
a7d4dd94 225After these checks the algorithm passes to the last stage.
72b7576f 226
a7d4dd94 227* **Third stage** -- overlap or inclusion test of a particular sensitive entity
18006a0f 228
a7d4dd94 229If 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 230
a7d4dd94 231@subsubsection occt_visu_2_2_3 Packages and classes
72b7576f 232
a7d4dd94 233Selection is implemented as a combination of various algorithms divided among several packages -- <i>SelectBasics</i>, <i>Select3D</i>, <i>SelectMgr</i> and <i>StdSelect</i>.
72b7576f 234
a7d4dd94 235<h4>SelectBasics</h4>
18006a0f 236
a7d4dd94 237<i>SelectBasics</i> package contains basic classes and interfaces for selection. The most notable are:
238 - <i>SelectBasics_SensitiveEntity</i> -- the base definition of a sensitive entity;
239 - <i>SelectBasics_EntityOwner</i> -- the base definition of the an entity owner -- the link between the sensitive entity and the object to be selected;
240 - <i>SelectBasics_PickResult</i> -- the structure for storing quantitative results of detection procedure, for example, depth and distance to the center of geometry;
241 - <i>SelectBasics_SelectingVolumeManager</i> -- the interface for interaction with the current selection frustum.
18006a0f 242
18006a0f 243
a7d4dd94 244Each custom sensitive entity must inherit at least <i>SelectBasics_SensitiveEntity</i>.
18006a0f 245
a7d4dd94 246<h4>Select3D</h4>
18006a0f 247
a7d4dd94 248<i>Select3D</i> package provides a definition of standard sensitive entities, such as:
249 - box;
250 - circle;
251 - curve;
252 - face;
253 - group;
254 - point;
255 - segment;
256 - triangle;
257 - triangulation;
258 - wire.
18006a0f 259
a7d4dd94 260Each basic sensitive entity inherits <i>Select3D_SensitiveEntity</i>, which is a child class of <i>SelectBasics_SensitiveEntity</i>.
18006a0f 261
a7d4dd94 262The package also contains two auxiliary classes, <i>Select3D_SensitivePoly</i> and <i>Select3D_SensitiveSet</i>.
72b7576f 263
a7d4dd94 264<i>Select3D_SensitivePoly</i> -- describes an arbitrary point set and implements basic functions for selection. It is important to know that this class does not perform any internal data checks. Hence, custom implementations of sensitive entity inherited from <i>Select3D_SensitivePoly</i> must satisfy the terms of Separating Axis Theorem to use standard OCCT overlap detection methods.
18006a0f 265
a7d4dd94 266<i>Select3D_SensitiveSet</i> -- a base class for all complex sensitive entities that require the third level BVH usage. It implements traverse of the tree and defines an interface for the methods that check sub-entities.
18006a0f 267
a7d4dd94 268<h4>SelectMgr</h4>
18006a0f 269
a7d4dd94 270<i>SelectMgr</i> package is used to maintain the whole selection process. For this purpose, the package provides the following services:
271 - activation and deactivation of selection modes for all selectable objects;
272 - interfaces to compute selection mode of the object;
273 - definition of selection filter classes;
274 - keeping selection BVH data up-to-date.
18006a0f 275
a7d4dd94 276A brief description of the main classes:
277 - <i>SelectMgr_FrustumBase</i>, <i>SelectMgr_Frustum</i>, <i>SelectMgr_RectangularFrustum</i>, <i>SelectMgr_TriangluarFrustum</i> and <i>SelectMgr_TriangularFrustumSet</i> -- interfaces and implementations of selecting frustums, these classes implement different SAT tests for overlap and inclusion detection. They also contain methods to measure characteristics of detected entities (depth, distance to center of geometry);
278 - <i>SelectMgr_SensitiveEntity</i>, <i>SelectMgr_Selection</i> and <i>SelectMgr_SensitiveEntitySet</i> -- store and handle sensitive entities; <i>SelectMgr_SensitiveEntitySet</i> implements a primitive set for the second level BVH tree;
279 - <i>SelectMgr_SelectableObject</i> and <i>SelectMgr_SelectableObjectSet</i> -- describe selectable objects. They also manage storage, calculation and removal of selections. <i>SelectMgr_SelectableObjectSet</i> implements a primitive set for the first level BVH tree;
280 - <i>SelectMgr_ViewerSelector</i> -- encapsulates all logics of the selection algorithm and implements the third level BVH tree traverse;
281 - <i>SelectMgr_SelectionManager</i> -- manages activation/deactivation, calculation and update of selections of every selectable object, and keeps BVH data up-to-date.
18006a0f 282
a7d4dd94 283<h4>StdSelect</h4>
285<i>StdSelect</i> package contains the implementation of some <i>SelectMgr</i> classes and tools for creation of selection structures. For example,
286 - <i>StdSelect_BRepOwner</i> -- defines an entity owner with a link to its topological shape and methods for highlighting;
287 - <i>StdSelect_BRepSelectionTool</i> -- contains algorithms for splitting standard AIS shapes into sensitive primitives;
288 - <i>StdSelect_ViewerSelector3d</i> -- an example of <i>SelectMgr_ViewerSelecor</i> implementation, which is used in a default OCCT selection mechanism;
289 - <i>StdSelect_FaceFilter</i>, <i>StdSelect_EdgeFilter</i> -- implementation of selection filters.
291@subsubsection occt_visu_2_2_4 Examples of usage
293The first code snippet illustrates the implementation of <i>SelectMgr_SelectableObject::ComputeSelection()</i> method in a custom interactive object. The method is used for computation of user-defined selection modes.
295Let 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).
297To 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.
299To 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 300
a7d4dd94 303void InteractiveBox::ComputeSelection (const Handle(SelectMgr_Selection)& theSel,
18006a0f 304 const Standard_Integer theMode)
a7d4dd94 306 switch (theMode)
18006a0f 307 {
a7d4dd94 308 case 0: // creation of face sensitives for selection of the whole box
309 {
310 Handle(SelectMgr_EntityOwner) anOwnr = new SelectMgr_EntityOwner (this, 5);
311 for (Standard_Integer aFaceIdx = 1; aFaceIdx <= myNbFaces; aFaceIdx++)
18006a0f 312 {
a7d4dd94 313 Select3D_TypeOfSensitivity aIsInteriorSensitivity = myIsInterior;
314 theSel->Add (new Select3D_SensitiveFace (anOwnr,
315 myFaces[aFaceIdx]->PointArray(),
316 aIsInteriorSensitivity));
18006a0f 317 }
a7d4dd94 318 break;
319 }
320 case 1: // creation of edge sensitives for selection of box edges only
18006a0f 321 {
a7d4dd94 322 for (Standard_Integer anEdgeIdx = 1; anEdgeIdx <= 12; anEdgeIdx++)
18006a0f 323 {
a7d4dd94 324 // 1 owner per edge, where 6 is a priority of the sensitive
325 Handle(MySelection_EdgeOwner) anOwnr = new MySelection_EdgeOwner (this, anEdgeIdx, 6);
326 theSel->Add (new Select3D_SensitiveSegment (anOwnr,
327 FirstPnt[anEdgeIdx]),
328 LastPnt[anEdgeIdx]));
18006a0f 329 }
a7d4dd94 330 break;
331 }
18006a0f 332 }
a7d4dd94 337The algorithms for creating selection structures store sensitive primitives in <i>SelectMgr_Selection</i> instance. Each <i>SelectMgr_Selection</i> sequence in the list of selections of the object must correspond to a particular selection mode.
339To describe the decomposition of the object into selectable primitives, a set of ready-made sensitive entities is supplied in <i>Select3D</i> package. Custom sensitive primitives can be defined through inheritance from <i>SelectBasics_SensitiveEntity</i>.
341To make custom interactive objects selectable or customize selection modes of existing objects, the entity owners must be defined. They must inherit <i>SelectMgr_EntityOwner</i> interface.
344Selection structures for any interactive object are created in <i>SelectMgr_SelectableObject::ComputeSelection()</i> method.
18006a0f 345
a7d4dd94 346The example below shows how computation of different selection modes of the topological shape can be done using standard OCCT mechanisms, implemented in <i>StdSelect_BRepSelectionTool</i>.
18006a0f 347
a7d4dd94 349 void MyInteractiveObject::ComputeSelection (const Handle(SelectMgr_Selection)& theSelection,
350 const Standard_Integer theMode)
18006a0f 351 {
352 switch (theMode)
353 {
354 case 0:
a7d4dd94 355 StdSelect_BRepSelectionTool::Load (theSelection, this, myTopoDSShape, TopAbs_SHAPE);
18006a0f 356 break;
357 case 1:
a7d4dd94 358 StdSelect_BRepSelectionTool::Load (theSelection, this, myTopoDSShape, TopAbs_VERTEX);
18006a0f 359 break;
360 case 2:
a7d4dd94 361 StdSelect_BRepSelectionTool::Load (theSelection, this, myTopoDSShape, TopAbs_EDGE);
18006a0f 362 break;
363 case 3:
a7d4dd94 364 StdSelect_BRepSelectionTool::Load (theSelection, this, myTopoDSShape, TopAbs_WIRE);
18006a0f 365 break;
366 case 4:
a7d4dd94 367 StdSelect_BRepSelectionTool::Load (theSelection, this, myTopoDSShape, TopAbs_FACE);
18006a0f 368 break;
369 }
370 }
a7d4dd94 373The <i>StdSelect_BRepSelectionTool</i> class provides a high level API for computing sensitive entities of the given type (for example, face, vertex, edge, wire and others) using topological data from the given <i>TopoDS_Shape</i>.
18006a0f 374
375The 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:
a7d4dd94 377 - each entity owner has to maintain its own <i>Prs3d_Presentation</i> object, that results in a large memory overhead for thousands of owners;
378 - drawing selected owners one by one is not efficient from the OpenGL usage viewpoint.
72b7576f 379
a7d4dd94 380Therefore, 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 381
a7d4dd94 382On the basis of <i>SelectMgr_EntityOwner::IsAutoHilight()</i> return value, <i>AIS_LocalContext</i> object either uses the traditional way of highlighting (in case if <i>IsAutoHilight()</i> returns true) or groups such owners according to their selectable objects and finally calls <i> SelectMgr_SelectableObject::HilightSelected()</i> or <i>SelectMgr_SelectableObject::ClearSelected()</i>, passing a group of owners as an argument.
18006a0f 383
18006a0f 384
a7d4dd94 385Hence, an application can derive its own interactive object and redefine virtual methods <i>HilightSelected()</i>, <i>ClearSelected()</i> and <i>HilightOwnerWithColor()</i> from <i>SelectMgr_SelectableObject</i>. <i>SelectMgr_SelectableObject::GetHilightPresentation</i> and <i>SelectMgr_SelectableObject::GetSelectPresentation</i> methods can be used to optimize filling of selection and highlight presentations according to the user's needs.
72b7576f 386
a7d4dd94 387The <i>AIS_InteractiveContext::HighlightSelected()</i> method can be used for efficient redrawing of the selection presentation for a given interactive object from an application code.
72b7576f 388
72b7576f 389
a7d4dd94 390After all the necessary sensitive entities are computed and packed in <i>SelectMgr_Selection</i> instance with the corresponding owners in a redefinition of <i>SelectMgr_SelectableObject::ComputeSelection()</i> method, it is necessary to register the prepared selection in <i>SelectMgr_SelectionManager</i> through the following steps:
391 - if there was no <i>AIS_InteractiveContext</i> opened, create an interactive context and display the selectable object in it;
392 - load the selectable object to the selection manager of the interactive context using <i>AIS_InteractiveContext::Load()</i> method. If the selection mode passed as a parameter to this method is not equal to -1, <i>ComputeSelection()</i> for this selection mode will be called;
393 - activate or deactivate the defined selection mode using <i>AIS_InteractiveContext::Activate()</i> or <i>AIS_InteractiveContext::Deactivate()</i> methods.
72b7576f 394
a7d4dd94 395After 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 396
a7d4dd94 397The code snippet below illustrates the above steps. It also contains the code to start the detection procedure and parse the results of selection.
72b7576f 398
a7d4dd94 399~~~~~
72b7576f 400
a7d4dd94 401// Suppose there is an instance of class InteractiveBox from the previous sample.
402// It contains an implementation of method InteractiveBox::ComputeSelection() for selection
403// modes 0 (whole box must be selected) and 1 (edge of the box must be selectable)
404Handle(InteractiveBox) aBox;
406// Assume there is a created interactive context
407const Handle(AIS_InteractiveContext)& aContext = GetContext();
408// To prevent automatic activation of the default selection mode
409aContext->SetAutoActivateSelection (Standard_False);
411aContext->Display (aBox);
413// Load a box to the selection manager without computation of any selection mode
414aContext->Load (aBox, -1, Standard_True);
415// Activate edge selection
416aContext->Activate (aBox, 1);
418// Run the detection mechanism for activated entities in the current mouse coordinates and
419// in the current view. Detected owners will be highlighted with context highlight color
420aContext->MoveTo (aXMousePos, aYMousePos, myView);
421// Select the detected owners
423// Iterate through the selected owners
424for (aContext->InitSelected(); aContext->MoreSelected() && !aHasSelected; aContext->NextSelected())
426 Handle(AIS_InteractiveObject) anIO = aContext->SelectedInteractive();
72b7576f 428
a7d4dd94 429// deactivate all selection modes for aBox1
430aContext->Deactivate (aBox1);
72b7576f 431
bf62b306 432~~~~~
72b7576f 433
a7d4dd94 434It is also important to know, that there are 2 types of detection implemented for rectangular selection in OCCT:
435 - <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;
436 - <b>overlap</b> detection. In this case the sensitive primitive is considered detected when it is partially overlapped by the selection rectangle.
72b7576f 437
a7d4dd94 438The standard OCCT selection mechanism uses inclusion detection by default. To change this, use the following code:
72b7576f 439
a7d4dd94 440~~~~~
72b7576f 441
a7d4dd94 442// Assume there is a created interactive context
443const Handle(AIS_InteractiveContext)& aContext = GetContext();
444// Retrieve the current viewer selector
445const Handle(StdSelect_ViewerSelector3d)& aMainSelector = aContext->MainSelector();
446// Set the flag to allow overlap detection
447aMainSelector->AllowOverlapDetection (Standard_True);
72b7576f 448
a7d4dd94 449~~~~~
72b7576f 450
bf62b306 451@section occt_visu_3 Application Interactive Services
452@subsection occt_visu_3_1 Introduction
72b7576f 453
bf62b306 454Application Interactive Services allow managing presentations and dynamic selection in a viewer in a simple and transparent manner.
72b7576f 455
bf62b306 456The central entity for management of visualization and selections is the **Interactive Context**. It is connected to the main viewer (and if need be, the trash bin viewer). It has two operating modes: the Neutral Point and the local visualization and selection context.
72b7576f 457
bf62b306 458The neutral point, which is the default mode, allows easily visualizing and selecting interactive objects loaded into the context.
72b7576f 459
bf62b306 460**Local Contexts** can be opened to prepare and use a temporary selection environment without disturbing
461the neutral point. It is possible to choose the interactive objects, which you want to act on, the selection modes, which you want to activate, and the temporary visualizations, which you will execute.
72b7576f 462
bf62b306 463When the operation is finished, you close the current local context and return to the state
464in which you were before opening it (neutral point or previous local context).
72b7576f 465
bf62b306 466**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 467
bf62b306 468@image html visualization_image016.png
469@image latex visualization_image016.png
72b7576f 470
bf62b306 471An 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.
72b7576f 472
bf62b306 473When an Interactive Object is visualized, the required graphic attributes are taken from its own **Drawer** if it has the required custom attributes or otherwise from the context drawer.
72b7576f 474
bf62b306 475@image html visualization_image017.png
476@image latex visualization_image017.png
72b7576f 477
bf62b306 478It can be necessary to filter the entities to be selected. Consequently there are **Filter** entities, which allow refining the dynamic detection context. Some of these filters can be used at the Neutral Point, others only in an open local context. It is possible to program custom filters and load them into the interactive context.
72b7576f 479
bf62b306 480@subsection occt_visu_3_2 Interactive objects
72b7576f 481
18006a0f 482Entities 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.
bf62b306 484@subsubsection occt_visu_3_2_1 Presentations
72b7576f 485
bf62b306 486An interactive object can have as many presentations as its creator wants to give it.
72b7576f 487
bf62b306 4883D presentations are managed by PresentationManager3D. As this is transparent in AIS, the user does not have to worry about it.
72b7576f 489
bf62b306 490A presentation is identified by an index and by the reference to the Presentation Manager which it depends on.
72b7576f 491
bf62b306 492By convention, the default mode of representation for the Interactive Object has index 0.
72b7576f 493
bf62b306 494@image html visualization_image018.png
495@image latex visualization_image018.png
72b7576f 496
bf62b306 497Calculation 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 498
bf62b306 499If you are creating your own type of interactive object, you must implement the Compute function in one of the following ways:
72b7576f 500
bf62b306 501#### For 3D:
72b7576f 502
bf62b306 503~~~~~
504void PackageName_ClassName::Compute
505 (const Handle(PrsMgr_PresentationManager3d)& aPresentationManager,
2683e647 506 const Handle(Prs3d_Presentation)& aPresentation,
507 const Standard_Integer aMode = 0);
bf62b306 508~~~~~
72b7576f 509
bf62b306 510#### For hidden line removal (HLR) mode in 3D:
512void PackageName_ClassName::Compute
513 (const Handle(Prs3d_Projector)& aProjector,
2683e647 514 const Handle(Prs3d_Presentation)& aPresentation);
bf62b306 515~~~~~
72b7576f 516
bf62b306 517@subsubsection occt_visu_3_2_2 Hidden Line Removal
72b7576f 518
2683e647 519The 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 520
bf62b306 521By 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 522
bf62b306 523* Initially by using one of the values of the enumeration *PrsMgr_TypeOfPresentation*:
524 * *PrsMgr_TOP_AllView*,
525 * *PrsMgr_TOP_ProjectorDependant*
72b7576f 526
bf62b306 527* Later by using the function *PrsMgr_PresentableObject::SetTypeOfPresentation*
72b7576f 528
bf62b306 529*AIS_Shape* class is an example of an interactive object that supports HLR representation. It supports two types of the HLR algorithm:
2683e647 530* the polygonal algorithm based on the shape's triangulation;
531* the exact algorithm that works with the shape's real geometry.
72b7576f 532
bf62b306 533The type of the HLR algorithm is stored in *AIS_Drawer* of the shape. It is a value of the *Prs3d_TypeOfHLR* enumeration and can be set to:
534 * *Prs3d_TOH_PolyAlgo* for a polygonal algorithm;
535 * *Prs3d_TOH_Algo* for an exact algorithm;
536 * *Prs3d_TOH_NotSet* if the type of algorithm is not set for the given interactive object instance.
72b7576f 537
bf62b306 538The type of the HLR algorithm used for *AIS_Shape* can be changed by calling the *AIS_Shape::SetTypeOfHLR()* method.
72b7576f 539
bf62b306 540The current HLR algorithm type can be obtained using *AIS_Shape::TypeOfHLR()* method is to be used.
72b7576f 541
bf62b306 542These 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*.
72b7576f 543
bf62b306 544So 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 545
bf62b306 546@subsubsection occt_visu_3_2_3 Presentation modes
72b7576f 547
bf62b306 548There are four types of interactive objects in AIS:
549 * the "construction element" or Datum,
550 * the Relation (dimensions and constraints)
551 * the Object
552 * the None type (when the object is of an unknown type).
72b7576f 553
bf62b306 554Inside 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:
555 * *AIS_InteractiveObject::Type*
556 * *AIS_InteractiveObject::Signature*.
72b7576f 557
67d7f07f 558**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 559
bf62b306 560The 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.
72b7576f 561
bf62b306 562Consequently, to get information about this class it is necessary to use virtual function *AIS_InteractiveObject::AcceptDisplayMode*.
72b7576f 563
bf62b306 564#### Display Mode
72b7576f 565
bf62b306 566The 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 567
bf62b306 568#### Highlight Mode
72b7576f 569
bf62b306 570At dynamic detection, the presentation echoed by the Interactive Context, is by default the presentation already on the screen.
72b7576f 571
bf62b306 572The 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 573
bf62b306 574Note 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 575
bf62b306 576For 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 577
bf62b306 578#### Infinite Status
2683e647 579If 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.
72b7576f 580
bf62b306 581Let us take for example the class called *IShape* representing an interactive object :
72b7576f 582
bf62b306 583~~~~~
585 (const TopoDS_Shape& SH, PrsMgr_TypeOfPresentation aType):
2683e647 586 AIS_InteractiveObject(aType), myShape(SH), myDrwr(new AIS_Drawer()) {SetHilightMode(0);}
bf62b306 587void myPk_IShape::Compute
588 (const Handle(PrsMgr_PresentationManager3d) & PM,
2683e647 589 const Handle(Prs3d_Presentation)& P,
bf62b306 590 const Standard_Integer TheMode)
592 switch (TheMode){
593 case 0:
594 StdPrs_WFDeflectionShape::Add (P,myShape,myDrwr); //algo for calculation of wireframe presentation break;
595 case 1:
596 StdPrs_ShadedShape::Add (P,myShape,myDrwr); //algo for calculation of shading presentation.
597 break;
598 }
600void myPk_IsShape::Compute
601 (const Handle(Prs3d_Projector)& Prj,
602 const Handle(Prs3d_Presentation) P)
604 StdPrs_HLRPolyShape::Add(P,myShape,myDrwr);
605 //Hidden line mode calculation algorithm
72b7576f 608
bf62b306 609@subsubsection occt_visu_3_2_4 Selection
72b7576f 610
a7d4dd94 611An interactive object can have an indefinite number of selection modes, each representing a "decomposition" into sensitive primitives. Each primitive has an <i>owner</i> (*SelectMgr_EntityOwner*) which allows identifying the exact interactive object or shape which has been detected (see @ref occt_visu_2_2 "Selection" chapter).
72b7576f 612
a7d4dd94 613The set of sensitive primitives, which correspond to a given mode, is stocked in a <b>selection</b> (*SelectMgr_Selection*).
72b7576f 614
a7d4dd94 615Each selection mode is identified by an index. By convention, the default selection mode that allows us to grasp the interactive object in its entirety is mode *0*. However, it can be modified in the custom interactive objects using method <i>SelectMgr_SelectableObject::setGlobalSelMode()</i>.
72b7576f 616
a7d4dd94 617The calculation of selection primitives (or sensitive entities) is done by the intermediary of 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_ConnectedInteractive::ComputeSelection*.
72b7576f 618
a7d4dd94 619A detailed explanation of the mechanism and the manner of implementing this function has been given in @ref occt_visu_2_2 "Selection" chapter.
72b7576f 620
a7d4dd94 621There 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*.
72b7576f 622
a7d4dd94 623You can change the default selection mode index of a custom interactive object using the following functions:
624 * *AIS_InteractiveObject::setGlobalSelMode* sets global selection mode;
625 * *AIS_InteractiveObject::GlobalSelectionMode* returns global selection mode of the object;
626 * *AIS_InteractiveObject::GlobalSelOwner* returns an entity owner that corresponds to a global selection mode.
bf62b306 627
a7d4dd94 628You also can temporarily change the priority of some interactive objects for selection of the global mode to facilitate their graphic detection using the following functions:
bf62b306 629 * *AIS_InteractiveObject::HasSelectionPriority* checks if there is a selection priority setting for the owner;
630 * *AIS_InteractiveObject::SelectionPriority* checks the current priority;
631 * *AIS_InteractiveObject::SetSelectionPriority* sets a priority;
632 * *AIS_InteractiveObject::UnsetSelectionPriority* unsets the priority.
2683e647 634
bf62b306 635@subsubsection occt_visu_3_2_5 Graphic attributes
72b7576f 636
18006a0f 637Graphic attributes manager, or *AIS Drawer*, stores graphic attributes for specific interactive objects and for interactive objects controlled by interactive context.
639Initially, all drawer attributes are filled out with the predefined values which will define the default 3D object appearance.
641When 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.
643Keep in mind the following points concerning graphic attributes:
bf62b306 644 * Each interactive object can have its own visualization attributes.
645 * The set of graphic attributes of an interactive object is stocked in an *AIS_Drawer*, which is only a *Prs3d_Drawer* with the possibility of a link to another drawer
646 * 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.)
647 * 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 648
bf62b306 649@image html visualization_image019.png "Figure 13. Redefinition of virtual functions for changes in AIS_Point"
650@image latex visualization_image019.png "Figure 13. Redefinition of virtual functions for changes in AIS_Point"
72b7576f 651
bf62b306 652@image html visualization_image020.png "Figure 14. Redefinition of virtual functions for changes in AIS_Shape."
653@image latex visualization_image020.png "Figure 14. Redefinition of virtual functions for changes in AIS_Shape."
72b7576f 654
bf62b306 655The following virtual functions provide settings for color, width, material and transparency:
656 * *AIS_InteractiveObject::UnsetColor*
657 * *AIS_InteractiveObject::SetWidth*
658 * *AIS_InteractiveObject::UnsetWidth*
659 * *AIS_InteractiveObject::SetMaterial (const Graphic3d_NameOfPhysicalMaterial & aName)*
2683e647 660 * *AIS_InteractiveObject::SetMaterial (const Graphic3d_MaterialAspect & aMat)*
bf62b306 661 * *AIS_InteractiveObject::UnsetMaterial*
662 * *AIS_InteractiveObject::SetTransparency*
663 * *AIS_InteractiveObject::UnsetTransparency*
72b7576f 664
bf62b306 665For other types of attribute, it is appropriate to change the Drawer of the object directly using:
666 * *AIS_InteractiveObject::SetAttributes*
667 * *AIS_InteractiveObject::UnsetAttributes*
72b7576f 668
bf62b306 669It is important to know which functions may imply the recalculation of presentations of the object.
72b7576f 670
bf62b306 671If the presentation mode of an interactive object is to be updated, a flag from *PrsMgr_PresentableObject* indicates this.
72b7576f 672
bf62b306 673The mode can be updated using the functions *Display* and *Redisplay* in *AIS_InteractiveContext*.
72b7576f 674
bf62b306 675@subsubsection occt_visu_3_2_6 Complementary Services
72b7576f 676
bf62b306 677When you use complementary services for interactive objects, pay special attention to the cases mentioned below.
72b7576f 678
bf62b306 679#### Change the location of an interactive object
72b7576f 680
bf62b306 681The following functions allow temporarily "moving" the representation and selection of Interactive Objects in a view without recalculation.
682 * *AIS_InteractiveContext::SetLocation*
683 * *AIS_InteractiveContext::ResetLocation*
684 * *AIS_InteractiveContext::HasLocation*
685 * *AIS_InteractiveContext::Location*
687#### Connect an interactive object to an applicative entity
72b7576f 688
bf62b306 689Each Interactive Object has functions that allow attributing it an *Owner* in form of a *Transient*.
690 * *AIS_InteractiveObject::SetOwner*
691 * *AIS_InteractiveObject::HasOwner*
692 * *AIS_InteractiveObject::Owner*
72b7576f 693
bf62b306 694An interactive object can therefore be associated or not with an applicative entity, without affecting its behavior.
72b7576f 695
bf62b306 696#### Resolving coincident topology
72b7576f 697
bf62b306 698Due 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 699
bf62b306 700To 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 701
2683e647 702The method *AIS_InteractiveObject::SetPolygonOffsets (const Standard_Integer aMode, const Standard_Real aFactor, const Standard_Real aUnits)* allows setting up the polygon offsets.
72b7576f 703
bf62b306 704The parameter *aMode* can contain various combinations of *Aspect_PolygonOffsetMode* enumeration elements:
705 * *Aspect_POM_None*
706 * *Aspect_POM_Off*
4ee1bdf4 707 * *Aspect_POM_Fill*
708 * *Aspect_POM_Line*
709 * *Aspect_POM_Point*
710 * *Aspect_POM_All*
72b7576f 711
bf62b306 712The combination of these elements defines the polygon display modes that will use the given offsets. You can switch off the polygon offsets by passing *Aspect_POM_Off*. Passing *Aspect_POM_None* allows changing the *aFactor* and *aUnits* values without changing the mode. If *aMode* is different from *Aspect_POM_Off*, the *aFactor* and *aUnits* arguments are used by the graphics renderer to calculate the depth offset value:
714 offset = aFactor * m + aUnits * r
716where *m* is the maximum depth slope for the currently displayed polygons, r is the minimum depth resolution (implementation-specific).
72b7576f 717
bf62b306 718Negative offset values move polygons closer to the viewer while positive values shift polygons away.
72b7576f 719
bf62b306 720**Warning**
3f812249 722This method has a side effect -- it creates its own shading aspect if not yet created, so it is better to set up the object shading aspect first.
72b7576f 723
bf62b306 724You can use the following functions to obtain the current settings for polygon offsets:
726 void AIS_InteractiveObject::PolygonOffsets
727 (Standard_Integer &aMode,
2683e647 728 Standard_Real &aFactor,
729 Standard_Real &aUnits)
bf62b306 730 Standard_Boolean AIS_InteractiveObject::HasPolygonOffsets()
72b7576f 732
bf62b306 733The same operation could be performed for the interactive object known by the *AIS_InteractiveContext* with the following methods:
735void AIS_InteractiveContext::SetPolygonOffsets
736 (const Handle(AIS_InteractiveObject) &anObj,
2683e647 737 const Standard_Integer aMode,
738 const Standard_Real aFactor,
739 const Standard_Real aUnits)
bf62b306 740void AIS_InteractiveContext::PolygonOffsets
741 (const Handle(AIS_InteractiveObject) &anObj,
2683e647 742 Standard_Integer &aMode,
743 Standard_Real &aFactor,
744 Standard_Real &aUnits)
745Standard_Boolean AIS_InteractiveContext::HasPolygonOffsets
bf62b306 746 (const Handle(AIS_InteractiveObject) &anObj)
72b7576f 748
bf62b306 749@subsection occt_visu_3_3 Interactive Context
72b7576f 750
bf62b306 751@subsubsection occt_visu_3_3_1 Rules
72b7576f 752
18006a0f 753The 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 754
bf62b306 755There 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 756
bf62b306 757~~~~~
758Handle (AIS_Shape) TheAISShape = new AIS_Shape (ashape);
4ee1bdf4 759 myIntContext->Display(TheAISShape);
760 myIntContext->SetDisplayMode(TheAISShape ,1);
761 myIntContext->SetColor(TheAISShape,Quantity_NOC_RED);
bf62b306 762~~~~~
72b7576f 763
bf62b306 764You can also write
72b7576f 765
bf62b306 766~~~~~
767Handle (AIS_Shape) TheAISShape = new AIS_Shape (ashape);
4ee1bdf4 768 TheAISShape->SetColor(Quantity_NOC_RED);
769 TheAISShape->SetDisplayMode(1);
770 myIntContext->Display(TheAISShape);
bf62b306 771~~~~~
72b7576f 772
bf62b306 773@subsubsection occt_visu_3_3_2 Groups of functions
72b7576f 774
18006a0f 775**Neutral Point** and **Local Context** constitute the two operating modes or states of the **Interactive Context**, which is the central entity which pilots visualizations and selections.
72b7576f 776
18006a0f 777The **Neutral Point**, which is the default mode, allows easily visualizing and selecting interactive objects, which have been loaded into the context. Opening **Local contexts** allows preparing and using a temporary selection environment without disturbing the neutral point.
779A set of functions allows choosing the interactive objects which you want to act on, the selection modes which you want to activate, and the temporary visualizations which you will execute. When the operation is finished, you close the current local context and return to the state in which you were before opening it (neutral point or previous local context).
72b7576f 780
bf62b306 781The Interactive Context is composed of many functions, which can be conveniently grouped according to the theme:
782 * management proper to the context;
783 * management in the local context;
784 * presentations and selection in open/closed context;
785 * selection strictly speaking.
72b7576f 786
18006a0f 787Some functions can only be used in open Local Context; others in closed local context; others do not have the same behavior in one state as in the other.
72b7576f 788
bf62b306 789@subsubsection occt_visu_3_3_3 Management of the Interactive Context
72b7576f 790
18006a0f 791The **Interactive Context** is made up of a **Principal Viewer** and, optionally, a trash bin or **Collector Viewer**.
793An 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.
795When an interactive object is visualized, the required graphic attributes are first taken from the object's own <i>Drawer</i> if one exists, or from the context drawer for the others.
797The following adjustable settings allow personalizing the behavior of presentations and selections:
798 * Default Drawer, containing all the color and line attributes which can be used by interactive objects, which do not have their own attributes.
bf62b306 799 * Default Visualization Mode for interactive objects. By default: *mode 0* ;
800 * Highlight color of entities detected by mouse movement. By default: *Quantity_NOC_CYAN1*;
801 * Pre-selection color. By default: *Quantity_NOC_GREEN*;
802 * Selection color (when you click on a detected object). By default: *Quantity_NOC_GRAY80*;
18006a0f 803 * Sub-Intensity color. By default: *Quantity_NOC_GRAY40*.
72b7576f 804
bf62b306 805All of these settings can be modified by functions proper to the Context.
72b7576f 806
bf62b306 807When 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.
72b7576f 808
bf62b306 809Let us examine the case of two interactive objects: *obj1* and *obj2*:
72b7576f 810
bf62b306 811~~~~~
4ee1bdf4 812TheCtx->Display(obj1,Standard_False); // False = no viewer update
813TheCtx->Display(obj2,Standard_True); // True = viewer update
bf62b306 816// obj2 is visualised in mode 2 (if it accepts this mode)
817// obj1 stays visualised in its mode 3.
72b7576f 819
18006a0f 820*PresentationManager3D* and *Selector3D*, which manage the presentation and selection of present interactive objects, are associated to the main Viewer. The same is true of the optional Collector.
72b7576f 821
bf62b306 822@subsection occt_visu_3_4 Local Context
18006a0f 823
bf62b306 824@subsubsection occt_visu_3_4_1 Rules and Conventions
72b7576f 825
bf62b306 826 * Opening a local context allows preparing an environment for temporary presentations and selections, which will disappear once the local context is closed.
827 * It is possible to open several local contexts, but only the last one will be active.
828 * When you close a local context, the previous one, which is still on the stack, is activated again. If none is left, you return to Neutral Point.
829 * Each local context has an index created when the context opens. You should close the local context, which you have opened.
72b7576f 830
bf62b306 831The interactive object, which is used the most by applications, is *AIS_Shape*. Consequently, standard functions are available which allow you to easily prepare selection operations on the constituent elements of shapes (selection of vertices, edges, faces etc) in an open local context. The selection modes specific to "Shape" type objects are called **Standard Activation Mode**. These modes are only taken into account in open local context and only act on interactive objects which have redefined the virtual function *AcceptShapeDecomposition()* so that it returns *TRUE*.
832 * Objects, which are temporarily in a local context, are not recognized by other local contexts a priori. Only objects visualized in Neutral Point are recognized by all local contexts.
833 * The state of a temporary interactive object in a local context can only be modified while another local context is open.
72b7576f 834
bf62b306 835**Warning**
72b7576f 836
bf62b306 837The specific modes of selection only concern the interactive objects, which are present in the Main Viewer. In the Collector, you can only locate interactive objects, which answer positively to the positioned filters when a local context is open, however, they are never decomposed in standard mode.
72b7576f 838
bf62b306 839@subsubsection occt_visu_3_4_2 Management of Local Context
72b7576f 840
bf62b306 841The local context can be opened using method *AIS_InteractiveContext::OpenLocalContext*. The following options are available:
4ee1bdf4 842 * *UseDisplayedObjects*: allows loading the interactive objects visualized at Neutral Point in the opened local context. If *FALSE*, the local context is empty after being opened. If *TRUE*, the objects at Neutral Point are modified by their default selection mode.
67d7f07f 843 * *AllowShapeDecomposition*: *AIS_Shape* allows or prevents decomposition in standard shape location mode of objects at Neutral Point, which are type-privileged (see @ref occt_visu_3_2_4 "Selection" chapter). This Flag is only taken into account when *UseDisplayedObjects* is *TRUE*.
18006a0f 844 * *AcceptEraseOfObjects*: authorizes other local contexts to erase the interactive objects present in this context. This option is rarely used. The last option has no current use.
72b7576f 845
bf62b306 846This function returns the index of the created local context. It should be kept and used when the context is closed.
72b7576f 847
bf62b306 848To load objects visualized at Neutral Point into a local context or remove them from it use methods
850 AIS_InteractiveContext::UseDisplayedObjects
851 AIS_InteractiveContext::NotUseDisplayedObjects
853Closing Local Contexts is done by:
855 AIS_InteractiveContext::CloseLocalContext
856 AIS_InteractiveContext::CloseAllContexts
72b7576f 858
bf62b306 859*Warning*
2683e647 860When the index is not specified in the first function, the current Context is closed. This option can be dangerous, as other Interactive Functions can open local contexts without necessarily warning the user. For greater security, you have to close the context with the index given on opening.
72b7576f 861
18006a0f 862To get the index of the current context, use function *AIS_InteractiveContext::IndexOfCurrentLocal*. It allows closing all open local contexts at one go. In this case, you find yourself directly at Neutral Point.
72b7576f 863
18006a0f 864When you close a local context, all temporary interactive objects are deleted, all selection modes concerning the context are canceled, and all content filters are emptied.
72b7576f 865
72b7576f 866
bf62b306 867@subsubsection occt_visu_3_4_3 Presentation in a Neutral Point
72b7576f 868
18006a0f 869You must distinguish between the **Neutral Point** and the **Open Local Context** states. Although the majority of visualization functions can be used in both situations, their behavior is different.
72b7576f 870
bf62b306 871Neutral Point should be used to visualize the interactive objects, which represent and select an applicative entity. Visualization and Erasing orders are straightforward:
72b7576f 872
bf62b306 873~~~~~
875 (const Handle(AIS_InteractiveObject)& anIobj,
2683e647 876 const Standard_Boolean updateviewer=Standard_True);
bf62b306 877
879 (const Handle(AIS_InteractiveObject)& anIobj,
2683e647 880 const Standard_Integer amode,
881 const Standard_Integer aSelectionMode,
882 const Standard_Boolean updateviewer = Standard_True,
883 const Standard_Boolean allowdecomposition = Standard_True);
bf62b306 884
885 AIS_InteractiveContext::Erase
886 AIS_InteractiveContext::EraseMode
887 AIS_InteractiveContext::ClearPrs
888 AIS_InteractiveContext::Redisplay
889 AIS_InteractiveContext::Remove
890 AIS_InteractiveContext::EraseAll
891 AIS_InteractiveContext::Hilight
892 AIS_InteractiveContext::HilightWithColor
895Bear in mind the following points:
896 * It is recommended to display and erase interactive objects when no local context is opened, and open a local context for local selection only.
2683e647 897 * The first *Display* function among the two ones available in *InteractiveContext* visualizes the object in its default mode (set with help of SetDisplayMode() method of InteractiveObject prior to Display() call), or in the default context mode, if applicable. If it has neither, the function displays it in 0 presentation mode. The object's default selection mode is automatically activated (0 mode by convention).
bf62b306 898 * Activating the displayed object by default can be turned off with help of *SetAutoActivateSelection()* method. This might be efficient if you are not interested in selection immediately after displaying an object.
899 * The second *Display* function should only be used in Neutral Point to visualize a supplementary mode for the object, which you can erase by *EraseMode (...)*. You activate the selection mode. This is passed as an argument. By convention, if you do not want to activate a selection mode, you must set the *SelectionMode* argument to -1. This function is especially interesting in open local context, as we will see below.
900 * In Neutral Point, it is not advisable to activate other selection modes than the default selection one. It is preferable to open a local context in order to activate particular selection modes.
4ee1bdf4 901 * When you call *Erase(Interactive object)* function, the *PutIncollector* argument, which is *FALSE* by default, allows you to visualize the object directly in the Collector and makes it selectable (by activation of 0 mode). You can nonetheless block its passage through the Collector by changing the value of this option. In this case, the object is present in the Interactive Context, but is not seen anywhere.
2683e647 902 * *Erase()* with *putInCollector = Standard_True* might be slow as it recomputes the object presentation in the Collector. Set *putInCollector* to *Standard_False* if you simply want to hide the object's presentation temporarily.
bf62b306 903 * Visualization attributes and graphic behavior can be modified through a set of functions similar to those for the interactive object (color, thickness of line, material, transparency, locations, etc.) The context then manages immediate and deferred updates.
904 * Call *Remove()* method of *InteractiveContext* as soon as the interactive object is no longer needed and you want to destroy it.. Otherwise, references to *InteractiveObject* are kept by *InteractiveContext*, and the *Object* is not destroyed, which results in memory leaks. In general, if the presentation of an interactive object can be computed quickly, it is recommended to *Remove()* it instead of using *Erase()* method.
72b7576f 905
18006a0f 906@subsubsection occt_visu_3_4_4 Presentation in the Local Context
72b7576f 907
bf62b306 908In open local context, the *Display* functions presented above can be as well.
72b7576f 909
bf62b306 910**WARNING**
72b7576f 911
2683e647 912The function *AIS_InteractiveObject::Display* automatically activates the object's default selection mode. When you only want to visualize an Interactive Object in open Context, you must call the function *AIS_InteractiveContext::Display*.
72b7576f 913
bf62b306 914You can activate or deactivate specific selection modes in the local open context in several different ways:
915Use the Display functions with the appropriate modes.
918 AIS_InteractiveContext::ActivateStandardMode
919 //can be used only if a Local Context is opened.
920 AIS_InteractiveContext::DeactivateStandardMode
921 AIS_InteractiveContext::ActivatedStandardModes
922 AIS_InteractiveContext::SetShapeDecomposition
72b7576f 924
bf62b306 925This activates the corresponding selection mode for all objects in Local Context, which accept decomposition into sub-shapes. Every new Object which has been loaded into the interactive context and which meets the decomposition criteria is automatically activated according to these modes.
72b7576f 926
bf62b306 927**WARNING**
72b7576f 928
4ee1bdf4 929If you have opened a local context by loading an object with the default options <i>(AllowShapeDecomposition = Standard_True)</i>, all objects of the "Shape" type are also activated with the same modes. You can change the state of these "Standard" objects by using *SetShapeDecomposition(Status)*.
72b7576f 930
bf62b306 931Load an interactive object by the function *AIS_InteractiveContext::Load*.
72b7576f 932
bf62b306 933This function allows loading an Interactive Object whether it is visualized or not with a given selection mode, and/or with the necessary decomposition option. If *AllowDecomp=TRUE* and obviously, if the interactive object is of the "Shape" type, these "standard" selection modes will be automatically activated as a function of the modes present in the Local Context.
72b7576f 934
bf62b306 935Use *AIS_InteractiveContext::Activate* and *AIS_InteractiveContext::Deactivate* to directly activate/deactivate selection modes on an object.
72b7576f 936
bf62b306 937@subsubsection occt_visu_3_4_5 Filters
72b7576f 938
18006a0f 939To define an environment of dynamic detection, you can use standard filter classes or create your own.
940A filter questions the owner of the sensitive primitive in local context to determine if it has the desired qualities. If it answers positively, it is kept. If not, it is rejected.
942The root class of objects is *SelectMgr_Filter*. The principle behind it is straightforward: a filter tests to see whether the owners <i>(SelectMgr_EntityOwner)</i> detected in mouse position by the Local context selector answer *OK*. If so, it is kept, otherwise it is rejected.
72b7576f 943
bf62b306 944You can create a custom class of filter objects by implementing the deferred function *IsOk()*:
72b7576f 945
bf62b306 946~~~~~
947class MyFilter : public SelectMgr_Filter { };
948virtual Standard_Boolean MyFilter::IsOk
949 (const Handle(SelectMgr_EntityOwner)& anObj) const = 0;
72b7576f 951
bf62b306 952In *SelectMgr*, there are also Composition filters (AND Filters, OR Filters), which allow combining several filters. In InteractiveContext , all filters that you add are stocked in an OR filter (which answers *OK* if at least one filter answers *OK*).
72b7576f 953
bf62b306 954There are Standard filters, which have already been implemented in several packages:
3f812249 955 * *StdSelect_EdgeFilter* -- for edges, such as lines and circles;
956 * *StdSelect_FaceFilter* -- for faces, such as planes, cylinders and spheres;
957 * *StdSelect_ShapeTypeFilter* -- for shape types, such as compounds, solids, shells and wires;
958 * *AIS_TypeFilter* -- for types of interactive objects;
959 * *AIS_SignatureFilter* -- for types and signatures of interactive objects;
960 * *AIS_AttributeFilter* -- for attributes of Interactive Objects, such as color and width.
72b7576f 961
18006a0f 962As there are specific behaviors on shapes, each new *Filter* class must, if necessary, redefine *AIS_LocalContext::ActsOn* function, which informs the Local Context if it acts on specific types of sub-shapes. By default, this function answers *FALSE*.
72b7576f 963
bf62b306 964**WARNING**
966Only type filters are activated in Neutral Point to make it possible to identify a specific type of visualized object. For filters to come into play, one or more object selection modes must be activated.
72b7576f 967
bf62b306 968There are several functions to manipulate filters:
4ee1bdf4 969* *AIS_InteractiveContext::AddFilter* adds a filter passed as an argument.
970* *AIS_InteractiveContext::RemoveFilter* removes a filter passed as an argument.
971* *AIS_InteractiveContext::RemoveFilters* removes all present filters.
972* *AIS_InteractiveContext::Filters* gets the list of filters active in a local context.
dba69de2 973
72b7576f 974<h4>Example </h4>
bf62b306 976~~~~~
4ee1bdf4 977myContext->OpenLocalContext(Standard_False);
bf62b306 978// no object in neutral point is loaded
72b7576f 979
4ee1bdf4 980myContext->ActivateStandardMode(TopAbs_Face);
bf62b306 981//activates decomposition of shapes into faces.
982Handle (AIS_Shape) myAIShape = new AIS_Shape ( ATopoShape);
72b7576f 983
4ee1bdf4 984myContext->Display(myAIShape,1,-1,Standard_True,Standard_True);
72b7576f 985
4ee1bdf4 986//shading visualization mode, no specific mode, authorization for decomposition into sub-shapes. At this Stage, myAIShape is decomposed into faces...
72b7576f 987
bf62b306 988Handle(StdSelect_FaceFilter) Fil1= new
989 StdSelect_FaceFilter(StdSelect_Revol);
990Handle(StdSelect_FaceFilter) Fil2= new
2683e647 991 StdSelect_FaceFilter(StdSelect_Plane);
72b7576f 992
4ee1bdf4 993myContext->AddFilter(Fil1);
72b7576f 995
bf62b306 996//only faces of revolution or planar faces will be selected
4ee1bdf4 998myContext->MoveTo( xpix,ypix,Vue);
bf62b306 999// detects the mouse position
72b7576f 1001
bf62b306 1002@subsubsection occt_visu_3_4_6 Selection in the Local Context
1004Dynamic detection and selection are put into effect in a straightforward way. There are only a few conventions and functions to be familiar with. The functions are the same in neutral point and in open local context:
3f812249 1005 * *AIS_InteractiveContext::MoveTo* -- passes mouse position to Interactive Context selectors
1006 * *AIS_InteractiveContext::Select* -- stocks what has been detected on the last *MoveTo*. Replaces the previously selected object. Empties the stack if nothing has been detected at the last move
1007 * *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.
1008 * *AIS_InteractiveContext::Select* -- selects everything found in the surrounding area.
1009 * *AIS_InteractiveContext::ShiftSelect* -- selects what was not previously in the list of selected, deselects those already present.
bf62b306 1010
1011Highlighting of detected and selected entities is automatically managed by the Interactive Context, whether you are in neutral point or Local Context. The Highlight colors are those dealt with above. You can nonetheless disconnect this automatic mode if you want to manage this part yourself :
1013 AIS_InteractiveContext::SetAutomaticHilight
1014 AIS_InteractiveContext::AutomaticHilight
72b7576f 1016
bf62b306 1017If there is no open local context, the objects selected are called **current objects**. If there is a local context, they are called **selected objects**. Iterators allow entities to be recovered in either case. A set of functions allows manipulating the objects, which have been placed in these different lists.
1021When a Local Context is open, you can select entities other than interactive objects (vertices, edges etc.) from decompositions in standard modes, or from activation in specific modes on specific interactive objects. Only interactive objects are stocked in the list of selected objects.
1023You can question the Interactive context by moving the mouse. The following functions can be used:
1024 * *AIS_InteractiveContext::HasDetected* informs if something has been detected;
1025 * *AIS_InteractiveContext::HasDetectedShape* informs if it is a shape;
1026 * *AIS_InteractiveContext::DetectedShape* gets the shape if the detected entity is an object;
1027 * *AIS_InteractiveContext::DetectedInteractive* gets the interactive object if the detected entity is an object.
1029After using the *Select* and *ShiftSelect* functions in Neutral Point, you can explore the list of selections, referred to as current objects in this context. The following functions can be used:
1030 * *AIS_InteractiveContext::InitCurrent* initiates a scan of this list;
1031 * *AIS_InteractiveContext::MoreCurrent* extends the scan;
1032 * *AIS_InteractiveContext::NextCurrent* resumes the scan;
1033 * *AIS_InteractiveContext::Current* gets the name of the current object detected in the scan;
1034 * *AIS_InteractiveContext::FirstCurrentObject* gets the first current interactive object;
1035 * *AIS_InteractiveContext::HilightCurrents* highlights current objects;
1036 * *AIS_InteractiveContext::UnhilightCurrents* removes highlight from current objects;
1037 * *AIS_InteractiveContext::ClearCurrents* empties the list of current objects in order to update it;
1038 * *AIS_InteractiveContext::IsCurrent* finds the current object.
1040In the Local Context, you can explore the list of selected objects available. The following functions can be used:
1041 * *AIS_InteractiveContext::InitSelected* initiates the list of objects;
1042 * *AIS_InteractiveContext::MoreSelected* extends the list of objects;
1043 * *AIS_InteractiveContext::NextSelected* resumes a scan;
1044 * *AIS_InteractiveContext::SelectedShape* gets the name of the selected object;
1045 * *AIS_InteractiveContext::HasSelectedShape* checks if the selected shape is obtained;
1046 * *AIS_InteractiveContext::Interactive* gets the picked interactive object;
1047 * *AIS_InteractiveContext::HasApplicative* checks if the applicative object has an owner from Interactive attributed to it;
1048 * *AIS_InteractiveContext::Applicative* gets the owner of the detected applicative entity;
1049 * *AIS_InteractiveContext::IsSelected* gets the name of the selected object.
72b7576f 1050
72b7576f 1051
bf62b306 1052<h4>Example </h4>
4ee1bdf4 1054myAISCtx->InitSelected();
1055while (myAISCtx->MoreSelected())
bf62b306 1056 {
4ee1bdf4 1057 if (myAISCtx->HasSelectedShape)
bf62b306 1058 {
4ee1bdf4 1059 TopoDS_Shape ashape = myAISCtx->SelectedShape();
bf62b306 1060 // to be able to use the picked shape
2683e647 1061 }
bf62b306 1062 else
1063 {
4ee1bdf4 1064 Handle_AIS_InteractiveObject anyobj = myAISCtx->Interactive();
bf62b306 1065 // to be able to use the picked interactive object
1066 }
4ee1bdf4 1067myAISCtx->NextSelected();
bf62b306 1068}
72b7576f 1070
bf62b306 1071You have to ask whether you have selected a shape or an interactive object before you can recover the entity in the Local Context or in the iteration loop. If you have selected a Shape from *TopoDS* on decomposition in standard mode, the *Interactive()* function returns the interactive object, which provided the selected shape. Other functions allow you to manipulate the content of Selected or Current Objects:
1072 * *AIS_InteractiveContext::EraseSelected* erases the selected objects;
1073 * *AIS_InteractiveContext::DisplaySelected* displays them;
1074 * *AIS_InteractiveContext::SetSelected* puts the objects in the list of selections;
1075 * *AIS_InteractiveContext::SetSelectedCurrent* takes the list of selected objects from a local context and puts it into the list of current objects in Neutral Point;
1076 * *AIS_InteractiveContext::AddOrRemoveSelected* adds or removes an object from the list of selected entities;
1077 * *AIS_InteractiveContext::HilightSelected* highlights the selected object;
1078 * *AIS_InteractiveContext::UnhilightSelected* removes highlighting from the selected object;
1079 * *AIS_InteractiveContext::ClearSelected* empties the list of selected objects.
72b7576f 1080
72b7576f 1081
bf62b306 1082You can highlight and remove highlighting from a current object, and empty the list of current objects using the following functions:
1084 AIS_InteractiveContext::HilightCurrents
1085 AIS_InteractiveContext::UnhilightCurrents
1086 AIS_InteractiveContext::ClearCurrents
1088When you are in an open Local Context, you may need to keep "temporary" interactive objects. This is possible using the following functions:
1089 * *AIS_InteractiveContext::KeepTemporary* transfers the characteristics of the interactive object seen in its local context (visualization mode, etc.) to the neutral point. When the local context is closed, the object does not disappear.
1090 * *AIS_InteractiveContext::SetSelectedCurrent* allows the selected object to become the current object when you close the local context.
72b7576f 1091
bf62b306 1092You can also want to use function *AIS_InteractiveContext::ClearLocalContext* to modify in a general way the state of the local context before continuing a selection (emptying objects, removing filters, standard activation modes).
72b7576f 1093
bf62b306 1094@subsubsection occt_visu_3_4_7 Recommendations
72b7576f 1095
bf62b306 1096The possibilities of use for local contexts are numerous depending on the type of operation that you want to perform:
72b7576f 1097 * working on all visualized interactive objects,
1098 * working on only a few objects,
1099 * working on a single object.
bf62b306 1101When you want to work on one type of entity, you should open a local context with the option *UseDisplayedObjects* set to FALSE. Some functions which allow you to recover the visualized interactive objects, which have a given Type, and Signature from the "Neutral Point" are:
72b7576f 1102
bf62b306 1103~~~~~
1104AIS_InteractiveContext::DisplayedObjects (AIS_ListOfInteractive& aListOfIO) const;
1105AIS_InteractiveContext::DisplayedObjects (const AIS_KindOfInteractive WhichKind, const Standard_Integer WhichSignature;
1106AIS_ListOfInteractive& aListOfIO) const;
72b7576f 1108
bf62b306 1109At this stage, you only have to load the functions *Load, Activate,* and so on.
72b7576f 1110
bf62b306 1111When you open a Local Context with default options, you must keep the following points in mind:
1112* The Interactive Objects visualized at Neutral Point are activated with their default selection mode. You must deactivate those, which you do not want to use.
1113* The Shape Type Interactive Objects are automatically decomposed into sub-shapes when standard activation modes are launched.
1114* The "temporary" Interactive Objects present in the Local Contexts are not automatically taken into account. You have to load them manually if you want to use them.
72b7576f 1115
bf62b306 1116The stages could be the following:
1117 1. Open a Local Context with the right options;
1118 2. Load/Visualize the required complementary objects with the desired activation modes.
1119 3. Activate Standard modes if necessary
1120 4. Create its filters and add them to the Local Context
1121 5. Detect/Select/recover the desired entities
1122 6. Close the Local Context with the adequate index.
72b7576f 1123
bf62b306 1124It is useful to create an **interactive editor**, to which you pass the Interactive Context. This allow setting up different contexts of selection/presentation according to the operation, which you want to perform.
1126Let us assume that you have visualized several types of interactive objects: *AIS_Points*, *AIS_Axes*, *AIS_Trihedrons*, and *AIS_Shapes*.
72b7576f 1127
bf62b306 1128For your applicative function, you need an axis to create a revolved object. You could obtain this axis by identifying:
72b7576f 1129 * an axis which is already visualized,
1130 * 2 points,
1131 * a rectilinear edge on the shapes which are present,
bf62b306 1132 * a cylindrical face on the shapes (You will take the axis of this face)
72b7576f 1133
bf62b306 1134~~~~~
1136 (const Handle(AIS_InteractiveContext)& Ctx,
2683e647 1137 ....) :
1138 myCtx(Ctx),
bf62b306 1139 ...
72b7576f 1140{
4ee1bdf4 1145myIndex =myCtx->OpenLocalContext();
72b7576f 1146
bf62b306 1147//the filters
72b7576f 1148
2683e647 1149Handle(AIS_SignatureFilter) F1 = new AIS_SignatureFilter(AIS_KOI_Datum,AIS_SD_Point);
bf62b306 1150//filter on the points
72b7576f 1151
bf62b306 1152Handle(AIS_SignatureFilter) F2 = new AIS_SignatureFilter(AIS_KOI_Datum,AIS_SD_Axis);
1153//filters on the axes.
72b7576f 1154
bf62b306 1155Handle(StdSelect_FaceFilter) F3 = new StdSelect_FaceFilter(AIS_Cylinder);
1156//cylindrical face filters
72b7576f 1157//...
bf62b306 1158// activation of standard modes on the shapes..
4ee1bdf4 1159myCtx->ActivateStandardMode(TopAbs_FACE);
72b7576f 1164
bf62b306 1165// at this point, you can call the selection/detection function
72b7576f 1166}
1168void myIHMEditor::MoveTo(xpix,ypix,Vue)
4ee1bdf4 1170{ myCTX->MoveTo(xpix,ypix,vue);
bf62b306 1171// the highlight of what is detected is automatic.
1173Standard_Boolean myIHMEditor::Select()
1175// returns true if you should continue the selection
4ee1bdf4 1176 myCTX->Select();
1177 myCTX->InitSelected();
1178 if(myCTX->MoreSelected())
2683e647 1179 {
1180 if(myCTX->HasSelectedShape())
4ee1bdf4 1181 { const TopoDS_Shape& sh = myCTX->SelectedShape();
bf62b306 1182 if( vertex){
1183 if(myFirstV...)
1184 {
4ee1bdf4 1185 //if it is the first vertex, you stock it, then you deactivate the faces and only keep the filter on the points:
bf62b306 1186 mypoint1 = ....;
4ee1bdf4 1187 myCtx->RemoveFilters();
1188 myCTX->DeactivateStandardMode(TopAbs_FACE);
1189 myCtx->Add(F1);
bf62b306 1190 // the filter on the AIS_Points
4ee1bdf4 1191 myFirstV = Standard_False;
1192 return Standard_True;
2683e647 1193 }
bf62b306 1194 else
2683e647 1195 {
bf62b306 1196 mypoint2 =...;
1197 // construction of the axis return Standard_False;
1198 }
2683e647 1199 }
1200 else
1201 {
bf62b306 1202 //it is a cylindrical face : you recover the axis; visualize it; and stock it.
1203 return Standard_False;
1204 }
2683e647 1205 }
bf62b306 1206 // it is not a shape but is no doubt a point.
1207 else
1208 {
1209 Handle(AIS_InteractiveObject)
4ee1bdf4 1210 SelObj = myCTX->SelectedInteractive();
1211 if(SelObj->Type()==AIS_KOI_Datum)
bf62b306 1212 {
4ee1bdf4 1213 if(SelObj->Signature()==1)
bf62b306 1214 {
1215 if (firstPoint)
1216 {
1217 mypoint1 =...
1218 return Standard_True;
1219 }
1220 else
1221 {
1222 mypoint2 = ...;
1223 //construction of the axis, visualization, stocking
1224 return Standard_False;
1225 }
1226 }
1228 else
1229 {
1230 // you have selected an axis; stock the axis
1231 return Standard_False;
1232 }
1233 }
1234 }
1235 }
1236 }
1237void myIHMEditor::Terminate()
72b7576f 1243
bf62b306 1244@subsection occt_visu_3_5 Standard Interactive Object Classes
72b7576f 1245
18006a0f 1246Interactive Objects are selectable and viewable objects connecting graphic representation and the underlying reference geometry.
1248They are divided into four types:
3f812249 1249 * the **Datum** -- a construction geometric element;
1250 * the **Relation** -- a constraint on the interactive shape and the corresponding reference geometry;
1251 * the **Object** -- a topological shape or connection between shapes;
1252 * **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 1253
1254Inside 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*).
1255If you want to give a particular type and signature to your interactive object, you must redefine the two virtual methods: <i>Type</i> and <i>Signature</i>.
1257@subsubsection occt_visu_3_5_1 Datum
1259The **Datum** groups together the construction elements such as lines, circles, points, trihedrons, plane trihedrons, planes and axes.
bf62b306 1260
1261*AIS_Point, AIS_Axis, AIS_Line, AIS_Circle, AIS_Plane* and *AIS_Trihedron* have four selection modes:
1262 * mode 0 : selection of a trihedron;
1263 * mode 1 : selection of the origin of the trihedron;
1264 * mode 2 : selection of the axes;
1265 * mode 3 : selection of the planes XOY, YOZ, XOZ.
72b7576f 1266
bf62b306 1267when you activate one of modes: 1 2 3 4, you pick AIS objects of type:
1268 * *AIS_Point*
1269 * *AIS_Axis* (and information on the type of axis)
1270 * *AIS_Plane* (and information on the type of plane).
72b7576f 1271
bf62b306 1272*AIS_PlaneTrihedron* offers three selection modes:
1273 * mode 0 : selection of the whole trihedron;
1274 * mode 1 : selection of the origin of the trihedron;
3f812249 1275 * mode 2 : selection of the axes -- same remarks as for the Trihedron.
72b7576f 1276
bf62b306 1277For the presentation of planes and trihedra, the default unit of length is millimeter, and the default value for the representation of axes is 100. If you modify these dimensions, you must temporarily recover the object **Drawer**. From it, take the *Aspects* in which the values for length are stored (*PlaneAspect* for the plane, *FirstAxisAspect* for trihedra), and change these values inside these Aspects. Finally, recalculate the presentation.
e5bd0d98 1278
18006a0f 1279@subsubsection occt_visu_3_5_2 Object
1281The **Object** type includes topological shapes, and connections between shapes.
e5bd0d98 1282
ba06f8bb 1283*AIS_Shape* has three visualization modes :
72b7576f 1284 * mode 0 : Line (default mode)
1285 * mode 1 : Shading (depending on the type of shape)
1286 * mode 2 : Bounding Box
ba06f8bb 1288And at maximum seven selection modes, depending on the shape complexity:
bf62b306 1289 * mode 0 : selection of the *AIS_Shape*;
1290 * mode 1 : selection of the vertices;
1291 * mode 2 : selection of the edges;
1292 * mode 3 : selection of the wires;
1293 * mode 4 : selection of the faces;
1294 * mode 5 : selection of the shells;
e5bd0d98 1295 * mode 6 : selection of the constituent solids.
72b7576f 1296
ba06f8bb 1297 * *AIS_Triangulation* is a simple interactive object for displaying triangular mesh contained in *Poly_Triangulation* container.
1298 * *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.
2683e647 1299 * *AIS_ConnectedShape* is an object connected to interactive objects having a shape; this class has the same decompositions as *AIS_Shape*. Furthermore, it allows a presentation of hidden parts, which are calculated automatically from the shape of its reference.
ba06f8bb 1300 * *AIS_MultipleConnectedInteractive* is an object connected to a list of interactive objects (which can also be Connected objects. It does not require memory hungry calculations of presentation)
1301 * *AIS_MultipleConnectedShape* is an interactive Object connected to a list of interactive objects having a Shape <i>(AIS_Shape, AIS_ConnectedShape, AIS_MultipleConnectedShape)</i>. The presentation of hidden parts is calculated automatically.
1302 * *AIS_TexturedShape* is an Interactive Object that supports texture mapping. It is constructed as a usual AIS_Shape, but has additional methods that allow to map a texture on it.
1303 * *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.
72b7576f 1304
18006a0f 1305
1306The class *AIS_ColoredShape* allows using custom colors and line widths for *TopoDS_Shape* objects and their sub-shapes.
1309 AIS_ColoredShape aColoredShape = new AIS_ColoredShape (theShape);
1311 // setup color of entire shape
1312 aColoredShape->SetColor (Quantity_Color (Quantity_NOC_RED));
1314 // setup line width of entire shape
1315 aColoredShape->SetWidth (1.0);
1317 // set transparency value
1318 aColoredShape->SetTransparency (0.5);
1320 // customize color of specified sub-shape
1321 aColoredShape->SetCustomColor (theSubShape, Quantity_Color (Quantity_NOC_BLUE1));
1323 // customize line width of specified sub-shape
1324 aColoredShape->SetCustomWidth (theSubShape, 0.25);
1327The 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.
1328- The type of point marker used to draw points can be specified as a presentation aspect.
1329- The presentation provides selection by a bounding box of the visualized set of points. It supports two display / highlighting modes: points or bounding box.
1331@image html point_cloud.png "A random colored cloud of points"
1335Handle(Graphic3d_ArrayOfPoints) aPoints = new Graphic3d_ArrayOfPoints (2000, Standard_True);
1336aPoints->AddVertex (gp_Pnt(-40.0, -40.0, -40.0), Quantity_Color (Quantity_NOC_BLUE1));
1337aPoints->AddVertex (gp_Pnt (40.0, 40.0, 40.0), Quantity_Color (Quantity_NOC_BLUE2));
1339Handle(AIS_PointCloud) aPntCloud = new AIS_PointCloud();
1340aPntCloud->SetPoints (aPoints);
1343The draw command *vpointcloud* builds a cloud of points from shape triangulation.
1344This command can also draw a sphere surface or a volume with a large amount of points (more than one million).
bf62b306 1347@subsubsection occt_visu_3_5_3 Relations
18006a0f 1348
1349The **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.
1351The following relations are provided by *AIS*:
bf62b306 1352 * *AIS_ConcentricRelation*
1353 * *AIS_FixRelation*
1354 * *AIS_IdenticRelation*
1355 * *AIS_ParallelRelation*
1356 * *AIS_PerpendicularRelation*
1357 * *AIS_Relation*
1358 * *AIS_SymmetricRelation*
1359 * *AIS_TangentRelation*
72b7576f 1360
bf62b306 1361The list of relations is not exhaustive.
72b7576f 1362
bf62b306 1363@subsubsection occt_visu_3_5_4 Dimensions
1364 * *AIS_AngleDimension*
1365 * *AIS_Chamf3dDimension*
1366 * *AIS_DiameterDimension*
1367 * *AIS_DimensionOwner*
1368 * *AIS_LengthDimension*
1369 * *AIS_OffsetDimension*
1370 * *AIS_RadiusDimension*
72b7576f 1371
bf62b306 1372 @subsubsection occt_visu_3_5_5 MeshVS_Mesh
72b7576f 1373
bf62b306 1374*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 1375
3f812249 1376However, 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 1377
bf62b306 1378The 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 1379
72b7576f 1380You can add/remove builders using the following methods:
bf62b306 1381~~~~~
1382 MeshVS_Mesh::AddBuilder (const Handle (MeshVS_PrsBuilder) &Builder, Standard_Boolean TreatAsHilighter)
1383 MeshVS_Mesh::RemoveBuilder (const Standard_Integer Index)
1384 MeshVS_Mesh::RemoveBuilderById (const Standard_Integer Id)
72b7576f 1386
bf62b306 1387There 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:
1389 MeshVS_DMF_WireFrame
1390 MeshVS_DMF_Shading
1391 MeshVS_DMF_Shrink
72b7576f 1393
bf62b306 1394It is also possible to display deformed mesh in wireframe, shading or shrink modes usung :
1396 MeshVS_DMF_DeformedPrsWireFrame
1397 MeshVS_DMF_DeformedPrsShading
1398 MeshVS_DMF_DeformedPrsShrink
72b7576f 1400
bf62b306 1401The following methods represent different kinds of data :
1403 MeshVS_DMF_VectorDataPrs
1404 MeshVS_DMF_NodalColorDataPrs
1405 MeshVS_DMF_ElementalColorDataPrs
1406 MeshVS_DMF_TextDataPrs
1407 MeshVS_DMF_EntitiesWithData
1410The following methods provide selection and highlighting :
1412 MeshVS_DMF_SelectionPrs
1413 MeshVS_DMF_HilightPrs
72b7576f 1415
bf62b306 1416*MeshVS_DMF_User* is a user-defined mode.
72b7576f 1417
bf62b306 1418These values will be used by the presentation builder.
1419There is also a set of selection modes flags that can be grouped in a combination of bits:
1420 * *MeshVS_SMF_0D*
1421 * *MeshVS_SMF_Link*
1422 * *MeshVS_SMF_Face*
1423 * *MeshVS_SMF_Volume*
3f812249 1424 * *MeshVS_SMF_Element* -- groups *0D, Link, Face* and *Volume* as a bit mask ;
bf62b306 1425 * *MeshVS_SMF_Node*
3f812249 1426 * *MeshVS_SMF_All* -- groups *Element* and *Node* as a bit mask;
bf62b306 1427 * *MeshVS_SMF_Mesh*
1428 * *MeshVS_SMF_Group*
1430Such an object, for example, can be used for displaying the object and stored in the STL file format:
72b7576f 1431
bf62b306 1432~~~~~
1433// read the data and create a data source
1434Handle (StlMesh_Mesh) aSTLMesh = RWStl::ReadFile (aFileName);
1435Handle (XSDRAWSTLVRML_DataSource) aDataSource = new XSDRAWSTLVRML_DataSource (aSTLMesh);
72b7576f 1436
bf62b306 1437// create mesh
1438Handle (MeshVS_Mesh) aMesh = new MeshVS();
4ee1bdf4 1439aMesh->SetDataSource (aDataSource);
72b7576f 1440
bf62b306 1441// use default presentation builder
1442Handle (MeshVS_MeshPrsBuilder) aBuilder = new MeshVS_MeshPrsBuilder (aMesh);
4ee1bdf4 1443aMesh->AddBuilder (aBuilder, Standard_True);
bf62b306 1444~~~~~
72b7576f 1445
bf62b306 1446*MeshVS_NodalColorPrsBuilder* allows representing a mesh with a color scaled texture mapped on it.
1447To do this you should define a color map for the color scale, pass this map to the presentation builder,
2683e647 1448and define an appropriate value in the range of 0.0 - 1.0 for every node.
72b7576f 1449
bf62b306 1450The following example demonstrates how you can do this (check if the view has been set up to display textures):
1453// assign nodal builder to the mesh
1454Handle (MeshVS_NodalColorPrsBuilder) aBuilder = new MeshVS_NodalColorPrsBuilder
2683e647 1455 (aMesh,MeshVS_DMF_NodalColorDataPrs | MeshVS_DMF_OCCMask);
4ee1bdf4 1456aBuilder->UseTexture (Standard_True);
bf62b306 1457
1458// prepare color map
1459Aspect_SequenceOfColor aColorMap;
1460aColorMap.Append ((Quantity_NameOfColor) Quantity_NOC_RED);
1461aColorMap.Append ((Quantity_NameOfColor) Quantity_NOC_BLUE1);
1463// assign color scale map values (0..1) to nodes
1464TColStd_DataMapOfIntegerReal aScaleMap;
2683e647 1465...
bf62b306 1466// iterate through the nodes and add an node id and an appropriate value to the map
1467aScaleMap.Bind (anId, aValue);
2683e647 1468
bf62b306 1469// pass color map and color scale values to the builder
4ee1bdf4 1470aBuilder->SetColorMap (aColorMap);
1471aBuilder->SetInvalidColor (Quantity_NOC_BLACK);
1472aBuilder->SetTextureCoords (aScaleMap);
1473aMesh->AddBuilder (aBuilder, Standard_True);
bf62b306 1474~~~~~
72b7576f 1475
bf62b306 1476@subsection occt_visu_3_6 Dynamic Selection
72b7576f 1477
a7d4dd94 1478The dynamic selection represents the topological shape, which you want to select, by decomposition of <i>sensitive primitives</i> -- the sub-parts of the shape that will be detected and highlighted. The sets of these primitives are handled by the powerful three-level BVH tree selection algorithm.
72b7576f 1479
a7d4dd94 1480For more details on the algorithm and examples of usage, please, refer to @ref occt_visu_2_2 "Selection" chapter.
72b7576f 1481
bf62b306 1482@section occt_visu_4 3D Presentations
72b7576f 1483
bf62b306 1484@subsection occt_visu_4_1 Glossary of 3D terms
72b7576f 1485
bf62b306 1486* **Anti-aliasing** This mode attempts to improve the screen resolution by drawing lines and curves in a mixture of colors so that to the human eye the line or curve is smooth. The quality of the result is linked to the quality of the algorithm used by the workstation hardware.
3f812249 1487* **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.
1488* **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.
1489* **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.
1490* **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.
1491* **View** -- is defined by a view orientation, a view mapping, and a context view.
1492* **Viewer** -- manages a set of views.
1493* **View orientation** -- defines the manner in which the observer looks at the scene in terms of View Reference Coordinates.
1494* **View mapping** -- defines the transformation from View Reference Coordinates to the Normalized Projection Coordinates. This follows the Phigs scheme.
1495* **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 1496
18006a0f 1497@subsection occt_visu_4_2 Graphic primitives
72b7576f 1498
18006a0f 1499The *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 1500
bf62b306 1501Graphic structures can be:
72b7576f 1502 * Displayed,
1503 * Highlighted,
1504 * Erased,
1505 * Transformed,
18006a0f 1506 * Connected to form a tree hierarchy of structures, created by transformations.
bf62b306 1507
1508There are classes for:
72b7576f 1509 * Visual attributes for lines, faces, markers, text, materials,
1510 * Vectors and vertices,
72b7576f 1511 * Graphic objects, groups, and structures.
18006a0f 1513@subsubsection occt_visu_4_2_2 Structure hierarchies
bf62b306 1514
18006a0f 1515The 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.
1517@subsubsection occt_visu_4_2_3 Graphic primitives
bf62b306 1518* **Markers**
72b7576f 1519 * Have one or more vertices,
1520 * Have a type, a scale factor, and a color,
bf62b306 1521 * Have a size, shape, and orientation independent of transformations.
1522* **Polygons**
72b7576f 1523 * Have one closed boundary,
1524 * Have at least three vertices,
1525 * Are planar and have a normal,
3f812249 1526 * Have interior attributes -- style, color, front and back material, texture and reflection ratio,
1527 * Have a boundary with the following attributes -- type, width scale factor, color. The boundary is only drawn when the interior style is hollow.
72b7576f 1528
bf62b306 1529* **Polygons with holes**
1530 * Have multiple closed boundaries, each one with at least three vertices,
72b7576f 1531 * Are planar and have a normal,
3f812249 1532 * Have interior attributes -- style, color, front and back material,
1533 * Have a boundary with the following attributes -- type, width scale factor, color. The boundary is only drawn when the interior style is hollow.
72b7576f 1534
bf62b306 1535* **Polylines**
72b7576f 1536 * Have two or more vertices,
3f812249 1537 * Have the following attributes -- type, width scale factor, color.
72b7576f 1538
bf62b306 1539* **Text**
72b7576f 1540 * Has geometric and non-geometric attributes,
3f812249 1541 * Geometric attributes -- character height, character up vector, text path, horizontal and vertical alignment, orientation, three-dimensional position, zoomable flag
1542 * Non-geometric attributes -- text font, character spacing, character expansion factor, color.
72b7576f 1543
18006a0f 1544@subsubsection occt_visu_4_2_4 Primitive arrays
72b7576f 1545
bf62b306 1546Primitive arrays are a more efficient approach to describe and display the primitives from the aspects of memory usage and graphical performance. The key feature of the primitive arrays is that the primitive data is not duplicated. For example, two polygons could share the same vertices, so it is more efficient to keep the vertices in a single array and specify the polygon vertices with indices of this array. In addition to such kind of memory savings, the OpenGl graphics driver provides the Vertex Buffer Objects (VBO). VBO is a sort of video memory storage that can be allocated to hold the primitive arrays, thus making the display operations more efficient and releasing the RAM memory.
72b7576f 1547
bf62b306 1548The Vertex Buffer Objects are enabled by default, but VBOs availability depends on the implementation of OpenGl. If the VBOs are unavailable or there is not enough video memory to store the primitive arrays, the RAM memory will be used to store the arrays.
72b7576f 1549
bf62b306 1550The Vertex Buffer Objects can be disabled at the application level. You can use the method *Graphic3d_GraphicDriver::EnableVBO (const Standard_Boolean status)* to enable/disable VBOs:
1552The following example shows how to disable the VBO support:
72b7576f 1553
bf62b306 1554~~~~~
4ee1bdf4 1555// get the graphic driver
bf62b306 1556Handle (Graphic3d_GraphicDriver) aDriver =
2683e647 1557 myAISContext->CurrentViewer()->Driver();
72b7576f 1558
4ee1bdf4 1559// disable VBO support
1560aDriver->EnableVBO (Standard_False);
bf62b306 1561~~~~~
72b7576f 1562
bf62b306 1563**Note** that the use of Vertex Buffer Objects requires the application level primitive data provided by the *Graphic3d_ArrayOfPrimitives* to be transferred to the video memory. *TKOpenGl* transfers the data and releases the *Graphic3d_ArrayOfPrimitives* internal pointers to the primitive data. Thus it might be necessary to pay attention to such kind of behaviour, as the pointers could be modified (nullified) by the *TKOpenGl*.
1565The different types of primitives could be presented with the following primitive arrays:
1566 * *Graphic3d_ArrayOfPoints,*
1567 * *Graphic3d_ArrayOfPolygons,*
1568 * *Graphic3d_ArrayOfPolylines,*
1569 * *Graphic3d_ArrayOfQuadrangles,*
1570 * *Graphic3d_ArrayOfQuadrangleStrips,*
1571 * *Graphic3d_ArrayOfSegments,*
1572 * *Graphic3d_ArrayOfTriangleFans,*
1573 * *Graphic3d_ArrayOfTriangles,*
1574 * *Graphic3d_ArrayOfTriangleStrips.*
1576The *Graphic3d_ArrayOfPrimitives* is a base class for these primitive arrays.
1578Method *Graphic3d_ArrayOfPrimitives::AddVertex* allows adding There is a set of similar methods to add vertices to the primitive array.
1580These methods take vertex coordinates as an argument and allow you to define the color, the normal and the texture coordinates assigned to the vertex. The return value is the actual number of vertices in the array.
1582You can also modify the values assigned to the vertex or query these values by the vertex index:
1583 * *void Graphic3d_ArrayOfPrimitives::SetVertice*
1584 * *void Graphic3d_ArrayOfPrimitives::SetVertexColor*
1585 * *void Graphic3d_ArrayOfPrimitives::SetVertexNormal*
1586 * *void Graphic3d_ArrayOfPrimitives::SetVertexTexel*
1587 * *gp_Pnt Graphic3d_ArrayOfPrimitives::Vertices*
2683e647 1588 * *gp_Dir Graphic3d_ArrayOfPrimitives::VertexNormal*
bf62b306 1589 * *gp_Pnt3d Graphic3d_ArrayOfPrimitives::VertexTexel*
1590 * *Quantity_Color Graphic3d_ArrayOfPrimitives::VertexColor*
1591 * *void Graphic3d_ArrayOfPrimitives::Vertices*
1592 * *void Graphic3d_ArrayOfPrimitives::VertexNormal*
1593 * *void Graphic3d_ArrayOfPrimitives::VertexTexel*
1594 * *void Graphic3d_ArrayOfPrimitives::VertexColor*
1596The following example shows how to define an array of points:
72b7576f 1597
bf62b306 1598~~~~~
1599// create an array
1600Handle (Graphic3d_ArrayOfPoints) anArray = new Graphic3d_ArrayOfPoints (aVerticiesMaxCount);
1602// add vertices to the array
4ee1bdf4 1603anArray->AddVertex (10.0, 10.0, 10.0);
1604anArray->AddVertex (0.0, 10.0, 10.0);
72b7576f 1605
bf62b306 1606// add the array to the structure
1607Handle (Graphic3d_Group) aGroup = Prs3d_Root::CurrentGroup (aPrs);
4ee1bdf4 1608aGroup->BeginPrimitives ();
1609aGroup->AddPrimitiveArray (anArray);
1610aGroup->EndPrimitives ();
bf62b306 1611~~~~~
72b7576f 1612
bf62b306 1613If the primitives share the same vertices (polygons, triangles, etc.) then you can define them as indices of the vertices array.
72b7576f 1614
bf62b306 1615The method *Graphic3d_ArrayOfPrimitives::AddEdge* allows defining the primitives by indices. This method adds an "edge" in the range <i> [1, VertexNumber() ] </i> in the array.
72b7576f 1616
bf62b306 1617It is also possible to query the vertex defined by an edge using method *Graphic3d_ArrayOfPrimitives::Edge*
72b7576f 1618
bf62b306 1619The following example shows how to define an array of triangles:
72b7576f 1620
bf62b306 1621~~~~~
1622// create an array
2683e647 1623Standard_Boolean IsNormals = Standard_False;
1624Standard_Boolean IsColors = Standard_False;
bf62b306 1625Standard_Boolean IsTextureCrds = Standard_False;
1626Handle (Graphic3d_ArrayOfTriangles) anArray =
2683e647 1627 new Graphic3d_ArrayOfTriangles (aVerticesMaxCount,
1628 aEdgesMaxCount,
1629 IsNormals,
1630 IsColors,
1631 IsTextureCrds);
bf62b306 1632// add vertices to the array
2683e647 1633anArray->AddVertex (-1.0, 0.0, 0.0); // vertex 1
1634anArray->AddVertex ( 1.0, 0.0, 0.0); // vertex 2
1635anArray->AddVertex ( 0.0, 1.0, 0.0); // vertex 3
1636anArray->AddVertex ( 0.0,-1.0, 0.0); // vertex 4
bf62b306 1637
1638// add edges to the array
2683e647 1639anArray->AddEdge (1); // first triangle
4ee1bdf4 1640anArray->AddEdge (2);
1641anArray->AddEdge (3);
2683e647 1642anArray->AddEdge (1); // second triangle
4ee1bdf4 1643anArray->AddEdge (2);
1644anArray->AddEdge (4);
bf62b306 1645
1646// add the array to the structure
1647Handle (Graphic3d_Group) aGroup = Prs3d_Root::CurrentGroup (aPrs);
4ee1bdf4 1648aGroup->BeginPrimitives ();
1649aGroup->AddPrimitiveArray (anArray);
1650aGroup->EndPrimitives ();
bf62b306 1651~~~~~
72b7576f 1652
bf62b306 1653If the primitive array presents primitives built from sequential sets of vertices, for example polygons, then you can specify the bounds, or the number of vertices for each primitive. You can use the method *Graphic3d_ArrayOfPrimitives::AddBound* to define the bounds and the color for each bound. This method returns the actual number of bounds.
72b7576f 1654
bf62b306 1655It is also possible to set the color and query the number of edges in the bound and bound color.
1657 Standard_Integer Graphic3d_ArrayOfPrimitives::Bound
1658 Quantity_Color Graphic3d_ArrayOfPrimitives::BoundColor
1659 void Graphic3d_ArrayOfPrimitives::BoundColor
1662The following example shows how to define an array of polygons:
72b7576f 1663
bf62b306 1664~~~~~
1665// create an array
2683e647 1666Standard_Boolean IsNormals = Standard_False;
bf62b306 1667Standard_Boolean IsVertexColors = Standard_False;
2683e647 1668Standard_Boolean IsFaceColors = Standard_False;
1669Standard_Boolean IsTextureCrds = Standard_False;
bf62b306 1670Handle (Graphic3d_ArrayOfPolygons) anArray =
2683e647 1671 new Graphic3d_ArrayOfPolygons (aVerticesMaxCount,
1672 aBoundsMaxCount,
1673 aEdgesMaxCount,
1674 IsNormals,
1675 IsVertexColors,
1676 IsFaceColors,
1677 IsTextureCrds);
bf62b306 1678
1679// add bounds to the array, first polygon
4ee1bdf4 1680anArray->AddBound (3);
2683e647 1681anArray->AddVertex (-1.0, 0.0, 0.0);
1682anArray->AddVertex ( 1.0, 0.0, 0.0);
1683anArray->AddVertex ( 0.0, 1.0, 0.0);
bf62b306 1684
1685// add bounds to the array, second polygon
4ee1bdf4 1686anArray->AddBound (4);
2683e647 1687anArray->AddVertex (-1.0, 0.0, 0.0);
1688anArray->AddVertex ( 1.0, 0.0, 0.0);
1689anArray->AddVertex ( 1.0,-1.0, 0.0);
1690anArray->AddVertex (-1.0,-1.0, 0.0);
bf62b306 1691
1692// add the array to the structure
1693Handle (Graphic3d_Group) aGroup = Prs3d_Root::CurrentGroup (aPrs);
4ee1bdf4 1694aGroup->BeginPrimitives ();
1695aGroup->AddPrimitiveArray (anArray);
1696aGroup->EndPrimitives ();
bf62b306 1697~~~~~
72b7576f 1698
bf62b306 1699There are also several helper methods. You can get the type of the primitive array:
1701 Graphic3d_TypeOfPrimitiveArray
1702 Graphic3d_ArrayOfPrimitives::Type
1703 Standard_CString Graphic3d_ArrayOfPrimitives::StringType
72b7576f 1705
bf62b306 1706and check if the primitive array provides normals, vertex colors and vertex texels (texture coordinates):
72b7576f 1707
bf62b306 1708~~~~~
1709 Standard_Boolean Graphic3d_ArrayOfPrimitives::HasVertexNormals
1710 Standard_Boolean Graphic3d_ArrayOfPrimitives::HasVertexColors
1711 Standard_Boolean Graphic3d_ArrayOfPrimitives::HasVertexTexels
72b7576f 1713or get the number of vertices, edges and bounds:
bf62b306 1714~~~~~
1715 Standard_Integer Graphic3d_ArrayOfPrimitives::VertexNumber
1716 Standard_Integer Graphic3d_ArrayOfPrimitives::EdgeNumber
1717 Standard_Integer Graphic3d_ArrayOfPrimitives::BoundNumber
18006a0f 1720@subsubsection occt_visu_4_2_5 Text primitive
72b7576f 1721
bf62b306 1722The OpenGl graphics driver uses advanced text rendering powered by FTGL library. This library provides vector text rendering, as a result the text can be rotated and zoomed without quality loss.
1723*Graphic3d* text primitives have the following features:
72b7576f 1724 * fixed size (non-zoomable) or zoomable,
1725 * can be rotated to any angle in the view plane,
1726 * support unicode charset.
bf62b306 1728The text attributes for the group could be defined with the *Graphic3d_AspectText3d* attributes group.
1729To add any text to the graphic structure you can use the following methods:
1731 void Graphic3d_Group::Text
1732 (const Standard_CString AText,
2683e647 1733 const Graphic3d_Vertex& APoint,
1734 const Standard_Real AHeight,
1735 const Quantity_PlaneAngle AAngle,
1736 const Graphic3d_TextPath ATp,
1737 const Graphic3d_HorizontalTextAlignment AHta,
1738 const Graphic3d_VerticalTextAlignment AVta,
1739 const Standard_Boolean EvalMinMax),
bf62b306 1740~~~~~
1741*AText* parameter is the text string, *APoint* is the three-dimensional position of the text, *AHeight* is the text height, *AAngle* is the orientation of the text (at the moment, this parameter has no effect, but you can specify the text orientation through the *Graphic3d_AspectText3d* attributes).
1743*ATp* parameter defines the text path, *AHta* is the horizontal alignment of the text, *AVta* is the vertical alignment of the text.
2683e647 1745You can pass *Standard_False* as *EvalMinMax* if you do not want the graphic3d structure boundaries to be affected by the text position.
bf62b306 1746
1747**Note** that the text orientation angle can be defined by *Graphic3d_AspectText3d* attributes.
1749 void Graphic3d_Group::Text
1750 (const Standard_CString AText,
2683e647 1751 const Graphic3d_Vertex& APoint,
1752 const Standard_Real AHeight,
1753 const Standard_Boolean EvalMinMax)
bf62b306 1754 void Graphic3d_Group::Text
1755 (const TCcollection_ExtendedString &AText,
1756 const Graphic3d_Vertex& APoint,
2683e647 1757 const Standard_Real AHeight,
1758 const Quantity_PlaneAngle AAngle,
1759 const Graphic3d_TextPath ATp,
1760 const Graphic3d_HorizontalTextAlignment AHta,
1761 const Graphic3d_VerticalTextAlignment AVta,
1762 const Standard_Boolean EvalMinMax)
bf62b306 1763 void Graphic3d_Group::Text
1764 (const TCcollection_ExtendedString &AText,
2683e647 1765 const Graphic3d_Vertex& APoint,
1766 const Standard_Real AHeight,
1767 const Standard_Boolean EvalMinMax)
bf62b306 1768~~~~~
72b7576f 1769
bf62b306 1770See the example:
1772// get the group
1773Handle (Graphic3d_Group) aGroup = Prs3d_Root::CurrentGroup (aPrs);
72b7576f 1774
bf62b306 1775// change the text aspect
1776Handle(Graphic3d_AspectText3d) aTextAspect = new Graphic3d_AspectText3d ();
4ee1bdf4 1777aTextAspect->SetTextZoomable (Standard_True);
1778aTextAspect->SetTextAngle (45.0);
1779aGroup->SetPrimitivesAspect (aTextAspect);
72b7576f 1780
bf62b306 1781// add a text primitive to the structure
72b7576f 1782Graphic3d_Vertex aPoint (1, 1, 1);
4ee1bdf4 1783aGroup->Text (Standard_CString ("Text"), aPoint, 16.0);
bf62b306 1784~~~~~
18006a0f 1786@subsubsection occt_visu_4_2_6 Materials
1788A *Graphic3d_MaterialAspect* is defined by:
1789 * Transparency;
3f812249 1790 * Diffuse reflection -- a component of the object color;
18006a0f 1791 * Ambient reflection;
3f812249 1792 * Specular reflection -- a component of the color of the light source;
18006a0f 1793 * Refraction index.
1795The following items are required to determine the three colors of reflection:
1796 * Color;
1797 * Coefficient of diffuse reflection;
1798 * Coefficient of ambient reflection;
1799 * Coefficient of specular reflection.
1801@subsubsection occt_visu_4_2_7 Textures
1803A *texture* is defined by a name.
1804Three types of texture are available:
1805 * 1D;
1806 * 2D;
1807 * Environment mapping.
1809@subsubsection occt_visu_4_2_8 Shaders
1811OCCT visualization core supports GLSL shaders. Currently OCCT supports only vertex and fragment GLSL shader. Shaders can be assigned to a generic presentation by its drawer attributes (Graphic3d aspects). To enable custom shader for a specific AISShape in your application, the following API functions are used:
1814// Create shader program
1815Handle(Graphic3d_ShaderProgram) aProgram = new Graphic3d_ShaderProgram();
1817// Attach vertex shader
1818aProgram->AttachShader (Graphic3d_ShaderObject::CreateFromFile(
1819 Graphic3d_TOS_VERTEX, "<Path to VS>"));
1821// Attach fragment shader
1822aProgram->AttachShader (Graphic3d_ShaderObject::CreateFromFile(
1823 Graphic3d_TOS_FRAGMENT, "<Path to FS>"));
1825// Set values for custom uniform variables (if they are)
1826aProgram->PushVariable ("MyColor", Graphic3d_Vec3(0.0f, 1.0f, 0.0f));
1828// Set aspect property for specific AISShape
1829theAISShape->Attributes()->ShadingAspect()->Aspect()->SetShaderProgram (aProgram);
72b7576f 1831
18006a0f 1832@subsection occt_visu_4_3 Graphic attributes
72b7576f 1833
18006a0f 1834@subsubsection occt_visu_4_3_1 Aspect package overview
72b7576f 1835
18006a0f 1836The *Aspect* package provides classes for the graphic elements in the viewer:
1837 * Groups of graphic attributes;
1838 * Edges, lines, background;
1839 * Window;
1840 * Driver;
1841 * Enumerations for many of the above.
72b7576f 1842
18006a0f 1843@subsection occt_visu_4_4 3D view facilities
72b7576f 1844
18006a0f 1845@subsubsection occt_visu_4_4_1 Overview
72b7576f 1846
bf62b306 1847The *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 1848
89a929ea 1849A 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 1850
bf62b306 1851The *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:
72b7576f 1852 * Default parameters of the viewer,
1853 * Views (orthographic, perspective),
1854 * Lighting (positional, directional, ambient, spot, headlight),
89a929ea 1855 * Clipping planes,
bf62b306 1856 * Instantiated sequences of views, planes, light sources, graphic structures, and picks,
72b7576f 1857 * Various package methods.
18006a0f 1859@subsubsection occt_visu_4_4_2 A programming example
72b7576f 1860
bf62b306 1861This sample TEST program for the *V3d* Package uses primary packages *Xw* and *Graphic3d* and secondary packages *Visual3d, Aspect, Quantity, Phigs* and *math*.
72b7576f 1862
bf62b306 1863~~~~~
1864//Create a default display connection
1865Handle(Aspect_DisplayConnection) aDisplayConnection = new Aspect_DisplayConnection();
72b7576f 1866
4ee1bdf4 1867//Create a Graphic Driver from the default Aspect_DisplayConnection
18006a0f 1868Handle(OpenGl_GraphicDriver) GD = new OpenGl_GraphicDriver (aDisplayConnection);
bf62b306 1869
1870//Create a Viewer to this Driver
1871Handle(V3d_Viewer) VM = new V3d_Viewer(GD, 400.,
4ee1bdf4 1872 // Space size
1873 V3d_Xpos,
1874 // Default projection
1875 Quantity_NOC_DARKVIOLET,
1876 // Default background
1877 V3d_ZBUFFER,
1878 // Type of visualization
1879 V3d_GOURAUD,
1880 // Shading model
1881 V3d_WAIT);
1882 // Update mode
1883// Create a structure in this Viewer
1884Handle(Graphic3d_Structure) S = new Graphic3d_Structure(VM->Viewer()) ;
1886// Type of structure
1887S->SetVisual (Graphic3d_TOS_SHADING);
1889// Create a group of primitives in this structure
bf62b306 1890Handle(Graphic3d_Group) G = new Graphic3d_Group(S) ;
72b7576f 1891
4ee1bdf4 1892// Fill this group with one polygon of size 100
bf62b306 1893Graphic3d_Array1OfVertex Points(0,3) ;
1894Points(0).SetCoord(-100./2.,-100./2.,-100./2.) ;
1895Points(1).SetCoord(-100./2., 100./2.,-100./2.) ;
1896Points(2).SetCoord( 100./2., 100./2.,-100./2.) ;
4ee1bdf4 1897Points(3).SetCoord( 100./2.,-100./2.,-100./2.) ;
1898Normal.SetCoord(0.,0.,1.) ;
1899G->Polygon(Points,Normal) ;
72b7576f 1900
4ee1bdf4 1901// Create Ambient and Infinite Lights in this Viewer
bf62b306 1902Handle(V3d_AmbientLight) L1 = new V3d_AmbientLight
4ee1bdf4 1903 (VM,Quantity_NOC_GRAY50) ;
bf62b306 1904Handle(V3d_DirectionalLight) L2 = new V3d_DirectionalLight
4ee1bdf4 1905 (VM,V3d_XnegYnegZneg,Quantity_NOC_WHITE) ;
72b7576f 1906
4ee1bdf4 1907// Create a 3D quality Window with the same DisplayConnection
1908Handle(Xw_Window) W = new Xw_Window(aDisplayConnection,"Test V3d",0.5,0.5,0.5,0.5) ;
72b7576f 1909
4ee1bdf4 1910// Map this Window to this screen
1911W->Map() ;
72b7576f 1912
4ee1bdf4 1913// Create a Perspective View in this Viewer
18006a0f 1914Handle(V3d_View) aView = new V3d_View(VM);
1915aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Perspective);
1916// Associate this View with the Window
1917aView ->SetWindow(W);
1918// Display ALL structures in this View
1920// Finally update the Visualization in this View
3f812249 1924As an alternative to manual setting of perspective parameters the *V3d_View::ZfitAll()* and *V3d_View::FitAll()* functions can be used:
72b7576f 1925
18006a0f 1926~~~~~
1927// Display shape in Viewer VM
1928Handle(AIS_InteractiveContext) aContext = new AIS_InteractiveContext (VM);
1930// Create a Perspective View in Viewer VM
1931Handle(V3d_View) V = new V3d_View (VM);
1932aview->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Perspective);
1933// Change Z-min and Z-max planes of projection volume to match the displayed objects
1935// Fit view to object size
72b7576f 1938
18006a0f 1939@subsubsection occt_visu_4_4_3 Define viewing parameters
72b7576f 1940
18006a0f 1941View 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 1942
3f812249 1943* **Eye** -- defines the observer (camera) position. Make sure the Eye point never gets between the Front and Back clipping planes.
72b7576f 1944
3f812249 1945* **Center** -- defines the origin of View Reference Coordinates (where camera is aimed at).
72b7576f 1946
3f812249 1947* **Direction** -- defines the direction of camera view (from the Eye to the Center).
72b7576f 1948
3f812249 1949* **Distance** -- defines the distance between the Eye and the Center.
72b7576f 1950
3f812249 1951* **Front** Plane -- defines the position of the front clipping plane in View Reference Coordinates system.
72b7576f 1952
3f812249 1953* **Back** Plane -- defines the position of the back clipping plane in View Reference Coordinates system.
72b7576f 1954
3f812249 1955* **ZNear** -- defines the distance between the Eye and the Front plane.
72b7576f 1956
3f812249 1957* **ZFar** -- defines the distance between the Eye and the Back plane.
dba69de2 1958
18006a0f 1959Most 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 1960
18006a0f 1961Example:
1963// rotate camera by X axis on 30.0 degrees
1964gp_Trsf aTrsf;
1965aTrsf.SetRotation (gp_Ax1 (gp_Pnt (0.0, 0.0, 0.0), gp_Dir (1.0, 0.0, 0.0)), 30.0);
1966aView->Camera()->Transform (aTrsf);
72b7576f 1968
18006a0f 1969@subsubsection occt_visu_4_4_4 Orthographic Projection
1971@image html view_frustum.png "Perspective and orthographic projection"
72b7576f 1972
18006a0f 1973The following code configures the camera for orthographic rendering:
72b7576f 1974
bf62b306 1975~~~~~
18006a0f 1976// Create an orthographic View in this Viewer
1977Handle(V3d_View) aView = new V3d_View (VM);
1978aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Orthographic);
1979// update the Visualization in this View
72b7576f 1982
18006a0f 1983@subsubsection occt_visu_4_4_5 Perspective Projection
72b7576f 1984
3f812249 1985**Field of view (FOVy)** -- defines the field of camera view by y axis in degrees (45° is default).
72b7576f 1986
18006a0f 1987@image html camera_perspective.png "Perspective frustum"
72b7576f 1988
18006a0f 1989The following code configures the camera for perspective rendering:
72b7576f 1990
bf62b306 1991~~~~~
18006a0f 1992// Create a perspective View in this Viewer
1993Handle(V3d_View) aView = new V3d_View(VM);
1994aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Perspective);
72b7576f 1997
72b7576f 1998
18006a0f 1999@subsubsection occt_visu_4_4_6 Stereographic Projection
72b7576f 2000
3f812249 2001**IOD** -- defines the intraocular distance (in world space units).
18006a0f 2002
2003There are two types of IOD:
2004* _IODType_Absolute_ : Intraocular distance is defined as an absolute value.
2005* _IODType_Relative_ : Intraocular distance is defined relative to the camera focal length (as its coefficient).
3f812249 2007**Field of view (FOV)** -- defines the field of camera view by y axis in degrees (45° is default).
18006a0f 2008
3f812249 2009**ZFocus** -- defines the distance to the point of stereographic focus.
18006a0f 2010
2011@image html stereo.png "Stereographic projection"
2013To enable stereo projection, your workstation should meet the following requirements:
2015* The graphic card should support quad buffering.
2016* You need active 3D glasses (LCD shutter glasses).
2017* The graphic driver needs to be configured to impose quad buffering for newly created OpenGl contexts; the viewer and the view should be created after that.
2019In stereographic projection mode the camera prepares two projection matrices to display different stereo-pictures for the left and for the right eye. In a non-stereo camera this effect is not visible because only the same projection is used for both eyes.
2021To enable quad buffering support you should provide the following settings to the graphic driver *opengl_caps*:
72b7576f 2022
18006a0f 2023~~~~~
2024Handle(OpenGl_GraphicDriver) aDriver = new OpenGl_GraphicDriver();
2025OpenGl_Caps& aCaps = aDriver->ChangeOptions();
2026aCaps.contextStereo = Standard_True;
bf62b306 2027~~~~~
72b7576f 2028
18006a0f 2029The following code configures the camera for stereographic rendering:
72b7576f 2030
18006a0f 2031~~~~~
2032// Create a Stereographic View in this Viewer
2033Handle(V3d_View) aView = new V3d_View(VM);
2034aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Stereo);
2035// Change stereo parameters
2036aView->Camera()->SetIOD (IODType_Absolute, 5.0);
2037// Finally update the Visualization in this View
72b7576f 2040
18006a0f 2041@subsubsection occt_visu_4_4_7 View frustum culling
72b7576f 2042
18006a0f 2043The algorithm of frustum culling on CPU-side is activated by default for 3D viewer. This algorithm allows skipping the presentation outside camera at the rendering stage, providing better performance. The following features support this method:
2044* *Graphic3d_Structure::CalculateBoundBox()* is used to calculate axis-aligned bounding box of a presentation considering its transformation.
2045* *V3d_View::SetFrustumCulling* enables or disables frustum culling for the specified view.
2046* Classes *OpenGl_BVHClipPrimitiveSet* and *OpenGl_BVHTreeSelector* handle the detection of outer objects and usage of acceleration structure for frustum culling.
2047* *BVH_BinnedBuilder* class splits several objects with null bounding box.
72b7576f 2048
18006a0f 2049@subsubsection occt_visu_4_4_8 Underlay and overlay layers management
72b7576f 2050
18006a0f 2051In addition to interactive 3d graphics displayed in the view you can display underlying and overlying graphics: text, color scales and drawings.
72b7576f 2052
bf62b306 2053All *V3d* view graphical objects in the overlay are managed by the default layer manager (*V3d_LayerMgr*). The *V3d* view has a basic layer manager capable of displaying the color scale, but you can redefine this class to provide your own overlay and underlay graphics.
72b7576f 2054
bf62b306 2055The method *V3d_View::SetLayerMgr(const Handle (V3d_LayerMgr)& aMgr)* allows assigning a custom layer manager to the *V3d* view.
72b7576f 2056
18006a0f 2057There are three virtual methods to prepare graphics in the manager for further drawing: setting up layer dimensions and drawing static graphics. These methods can be redefined:
bf62b306 2059~~~~~
2060 void V3d_LayerMgr::Begin ()
2061 void V3d_LayerMgr::Redraw ()
2062 void V3d_LayerMgr::End ()
72b7576f 2064
bf62b306 2065The layer manager controls layers (*Visual3d_Layer*) and layer items (*Visual3d_LayerItem*). Both the overlay and underlay layers can be created by the layer manager.
72b7576f 2066
18006a0f 2067The layer entity is presented by the *Visual3d_Layer* class. This entity provides drawing services in the layer, for example:
bf62b306 2068~~~~~
2069 void Visual3d_Layer::DrawText
2070 void Visual3d_Layer::DrawRectangle
2071 void Visual3d_Layer::SetColor
2072 void Visual3d_Layer::SetViewport
18006a0f 2074
2075The following example demonstrates how to draw overlay graphics by the *V3d_LayerMgr*:
72b7576f 2076
bf62b306 2077~~~~~
2078// redefined method of V3d_LayerMgr
2079void MyLayerMgr::Redraw ()
72b7576f 2080{
2683e647 2081 Quantity_Color aRed (Quantity_NOC_RED);
2082 myOverlayLayer->SetColor (aRed);
2083 myOverlayLayer->DrawRectangle (0, 0, 100, 100);
72b7576f 2084}
bf62b306 2085~~~~~
72b7576f 2086
2683e647 2087The layer contains layer items that will be displayed on view redraw. Such items are *Visual3d_LayerItem* entities. To manipulate *Visual3d_LayerItem* entities assigned to the layer's internal list you can use the following methods:
72b7576f 2088
bf62b306 2089~~~~~
2090 void Visual3d_Layer::AddLayerItem (const Handle (Visual3d_LayerItem)& Item)
2683e647 2091 void Visual3d_Layer::RemoveLayerItem (const Handle (Visual3d_LayerItem)& Item)
bf62b306 2092 void Visual3d_Layer::RemoveAllLayerItems ()
2683e647 2093 const Visual3d_NListOfLayerItem& Visual3d_Layer::GetLayerItemList ()
bf62b306 2094~~~~~
2683e647 2095The layer's items are rendered when the method *void Visual3d_Layer::RenderLayerItems()* is called by the graphical driver.
72b7576f 2096
bf62b306 2097The *Visual3d_LayerItem* has virtual methods that are used to render the item:
2099 void Visual3d_LayerItem::RedrawLayerPrs ()
2100 void Visual3d_LayerItem::ComputeLayerPrs ()
72b7576f 2102
bf62b306 2103The item presentation can be computed before drawing by the *ComputeLayerPrs* method to save time on redraw. It also has an additional flag that is used to tell that the presentation should be recomputed:
2105 void Visual3d_LayerItem::SetNeedToRecompute (const Standard_Boolean NeedToRecompute)
2106 Standard_Boolean Visual3d_LayerItem::IsNeedToRecompute
72b7576f 2108
2683e647 2109An example of *Visual3d_LayerItem* is *V3d_ColorScaleLayerItem* that represents the color scale entity as the layer's item.
2110The *V3d_ColorScaleLayerItem* sends render requests to the color scale entity represented by it. As this entity (*V3d_ColorScale*) is assigned to the *V3d_LayerMgr* it uses its overlay layer's services for drawing:
72b7576f 2111
72b7576f 2112<h4>Example </h4>
bf62b306 2114~~~~~
2115// tell V3d_ColorScale to draw itself
2116void V3d_ColorScaleLayerItem::RedrawLayerPrs ()
72b7576f 2117{
2683e647 2118 Visual3d_LayerItem::RedrawLayerPrs ()
2119 if (!MyColorScale.IsNull ())
2120 MyColorScale->DrawScale ();
72b7576f 2121}
bf62b306 2123// V3d_ColorScale has a reference to a LayerMgr
2124void V3d_ColorScale::DrawScale ()
2683e647 2126 // calls V3d_ColorScale::PaintRect, V3d_ColorScale::PaintText, etc.
bf62b306 2127}
72b7576f 2128
bf62b306 2129// PaintRect method uses overlay layer of LayerMgr to draw a rectangle
2130void V3d_ColorScale::PaintRect
2683e647 2131 (const Standard_Integer X, const Standard_Integer Y,
2132 const Standard_Integer W, const Standard_Integer H,
2133 const Quantity_Color aColor,
2134 const Standard_Boolean aFilled)
bf62b306 2135{
2683e647 2136 const Handle (Visual3d_Layer)& theLayer = myLayerMgr->Overlay ();
2137 ...
2138 theLayer->SetColor (aColor);
2139 theLayer->DrawRectangle (X, Y, W, H);
2140 ...
bf62b306 2141}
72b7576f 2143
18006a0f 2144@subsubsection occt_visu_4_4_9 View background styles
bf62b306 2145There are three types of background styles available for *V3d_view*: solid color, gradient color and image.
72b7576f 2146
bf62b306 2147To set solid color for the background you can use the following methods:
2149 void V3d_View::SetBackgroundColor
2150 (const Quantity_TypeOfColor Type,
2683e647 2151 const Quantity_Parameter V1,
2152 const Quantity_Parameter V2,
2153 const Quantity_Parameter V3)
bf62b306 2154~~~~~
72b7576f 2155
bf62b306 2156This method allows you to specify the background color in RGB (red, green, blue) or HLS (hue, lightness, saturation) color spaces, so the appropriate values of the Type parameter are *Quantity_TOC_RGB* and *Quantity_TOC_HLS*.
72b7576f 2157
bf62b306 2158**Note** that the color value parameters *V1,V2,V3* should be in the range between *0.0-1.0.*
72b7576f 2159
bf62b306 2160~~~~~
2161 void V3d_View::SetBackgroundColor(const Quantity_Color &Color)
2162 void V3d_View::SetBackgroundColor(const Quantity_NameOfColor Name)
72b7576f 2164
bf62b306 2165The gradient background style could be set up with the following methods:
2167 void V3d_View::SetBgGradientColors
2168 (const Quantity_Color& Color1,
2683e647 2169 const Quantity_Color& Color2,
2170 const Aspect_GradientFillMethod FillStyle,
2171 const Standard_Boolean update)
bf62b306 2172
2173 void V3d_View::SetBgGradientColors
2174 (const Quantity_NameOfColor Color1,
2683e647 2175 const Quantity_NameOfColor Color2,
2176 const Aspect_GradientFillMethod FillStyle,
2177 const Standard_Boolean update)
bf62b306 2178~~~~~
72b7576f 2179
bf62b306 2180The *Color1* and *Color2* parameters define the boundary colors of interpolation, the *FillStyle* parameter defines the direction of interpolation. You can pass *Standard_True* as the last parameter to update the view.
72b7576f 2181
bf62b306 2182The fill style can be also set with the method *void V3d_View::SetBgGradientStyle(const Aspect_GradientFillMethod AMethod, const Standard_Boolean update)*.
72b7576f 2183
bf62b306 2184To get the current background color you can use the following methods:
2186 void V3d_View::BackgroundColor
2187 (const Quantity_TypeOfColor Type,
2683e647 2188 Quantity_Parameter &V1,
2189 Quantity_Parameter &V2,
2190 Quantity_Parameter &V3)
bf62b306 2191 Quantity_Color V3d_View::BackgroundColor()
2192 void V3d_View::GradientBackgroundColors(Quantity_Color& Color1, Quantity_Color& Color2)
2193 Aspect_GradientBackground GradientBackground()
2196To set the image as a background and change the background image style you can use the following methods:
4ee1bdf4 2198 void V3d_View::SetBackgroundImage
bf62b306 2199 (const Standard_CString FileName,
2683e647 2200 const Aspect_FillMethod FillStyle,
2201 const Standard_Boolean update)
4ee1bdf4 2202 void V3d_View::SetBgImageStyle
bf62b306 2203 (const Aspect_FillMethod FillStyle,
2683e647 2204 const Standard_Boolean update)
bf62b306 2205~~~~~
72b7576f 2206
bf62b306 2207The *FileName* parameter defines the image file name and the path to it, the *FillStyle* parameter defines the method of filling the background with the image. The methods are:
3f812249 2208 * *Aspect_FM_NONE* -- draws the image in the default position;
2209 * *Aspect_FM_CENTERED* -- draws the image at the center of the view;
2210 * *Aspect_FM_TILED* -- tiles the view with the image;
2211 * *Aspect_FM_STRETCH* -- stretches the image over the view.
72b7576f 2212
72b7576f 2213
18006a0f 2214@subsubsection occt_visu_4_4_10 Dumping a 3D scene into an image file
72b7576f 2215
18006a0f 2216The 3D scene displayed in the view can be dumped in high resolution into an image file. The high resolution (8192x8192 on some implementations) is achieved using the Frame Buffer Objects (FBO) provided by the graphic driver. Frame Buffer Objects enable off-screen rendering into a virtual view to produce images in the background mode (without displaying any graphics on the screen).
72b7576f 2217
bf62b306 2218The *V3d_View* has the following methods for dumping the 3D scene:
4ee1bdf4 2219~~~~
2220Standard_Boolean V3d_View::Dump
2221 (const Standard_CString theFile,
2222 const Image_TypeOfImage theBufferType)
2224Dumps the scene into an image file with the view dimensions.
2227Standard_Boolean V3d_View::Dump
2228 (const Standard_CString theFile,
2229 const Aspect_FormatOfSheetPaper theFormat,
2230 const Image_TypeOfImage theBufferType)
2232Makes the dimensions of the output image compatible to a certain format of printing paper passed by *theFormat* argument.
bf62b306 2233
2234These methods dump the 3D scene into an image file passed by its name and path as theFile.
72b7576f 2235
18006a0f 2236The raster image data handling algorithm is based on the *Image_PixMap* class. The supported extensions are ".png", ".bmp", ".png", ".png".
72b7576f 2237
4ee1bdf4 2238The value passed as *theBufferType* argument defines the type of the buffer for an output image <i>(RGB, RGBA, floating-point, RGBF, RGBAF)</i>. Both methods return *Standard_True* if the scene has been successfully dumped.
72b7576f 2239
18006a0f 2240There is also class *Image_AlienPixMap* providing import / export from / to external image files in formats supported by **FreeImage** library.
bf62b306 2242**Note** that dumping the image for a paper format with large dimensions is a memory consuming operation, it might be necessary to take care of preparing enough free memory to perform this operation.
72b7576f 2243
4ee1bdf4 2244~~~~
2245Handle_Image_PixMap V3d_View::ToPixMap
2246 (const Standard_Integer theWidth,
2247 const Standard_Integer theHeight,
2248 const Image_TypeOfImage theBufferType,
2249 const Standard_Boolean theForceCentered)
2251Dumps the displayed 3d scene into a pixmap with a width and height passed as *theWidth* and theHeight arguments.
72b7576f 2252
4ee1bdf4 2253The value passed as *theBufferType* argument defines the type of the buffer for a pixmap <i>(RGB, RGBA, floating-point, RGBF, RGBAF)</i>. The last parameter allows centering the 3D scene on dumping.
72b7576f 2254
bf62b306 2255All these methods assume that you have created a view and displayed a 3d scene in it. However, the window used for such a view could be virtual, so you can dump the 3d scene in the background mode without displaying it on the screen. To use such an opportunity you can perform the following steps:
2256* Create display connection;
2257* Initialize graphic driver;
2258* Create a window;
2259* Set up the window as virtual, *Aspect_Window::SetVirtual()* ;
2260* Create a view and an interactive context;
2261* Assign the virtual window to the view;
2262* Display a 3D scene;
2263* Use one of the functions described above to dump the 3D scene.
72b7576f 2264
bf62b306 2265The following example demonstrates this procedure for *WNT_Window* :
72b7576f 2266
bf62b306 2267~~~~~
2268// create a dummy display connection
2269Handle(Aspect_DisplayConnection) aDisplayConnection;
2271// create a graphic driver
2272Handle (Graphic3d_GraphicDriver) aDriver = Graphic3d::InitGraphicDriver (aDisplayConnection);
2274// create a window
2683e647 2275Standard_Integer aDefWidth = 800;
bf62b306 2276Standard_Integer aDefHeight = 600;
4ee1bdf4 2277Handle (WNT_WClass) aWClass = new WNT_WClass ("Virtual Class",DefWindowProc,
2683e647 2278 CS_VREDRAW | CS_HREDRAW, 0, 0,
2279 ::LoadCursor (NULL, IDC_ARROW));
2280Handle (WNT_Window) aWindow = new WNT_Window ("VirtualWnd", aWClass,
2282 aDefWidth, aDefHeight);
bf62b306 2283
2284// set up the window as virtual
4ee1bdf4 2285aWindow->SetVirtual (Standard_True);
bf62b306 2286
2287// create a view and an interactive context
4ee1bdf4 2288Handle (V3d_Viewer) aViewer = new V3d_Viewer (aDriver,
2683e647 2289 Standard_ExtString ("Virtual"));
4ee1bdf4 2290Handle (AIS_InteractiveContext) aContext = new AIS_InteractiveContext (aViewer);
2291Handle (V3d_View) aView = aViewer->CreateView ();
bf62b306 2292
2293// assign the virtual window to the view
4ee1bdf4 2294aView->SetWindow (aWindow);
bf62b306 2295
2296// display a 3D scene
4ee1bdf4 2297Handle (AIS_Shape) aBox = new AIS_Shape (BRepPrimAPI_MakeBox (5, 5, 5));
2298aContext->Display (aBox);
72b7576f 2300
bf62b306 2301// dump the 3D scene into an image file
4ee1bdf4 2302aView->Dump ("3dscene.png");
bf62b306 2303~~~~~
72b7576f 2304
18006a0f 2305@subsubsection occt_visu_4_4_11 Printing a 3D scene
72b7576f 2306
bf62b306 2307The contents of a view can be printed out. Moreover, the OpenGl graphic driver used by the v3d view supports printing in high resolution. The print method uses the OpenGl frame buffer (Frame Buffer Object) for rendering the view contents and advanced print algorithms that allow printing in, theoretically, any resolution.
72b7576f 2308
2683e647 2309The method *void V3d_View::Print(const Aspect_Handle hPrnDC, const Standard_Boolean showDialog, const Standard_Boolean showBackground, const Standard_CString filename, const Aspect_PrintAlgo printAlgorithm)* prints the view contents:
72b7576f 2310
18006a0f 2311*hPrnDC* is the printer device handle. You can pass your own printer handle or *NULL* to select the printer by the default dialog. In that case you can use the default dialog or pass *Standard_False* as the *showDialog* argument to select the default printer automatically.
72b7576f 2312
bf62b306 2313You can define the filename for the printer driver if you want to print out the result into a file.
2314If you do not want to print the background, you can pass *Standard_False* as the *showBackground* argument.
2315The *printAlgorithm* argument allows choosing between two print algorithms that define how the 3d scene is mapped to the print area when the maximum dimensions of the frame buffer are smaller than the dimensions of the print area by choosing *Aspect_PA_STRETCH* or *Aspect_PA_TILE*
72b7576f 2316
bf62b306 2317The first value defines the stretch algorithm: the scene is drawn with the maximum possible frame buffer dimensions and then is stretched to the whole printing area. The second value defines *TileSplit* algorithm: covering the whole printing area by rendering multiple parts of the viewer.
72b7576f 2318
18006a0f 2319**Note** that at the moment the printing is implemented only for Windows.
72b7576f 2320
18006a0f 2321@subsubsection occt_visu_4_4_12 Vector image export
72b7576f 2322
18006a0f 2323The 3D content of a view can be exported to the vector image file format. The vector image export is powered by the *GL2PS* library. You can export 3D scenes into a file format supported by the GL2PS library: PostScript (PS), Encapsulated PostScript (EPS), Portable Document Format (PDF), Scalable Vector Graphics (SVG), LaTeX file format and Portable LaTeX Graphics (PGF).
72b7576f 2324
bf62b306 2325The method *void Visual3d_View::Export (const Standard_CString FileName, const Graphic3d_ExportFormat Format, const Graphic3d_SortType aSortType, const Standard_Real Precision, const Standard_Address ProgressBarFunc, const Standard_Address ProgressObject)* of *Visual3d_View* class allows exporting a 3D scene:
72b7576f 2326
bf62b306 2327The *FileName* defines the output image file name and the *Format* argument defines the output file format:
18006a0f 2328 * *Graphic3d_EF_PostScript (PS)*,
2329 * *Graphic3d_EF_EhnPostScript (EPS)*,
2330 * *Graphic3d_EF_TEX (TEX)*,
2331 * *Graphic3d_EF_PDF (PDF)*,
2332 * *Graphic3d_EF_SVG (SVG)*,
2333 * *Graphic3d_EF_PGF (PGF)*.
72b7576f 2334
bf62b306 2335The *aSortType* parameter defines *GL2PS* sorting algorithm for the primitives. The *Precision, ProgressBarFunc* and *ProgressObject* parameters are implemented for future uses and at the moment have no effect.
72b7576f 2336
bf62b306 2337The *Export* method supports only basic 3d graphics and has several limitations:
2338 * Rendering large scenes could be slow and can lead to large output files;
2339 * Transparency is only supported for PDF and SVG output;
18006a0f 2340 * Textures and some effects are not supported by the *GL2PS* library.
72b7576f 2341
18006a0f 2342@subsubsection occt_visu_4_4_13 Ray tracing support
72b7576f 2343
18006a0f 2344OCCT visualization provides rendering by real-time ray tracing technique. It is allowed to switch easily between usual rasterization and ray tracing rendering modes. The core of OCCT ray tracing is written using GLSL shaders. The ray tracing has a wide list of features:
2345* Hard shadows
2346* Refractions
2347* Reflection
2348* Transparency
2349* Texturing
2350* Support of non-polygon objects, such as lines, text, highlighting, selection.
2351* Performance optimization using 2-level bounding volume hierarchy (BVH).
72b7576f 2352
18006a0f 2353The ray tracing algorithm is recursive (Whitted's algorithm). It uses BVH effective optimization structure. The structure prepares optimized data for a scene geometry for further displaying it in real-time. The time-consuming re-computation of the BVH is not necessary for view operations, selections, animation and even editing of the scene by transforming location of the objects. It is only necessary when the list of displayed objects or their geometry changes.
2354To make the BVH reusable it has been added into an individual reusable OCCT package *TKMath/BVH*.
2356There are several ray-tracing options that user can switch on/off:
2357* Maximum ray tracing depth
2358* Shadows rendering
2359* Specular reflections
2360* Adaptive anti aliasing
2361* Transparency shadow effects
2365Graphic3d_RenderingParams& aParams = aView->ChangeRenderingParams();
2366// specifies rendering mode
2367aParams.Method = Graphic3d_RM_RAYTRACING;
2368// maximum ray-tracing depth
2369aParams.RaytracingDepth = 3;
2370// enable shadows rendering
2371aParams.IsShadowEnabled = Standard_True;
2372// enable specular reflections.
2373aParams.IsReflectionEnabled = Standard_True;
2374// enable adaptive anti-aliasing
2375aParams.IsAntialiasingEnabled = Standard_True;
2376// enable light propagation through transparent media.
2377aParams.IsTransparentShadowEnabled = Standard_True;
2378// update the view
2382@subsubsection occt_visu_4_4_14 Display priorities
2384Structure display priorities control the order, in which structures are drawn. When you display a structure you specify its priority. The lower is the value, the lower is the display priority. When the display is regenerated, the structures with the lowest priority are drawn first. The structures with the same display priority are drawn in the same order as they have been displayed. OCCT supports eleven structure display priorities.
2386@subsubsection occt_visu_4_4_15 Z-layer support
2683e647 2388OCCT features depth-arranging functionality called z-layer. A graphical presentation can be put into a z-layer. In general, this function can be used for implementing "bring to front" functionality in a graphical application.
18006a0f 2389
2393// set z-layer to an interactive object
2683e647 2394Handle(AIS_InteractiveContext) aContext = ...
2395Handle(AIS_InteractiveObject) anInterObj = ...
18006a0f 2396Standard_Integer anId = 3;
2397aViewer->AddZLayer (anId);
2398aContext->SetZLayer (anInterObj, anId);
2401For each z-layer, it is allowed to:
2402* Enable / disable depth test for layer.
2403* Enable / disable depth write for layer.
2404* Enable / disable depth buffer clearing.
2405* Enable / disable polygon offset.
2683e647 2407The corresponding method *SetZLayerOption (...)* is available in *Graphic3d_GraphicDriver* interface. You can get the options using getter from *Visual3d_ViewManager* and *V3d_Viewer*. It returns *Graphic3d_ZLayerSettings* cached in *Visual3d_ViewManager* for a given *LayerId*.
18006a0f 2408
2411// change z-layer settings
2412Graphic3d_ZLayerSettings aSettings = aViewer->ZLayerSettings (anId);
2413aSettings.EnableSetting (Graphic3d_ZLayerDepthTest);
2414aSettings.EnableSetting (Graphic3d_ZLayerDepthWrite);
2415aSettings.EnableSetting (Graphic3d_ZLayerDepthClear);
2416aSettings.EnableSetting (Graphic3d_ZLayerDepthOffset);
2417aViewer->SetZLayerSettings (anId, aSettings);
2421@subsubsection occt_visu_4_4_16 Clipping planes
2423The ability to define custom clipping planes could be very useful for some tasks. OCCT provides such an opportunity.
2425The *Graphic3d_ClipPlane* class provides the services for clipping planes: it holds the plane equation coefficients and provides its graphical representation. To set and get plane equation coefficients you can use the following methods:
2428Graphic3d_ClipPlane::Graphic3d_ClipPlane(const gp_Pln& thePlane)
2429void Graphic3d_ClipPlane::SetEquation (const gp_Pln& thePlane)
2430Graphic3d_ClipPlane::Graphic3d_ClipPlane(const Equation& theEquation)
2431void Graphic3d_ClipPlane::SetEquation (const Equation& theEquation)
2432gp_Pln Graphic3d_ClipPlane::ToPlane() const
2435The clipping planes can be activated with the following method:
2437void Graphic3d_ClipPlane::SetOn (const Standard_Boolean theIsOn)
2440The number of clipping planes is limited. You can check the limit value via method *Graphic3d_GraphicDriver::InquirePlaneLimit()*;
2443// get the limit of clipping planes for the current view
2444Standard_Integer aMaxClipPlanes = aView->Viewer()->Driver()->InquirePlaneLimit();
2447Let us see for example how to create a new clipping plane with custom parameters and add it to a view or to an object:
2449// create a new clipping plane
2450const Handle(Graphic3d_ClipPlane)& aClipPlane = new Graphic3d_ClipPlane();
2451// change equation of the clipping plane
2683e647 2452Standard_Real aCoeffA = ...
2453Standard_Real aCoeffB = ...
2454Standard_Real aCoeffC = ...
2455Standard_Real aCoeffD = ...
18006a0f 2456aClipPlane->SetEquation (gp_Pln (aCoeffA, aCoeffB, aCoeffC, aCoeffD));
2457// set capping
2458aClipPlane->SetCapping (aCappingArg == "on");
2459// set the material with red color of clipping plane
2460Graphic3d_MaterialAspect aMat = aClipPlane->CappingMaterial();
2461Quantity_Color aColor (1.0, 0.0, 0.0, Quantity_TOC_RGB);
2462aMat.SetAmbientColor (aColor);
2463aMat.SetDiffuseColor (aColor);
2464aClipPlane->SetCappingMaterial (aMat);
2465// set the texture of clipping plane
2683e647 2466Handle(Graphic3d_Texture2Dmanual) aTexture = ...
18006a0f 2467aTexture->EnableModulate();
2469aClipPlane->SetCappingTexture (aTexture);
2470// add the clipping plane to an interactive object
2683e647 2471Handle(AIS_InteractiveObject) aIObj = ...
18006a0f 2472aIObj->AddClipPlane (aClipPlane);
2473// or to the whole view
2474aView->AddClipPlane (aClipPlane);
2475// activate the clipping plane
2477// update the view
2482@subsubsection occt_visu_4_4_17 Automatic back face culling
2484Back face culling reduces the rendered number of triangles (which improves the performance) and eliminates artifacts at shape boundaries. However, this option can be used only for solid objects, where the interior is actually invisible from any point of view. Automatic back-face culling mechanism is turned on by default, which is controlled by *V3d_View::SetBackFacingModel()*.
2486The following features are applied in *StdPrs_ToolShadedShape::IsClosed()*, which is used for definition of back face culling in *ShadingAspect*:
2487* disable culling for free closed Shells (not inside the Solid) since reversed orientation of a free Shell is a valid case;
2488* enable culling for Solids packed into a compound;
2489* ignore Solids with incomplete triangulation.
2491Back face culling is turned off at TKOpenGl level in the following cases:
2492* clipping/capping planes are in effect;
2493* for translucent objects;
2494* with hatching presentation style.
2496@subsection occt_visu_4_5 Examples: creating a 3D scene
2498To create 3D graphic objects and display them in the screen, follow the procedure below:
24991. Create attributes.
25002. Create a 3D viewer.
25013. Create a view.
25024. Create an interactive context.
25035. Create interactive objects.
25046. Create primitives in the interactive object.
25057. Display the interactive object.
2507@subsubsection occt_visu_4_5_1 Create attributes
2509Create colors.
2512Quantity_Color aBlack (Quantity_NOC_BLACK);
2513Quantity_Color aBlue (Quantity_NOC_MATRABLUE);
2514Quantity_Color aBrown (Quantity_NOC_BROWN4);
2515Quantity_Color aFirebrick (Quantity_NOC_FIREBRICK);
2516Quantity_Color aForest (Quantity_NOC_FORESTGREEN);
2517Quantity_Color aGray (Quantity_NOC_GRAY70);
2518Quantity_Color aMyColor (0.99, 0.65, 0.31, Quantity_TOC_RGB);
2519Quantity_Color aBeet (Quantity_NOC_BEET);
2520Quantity_Color aWhite (Quantity_NOC_WHITE);
2523Create line attributes.
2526Handle(Graphic3d_AspectLine3d) anAspectBrown = new Graphic3d_AspectLine3d();
2527Handle(Graphic3d_AspectLine3d) anAspectBlue = new Graphic3d_AspectLine3d();
2528Handle(Graphic3d_AspectLine3d) anAspectWhite = new Graphic3d_AspectLine3d();
2529anAspectBrown->SetColor (aBrown);
2530anAspectBlue ->SetColor (aBlue);
2531anAspectWhite->SetColor (aWhite);
2534Create marker attributes.
2536Handle(Graphic3d_AspectMarker3d aFirebrickMarker = new Graphic3d_AspectMarker3d();
2537// marker attributes
2538aFirebrickMarker->SetColor (Firebrick);
2539aFirebrickMarker->SetScale (1.0);
2540aFirebrickMarker->SetType (Aspect_TOM_BALL);
2541// or this
2542// it is a preferred way (supports full-color images on modern hardware).
2543aFirebrickMarker->SetMarkerImage (theImage)
2546Create facet attributes.
2548Handle(Graphic3d_AspectFillArea3d) aFaceAspect = new Graphic3d_AspectFillArea3d();
2549Graphic3d_MaterialAspect aBrassMaterial (Graphic3d_NOM_BRASS);
2550Graphic3d_MaterialAspect aGoldMaterial (Graphic3d_NOM_GOLD);
2551aFaceAspect->SetInteriorStyle (Aspect_IS_SOLID);
2552aFaceAspect->SetInteriorColor (aMyColor);
2553aFaceAspect->SetDistinguishOn ();
2554aFaceAspect->SetFrontMaterial (aGoldMaterial);
2555aFaceAspect->SetBackMaterial (aBrassMaterial);
2559Create text attributes.
2561Handle(Graphic3d_AspectText3d) aTextAspect = new Graphic3d_AspectText3d (aForest, Graphic3d_NOF_ASCII_MONO, 1.0, 0.0);
2564@subsubsection occt_visu_4_5_2 Create a 3D Viewer (a Windows example)
2567// create a default connection
2568Handle(Aspect_DisplayConnection) aDisplayConnection;
2569// create a graphic driver from default connection
2570Handle(OpenGl_GraphicDriver) aGraphicDriver = new OpenGl_GraphicDriver (GetDisplayConnection());
2571// create a viewer
2572TCollection_ExtendedString aName ("3DV");
2573myViewer = new V3d_Viewer (aGraphicDriver,aName.ToExtString(), "");
2574// set parameters for V3d_Viewer
2575// defines default lights -
2576// positional-light 0.3 0.0 0.0
2577// directional-light V3d_XnegYposZpos
2578// directional-light V3d_XnegYneg
2579// ambient-light
2581// activates all the lights defined in this viewer
2583// set background color to black
2584a3DViewer->SetDefaultBackgroundColor (Quantity_NOC_BLACK);
2588@subsubsection occt_visu_4_5_3 Create a 3D view (a Windows example)
2590It is assumed that a valid Windows window may already be accessed via the method *GetSafeHwnd()*.
2592Handle (WNT_Window) aWNTWindow = new WNT_Window (GetSafeHwnd());
2593myView = myViewer->CreateView();
2594myView->SetWindow (aWNTWindow);
2597@subsubsection occt_visu_4_5_4 Create an interactive context
2600myAISContext = new AIS_InteractiveContext (myViewer);
2603You are now able to display interactive objects such as an *AIS_Shape*.
2606TopoDS_Shape aShape = BRepAPI_MakeBox (10, 20, 30).Solid();
2607Handle(AIS_Shape) anAISShape = new AIS_Shape(aShape);
2608myAISContext->Display (anAISShape);
2683e647 2611@subsubsection occt_visu_4_5_5 Create your own interactive object
18006a0f 2612
2613Follow the procedure below to compute the presentable object:
67d7f07f 26151. Build a presentable object inheriting from *AIS_InteractiveObject* (refer to the Chapter on @ref occt_visu_2_1 "Presentable Objects").
18006a0f 26162. Reuse the *Prs3d_Presentation* provided as an argument of the compute methods.
2618**Note** that there are two compute methods: one for a standard representation, and the other for a degenerated representation, i.e. in hidden line removal and wireframe modes.
2621Let us look at the example of compute methods
2626 (const Handle(PrsMgr_PresentationManager3d)& thePrsManager,
2627 const Handle(Prs3d_Presentation)& thePrs,
2628 const Standard_Integer theMode)
2630 //...
2634myPresentableObject::Compute (const Handle(Prs3d_Projector)& ,
2635 const Handle(Prs3d_Presentation)& thePrs)
2637 //...
2641@subsubsection occt_visu_4_5_6 Create primitives in the inte