8fd3d17c224e2b1c9686f68d2d122ac37eda1d33
[occt.git] / dox / user_guides / visualization / visualization.md
1 Visualization    {#occt_user_guides__visualization}
2 ========================
3 @tableofcontents 
4
5 @section occt_visu_1 Introduction
6
7 Visualization in Open CASCADE Technology is based on the  separation of:
8   * on the one hand -- the data which stores the geometry and topology  of the entities you want to display and select, and 
9   * on the other hand -- its **presentation** (what you see  when an object is displayed in a scene) and **selection** (possibility to choose the whole object or its sub-parts interactively to apply application-defined operations to the selected entities). 
10
11 Presentations are managed through the **Presentation** component, and selection through the **Selection** component.
12
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.
14
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.  
16
17 If, however, you require types of interactive objects and  filters other than those provided, you will need to know the mechanics of  presentable and selectable objects, specifically how to implement their virtual  functions. To do this requires familiarity with such fundamental concepts as the sensitive primitive and the presentable object.  
18
19 The the following packages are used to display 3D objects:
20   * *AIS*; 
21   * *StdPrs*; 
22   * *Prs3d*; 
23   * *PrsMgr*; 
24   * *V3d*; 
25   * *Graphic3d*.
26
27 The packages used to display 3D objects are also applicable for visualization of 2D objects.
28
29 The figure below presents a schematic overview of the relations between the key concepts and packages in visualization. Naturally, "Geometry & Topology" is just an example of application data that can be handled by *AIS*, and application-specific interactive objects can deal with any  kind of data. 
30
31 @image html visualization_image003.png "Key concepts and packages in visualization"
32 @image latex visualization_image003.png "Key concepts and packages in visualization"
33
34 To answer different needs of CASCADE users, this User's Guide offers the following three paths in reading it.
35   
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".   
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.
38  
39 For advanced information on visualization algorithms, see our <a href="http://www.opencascade.com/content/tutorial-learning">E-learning & Training</a> offerings.  
40
41 @section occt_visu_2  Fundamental Concepts
42
43 @subsection occt_visu_2_1 Presentation 
44
45 In Open CASCADE Technology, presentation services are  separated from the data, which they represent, which is generated by  applicative algorithms.  This division allows you to modify a geometric or topological   algorithm and its resulting objects without modifying the visualization  services.  
46
47 @subsubsection occt_visu_2_1_1 Structure of  the Presentation
48
49 Displaying an object on the screen involves three kinds of entities:
50   * a presentable object, the *AIS_InteractiveObject*
51   * a viewer 
52   * an interactive context, the *AIS_InteractiveContext*. 
53
54 <h4>The presentable object</h4>
55 The purpose of a presentable object is to provide the  graphical representation of an object in the form of *Graphic3d* structure. On  the first display request, it creates this structure by calling the appropriate  algorithm and retaining this framework for further display.  
56
57 Standard presentation algorithms are provided in the *StdPrs*  and *Prs3d* packages. You can, however, write specific presentation algorithms of  your own, provided that they create presentations made of structures from the *Graphic3d* packages. You can also create several presentations of a single  presentable object: one for each visualization mode supported by your  application.  
58
59 Each object to be presented individually must be presentable  or associated with a presentable object. 
60
61 <h4>The viewer </h4>
62 The viewer allows interactively manipulating views of the object. When you zoom, translate or rotate a view, the viewer operates on  the graphic structure created by the presentable object and not on the data  model of the application. Creating Graphic3d structures in your presentation  algorithms allows you to use the 3D viewers provided in Open CASCADE Technology for 3D visualisation.  
63
64 <h4>The Interactive Context </h4>
65 The  interactive context controls the entire presentation process from a common  high-level API. When the application requests the display of an object, the  interactive context requests the graphic structure from the presentable object  and sends it to the viewer for displaying. 
66
67 @subsubsection occt_visu_2_1_2 Presentation packages
68
69 Presentation involves at least the *AIS, PrsMgr, StdPrs* and  *V3d* packages. Additional packages, such as *Prs3d* and *Graphic3d* may be used if  you need to implement your own presentation algorithms.  
70
71 * *AIS* package provides all  classes to implement interactive objects (presentable and selectable entities).  
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.
76 * *Graphic3d* package provides resources to create 3D graphic structures.
77 * *Visual3d* package contains classes implementing commands for 3D viewer.
78 * *DsgPrs* package provides tools for display of dimensions, relations and XYZ trihedrons.
79
80 @subsubsection occt_visu_2_1_3 A Basic Example: How to display a 3D object 
81
82 ~~~~~
83 Void Standard_Real dx  = ...; //Parameters   
84 Void Standard_Real dy  = ...; //to build  a wedge  
85 Void Standard_Real dz  = ...;  
86 Void Standard_Real ltx = ...; 
87
88 Handle(V3d_Viewer)aViewer = ...;  
89 Handle(AIS_InteractiveContext)aContext;  
90 aContext = new AIS_InteractiveContext(aViewer);     
91
92 BRepPrimAPI_MakeWedge w(dx, dy, dz, ltx);  
93 TopoDS_Solid & = w.Solid();  
94 Handle(AIS_Shape) anAis = new AIS_Shape(S);  
95 //creation of the presentable  object  
96 aContext -> Display(anAis);  
97 //Display the presentable  object in the 3d viewer. 
98 ~~~~~
99
100 The shape is created using the *BRepPrimAPI_MakeWedge*  command. An *AIS_Shape* is then created from the shape. When calling the *Display* command, the interactive context calls the Compute method of the  presentable object to calculate the presentation data and transfer it to the  viewer. See figure below.  
101
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"
104
105 @subsection occt_visu_2_2 Selection 
106
107 Objects that may be selected graphically, are displayed as sets of sensitive primitives, which provide sensitive zones in 2D graphic space. These zones are sorted according to their position on the screen when starting the selection process.  
108   
109 @image html visualization_image006.png "A model"
110 @image latex visualization_image006.png "A model"
111
112 The position of the mouse is also associated with a sensitive zone. When moving within the window where objects are displayed, the areas touched by the zone of the mouse are analyzed. The owners of these areas  are then highlighted or signaled by other means such as the name of the object highlighted in a list. That way, you are informed of the identity of the detected element.  
113
114 @image html visualization_image007.png "Modeling faces with sensitive primitives"
115 @image latex visualization_image007.png "Modeling faces with sensitive primitives"
116
117 @image html visualization_image008.png "In a dynamic selection, each sensitive polygon is represented by its  bounding rectangle"   
118 @image latex visualization_image008.png "In a dynamic selection, each sensitive polygon is represented by its  bounding rectangle"
119
120 @image html visualization_image009.png "Reference to the sensitive primitive, then to the owner"
121 @image latex visualization_image009.png "Reference to the sensitive primitive, then to the owner"
122
123
124 @subsubsection occt_visu_2_2_1 The Sensitive Primitive
125
126 The sensitive primitive along with the entity owner allows defining what can be made selectable, and providing the link between the applicative object and the sensitive zones defined by the 2D bounding boxes. To be dynamically selectable, an object has to be  represented either as a sensitive primitive or a set of them, e.g. 2D  boxes that will be included in a sorting algorithm.
127
128 The use of 2D boxes allows a pre-selection of the detected  entities. After pre-selection, the algorithm checks which sensitive primitives are actually detected. When detected, the primitives provide their owners' identity.
129
130 @image html visualization_image010.png "Example of sensitive primitives"
131 @image latex visualization_image010.png "Example of sensitive primitives"
132
133 In the example, the sensitive line segment proposes a bounding box to the selector. During selection, positions 1 and 2 of the mouse detect the box  but after sorting, only position 2 retains the line segment as selected by the  algorithm.  
134
135 When the Box associated with the position of the mouse intersects the Box of a sensitive primitive, the owner of the sensitive  primitive is called and its presentation is highlighted.  
136
137 The notion of sensitive primitive is important for the developer when defining his own classes of sensitive primitives for the chosen selection modes. The classes must contain *Areas* and *Matches*  functions. 
138
139 The former provides the list of 2D sensitive boxes representing the sensitive primitive at pre-selection and the latter determines if the detection of the primitive by the 2D boxes is valid. 
140
141
142 @subsubsection occt_visu_2_2_2 Dynamic Selection 
143
144 Dynamic selection causes objects in a view to be  automatically highlighted 
145 as the mouse cursor moves over them. This allows the  user to be certain that the picked object
146  is the correct one. Dynamic Selection  is based on the following two concepts:  
147
148   * a Selectable Object (*AIS_InteractiveObject*) 
149   * an Interactive Context
150   
151 <h4>Selectable Object</h4>
152
153 A selectable object presents a given number of selection  modes which can be redefined, and which will be activated or deactivated in the selection manager's selectors.  
154
155 Note that the selection mode of a selectable object, can refer to the selection mode of  the object itself or to the selection mode of its part.
156
157 For each selection mode, a *SelectMgr_Selection* object  class is included in the selectable object. (Each selection mode establishes a  priority of selection for each class of selectable object defined.)  
158
159 The notion of **Selection** is comparable to the notion of **Display**.  Just as a display contains a set of graphic primitives that allow display of  the entity in a specific display mode, a **Selection** contains a set of sensitive  primitives, which allow detection of the entities they are associated with.  
160
161 <h4>Interactive Context</h4>
162
163 The interactive context is used to manage both selectable  objects and selection processes.  
164
165 Selection modes may be activated or de-activated for given  selectable objects. Information is then provided about the status of  activated/de-activated selection modes for a given object in a given selector. 
166
167 See also @ref occt_visu_3 "AIS: Application Interactive Services".
168
169 Let us consider, for example, a 3D selectable shape object, which  corresponds to a topological shape.  
170
171 For this class, seven selection modes can be defined:  
172 * mode 0 - selection of the shape itself 
173 * mode 1 - selection of vertices  
174 * mode 2 - selection of edges  
175 * mode 3 - selection of wires  
176 * mode 4 - selection of faces  
177 * mode 5 - selection of shells  
178 * mode 6 - selection of solids  
179 * mode 7 - selection of compsolids 
180 * mode 8 - selection of compounds  
181
182 Selection 2 includes the sensitive primitives that model all  the edges of the shape. Each of these primitives contains a reference to the  edge it represents.  
183
184 The selections may be calculated before any activation and  are graph independent as long as they are not activated in a given selector.  Activation of selection mode 3 in a selector associated with a view V leads to  the projection of the 3D sensitive primitives contained in the selection; then  the 2D areas which represent the 2D bounding boxes of these primitives are  provided to the sorting process of the selector containing all the detectable  areas.  
185
186 To deactivate selection mode 3 remove all those 2D areas. 
187
188
189 @subsubsection occt_visu_2_2_3  Selection Packages
190
191 Selection of 3D data structures is provided using various algorithms. The following selection packages exist : *SelectBasics*,  *SelectMgr*, *Select3D* and *StdSelect*.
192
193 ### Basic Selection
194
195 *SelectBasics* package contains the basic classes  of the selection:  
196   * the main definition of a sensitive primitive: *SensitiveEntity*, which is a selectable entity in a view;
197   * the definition of a sensitive primitive owner: *EntityOwner* this entity relates the primitive to the application entity which is to be selected in the view.
198   * the algorithm used for sorting sensitive boxes: *SortAlgo* 
199
200 *EntityOwner* is used to establish a link from *SensitiveEntity*  to application-level objects. For example, *SelectMgr_EntityOwner* (see  below) class holds a pointer to corresponding *SelectableObject*. 
201
202 ### Standard Selections
203
204 *Select3D* package provides definition of all 3D standard sensitive primitives such as point, curve and face. All these classes inherit from 3D *SensitiveEntry* from *SelectBasics* with an additional method, which allows recovery of the bounding boxes in the 2D graphic selection space, if required. This package also includes the 3D-2D projector.
205
206 *StdSelect* package provides standard uses of the classes described above and main tools used to prevent the developer from redefining the selection objects. In particular, *StdSelect* includes standard modes for selection of topological shapes, definition of several filter standard <i> Selection2d.ap </i> classes and 3D viewer selectors.
207
208 Note that each new Interactive Object must have all its selection modes defined.
209
210 ### Selection Management
211
212 *SelectMgr* package is used to manage the whole dynamic selection process.
213
214 It provides low level services and classes *SelectMgr_SelectionManager* and *SelectMgr_ViewerSelector*. They can be used when you do not want to use the services provided by *AIS*.
215
216 There are also implementations of *ViewerSelector*  interface for 3D selection in *StdSelect* package: *ViewerSelector3d*. 
217
218 *SelectMgr* manages the process of dynamic selection through the following services:
219
220   * Activating and deactivating selection modes for Interactive Objects.
221   * Adding and removing viewer selectors.
222   * Definitions of abstract filter classes.
223
224 The principle of graphic selection consists in representing the objects which you want to select by a bounding box in the selection view.
225 The object is selected when you use the mouse to designate the zone produced by the object.
226
227 To realize this, the application creates a selection structure which is independent of the point of view.
228 This structure is made up of sensitive primitives which have one owner object associated to each of them.
229 The role of the sensitive primitive is to reply to the requests of the selection algorithm whereas the owner's purpose is to make the link between the sensitive primitive and the object to be selected.
230 Each selection structure corresponds to a selection mode which defines the elements that can be selected.
231
232 ### Example: Selection of a Geometric Model
233
234 For example, to select a complete geometric model, the application can create a sensitive primitive for each face of the interactive object representing the geometric model.
235 In this case, all the primitives share the same owner.
236 On the other hand, to select an edge in a model, the application must create one sensitive primitive per edge.
237
238 ~~~~
239
240 void InteractiveBox::ComputeSelection (const Handle(SelectMgr_Selection)& theSel,
241                                        const Standard_Integer theMode)
242 {
243 switch (theMode)
244 {
245   case 0: // locating the whole box by making its faces sensitive
246   {
247     Handle(SelectMgr_EntityOwner) anOwner = new SelectMgr_EntityOwner (this, 5);
248     for (Standard_Integer anIt = 1; anIt <= aFacesNb; anIt++)
249     {
250       theSel->Add (new Select3D_SensitiveFace (anOwner,[array of the vertices] face I);
251       break;
252     }
253   case 1: // locating the edges
254   {
255     for (Standard_Integer anIt = 1; anIt <= 12; anIt++)
256     {
257       // 1 owner per edge
258       Handle(mypk_EdgeOwner) anOwner = new mypk_EdgeOwner (this, anIt, 6); // 6->priority
259       theSel->Add (new Select3D_SensitiveSegment (anOwner, firstpt (anIt), lastpt (anIt));
260     }
261   }
262 }
263
264 ~~~~
265
266 The algorithms for creating selection structures store the sensitive primitives in a <i>SelectMgr_Selection</i> object.
267 To do this, a set of ready-made sensitive primitives is supplied in the <i>Select3D</i>package.
268 New sensitive primitives can be defined through inheritance from <i>SensitiveEntity</i>.
269 For the application to make its own objects selectable, it must define owner classes inheriting <i>SelectMgr_EntityOwner</i>.
270
271 Selection structures for any interactive object are generated in <i>ComputeSelection()</i> method.
272 In the example below there are different modes of selection on the topological shape contained within the interactive object,
273 selection of the shape itself, the vertices, the edges, the wires, the faces.
274
275 ~~~~
276   void MyPack_MyClass::ComputeSelection(
277                 const Handle(SelectMgr_Selection)& theaSelection,
278                 const Standard_Integer theMode)
279   {
280     switch (theMode)
281     {
282       case 0:
283         StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_SHAPE);
284         break;
285       case 1:
286         StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_VERTEX);
287         break;
288       case 2:
289         StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_EDGE);
290         break;
291       case 3:
292         StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_WIRE);
293         break;
294       case 4:
295         StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_FACE);
296         break;
297     }
298   }
299 ~~~~
300
301 The <i>StdSelect_BRepSelectionTool</i> object provides a high level service which will make the topological shape <i>myShape</i> selectable when the <i>AIS_InteractiveContext</i> is asked to display your object.
302
303 Note:
304
305 The traditional way of highlighting selected entity owners adopted by Open CASCADE Technology assumes that each entity owner highlights itself on its own. This approach has two drawbacks:
306
307   * Each entity owner has to maintain its own <i>Prs3d_Presentation object</i>, that results in large memory overhead for thousands of owners.
308   * Drawing selected owners one by one is not efficient from the OpenGL usage viewpoint.
309
310 That is why a different method has been introduced.
311 On the basis of <i>SelectMgr_EntityOwner::IsAutoHilight()</i> return value <i>AIS_LocalContext</i>
312 object either uses the traditional way of highlighting (<i>IsAutoHilight()</i> returned true)
313 or groups such owners according to their Selectable Objects and finally calls <i> SelectMgr_SelectableObject::HilightSelected()</i> or
314 <i>ClearSelected()</i>, passing a group of owners as an argument.
315
316 Hence, an application can derive its own interactive object and redefine <i> HilightSelected()</i>,
317 <i>ClearSelected()</i> and <i>HilightOwnerWithColor()</i> virtual methods
318 to take advantage of such OpenGL technique as arrays of primitives.
319 In any case, these methods should at least have empty implementation.
320
321 The <i>AIS_LocalContext::UpdateSelected (const Handle(AIS_InteratciveObject)&, Standard_Boolean)</i>
322 method can be used for efficient redrawing a selection presentation for a given interactive object from an application code.
323
324 Additionally, the <i>SelectMgr_SelectableObject::ClearSelections()</i> method now accepts an optional Boolean argument.
325 This parameter defines whether all object selections should be flagged for further update or not.
326 This improved method can be used to re-compute an object selection (without redisplaying the object completely)
327 when some selection mode is activated not for the first time.
328
329 @subsubsection occt_visu_2_2_4 How to use dynamic selection
330
331 Several operations must be performed prior to using dynamic  selection:  
332 1. Implement specific sensitive primitives  if those defined in Select3D are not sufficient. These primitives must inherit  from *SensitiveEntity* from *SelectBasics* or from a suitable Select3D  sensitive entity class when a projection from 3D to 2D is necessary.  
333 2. Define all the owner types, which will  be used, and the classes of selectable objects, i.e. the number of possible  selection modes for these objects and the calculation of the decomposition of  the object into sensitive primitives of all the primitives describing this  mode. It is possible to define only one default selection mode for a selectable  object if this object is to be selectable in a unique way.  
334 3. Install the process, which provides the  user with the identity of the owner of the detected entities in the selection  loop.  
335
336 When all these steps have been carried out, follow the  procedure below:  
337 1. Create an interactive context.  
338 2. Create the selectable objects and  calculate their various possible selections.  
339 3. Load these selectable objects in the  interactive context. The objects may be common to all the selectors, i.e. they  will be seen by all the selectors in the selection manager, or local to one  selector or more.  
340 4. Activate or deactivate the objects' selection modes in  the selector(s). When activating a selection mode in a selector for a given  object, the manager sends the order to make the sensitive primitives in this  selector selectable. If the primitives are to projected from 3D to 2D, the  selector calls the specific method used to carry out this projection.  
341
342 At this stage, the selection of selectable entities in the  selectors is available.  
343 The selection loop informs constantly the selectors with the  position of the mouse and questions them about the detected entities.  
344
345 Let us suppose that you create an application that displays  houses in a viewer of the V3d package and you want to select houses or parts of  these houses (windows, doors, etc.) in the graphic window.  
346 You define a selectable object called *House* and  propose four possible selection modes for this object:  
347 1. selection of the house itself; 
348 2. selection of the rooms  
349 3. selection of the walls  
350 4. selection of the doors.  
351
352 You have to write the method, which calculates the four  selections above, i.e. the sensitive primitives which are activated when the  mode is.  
353 You must define the class *Owner* specific to your  application. This class will contain the reference to the house element it  represents: wall, door or room. It inherits from *EntityOwner* from *SelectMgr*.   
354 For example, let us consider a house with the following  representation:  
355
356 @image html visualization_image011.png "Selection of rooms in a house"
357 @image latex visualization_image011.png "Selection of rooms in a house"
358
359 To build the selection, which corresponds to the mode "selection  of the rooms" 
360 (selection 2 in the list of selection modes), use the following  procedure:  
361
362 ~~~~~
363
364 Void House::ComputeSelection 
365         (Const  Handle(SelectMgr_Selection)& Sel, 
366          const Standard_Integer mode { 
367                  switch(mode){   
368                 case 0: //Selection of the rooms  
369                 {   
370                 for(Standard_Integer i = 1; i <= myNbRooms; i++)   
371                 { 
372                 //for every room, create an instance of the owner, the given room  and its name. 
373                 Handle(RoomOwner) aRoomOwner = new RoomOwner (Room(i),  NameRoom(i)); 
374                 //Room() returns a room and NameRoom() returns its name.  
375         Handle(Select3d_SensitiveBox) aSensitiveBox; 
376         aSensitiveBox = new Select3d_SensitiveBox  
377                 (aRoomOwner, Xmin, Ymin, Zmin,  Xmax, Ymax, Zmax); 
378                  Sel -> Add(aSensitiveBox);   
379                 }   
380                 break;   
381                 Case 1: ... //Selection of the doors   
382                 } //Switch     
383 ) // ComputeSelection  
384 ~~~~~
385
386 @image html visualization_image012.png "Activated sensitive boxes  corresponding to selection mode 0 (selection of rooms)"
387 @image latex visualization_image012.png "Activated sensitive boxes  corresponding to selection mode 0 (selection of rooms)"
388
389 @image html visualization_image013.png "Activated sensitive rectangles in the selector during dynamic selection in view 1"
390 @image latex visualization_image013.png "Activated sensitive rectangles in the selector during dynamic selection in view 1"
391
392 @image html visualization_image014.png "Activated sensitive polygons corresponding  to selection mode 1 (selection of doors)"
393 @image latex visualization_image014.png "Activated sensitive polygons corresponding  to selection mode 1 (selection of doors)"
394
395 @image html visualization_image015.png "Sensitive rectangles in the selector during  dynamic selection in view 2"
396 @image latex visualization_image015.png "Sensitive rectangles in the selector during  dynamic selection in view 2"
397
398 @section occt_visu_3 Application Interactive Services 
399 @subsection occt_visu_3_1 Introduction 
400
401 Application Interactive Services allow managing presentations and dynamic selection in a viewer in a simple and  transparent manner. 
402
403 The central entity for management of visualization and selections is the **Interactive Context**. It is connected to the main viewer (and if  need be, the trash bin viewer). It has two operating modes: the Neutral Point and  the local visualization and selection context. 
404
405 The neutral point, which is the  default mode, allows easily visualizing and selecting interactive objects loaded into the context. 
406
407 **Local Contexts** can be opened to prepare and use a temporary selection environment without disturbing
408 the neutral point. It is possible to choose the interactive objects, which you want to act on, the selection modes, which you want to activate, and the temporary visualizations, which you will execute. 
409
410 When the operation is finished, you close the current local context and return to the state 
411 in which you were before opening it (neutral point or previous local context).  
412
413 **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.  
414
415 @image html visualization_image016.png 
416 @image latex visualization_image016.png 
417
418 An Interactive Object is a "virtual" entity, which can be  presented and selected. An Interactive Object can have a certain number of specific graphic attributes, such as visualization mode, color and  material. 
419
420 When an Interactive Object is visualized, the required graphic attributes are taken from its own **Drawer** if it has the required custom attributes or otherwise from the context drawer. 
421
422 @image html visualization_image017.png 
423 @image latex visualization_image017.png 
424
425 It can be necessary to filter the entities to be selected. Consequently there are **Filter** entities, which allow refining the dynamic detection context.  Some of these filters can be used at the Neutral Point, others only in an open local context. It is possible to program custom filters and load them into the interactive context.  
426
427 @subsection occt_visu_3_2 Interactive objects
428
429 Entities which are visualized and selected in the AIS viewer are objects. They connect the underlying reference geometry of a model to its graphic representation in *AIS*. You can use the predefined OCCT classes of standard interactive objects, for which all necessary functions have already been programmed, or, if you are an advanced user, you can implement your own classes of interactive objects.
430
431 @subsubsection occt_visu_3_2_1 Presentations
432
433 An interactive object can have as many  presentations as its creator wants to give it. 
434
435 3D presentations are managed by PresentationManager3D. As this is  transparent in AIS, the user does not have to worry about it. 
436
437 A presentation is identified by an index and by the reference to  the Presentation Manager which it depends on. 
438
439 By convention, the default mode of  representation for the Interactive Object has index 0. 
440
441 @image html visualization_image018.png 
442 @image latex visualization_image018.png 
443
444 Calculation of different presentations of an interactive  object is done by the *Compute* functions inheriting from *PrsMgr_  PresentableObject::Compute* functions. They are automatically called by *PresentationManager*  at a visualization or an update request.  
445
446 If you are creating your own type of interactive object, you  must implement the Compute function in one of the following ways:  
447
448 #### For 3D:
449
450 ~~~~~
451 void PackageName_ClassName::Compute  
452         (const  Handle(PrsMgr_PresentationManager3d)& aPresentationManager,   
453          const  Handle(Prs3d_Presentation)& aPresentation,  
454          const Standard_Integer aMode =  0);  
455 ~~~~~
456
457 ####  For hidden line removal (HLR) mode in 3D:
458 ~~~~~
459 void PackageName_ClassName::Compute  
460         (const  Handle(Prs3d_Projector)& aProjector,  
461          const  Handle(Prs3d_Presentation)& aPresentation);  
462 ~~~~~
463
464 @subsubsection occt_visu_3_2_2 Hidden Line Removal
465
466 The view can have two states: the normal mode or the computed  mode (Hidden Line Removal mode). When the latter is active, the view looks for all presentations displayed in the normal mode, which have been signalled  as accepting HLR mode. An internal mechanism allows calling the interactive  object's own *Compute*, that is projector function. 
467
468 By  convention, the Interactive Object accepts or rejects the  representation of HLR mode. It is possible to make this declaration in one of two ways:
469
470 * Initially by using one of the values of the enumeration  *PrsMgr_TypeOfPresentation*: 
471   * *PrsMgr_TOP_AllView*,
472   * *PrsMgr_TOP_ProjectorDependant*
473
474 * Later by using the function *PrsMgr_PresentableObject::SetTypeOfPresentation* 
475
476 *AIS_Shape* class is an example of an interactive object that supports  HLR representation. It supports two types of the HLR algorithm:  
477 * the  polygonal algorithm based on the shape's triangulation; 
478 * the  exact algorithm that works with the shape's real geometry. 
479
480 The 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: 
481         * *Prs3d_TOH_PolyAlgo* for a polygonal algorithm; 
482         * *Prs3d_TOH_Algo*  for an exact algorithm; 
483         * *Prs3d_TOH_NotSet*  if the type of algorithm is not set for the given interactive object instance. 
484
485 The type of the HLR algorithm used for *AIS_Shape* can be changed by calling the *AIS_Shape::SetTypeOfHLR()* method. 
486
487 The current  HLR algorithm type can be obtained using *AIS_Shape::TypeOfHLR()* method  is to be used. 
488
489 These methods get the  value from the drawer of *AIS_Shape*. If the HLR algorithm type in the *AIS_Drawer* is set to *Prs3d_TOH_NotSet*, the *AIS_Drawer* gets the value from the default  drawer of *AIS_InteractiveContext*.
490
491 So it is possible to change the default HLR algorithm used by all newly displayed interactive objects. The  value of the HLR algorithm type stored in the context drawer can be *Prs3d_TOH_Algo* or *Prs3d_TOH_PolyAlgo*. The polygonal algorithm is the default one. 
492
493 @subsubsection occt_visu_3_2_3 Presentation modes
494
495 There are four types of interactive objects in AIS:  
496   * the "construction element" or Datum, 
497   * the Relation (dimensions and constraints) 
498   * the Object 
499   * the None type (when the object is  of an unknown type). 
500
501 Inside these categories, additional characterization is  available by means of a signature (an index.) By default, the interactive  object has a NONE type and a signature of 0 (equivalent to NONE.) If you want  to give a particular type and signature to your interactive object, you must  redefine two virtual functions:  
502   * *AIS_InteractiveObject::Type*  
503   * *AIS_InteractiveObject::Signature*.  
504
505 **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".  
506
507 The interactive context can have a  default mode of representation for the set of interactive objects. This mode  may not be accepted by a given class of objects. 
508
509 Consequently, to get information about this class it is necessary to use virtual  function *AIS_InteractiveObject::AcceptDisplayMode*.  
510
511 #### Display Mode
512
513 The functions *AIS_InteractiveContext::SetDisplayMode* and *AIS_InteractiveContext::UnsetDisplayMode* allow setting a custom display mode for an objects, which can be different from that proposed by the interactive context.
514
515 #### Highlight Mode
516
517 At dynamic detection, the presentation echoed  by the Interactive Context, is by default the presentation already on the screen. 
518
519 The functions  *AIS_InteractiveObject::SetHilightMode* and *AIS_InteractiveObject::UnSetHilightMode* allow specifying the display mode used for highlighting (so called highlight mode), which is valid independently from the active  representation of the object. It makes no difference whether this choice is  temporary or definitive. 
520
521 Note that the same presentation (and consequently the same  highlight mode) is used for highlighting *detected* objects and for  highlighting *selected* objects, the latter being drawn with a special *selection  color* (refer to the section related to *Interactive Context*  services). 
522
523 For example, you want to systematically highlight  the wireframe presentation of a shape - non regarding if it is visualized in  wireframe presentation or with shading. Thus, you set the highlight mode to *0* in the constructor of the interactive object. Do not forget to implement this representation mode in the *Compute* functions.  
524
525 #### Infinite Status
526 If you do not want an object to be affected  by a *FitAll* view, you must declare it infinite; you can cancel its "infinite"  status using *AIS_InteractiveObject::SetInfiniteState* and *AIS_InteractiveObject::IsInfinite* functions. 
527
528 Let us take for example the class called *IShape* representing  an interactive object :
529
530 ~~~~~ 
531 myPk_IShape::myPK_IShape  
532         (const TopoDS_Shape& SH,  PrsMgr_TypeOfPresentation aType):  
533         AIS_InteractiveObject(aType), myShape(SH), myDrwr(new AIS_Drawer())  {SetHilightMode(0);}   
534 void myPk_IShape::Compute  
535         (const Handle(PrsMgr_PresentationManager3d)  & PM,  
536          const Handle(Prs3d_Presentation)& P,   
537          const Standard_Integer TheMode) 
538
539         switch (TheMode){  
540         case 0: 
541         StdPrs_WFDeflectionShape::Add  (P,myShape,myDrwr);  //algo for  calculation of wireframe presentation break;  
542         case 1: 
543         StdPrs_ShadedShape::Add  (P,myShape,myDrwr);   //algo for calculation of shading presentation.  
544         break; 
545         }  
546 }  
547 void myPk_IsShape::Compute  
548         (const  Handle(Prs3d_Projector)& Prj,  
549         const  Handle(Prs3d_Presentation) P)  
550
551         StdPrs_HLRPolyShape::Add(P,myShape,myDrwr); 
552         //Hidden line mode calculation algorithm  
553 }  
554 ~~~~~
555
556 @subsubsection occt_visu_3_2_4 Selection 
557
558 An interactive object can have an indefinite number of selection modes, each representing a "decomposition" into sensitive primitives;  each primitive has an Owner (*SelectMgr_EntityOwner*) which allows identifying the exact entity which has been detected (see ref occt_visu_3_6 "Dynamic Selection" chapter).  
559
560 The set of sensitive primitives, which correspond to a given  mode, is stocked in a SELECTION (*SelectMgr_Selection*). 
561
562 Each Selection mode is identified by an index. By  Convention, the default selection mode that allows us to grasp the Interactive  object in its entirety is mode *0*.  
563
564 The calculation of Selection primitives (or sensitive  primitives) is done by the intermediary of a virtual function, *ComputeSelection*.  This should be implemented for each type of interactive object on which you  want to make different type selections using the function *AIS_ConnectedInteractive::ComputeSelection*.  
565
566 A detailed explanation of the mechanism and the manner of  implementing this function has been given in @ref occt_visu_3_6 "Dynamic Selection" chapter.  
567
568 Moreover, just as the most frequently manipulated entity is *TopoDS_Shape*, the most used Interactive Object is *AIS_Shape*. You will see below activation functions for standard selection modes are proposed in the  Interactive context (selection by vertex, by edges etc). To create new classes  of interactive object with the same behavior as *AIS_Shape* -- such as vertices  and edges -- you must redefine the virtual function *AIS_ConnectedInteractive::AcceptShapeDecomposition*.  
569
570 You can change the default selection mode index of an  Interactive Object using the following functions: 
571   * *AIS_InteractiveObject::HasSelectionMode* checks if there is a selection mode; 
572   * *AIS_InteractiveObject::SelectionMode* check the current selection mode; 
573   * *AIS_InteractiveContext::SetSelectionMode* sets a selection mode; 
574   * *AIS_InteractiveContext::UnsetSelectionMode* unsets a selection mode.
575   
576 These functions can be useful if you decide that the *0*  mode used by default will not do. In the same way, you can temporarily  change the priority of certain interactive objects for selection of 0 mode to facilitate detecting them graphically using the following functions: 
577   * *AIS_InteractiveObject::HasSelectionPriority* checks if there is a selection priority setting for the  owner; 
578   * *AIS_InteractiveObject::SelectionPriority* checks the current priority; 
579   * *AIS_InteractiveObject::SetSelectionPriority* sets a priority; 
580   * *AIS_InteractiveObject::UnsetSelectionPriority* unsets the priority.
581   
582     
583 @subsubsection occt_visu_3_2_5 Graphic attributes
584
585 Graphic attributes manager, or *AIS Drawer*, stores graphic attributes for specific interactive objects and for interactive objects controlled by interactive context.
586
587 Initially, all drawer attributes are filled out with the predefined values which will define the default 3D object appearance.
588
589 When an interactive object is visualized, the required graphic attributes are first taken from its own drawer if one exists, or from the context drawer if no specific drawer for that type of object exists.
590
591 Keep in mind the following points concerning graphic attributes:
592   * Each interactive object can have its own visualization  attributes.
593   * 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 
594   * 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.) 
595   * 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. 
596
597 @image html visualization_image019.png "Figure 13. Redefinition of virtual functions for changes in AIS_Point"
598 @image latex visualization_image019.png "Figure 13. Redefinition of virtual functions for changes in AIS_Point"
599
600 @image html visualization_image020.png "Figure 14. Redefinition of virtual functions for changes in AIS_Shape."
601 @image latex visualization_image020.png "Figure 14. Redefinition of virtual functions for changes in AIS_Shape."
602
603 The  following virtual functions provide settings for color, width, material and transparency:  
604   * *AIS_InteractiveObject::UnsetColor* 
605   * *AIS_InteractiveObject::SetWidth* 
606   * *AIS_InteractiveObject::UnsetWidth* 
607   * *AIS_InteractiveObject::SetMaterial   (const Graphic3d_NameOfPhysicalMaterial & aName)* 
608   * *AIS_InteractiveObject::SetMaterial   (const Graphic3d_MaterialAspect & aMat)* 
609   * *AIS_InteractiveObject::UnsetMaterial* 
610   * *AIS_InteractiveObject::SetTransparency* 
611   * *AIS_InteractiveObject::UnsetTransparency* 
612
613 For other types of attribute, it is  appropriate to change the Drawer of the object directly using:  
614   * *AIS_InteractiveObject::SetAttributes*
615   * *AIS_InteractiveObject::UnsetAttributes*
616
617 It is important to know which functions may imply the recalculation of  presentations of the object. 
618
619 If the presentation mode of an interactive object is to be updated, a flag from *PrsMgr_PresentableObject*  indicates this. 
620
621 The mode can be updated using the functions *Display*  and *Redisplay* in *AIS_InteractiveContext*.  
622
623 @subsubsection occt_visu_3_2_6 Complementary  Services
624
625 When you use complementary services for interactive objects, pay special attention to the cases mentioned below. 
626
627 #### Change the location of an interactive object
628
629 The following functions  allow temporarily "moving" the representation and selection of  Interactive Objects in a view without recalculation.  
630   * *AIS_InteractiveContext::SetLocation*  
631   * *AIS_InteractiveContext::ResetLocation*  
632   * *AIS_InteractiveContext::HasLocation*  
633   * *AIS_InteractiveContext::Location*  
634  
635 #### Connect an interactive object to an applicative  entity
636
637 Each Interactive Object has functions that allow attributing it an *Owner* in form of a *Transient*.  
638   * *AIS_InteractiveObject::SetOwner*  
639   * *AIS_InteractiveObject::HasOwner*  
640   * *AIS_InteractiveObject::Owner*  
641
642 An interactive object can therefore be associated or not with an applicative entity, without affecting its behavior. 
643
644 #### Resolving coincident topology
645
646 Due to the fact that the accuracy of three-dimensional  graphics coordinates has a finite resolution the elements of topological  objects can coincide producing the effect of "popping" some elements one over  another. 
647
648 To the problem when the elements of two or  more Interactive Objects are coincident you can apply the polygon offset. It is a  sort of graphics computational offset, or depth buffer offset, that allows you  to arrange elements (by modifying their depth value) without changing their  coordinates. The graphical elements that accept this kind of offsets are solid  polygons or displayed as boundary lines and points. The polygons could be  displayed as lines or points by setting the appropriate interior style. 
649
650 The method *AIS_InteractiveObject::SetPolygonOffsets (const Standard_Integer aMode, const Standard_Real aFactor, const Standard_Real aUnits)* allows setting up the polygon  offsets.
651
652 The  parameter *aMode* can contain various combinations of *Aspect_PolygonOffsetMode* enumeration elements: 
653   * *Aspect_POM_None*
654   * *Aspect_POM_Off*
655   * *Aspect_POM_Fill*
656   * *Aspect_POM_Line*
657   * *Aspect_POM_Point*
658   * *Aspect_POM_All*
659
660 The combination  of these elements defines the polygon display modes that will use the given  offsets. You can switch off the polygon offsets by passing *Aspect_POM_Off*.  Passing *Aspect_POM_None* allows changing the *aFactor* and *aUnits* values  without changing the mode. If *aMode* is different from *Aspect_POM_Off*, the  *aFactor* and *aUnits* arguments are used by the graphics renderer to calculate the  depth offset value: 
661 ~~~~~
662  offset  = aFactor * m + aUnits * r
663 ~~~~~
664 where  *m* is the maximum depth slope for the currently displayed polygons, r is the minimum  depth resolution (implementation-specific). 
665
666 Negative  offset values move polygons closer to the viewer while positive values shift  polygons away. 
667
668 **Warning**
669  
670 This  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. 
671
672 You can use the following  functions to obtain the current settings for polygon offsets: 
673 ~~~~~
674   void  AIS_InteractiveObject::PolygonOffsets
675                 (Standard_Integer &aMode, 
676                  Standard_Real &aFactor, 
677                  Standard_Real &aUnits) 
678   Standard_Boolean AIS_InteractiveObject::HasPolygonOffsets() 
679 ~~~~~
680
681 The same  operation could be performed for the interactive object known by the *AIS_InteractiveContext* with the following methods: 
682 ~~~~~
683 void  AIS_InteractiveContext::SetPolygonOffsets
684         (const Handle(AIS_InteractiveObject) &anObj, 
685          const Standard_Integer aMode,  
686          const Standard_Real aFactor, 
687          const Standard_Real aUnits) 
688 void  AIS_InteractiveContext::PolygonOffsets
689         (const Handle(AIS_InteractiveObject) &anObj, 
690          Standard_Integer &aMode,  
691          Standard_Real &aFactor, 
692          Standard_Real &aUnits) 
693 Standard_Boolean      AIS_InteractiveContext::HasPolygonOffsets
694         (const Handle(AIS_InteractiveObject) &anObj) 
695 ~~~~~
696
697 @subsection occt_visu_3_3 Interactive Context 
698
699 @subsubsection occt_visu_3_3_1 Rules 
700
701 The Interactive Context allows managing in a transparent  way the graphic and **selectable** behavior of interactive objects in one or  more viewers. Most functions which allow modifying the attributes of  interactive objects, and which were presented in the preceding chapter, will be  looked at again here.  
702
703 There is one essential rule to follow: the modification of  an interactive object, which is already known by the Context, must be done  using Context functions. You can only directly call the functions available for  an interactive object if it has not been loaded into an Interactive Context.  
704
705 ~~~~~
706 Handle (AIS_Shape) TheAISShape = new AIS_Shape (ashape);  
707         myIntContext->Display(TheAISShape);  
708         myIntContext->SetDisplayMode(TheAISShape ,1);  
709         myIntContext->SetColor(TheAISShape,Quantity_NOC_RED);  
710 ~~~~~
711
712 You can also write  
713
714 ~~~~~
715 Handle (AIS_Shape) TheAISShape = new AIS_Shape (ashape);  
716         TheAISShape->SetColor(Quantity_NOC_RED);  
717         TheAISShape->SetDisplayMode(1);  
718         myIntContext->Display(TheAISShape);  
719 ~~~~~
720
721 @subsubsection occt_visu_3_3_2 Groups of functions 
722
723 **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.
724
725 The **Neutral Point**, which is the default mode, allows easily visualizing and selecting interactive objects, which have been loaded into the context. Opening **Local contexts** allows preparing and using a temporary selection environment without disturbing the neutral point.
726
727 A set of functions allows choosing the interactive objects which you want to act on, the selection modes which you want to activate, and the temporary visualizations which you will execute. When the operation is finished, you close the current local context and return to the state in which you were before opening it (neutral point or previous local context).
728
729 The Interactive Context is composed of many  functions, which can be conveniently grouped according to the theme:  
730   * management proper to the context; 
731   * management in the local context; 
732   * presentations and selection in open/closed context; 
733   * selection strictly speaking. 
734
735 Some functions can only be used in open Local Context; others in closed local context; others do not have the same behavior in one state as in the other.
736
737 @subsubsection occt_visu_3_3_3 Management of the Interactive Context 
738
739 The **Interactive Context** is made up of a **Principal Viewer** and, optionally, a trash bin or **Collector Viewer**.
740
741 An interactive object can have a certain number of specific graphic attributes, such as visualization mode, color, and material. Correspondingly, the interactive context has a set of graphic attributes, the *Drawer*, which is valid by default for the objects it controls.
742
743 When an interactive object is visualized, the required graphic attributes are first taken from the object's own <i>Drawer</i> if one exists, or from the context drawer for the others.
744
745 The following adjustable settings allow personalizing the behavior of presentations  and selections:
746   * Default Drawer, containing all the color and line attributes  which can be used by interactive objects, which do not have their own attributes.
747   * Default Visualization Mode for interactive objects.  By default: *mode  0* ;  
748   * Highlight color of entities detected by mouse movement. By default: *Quantity_NOC_CYAN1*;  
749   * Pre-selection color. By default:  *Quantity_NOC_GREEN*;  
750   * Selection color (when you click on a detected object). By default:  *Quantity_NOC_GRAY80*;  
751   * Sub-Intensity color. By default: *Quantity_NOC_GRAY40*.
752
753 All of these settings can be modified by functions proper to  the Context.  
754
755 When you change a graphic attribute pertaining to the  Context (visualization mode, for example), all interactive objects, which do  not have the corresponding appropriate attribute, are updated.  
756
757 Let us examine the case of two interactive objects: *obj1* and *obj2*:  
758
759 ~~~~~
760 TheCtx->Display(obj1,Standard_False); // False = no viewer update 
761 TheCtx->Display(obj2,Standard_True); // True = viewer update  
762 TheCtx->SetDisplayMode(obj1,3,Standard_False); 
763 TheCtx->SetDisplayMode(2); 
764 // obj2 is visualised in mode 2 (if it accepts this mode) 
765 // obj1 stays visualised in its mode 3.  
766 ~~~~~
767
768 *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. 
769
770 @subsection occt_visu_3_4 Local Context 
771
772 @subsubsection occt_visu_3_4_1 Rules and Conventions 
773
774   * Opening a local context allows preparing an environment for  temporary presentations and selections, which will disappear once the local  context is closed. 
775   * It is possible to open several local contexts, but only the last  one will be active. 
776   * 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. 
777   * Each local context has an index created when the context opens. You  should close the local context, which you have opened. 
778
779 The interactive object, which is used the most by  applications, is *AIS_Shape*. Consequently, standard functions are  available which allow you to easily prepare selection operations on the  constituent elements of shapes (selection of vertices, edges, faces etc) in an  open local context. The selection modes specific to "Shape" type objects are  called **Standard Activation Mode**. These modes are only taken into account  in open local context and only act on interactive objects which have redefined  the virtual function *AcceptShapeDecomposition()* so that it returns *TRUE*.   
780   * 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. 
781   * The state of a temporary interactive object in a local context  can only be modified while another local context is open. 
782
783 **Warning**
784
785 The specific modes of selection only concern the interactive  objects, which are present in the Main Viewer. In the Collector, you can only  locate interactive objects, which answer positively to the positioned filters  when a local context is open, however, they are never decomposed in  standard mode.  
786
787 @subsubsection occt_visu_3_4_2 Management of Local Context
788
789 The local context can be opened using method *AIS_InteractiveContext::OpenLocalContext*. The following options are available:
790   * *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. 
791   * *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*. 
792   * *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.
793
794 This function returns the index of the created local context.  It should be kept and used when the context is closed.  
795
796 To load objects visualized at Neutral Point into a local  context or remove them from it use methods
797 ~~~~~ 
798   AIS_InteractiveContext::UseDisplayedObjects  
799   AIS_InteractiveContext::NotUseDisplayedObjects  
800 ~~~~~
801 Closing Local Contexts is done by:  
802 ~~~~~
803   AIS_InteractiveContext::CloseLocalContext  
804   AIS_InteractiveContext::CloseAllContexts  
805 ~~~~~
806
807 *Warning* 
808 When the index is not specified in the first function, the  current Context is closed. This option can be dangerous, as other Interactive  Functions can open local contexts without necessarily warning the user. For  greater security, you have to close the context with the index given on  opening. 
809
810 To get the index of the current context, use function *AIS_InteractiveContext::IndexOfCurrentLocal*. It allows closing all open local  contexts at one go. In this case, you find yourself directly at Neutral Point.  
811
812 When you close a local context, all temporary interactive  objects are deleted, all selection modes concerning the context are canceled, and all content filters are emptied.
813
814
815 @subsubsection occt_visu_3_4_3 Presentation in a Neutral Point 
816
817 You must distinguish between the **Neutral Point** and the **Open Local Context** states. Although the majority of visualization  functions can be used in both situations, their behavior is different.
818
819 Neutral Point should be used to visualize the interactive  objects, which represent and select an applicative entity. Visualization and  Erasing orders are straightforward: 
820
821 ~~~~~
822 AIS_InteractiveContext::Display  
823         (const  Handle(AIS_InteractiveObject)& anIobj, 
824          const  Standard_Boolean updateviewer=Standard_True);  
825
826 AIS_InteractiveContext::Display  
827         (const  Handle(AIS_InteractiveObject)& anIobj,  
828          const  Standard_Integer amode, 
829          const  Standard_Integer aSelectionMode, 
830          const  Standard_Boolean updateviewer = Standard_True,  
831          const  Standard_Boolean allowdecomposition =  Standard_True);  
832
833   AIS_InteractiveContext::Erase  
834   AIS_InteractiveContext::EraseMode  
835   AIS_InteractiveContext::ClearPrs  
836   AIS_InteractiveContext::Redisplay  
837   AIS_InteractiveContext::Remove  
838   AIS_InteractiveContext::EraseAll  
839   AIS_InteractiveContext::Hilight  
840   AIS_InteractiveContext::HilightWithColor  
841 ~~~~~
842   
843 Bear in mind the following points:  
844   * It is recommended to display and erase interactive objects when  no local context is opened, and open a local context for local selection only.
845   * 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). 
846   * 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.
847   * 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. 
848   * 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. 
849   * 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. 
850   * *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.
851   * 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. 
852   * 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.
853
854 @subsubsection occt_visu_3_4_4 Presentation in the Local Context
855
856 In open local context, the *Display* functions presented above can be as well.  
857
858 **WARNING** 
859
860 The function *AIS_InteractiveObject::Display* automatically  activates the object's default selection mode. When you only want to visualize  an Interactive Object in open Context, you must call the function *AIS_InteractiveContext::Display*.  
861
862 You can activate or deactivate specific selection modes in the local open context in several different ways:  
863 Use the Display functions with the appropriate modes.
864    
865 ~~~~~
866   AIS_InteractiveContext::ActivateStandardMode
867   //can be used only if a  Local Context is opened.   
868   AIS_InteractiveContext::DeactivateStandardMode  
869   AIS_InteractiveContext::ActivatedStandardModes  
870   AIS_InteractiveContext::SetShapeDecomposition  
871 ~~~~~
872
873 This activates the corresponding  selection mode for all objects in Local Context, which accept decomposition  into sub-shapes. Every new Object which has been loaded into the interactive  context and which meets the decomposition criteria is automatically  activated according to these modes.  
874
875 **WARNING**
876
877 If you have opened a local context by loading an object with  the default options <i>(AllowShapeDecomposition = Standard_True)</i>, all objects of  the "Shape" type are also activated with the same modes. You can change the  state of these "Standard" objects by using *SetShapeDecomposition(Status)*.  
878
879 Load an interactive object by the function *AIS_InteractiveContext::Load*.  
880
881 This function allows loading an Interactive Object  whether it is visualized or not with a given selection mode, and/or with the necessary decomposition option. If *AllowDecomp=TRUE* and obviously, if the  interactive object is of the "Shape" type, these "standard" selection modes  will be automatically activated as a function of the modes present in the Local  Context.  
882
883 Use *AIS_InteractiveContext::Activate* and *AIS_InteractiveContext::Deactivate* to directly activate/deactivate selection modes on an object.
884
885 @subsubsection occt_visu_3_4_5 Filters 
886
887 To define an environment of dynamic detection, you can use standard filter classes or create your own.
888 A filter questions the owner of the sensitive primitive in local context to determine if it has the desired qualities. If it answers positively, it is kept. If not, it is rejected.
889
890 The root class of objects is *SelectMgr_Filter*.  The principle behind it is straightforward: a filter tests to see whether the  owners <i>(SelectMgr_EntityOwner)</i> detected in mouse position by the Local  context selector answer *OK*. If so, it is kept, otherwise it is rejected.  
891
892 You can create a custom class of filter objects by  implementing the deferred function *IsOk()*:  
893
894 ~~~~~
895 class MyFilter : public SelectMgr_Filter { };  
896 virtual Standard_Boolean MyFilter::IsOk  
897         (const Handle(SelectMgr_EntityOwner)&  anObj) const = 0; 
898 ~~~~~
899
900 In *SelectMgr*, there are also Composition filters (AND  Filters, OR Filters), which allow combining several filters. In  InteractiveContext , all filters that you add are stocked in an OR filter  (which answers *OK* if at least one filter answers *OK*).  
901
902 There are Standard filters, which have already been  implemented in several packages:  
903   * *StdSelect_EdgeFilter* -- for edges, such as lines and circles;  
904   * *StdSelect_FaceFilter* -- for faces, such as planes, cylinders and spheres;  
905   * *StdSelect_ShapeTypeFilter* -- for shape types, such as compounds, solids, shells and wires;
906   * *AIS_TypeFilter* -- for types  of interactive objects;  
907   * *AIS_SignatureFilter* -- for types  and signatures of interactive objects; 
908   * *AIS_AttributeFilter* -- for attributes of Interactive Objects, such as color and width.  
909
910 As there are specific behaviors on shapes, each new *Filter* class must, if necessary, redefine *AIS_LocalContext::ActsOn* function, which informs the Local Context if it acts on specific types of sub-shapes.  By default, this  function answers *FALSE*.
911
912 **WARNING**
913  
914 Only type filters are activated in Neutral Point to  make it possible to identify a specific type of visualized object. For filters to come into play, one or more object selection modes must be activated.  
915
916 There are several functions to manipulate filters:  
917 * *AIS_InteractiveContext::AddFilter* adds a filter passed as an argument.  
918 * *AIS_InteractiveContext::RemoveFilter* removes a filter passed as an argument.  
919 * *AIS_InteractiveContext::RemoveFilters* removes all present filters.  
920 * *AIS_InteractiveContext::Filters* gets the list of filters active in a local context.  
921   
922 <h4>Example </h4>
923
924 ~~~~~
925 myContext->OpenLocalContext(Standard_False);  
926 // no object in neutral point is  loaded  
927
928 myContext->ActivateStandardMode(TopAbs_Face);  
929 //activates decomposition of  shapes into faces.  
930 Handle (AIS_Shape) myAIShape = new AIS_Shape (  ATopoShape);  
931
932 myContext->Display(myAIShape,1,-1,Standard_True,Standard_True);  
933
934 //shading visualization mode,  no specific mode, authorization for decomposition into sub-shapes. At this  Stage, myAIShape is decomposed into faces...  
935
936 Handle(StdSelect_FaceFilter) Fil1= new  
937         StdSelect_FaceFilter(StdSelect_Revol);   
938 Handle(StdSelect_FaceFilter) Fil2= new 
939       StdSelect_FaceFilter(StdSelect_Plane);  
940
941 myContext->AddFilter(Fil1);   
942 myContext->AddFilter(Fil2);  
943
944 //only faces of revolution or  planar faces will be selected 
945       
946 myContext->MoveTo( xpix,ypix,Vue);  
947 // detects the mouse position  
948 ~~~~~
949
950 @subsubsection occt_visu_3_4_6 Selection in the Local Context
951  
952 Dynamic detection and selection are put into effect in a  straightforward way. There are only a few conventions and functions to be  familiar with. The functions are the same in neutral point and in open local context:   
953   * *AIS_InteractiveContext::MoveTo* -- passes  mouse position to Interactive Context selectors  
954   * *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  
955   * *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.  
956   * *AIS_InteractiveContext::Select* -- selects  everything found in the surrounding area.  
957   * *AIS_InteractiveContext::ShiftSelect* -- selects  what was not previously in the list of selected, deselects those already present.  
958
959 Highlighting of detected and selected entities is  automatically managed by the Interactive Context, whether you are in neutral  point or Local Context. The Highlight colors are those dealt with above. You  can nonetheless disconnect this automatic mode if you want to manage this part yourself :  
960 ~~~~~
961   AIS_InteractiveContext::SetAutomaticHilight  
962   AIS_InteractiveContext::AutomaticHilight  
963 ~~~~~
964
965 If there is no open local context, the objects selected are called **current objects**. If there is a  local context, they are called **selected objects**. Iterators allow  entities to be recovered in either case. A set of functions allows manipulating the objects, which have been placed in these different lists.  
966
967 **WARNING**
968
969 When a Local Context is open, you can select entities other  than interactive objects (vertices, edges etc.) from decompositions in standard  modes, or from activation in specific modes on specific interactive objects.  Only interactive objects are stocked in the list of selected objects. 
970
971 You can  question the Interactive context by moving the mouse. The following functions can be used:  
972   * *AIS_InteractiveContext::HasDetected* informs if something has been detected; 
973   * *AIS_InteractiveContext::HasDetectedShape* informs if it is a shape; 
974   * *AIS_InteractiveContext::DetectedShape* gets the shape if the detected entity is an object;
975   * *AIS_InteractiveContext::DetectedInteractive* gets the interactive object if the detected entity is an object. 
976
977 After using the *Select* and *ShiftSelect* functions in Neutral Point, you can explore the list of selections, referred to as current objects  in this context. The following functions can be used:    
978   * *AIS_InteractiveContext::InitCurrent* initiates a scan of this list; 
979   * *AIS_InteractiveContext::MoreCurrent* extends the scan; 
980   * *AIS_InteractiveContext::NextCurrent* resumes the scan; 
981   * *AIS_InteractiveContext::Current* gets the name of the current object  detected in the scan; 
982   * *AIS_InteractiveContext::FirstCurrentObject* gets the first current interactive object; 
983   * *AIS_InteractiveContext::HilightCurrents* highlights current objects; 
984   * *AIS_InteractiveContext::UnhilightCurrents* removes highlight from current objects; 
985   * *AIS_InteractiveContext::ClearCurrents* empties the list of current objects in order to update it; 
986   * *AIS_InteractiveContext::IsCurrent* finds the current object. 
987
988 In the Local Context, you can explore the list of selected  objects available. The following functions can be used:    
989   * *AIS_InteractiveContext::InitSelected* initiates the list of objects; 
990   * *AIS_InteractiveContext::MoreSelected* extends the list of objects; 
991   * *AIS_InteractiveContext::NextSelected* resumes a scan;
992   * *AIS_InteractiveContext::SelectedShape* gets the name of the selected object; 
993   * *AIS_InteractiveContext::HasSelectedShape* checks if the selected shape is obtained; 
994   * *AIS_InteractiveContext::Interactive* gets the picked interactive object; 
995   * *AIS_InteractiveContext::HasApplicative* checks if the applicative object has an owner from  Interactive attributed to it; 
996   * *AIS_InteractiveContext::Applicative* gets the owner of the detected applicative entity; 
997   * *AIS_InteractiveContext::IsSelected* gets the name of the selected object. 
998
999
1000 <h4>Example </h4>
1001 ~~~~~
1002 myAISCtx->InitSelected();  
1003 while (myAISCtx->MoreSelected())  
1004         { 
1005         if  (myAISCtx->HasSelectedShape) 
1006                 { 
1007                 TopoDS_Shape  ashape = myAISCtx->SelectedShape(); 
1008                         // to be able  to use the picked shape 
1009                                     }  
1010                 else  
1011                 { 
1012                 Handle_AIS_InteractiveObject  anyobj = myAISCtx->Interactive(); 
1013                 // to be able to use the picked interactive object  
1014                 }  
1015 myAISCtx->NextSelected();  
1016 }     
1017 ~~~~~
1018
1019 You have to ask whether you have selected a shape  or an interactive object before you can recover the entity in the Local Context or in the iteration loop. If you have  selected a Shape from *TopoDS* on decomposition in standard mode, the *Interactive()* function returns the interactive object, which provided the selected  shape. Other functions allow you to manipulate the content of Selected or  Current Objects:  
1020   * *AIS_InteractiveContext::EraseSelected* erases the selected objects; 
1021   * *AIS_InteractiveContext::DisplaySelected* displays them; 
1022   * *AIS_InteractiveContext::SetSelected* puts the objects in the list of  selections;
1023   * *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;
1024   * *AIS_InteractiveContext::AddOrRemoveSelected* adds or removes an object from the list of selected entities; 
1025   * *AIS_InteractiveContext::HilightSelected* highlights the selected object;
1026   * *AIS_InteractiveContext::UnhilightSelected* removes highlighting from the selected object; 
1027   * *AIS_InteractiveContext::ClearSelected* empties the list of selected objects. 
1028
1029
1030 You can highlight and remove highlighting from a current  object, and empty the list of current objects using the following functions:  
1031 ~~~~~
1032   AIS_InteractiveContext::HilightCurrents  
1033   AIS_InteractiveContext::UnhilightCurrents  
1034   AIS_InteractiveContext::ClearCurrents  
1035 ~~~~~
1036 When you are in an open Local Context, you may need to keep  "temporary" interactive objects. This is possible using the following functions: 
1037   * *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.  
1038   * *AIS_InteractiveContext::SetSelectedCurrent* allows the selected object to become the current object when you  close the local context.  
1039
1040 You can also want to use function *AIS_InteractiveContext::ClearLocalContext* to modify in a general way the state of the local context before continuing a selection (emptying objects, removing  filters, standard activation modes). 
1041
1042 @subsubsection occt_visu_3_4_7 Recommendations 
1043
1044 The possibilities of use for local contexts are numerous  depending on the type of operation that you want to perform:  
1045   * working on all visualized interactive objects, 
1046   * working on only a few objects, 
1047   * working on a single object. 
1048
1049 When you want to work on one type of entity, you should  open a local context with the option *UseDisplayedObjects* set to FALSE. Some  functions which allow you to recover the visualized interactive objects, which  have a given Type, and Signature from the "Neutral Point" are:  
1050
1051 ~~~~~
1052 AIS_InteractiveContext::DisplayedObjects (AIS_ListOfInteractive&  aListOfIO) const;  
1053 AIS_InteractiveContext::DisplayedObjects (const AIS_KindOfInteractive  WhichKind, const Standard_Integer  WhichSignature;
1054 AIS_ListOfInteractive&  aListOfIO) const;  
1055 ~~~~~
1056
1057 At this stage, you only have to load the functions *Load, Activate,* and so on.  
1058
1059 When you open a Local Context with default options, you  must keep the following points in mind:  
1060 * 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.  
1061 * The Shape Type  Interactive Objects are automatically decomposed into sub-shapes when standard  activation modes are launched.  
1062 * 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.  
1063
1064 The stages could be the following:
1065   1. Open  a Local Context with the right options;  
1066   2. Load/Visualize  the required complementary objects with the desired activation modes.  
1067   3. Activate  Standard modes if necessary  
1068   4. Create  its filters and add them to the Local Context  
1069   5. Detect/Select/recover  the desired entities  
1070   6. Close  the Local Context with the adequate index.  
1071
1072 It is useful to create an **interactive editor**, to which you  pass the Interactive Context. This allow setting up different  contexts of selection/presentation according to the operation, which you want  to perform. 
1073  
1074 Let us assume that you have visualized several types of interactive objects: *AIS_Points*,  *AIS_Axes*, *AIS_Trihedrons*, and *AIS_Shapes*.  
1075
1076 For your applicative function, you need an axis to create a  revolved object. You could obtain this axis by identifying:  
1077   * an axis which is already visualized,
1078   * 2 points,
1079   * a rectilinear edge on the shapes which are present,
1080   * a cylindrical face on the shapes (You will take the axis of this  face) 
1081
1082 ~~~~~
1083 myIHMEditor::myIHMEditor  
1084         (const  Handle(AIS_InteractiveContext)& Ctx, 
1085          ....) : 
1086          myCtx(Ctx),  
1087         ...  
1088
1089
1090
1091 myIHMEditor::PrepareContext() 
1092
1093 myIndex =myCtx->OpenLocalContext();  
1094
1095 //the filters  
1096
1097 Handle(AIS_SignatureFilter) F1 = new  AIS_SignatureFilter(AIS_KOI_Datum,AIS_SD_Point);   
1098 //filter on the points  
1099
1100 Handle(AIS_SignatureFilter) F2 = new AIS_SignatureFilter(AIS_KOI_Datum,AIS_SD_Axis);   
1101 //filters on the axes.  
1102
1103 Handle(StdSelect_FaceFilter) F3 = new StdSelect_FaceFilter(AIS_Cylinder);   
1104 //cylindrical face filters  
1105 //... 
1106 // activation of standard modes  on the shapes..  
1107 myCtx->ActivateStandardMode(TopAbs_FACE); 
1108 myCtx->ActivateStandardMode(TopAbs_VERTEX); 
1109 myCTX->Add(F1); 
1110 myCTX->Add(F2); 
1111 myCTX->Add(F3);  
1112
1113 // at  this point, you can call the selection/detection function  
1114
1115
1116 void myIHMEditor::MoveTo(xpix,ypix,Vue) 
1117
1118 {  myCTX->MoveTo(xpix,ypix,vue);  
1119 // the highlight of what is  detected is automatic.  
1120 }      
1121 Standard_Boolean myIHMEditor::Select()  
1122 {
1123 // returns true if you should  continue the selection      
1124                 myCTX->Select();   
1125                 myCTX->InitSelected();  
1126                 if(myCTX->MoreSelected()) 
1127                  {
1128                  if(myCTX->HasSelectedShape())     
1129                 { const  TopoDS_Shape& sh = myCTX->SelectedShape(); 
1130                 if(  vertex){  
1131                         if(myFirstV...)   
1132                         {  
1133                         //if it is the  first vertex, you stock it, then you deactivate the faces and only keep the  filter on the points: 
1134                         mypoint1 =  ....; 
1135                         myCtx->RemoveFilters(); 
1136                         myCTX->DeactivateStandardMode(TopAbs_FACE);   
1137                         myCtx->Add(F1);   
1138                         // the filter  on the AIS_Points  
1139                         myFirstV = Standard_False;  
1140                         return Standard_True;  
1141                          }
1142                         else
1143                          { 
1144                         mypoint2 =...;  
1145                         //  construction of the axis return Standard_False;  
1146                         } 
1147                  } 
1148                  else  
1149                   {  
1150                 //it is a  cylindrical face : you recover the axis; visualize it; and stock it.  
1151                 return  Standard_False;  
1152                 }  
1153                   }  
1154                 // it is not  a shape but is no doubt a point.  
1155                 else  
1156                 {  
1157                 Handle(AIS_InteractiveObject)   
1158                 SelObj =  myCTX->SelectedInteractive(); 
1159                 if(SelObj->Type()==AIS_KOI_Datum)   
1160                 { 
1161                         if(SelObj->Signature()==1)   
1162                         { 
1163                                 if  (firstPoint) 
1164                                 { 
1165                                 mypoint1  =...  
1166                                 return  Standard_True;  
1167                                 } 
1168                                 else 
1169                                 {  
1170                                 mypoint2 =  ...;  
1171                                 //construction  of the axis, visualization, stocking  
1172                                 return  Standard_False;  
1173                 } 
1174                 } 
1175
1176                 else  
1177                 {  
1178                 // you have  selected an axis; stock the axis  
1179                 return  Standard_False; 
1180                 } 
1181                 } 
1182                 } 
1183                 } 
1184                 }  
1185 void myIHMEditor::Terminate()
1186 {
1187 myCtx->CloseLocalContext(myIndex); 
1188 ...
1189 }
1190 ~~~~~
1191
1192 @subsection occt_visu_3_5 Standard Interactive Object Classes 
1193
1194 Interactive Objects are selectable and viewable objects connecting graphic representation and the underlying reference geometry.
1195
1196 They are divided into four types:
1197   * the **Datum** -- a construction geometric element;
1198   * the **Relation** -- a constraint on the interactive shape and the corresponding reference geometry;
1199   * the **Object** -- a topological shape or connection between shapes;
1200   * **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.
1201
1202 Inside these categories, there is a possibility of additional characterization by means of a signature. The signature provides an index to the further characterization. By default, the **Interactive Object** has a *None* type and a signature of 0 (equivalent to *None*).
1203 If you want to give a particular type and signature to your interactive object, you must redefine the two virtual methods: <i>Type</i> and <i>Signature</i>.
1204
1205 @subsubsection occt_visu_3_5_1 Datum
1206
1207 The **Datum** groups together the construction elements such as lines, circles, points, trihedrons, plane trihedrons, planes and axes.
1208   
1209 *AIS_Point,  AIS_Axis,  AIS_Line,  AIS_Circle,  AIS_Plane* and *AIS_Trihedron* have four selection modes: 
1210   * mode 0 : selection of a trihedron; 
1211   * mode 1 : selection of the origin of the trihedron; 
1212   * mode 2 : selection of the axes; 
1213   * mode 3 : selection of the planes XOY, YOZ, XOZ. 
1214
1215 when you activate one of modes: 1 2 3 4, you pick AIS  objects of type:  
1216   * *AIS_Point* 
1217   * *AIS_Axis* (and information on the type of axis) 
1218   * *AIS_Plane* (and information on the type of plane). 
1219
1220 *AIS_PlaneTrihedron* offers three selection modes:  
1221   * mode 0 : selection of the whole trihedron; 
1222   * mode 1 : selection of the origin of the trihedron; 
1223   * mode 2 : selection of the axes -- same remarks as for the Trihedron.
1224
1225 For 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.  
1226
1227 @subsubsection occt_visu_3_5_2 Object
1228
1229 The **Object** type includes topological shapes, and connections between shapes.
1230
1231 *AIS_Shape* has three visualization modes :
1232   * mode 0 : Line (default mode) 
1233   * mode 1 : Shading (depending on the type of shape) 
1234   * mode 2 : Bounding Box 
1235
1236 And at maximum seven selection modes, depending on the shape complexity:
1237   * mode 0 : selection of the *AIS_Shape*; 
1238   * mode 1 : selection of the vertices; 
1239   * mode 2 : selection of the edges; 
1240   * mode 3 : selection of the wires; 
1241   * mode 4 : selection of the faces; 
1242   * mode 5 : selection of the shells; 
1243   * mode 6 : selection of the constituent solids. 
1244
1245   * *AIS_Triangulation* is a simple interactive object for displaying  triangular mesh contained in *Poly_Triangulation* container. 
1246   * *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.  
1247   * *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.  
1248   * *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) 
1249   * *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.  
1250   * *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. 
1251   * *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. 
1252
1253
1254 The class *AIS_ColoredShape* allows using custom colors and line widths for *TopoDS_Shape* objects and their sub-shapes.
1255
1256 ~~~~~
1257   AIS_ColoredShape aColoredShape = new AIS_ColoredShape (theShape);
1258
1259   // setup color of entire shape
1260   aColoredShape->SetColor (Quantity_Color (Quantity_NOC_RED));
1261
1262   // setup line width of entire shape
1263   aColoredShape->SetWidth (1.0);
1264
1265   // set transparency value
1266   aColoredShape->SetTransparency (0.5);
1267
1268   // customize color of specified sub-shape
1269   aColoredShape->SetCustomColor (theSubShape, Quantity_Color (Quantity_NOC_BLUE1));
1270
1271   // customize line width of specified sub-shape
1272   aColoredShape->SetCustomWidth (theSubShape, 0.25);
1273 ~~~~~
1274
1275 The presentation class *AIS_PointCloud* can be used for efficient drawing of large arbitrary sets of colored points. It uses *Graphic3d_ArrayOfPoints* to pass point data into OpenGl graphic driver to draw a set points as an array of "point sprites". The point data is packed into vertex buffer object for performance.
1276 - The type of point marker used to draw points can be specified as a presentation aspect.
1277 - The presentation provides selection by a bounding box of the visualized set of points. It supports two display / highlighting modes: points or bounding box.
1278
1279 @image html point_cloud.png "A random colored cloud of points"
1280
1281 Example:
1282 ~~~~~
1283 Handle(Graphic3d_ArrayOfPoints) aPoints = new Graphic3d_ArrayOfPoints (2000, Standard_True);
1284 aPoints->AddVertex (gp_Pnt(-40.0, -40.0, -40.0), Quantity_Color (Quantity_NOC_BLUE1));
1285 aPoints->AddVertex (gp_Pnt (40.0,  40.0,  40.0), Quantity_Color (Quantity_NOC_BLUE2));
1286
1287 Handle(AIS_PointCloud) aPntCloud = new AIS_PointCloud();
1288 aPntCloud->SetPoints (aPoints);
1289 ~~~~~
1290
1291 The draw command *vpointcloud* builds a cloud of points from shape triangulation.
1292 This command can also draw a sphere surface or a volume with a large amount of points (more than one million).
1293
1294
1295 @subsubsection occt_visu_3_5_3 Relations 
1296
1297 The **Relation** is made up of constraints on one or more interactive shapes and the corresponding reference geometry. For example, you might want to constrain two edges in a parallel relation. This constraint is considered as an object in its own right, and is shown as a sensitive primitive. This takes the graphic form of a perpendicular arrow marked with the || symbol and lying between the two edges.
1298
1299 The following relations are provided by *AIS*:
1300   * *AIS_ConcentricRelation* 
1301   * *AIS_FixRelation*
1302   * *AIS_IdenticRelation* 
1303   * *AIS_ParallelRelation*
1304   * *AIS_PerpendicularRelation*
1305   * *AIS_Relation*
1306   * *AIS_SymmetricRelation*
1307   * *AIS_TangentRelation*
1308
1309 The list of relations is not exhaustive.    
1310
1311 @subsubsection occt_visu_3_5_4 Dimensions
1312   * *AIS_AngleDimension* 
1313   * *AIS_Chamf3dDimension* 
1314   * *AIS_DiameterDimension* 
1315   * *AIS_DimensionOwner*
1316   * *AIS_LengthDimension*
1317   * *AIS_OffsetDimension*
1318   * *AIS_RadiusDimension*
1319
1320   @subsubsection occt_visu_3_5_5 MeshVS_Mesh
1321
1322 *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.  
1323
1324 However, the *DataSource* does not provide any  information on attributes, for example nodal colors, but you can apply them in  a special way -- by choosing the appropriate presentation builder.  
1325
1326 The presentations of *MeshVS_Mesh* are built with the  presentation builders *MeshVS_PrsBuilder*. You can choose between the  builders to represent the object in a different way. Moreover, you can redefine  the base builder class and provide your own presentation builder. 
1327
1328 You can add/remove builders using the following methods: 
1329 ~~~~~
1330   MeshVS_Mesh::AddBuilder (const Handle (MeshVS_PrsBuilder) &Builder, Standard_Boolean TreatAsHilighter) 
1331   MeshVS_Mesh::RemoveBuilder (const Standard_Integer  Index) 
1332   MeshVS_Mesh::RemoveBuilderById (const Standard_Integer Id) 
1333 ~~~~~
1334
1335 There is a set of reserved display and highlighting mode flags for *MeshVS_Mesh*. Mode value is a number of bits that allows selecting additional display parameters and combining the following mode flags, which allow displaying mesh in wireframe, shading and shrink modes: 
1336 ~~~~~
1337   MeshVS_DMF_WireFrame
1338   MeshVS_DMF_Shading
1339   MeshVS_DMF_Shrink
1340 ~~~~~  
1341
1342 It is also possible to display  deformed mesh in wireframe, shading or shrink modes usung :  
1343 ~~~~~
1344         MeshVS_DMF_DeformedPrsWireFrame
1345         MeshVS_DMF_DeformedPrsShading  
1346         MeshVS_DMF_DeformedPrsShrink
1347 ~~~~~  
1348
1349 The following methods represent  different kinds of data :
1350 ~~~~~
1351   MeshVS_DMF_VectorDataPrs  
1352   MeshVS_DMF_NodalColorDataPrs
1353   MeshVS_DMF_ElementalColorDataPrs
1354   MeshVS_DMF_TextDataPrs
1355   MeshVS_DMF_EntitiesWithData
1356 ~~~~~  
1357
1358 The following methods provide selection  and highlighting :
1359 ~~~~~
1360   MeshVS_DMF_SelectionPrs
1361   MeshVS_DMF_HilightPrs
1362 ~~~~~  
1363
1364 *MeshVS_DMF_User* is a user-defined  mode.  
1365
1366 These values will be used by the  presentation builder. 
1367 There is also a set of selection modes flags that can be grouped in a combination of bits: 
1368   * *MeshVS_SMF_0D*
1369   * *MeshVS_SMF_Link*
1370   * *MeshVS_SMF_Face*
1371   * *MeshVS_SMF_Volume*
1372   * *MeshVS_SMF_Element* -- groups *0D, Link, Face* and *Volume*  as a bit mask ;
1373   * *MeshVS_SMF_Node*
1374   * *MeshVS_SMF_All* -- groups *Element* and *Node* as a bit mask; 
1375   * *MeshVS_SMF_Mesh*
1376   * *MeshVS_SMF_Group*
1377
1378 Such an object, for example, can be used for displaying the object and stored in the STL file format: 
1379
1380 ~~~~~
1381 // read the data and create a data source
1382 Handle  (StlMesh_Mesh) aSTLMesh = RWStl::ReadFile (aFileName); 
1383 Handle  (XSDRAWSTLVRML_DataSource) aDataSource = new XSDRAWSTLVRML_DataSource (aSTLMesh); 
1384
1385 // create mesh 
1386 Handle  (MeshVS_Mesh) aMesh = new MeshVS(); 
1387 aMesh->SetDataSource  (aDataSource); 
1388
1389 // use default presentation builder
1390 Handle  (MeshVS_MeshPrsBuilder) aBuilder =  new  MeshVS_MeshPrsBuilder (aMesh); 
1391 aMesh->AddBuilder  (aBuilder, Standard_True); 
1392 ~~~~~
1393
1394 *MeshVS_NodalColorPrsBuilder* allows representing a mesh  with a color scaled texture mapped on it. 
1395 To do this you should define a color  map for the color scale, pass this map to the presentation builder, 
1396 and define an appropriate value in the range of 0.0 - 1.0 for every node. 
1397
1398 The following example demonstrates how you can do this (check if the view has been set up to display textures): 
1399
1400 ~~~~~
1401 // assign nodal builder to the mesh
1402 Handle  (MeshVS_NodalColorPrsBuilder) aBuilder = new MeshVS_NodalColorPrsBuilder 
1403         (aMesh,MeshVS_DMF_NodalColorDataPrs | MeshVS_DMF_OCCMask); 
1404 aBuilder->UseTexture  (Standard_True); 
1405
1406 // prepare color map
1407 Aspect_SequenceOfColor  aColorMap; 
1408 aColorMap.Append  ((Quantity_NameOfColor) Quantity_NOC_RED); 
1409 aColorMap.Append  ((Quantity_NameOfColor) Quantity_NOC_BLUE1); 
1410
1411 // assign color scale map  values (0..1) to nodes
1412 TColStd_DataMapOfIntegerReal  aScaleMap; 
1413 ...
1414 // iterate through the  nodes and add an node id and an appropriate value to the map
1415 aScaleMap.Bind  (anId, aValue); 
1416   
1417 // pass color map and color scale values to the builder
1418 aBuilder->SetColorMap  (aColorMap); 
1419 aBuilder->SetInvalidColor  (Quantity_NOC_BLACK); 
1420 aBuilder->SetTextureCoords  (aScaleMap); 
1421 aMesh->AddBuilder  (aBuilder, Standard_True); 
1422 ~~~~~
1423
1424 @subsection occt_visu_3_6 Dynamic Selection 
1425
1426 The idea of dynamic selection is to represent the entities, which you want to select by a bounding box in the actual 2D space of the selection view. The set of these zones is ordered by a powerful sorting  algorithm. 
1427 To then find the applicative entities actually detected at this position, all you have to do is read which rectangles are touched at mouse position (X,Y) of the view, and judiciously reject some of the entities which  have provided these rectangles.  
1428
1429 @subsubsection occt_visu_3_6_1 How to go from the objects to 2D boxes 
1430
1431
1432 An intermediary stage consists in representing what you can  make selectable by means of sensitive primitives and owners, entities of a high enough level to be known by the selector mechanisms.  
1433
1434 The sensitive primitive is capable of:  
1435   * giving a 2D bounding box to the selector. 
1436   * answering the rejection criteria positively or negatively by a  "Matches" function. 
1437   * being projected from 3D in the 2D space of the view if need be. 
1438   * returning the owner which it will represent in terms of  selection. 
1439
1440 A set of standard sensitive primitives exists in Select3D  packages for 3D primitives.  
1441
1442 The owner is the entity, which makes it possible to link the  sensitive primitives and the objects that you really wanted to detect. It  stocks the diverse information, which makes it possible to find objects. An  owner has a priority (*5* by default), which you can change to  make one entity more selectable than another.  
1443
1444 @image html visualization_image021.png 
1445 @image latex visualization_image021.png 
1446
1447 @subsubsection occt_visu_3_6_2 Implementation in an interactive/selectable object 
1448    
1449 Define the number of selection modes possible, i.e. what  you want to identify by activating each of the selection modes. 
1450
1451 For example: for an  interactive object representing a topological shape:  
1452 * mode 0: selection of the interactive object itself;  
1453 * mode 1: selection of the vertices; 
1454 * mode 2: selection of the edges;  
1455 * mode 3: selection of the wires;  
1456 * mode 4: selection of the detectable faces. 
1457
1458 For each selection mode of an interactive object, "model" is the set of entities, which you want to locate by these primitives and these  owners.  
1459
1460 There is an "owner" root class, *SelectMgr_EntityOwner*,  containing a reference to a selectable object, which has created it. If you  want to stock its information, you have to create classes derived from this  root class. Example: for shapes, there is the *StdSelect_BRepOwner* class,  which can save a *TopoDS* shape as a field as well as the Interactive Object.  
1461
1462 The set of sensitive primitives which has been calculated  for a given mode is stocked in *SelectMgr_Selection*.  
1463
1464 For an Interactive object, the modeling is done in the *ComputeSelection* virtual function.  
1465
1466 Let us consider an example of an interactive object representing a box. 
1467
1468 We are interested in two location modes: 
1469   * mode 0: location of the whole box.  
1470   * mode 1: location of the edges on the box. 
1471
1472 For the first  mode, all sensitive primitives will have the same owner, which will represent  the interactive object. In the second case, we have to create an owner for each  edge, and this owner will have to contain the index for the edge, which it  represents. You will create a class of owner, which derives from *SelectMgr_EntityOwner*. 
1473
1474 The *ComputeSelection*  function for the interactive box can have the following form:  
1475
1476 ~~~~~
1477 void InteractiveBox::ComputeSelection  
1478         (const  Handle(SelectMgr_Selection)& Sel, 
1479          const Standard_Integer Mode)  
1480
1481         switch(Mode) 
1482                 {  case 0:   //locating the whole box by  making its faces sensitive...  
1483                 { 
1484         Handle(SelectMgr_EntityOwner)  Ownr = new SelectMgr_EntityOwner(this,5);   
1485         for(Standard_Integer  I=1;I<=Nbfaces;I++)  
1486         {  
1487         //Array is a  TColgp_Array1OfPnt: which represents the array of vertices. Sensitivity is  
1488         Select3D_TypeOfSensitivity value 
1489         Sel->Add(new  Select3D_SensitiveFace(Ownr,Array,Sensitivity));  
1490                         } 
1491                         break;  
1492            } 
1493           case 1:  
1494         // locates the edges  {  
1495         for(Standard_Integer i=1;i<=12;i++)  
1496                         { 
1497                                 // 1 owner  per edge... 
1498                                 Handle(mypk_EdgeOwner)  Ownr = new  mypk_EdgeOwner(this,i,6); 
1499                                         //6->priority 
1500                                         Sel->Add(new  Select3D_SensitiveSegment (Ownr,firstpt(i),lastpt(i)));  
1501                                         } 
1502                                 break;  
1503                         } 
1504                 } 
1505         } 
1506 ~~~~~
1507
1508 Selectable objects are loaded in the selection manager,  which has one or more selectors; in general, we suggest assigning one selector  per viewer. All you have to do afterwards is to activate or deactivate the  different selection modes for selectable objects. The *SelectionManager*  looks after the call to the *ComputeSelection* functions for different  objects. 
1509
1510 NOTE: This procedure is completely hidden if you use the @ref occt_visu_3_3 "AIS Interactive Context"
1511
1512 <h4>Example </h4>
1513 ~~~~~
1514 //We have several " interactive boxes " box1, box2, box3;  
1515         Handle(SelectMgr_SelectionManager) SM = new  SelectMgr_SelectionManager();  
1516         Handle(StdSelect_ViewerSelector3d) VS = new  StdSelect_ViewerSelector3d();  
1517                 SM->Add(VS); 
1518                 SM->Load(box1);SM->Load(box2);SM->Load(box3); 
1519                 // box load.  
1520                 SM->Activate(box1,0,VS); 
1521                 // activates  mode 0 of box 1 in the selector VS 
1522                 SM->Activate(box1,1,VS);   
1523                 M->Activate(box3,1,VS);   
1524 VS->Pick(xpix,ypix,vue3d)  
1525 // detection of primitives by mouse position.  
1526 Handle(EntityOwner)  POwnr = VS->OnePicked();  
1527 // picking of the "best" owner detected  
1528 for(VS->Init();VS->More();VS->Next())   
1529         { 
1530         VS->Picked();   
1531         // picking of all owners  detected  
1532           } 
1533         SM->Deactivate(box1);   
1534         // deactivate all active modes  of box1  
1535 ~~~~~
1536
1537 @section occt_visu_4 3D Presentations
1538
1539 @subsection occt_visu_4_1 Glossary of 3D terms 
1540
1541 * **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.
1542 * **Depth-cueing**      Reduces the color intensity for the portion of an object further away from the eye to give the impression of depth. This is used for wireframe objects. Shaded objects do not require this.
1543 * **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.
1544 * **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.
1545 * **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.
1546 * **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. 
1547 * **View**      -- is defined by a view orientation, a view mapping, and a context view.
1548 * **Viewer** -- manages a set of views.
1549 * **View orientation** -- defines the manner in which the observer looks at the scene in terms of View Reference Coordinates.
1550 * **View mapping** -- defines the transformation from View Reference Coordinates to the Normalized Projection Coordinates. This follows the Phigs scheme.
1551 * **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.
1552
1553 @subsection occt_visu_4_2 Graphic primitives
1554
1555 The *Graphic3d* package is used to create 3D graphic objects in a 3D viewer. These objects called **structures** are made up of groups of primitives and attributes, such as polylines, planar polygons with or without holes, text and markers, and attributes, such as color, transparency, reflection, line type, line width, and text font. A group is the smallest editable element of a structure. A transformation can be applied to a structure. Structures can be connected to form a tree of structures, composed by transformations. Structures are globally manipulated by the viewer.
1556
1557 Graphic structures can be:  
1558   * Displayed, 
1559   * Highlighted, 
1560   * Erased, 
1561   * Transformed, 
1562   * Connected to form a tree hierarchy of structures, created by transformations.
1563   
1564 There are classes for: 
1565   * Visual attributes for lines, faces, markers, text, materials, 
1566   * Vectors and vertices, 
1567   * Graphic objects, groups, and structures. 
1568
1569 @subsubsection occt_visu_4_2_2 Structure hierarchies
1570
1571 The root is the top of a structure hierarchy or structure network. The attributes of a parent structure are passed to its descendants. The attributes of the descendant structures do not affect the parent. Recursive structure networks are not supported.
1572
1573 @subsubsection occt_visu_4_2_3 Graphic primitives
1574 * **Markers** 
1575   * Have one or more vertices, 
1576   * Have a type, a scale factor, and a color, 
1577   * Have a size, shape, and orientation independent of  transformations. 
1578 * **Polygons** 
1579   * Have one closed boundary, 
1580   * Have at least three vertices, 
1581   * Are planar and have a normal, 
1582   * Have interior attributes -- style, color, front and back material,  texture and reflection ratio, 
1583   * Have a boundary with the following attributes -- type, width scale  factor, color. The boundary is only drawn when the interior style is hollow. 
1584
1585 * **Polygons with holes** 
1586   * Have multiple closed boundaries, each one with at least three  vertices, 
1587   * Are planar and have a normal, 
1588   * Have interior attributes -- style, color, front and back material,  
1589   * Have a boundary with the following attributes -- type, width scale  factor, color. The boundary is only drawn when the interior style is hollow. 
1590
1591 * **Polylines** 
1592   * Have two or more vertices, 
1593   * Have the following attributes -- type, width scale factor, color. 
1594
1595 * **Text** 
1596   * Has geometric and non-geometric attributes, 
1597   * Geometric attributes -- character height, character up vector,  text path, horizontal and vertical alignment, orientation, three-dimensional  position, zoomable flag
1598   * Non-geometric attributes -- text font, character spacing,  character expansion factor, color. 
1599
1600 @subsubsection occt_visu_4_2_4 Primitive  arrays
1601
1602 Primitive arrays are a more efficient approach to describe  and display the primitives from the aspects of memory usage and graphical  performance. The key feature of the primitive arrays is that the primitive data  is not duplicated. For example, two polygons could share the same vertices, so  it is more efficient to keep the vertices in a single array and specify the  polygon vertices with indices of this array. In addition to such kind of memory  savings, the OpenGl graphics driver provides the Vertex Buffer Objects (VBO).  VBO is a sort of video memory storage that can be allocated to hold the  primitive arrays, thus making the display operations more efficient and  releasing the RAM memory. 
1603
1604 The Vertex Buffer Objects are enabled by default, but VBOs  availability depends on the implementation of OpenGl. If the VBOs are  unavailable or there is not enough video memory to store the primitive arrays,  the RAM memory will be used to store the arrays.  
1605
1606 The Vertex Buffer Objects can be disabled at the application  level. You can use the method *Graphic3d_GraphicDriver::EnableVBO (const Standard_Boolean status)* to enable/disable VBOs: 
1607   
1608 The following example shows how to disable the VBO support:  
1609
1610 ~~~~~
1611 // get the graphic  driver
1612 Handle (Graphic3d_GraphicDriver) aDriver =  
1613   myAISContext->CurrentViewer()->Driver(); 
1614
1615 // disable VBO support
1616 aDriver->EnableVBO (Standard_False); 
1617 ~~~~~
1618
1619 **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*. 
1620
1621 The different types of primitives could be presented with  the following primitive arrays: 
1622   * *Graphic3d_ArrayOfPoints,*
1623   * *Graphic3d_ArrayOfPolygons,*
1624   * *Graphic3d_ArrayOfPolylines,*
1625   * *Graphic3d_ArrayOfQuadrangles,*
1626   * *Graphic3d_ArrayOfQuadrangleStrips,*
1627   * *Graphic3d_ArrayOfSegments,*
1628   * *Graphic3d_ArrayOfTriangleFans,*
1629   * *Graphic3d_ArrayOfTriangles,*
1630   * *Graphic3d_ArrayOfTriangleStrips.*
1631
1632 The *Graphic3d_ArrayOfPrimitives* is a base class for these  primitive arrays. 
1633
1634 Method *Graphic3d_ArrayOfPrimitives::AddVertex* allows adding There is a set of similar methods to add vertices to the  primitive array.
1635
1636 These methods take vertex coordinates as an argument and  allow you to define the color, the normal and the texture coordinates assigned  to the vertex. The return value is the actual number of vertices in the array. 
1637
1638 You can also modify the values assigned to the vertex or  query these values by the vertex index: 
1639   * *void Graphic3d_ArrayOfPrimitives::SetVertice*
1640   * *void  Graphic3d_ArrayOfPrimitives::SetVertexColor*
1641   * *void  Graphic3d_ArrayOfPrimitives::SetVertexNormal*
1642   * *void  Graphic3d_ArrayOfPrimitives::SetVertexTexel*
1643   * *gp_Pnt  Graphic3d_ArrayOfPrimitives::Vertices*
1644   * *gp_Dir   Graphic3d_ArrayOfPrimitives::VertexNormal*
1645   * *gp_Pnt3d  Graphic3d_ArrayOfPrimitives::VertexTexel*
1646   * *Quantity_Color  Graphic3d_ArrayOfPrimitives::VertexColor*
1647   * *void  Graphic3d_ArrayOfPrimitives::Vertices*
1648   * *void  Graphic3d_ArrayOfPrimitives::VertexNormal*
1649   * *void  Graphic3d_ArrayOfPrimitives::VertexTexel*
1650   * *void  Graphic3d_ArrayOfPrimitives::VertexColor*
1651
1652 The following example shows how to define an array of  points: 
1653
1654 ~~~~~
1655 // create an array
1656 Handle (Graphic3d_ArrayOfPoints) anArray = new Graphic3d_ArrayOfPoints (aVerticiesMaxCount); 
1657
1658 // add vertices to the array
1659 anArray->AddVertex  (10.0, 10.0, 10.0); 
1660 anArray->AddVertex  (0.0, 10.0, 10.0); 
1661
1662 // add the array to the structure
1663 Handle (Graphic3d_Group) aGroup  =  Prs3d_Root::CurrentGroup (aPrs); 
1664 aGroup->BeginPrimitives (); 
1665 aGroup->AddPrimitiveArray (anArray); 
1666 aGroup->EndPrimitives (); 
1667 ~~~~~
1668
1669 If the primitives share the same vertices (polygons,  triangles, etc.) then you can define them as indices of the vertices array. 
1670
1671 The method *Graphic3d_ArrayOfPrimitives::AddEdge* allows defining the primitives by indices. This method adds an "edge" in the range <i> [1, VertexNumber() ] </i>  in the array. 
1672
1673 It is also possible to query the vertex defined by an edge using method *Graphic3d_ArrayOfPrimitives::Edge*
1674
1675 The following example shows how to define an array of  triangles: 
1676
1677 ~~~~~
1678 // create an array
1679 Standard_Boolean  IsNormals     = Standard_False;  
1680 Standard_Boolean  IsColors      = Standard_False; 
1681 Standard_Boolean  IsTextureCrds = Standard_False; 
1682 Handle (Graphic3d_ArrayOfTriangles) anArray =  
1683           new Graphic3d_ArrayOfTriangles (aVerticesMaxCount, 
1684                                           aEdgesMaxCount, 
1685                                           IsNormals, 
1686                                           IsColors, 
1687                                           IsTextureCrds); 
1688 // add vertices to the array
1689 anArray->AddVertex  (-1.0, 0.0, 0.0);   // vertex 1
1690 anArray->AddVertex  ( 1.0, 0.0, 0.0);   // vertex 2
1691 anArray->AddVertex  ( 0.0, 1.0, 0.0);   // vertex 3 
1692 anArray->AddVertex  ( 0.0,-1.0, 0.0);   // vertex 4 
1693
1694 // add edges to the array
1695 anArray->AddEdge  (1);  // first triangle
1696 anArray->AddEdge  (2); 
1697 anArray->AddEdge  (3); 
1698 anArray->AddEdge  (1);  // second triangle
1699 anArray->AddEdge  (2); 
1700 anArray->AddEdge  (4); 
1701
1702 // add the array to the structure
1703 Handle  (Graphic3d_Group) aGroup =  Prs3d_Root::CurrentGroup (aPrs); 
1704 aGroup->BeginPrimitives  (); 
1705 aGroup->AddPrimitiveArray  (anArray); 
1706 aGroup->EndPrimitives  (); 
1707 ~~~~~
1708
1709 If the primitive array presents primitives built from  sequential sets of vertices, for example polygons, then you can specify the  bounds, or the number of vertices for each primitive. You can use the method *Graphic3d_ArrayOfPrimitives::AddBound* to define the bounds and the color for each bound. This method returns the actual number of bounds. 
1710
1711 It is also possible to set the color and query the number of  edges in the bound and bound color. 
1712 ~~~~~
1713   Standard_Integer  Graphic3d_ArrayOfPrimitives::Bound
1714   Quantity_Color  Graphic3d_ArrayOfPrimitives::BoundColor
1715   void  Graphic3d_ArrayOfPrimitives::BoundColor
1716 ~~~~~
1717
1718 The following example shows how to define an array of  polygons: 
1719
1720 ~~~~~
1721 // create an array
1722 Standard_Boolean  IsNormals      = Standard_False;  
1723 Standard_Boolean  IsVertexColors = Standard_False; 
1724 Standard_Boolean  IsFaceColors   = Standard_False; 
1725 Standard_Boolean  IsTextureCrds  = Standard_False; 
1726 Handle (Graphic3d_ArrayOfPolygons) anArray =  
1727           new Graphic3d_ArrayOfPolygons (aVerticesMaxCount, 
1728                                          aBoundsMaxCount, 
1729                                          aEdgesMaxCount, 
1730                                          IsNormals, 
1731                                          IsVertexColors, 
1732                                          IsFaceColors, 
1733                                          IsTextureCrds); 
1734
1735 // add bounds to the array, first polygon
1736 anArray->AddBound (3);  
1737 anArray->AddVertex (-1.0,  0.0, 0.0);    
1738 anArray->AddVertex  ( 1.0, 0.0, 0.0);    
1739 anArray->AddVertex  ( 0.0, 1.0, 0.0);    
1740
1741 // add bounds to the array, second polygon
1742 anArray->AddBound (4); 
1743 anArray->AddVertex (-1.0,  0.0, 0.0);    
1744 anArray->AddVertex  ( 1.0, 0.0, 0.0);    
1745 anArray->AddVertex  ( 1.0,-1.0, 0.0);    
1746 anArray->AddVertex  (-1.0,-1.0, 0.0);    
1747
1748 // add the array to the structure 
1749 Handle  (Graphic3d_Group) aGroup = Prs3d_Root::CurrentGroup  (aPrs); 
1750 aGroup->BeginPrimitives  (); 
1751 aGroup->AddPrimitiveArray  (anArray); 
1752 aGroup->EndPrimitives  (); 
1753 ~~~~~
1754
1755 There are also several helper methods. You can get the type  of the primitive array: 
1756 ~~~~~
1757   Graphic3d_TypeOfPrimitiveArray 
1758   Graphic3d_ArrayOfPrimitives::Type
1759   Standard_CString  Graphic3d_ArrayOfPrimitives::StringType
1760 ~~~~~
1761
1762 and check if the primitive array provides normals, vertex colors and vertex texels (texture coordinates): 
1763
1764 ~~~~~
1765   Standard_Boolean Graphic3d_ArrayOfPrimitives::HasVertexNormals
1766   Standard_Boolean Graphic3d_ArrayOfPrimitives::HasVertexColors
1767   Standard_Boolean Graphic3d_ArrayOfPrimitives::HasVertexTexels
1768 ~~~~~
1769 or get the number of vertices, edges and bounds: 
1770 ~~~~~
1771   Standard_Integer Graphic3d_ArrayOfPrimitives::VertexNumber
1772   Standard_Integer Graphic3d_ArrayOfPrimitives::EdgeNumber
1773   Standard_Integer Graphic3d_ArrayOfPrimitives::BoundNumber
1774 ~~~~~
1775   
1776 @subsubsection occt_visu_4_2_5 Text primitive
1777
1778 The OpenGl graphics driver uses advanced text rendering  powered by FTGL library. This library provides vector text rendering, as a  result the text can be rotated and zoomed without quality loss.  
1779 *Graphic3d* text primitives have the following features: 
1780   * fixed size (non-zoomable) or zoomable, 
1781   * can be rotated to any angle in the view plane,
1782   * support unicode charset.
1783
1784 The text attributes for the group could be defined with the *Graphic3d_AspectText3d* attributes group. 
1785 To add any text to the graphic structure you can use the  following methods: 
1786 ~~~~~
1787  void Graphic3d_Group::Text
1788                         (const Standard_CString AText, 
1789                          const Graphic3d_Vertex& APoint, 
1790                          const Standard_Real AHeight, 
1791                          const Quantity_PlaneAngle AAngle, 
1792                          const Graphic3d_TextPath ATp, 
1793                          const Graphic3d_HorizontalTextAlignment  AHta, 
1794                          const Graphic3d_VerticalTextAlignment  AVta, 
1795                          const Standard_Boolean EvalMinMax), 
1796 ~~~~~                   
1797 *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). 
1798
1799 *ATp* parameter defines the text path, *AHta* is the horizontal alignment of the text,  *AVta* is the vertical alignment of the text. 
1800
1801 You can  pass *Standard_False* as *EvalMinMax* if you do not want the graphic3d structure  boundaries to be affected by the text position.  
1802
1803 **Note** that the text orientation angle can be defined by *Graphic3d_AspectText3d* attributes. 
1804 ~~~~~
1805   void  Graphic3d_Group::Text
1806                         (const Standard_CString AText, 
1807                          const Graphic3d_Vertex& APoint, 
1808                          const Standard_Real AHeight, 
1809                          const Standard_Boolean EvalMinMax) 
1810   void  Graphic3d_Group::Text
1811                         (const TCcollection_ExtendedString  &AText,  
1812                          const Graphic3d_Vertex& APoint, 
1813                          const Standard_Real AHeight, 
1814                          const Quantity_PlaneAngle AAngle, 
1815                          const Graphic3d_TextPath ATp, 
1816                          const Graphic3d_HorizontalTextAlignment  AHta, 
1817                          const Graphic3d_VerticalTextAlignment  AVta, 
1818                          const Standard_Boolean EvalMinMax) 
1819   void  Graphic3d_Group::Text
1820                         (const TCcollection_ExtendedString  &AText,  
1821                          const Graphic3d_Vertex& APoint, 
1822                          const Standard_Real AHeight, 
1823                          const Standard_Boolean EvalMinMax) 
1824 ~~~~~
1825
1826 See the example:
1827 ~~~~~
1828 // get the group
1829 Handle (Graphic3d_Group) aGroup =  Prs3d_Root::CurrentGroup  (aPrs);  
1830
1831 // change the text  aspect
1832 Handle(Graphic3d_AspectText3d) aTextAspect =  new Graphic3d_AspectText3d (); 
1833 aTextAspect->SetTextZoomable  (Standard_True); 
1834 aTextAspect->SetTextAngle  (45.0); 
1835 aGroup->SetPrimitivesAspect (aTextAspect);   
1836
1837 // add a text primitive  to the structure
1838 Graphic3d_Vertex aPoint (1, 1, 1); 
1839 aGroup->Text (Standard_CString ("Text"), aPoint, 16.0); 
1840 ~~~~~
1841
1842 @subsubsection occt_visu_4_2_6 Materials
1843
1844 A *Graphic3d_MaterialAspect* is defined by:
1845   * Transparency;
1846   * Diffuse reflection -- a component of the object color;
1847   * Ambient reflection;
1848   * Specular reflection -- a component of the color of the light source;
1849   * Refraction index.
1850
1851 The following items are required to determine the three colors of reflection:
1852   * Color;
1853   * Coefficient of diffuse reflection;
1854   * Coefficient of ambient reflection;
1855   * Coefficient of specular reflection.
1856
1857 @subsubsection occt_visu_4_2_7 Textures
1858
1859 A *texture* is defined by a name.
1860 Three types of texture are available:
1861   * 1D;
1862   * 2D;
1863   * Environment mapping.
1864
1865 @subsubsection occt_visu_4_2_8 Shaders
1866
1867 OCCT visualization core supports GLSL shaders. Currently OCCT supports only vertex and fragment GLSL shader. Shaders can be assigned to a generic presentation by its drawer attributes (Graphic3d aspects). To enable custom shader for a specific AISShape in your application, the following API functions are used:
1868
1869 ~~~~~
1870 // Create shader program
1871 Handle(Graphic3d_ShaderProgram) aProgram = new Graphic3d_ShaderProgram();
1872
1873 // Attach vertex shader
1874 aProgram->AttachShader (Graphic3d_ShaderObject::CreateFromFile(
1875                                Graphic3d_TOS_VERTEX, "<Path to VS>"));
1876
1877 // Attach fragment shader
1878 aProgram->AttachShader (Graphic3d_ShaderObject::CreateFromFile(
1879                                Graphic3d_TOS_FRAGMENT, "<Path to FS>"));
1880
1881 // Set values for custom uniform variables (if they are)
1882 aProgram->PushVariable ("MyColor", Graphic3d_Vec3(0.0f, 1.0f, 0.0f));
1883
1884 // Set aspect property for specific AISShape
1885 theAISShape->Attributes()->ShadingAspect()->Aspect()->SetShaderProgram (aProgram);
1886 ~~~~~
1887
1888 @subsection occt_visu_4_3 Graphic attributes
1889
1890 @subsubsection occt_visu_4_3_1 Aspect package overview
1891
1892 The *Aspect* package provides classes for the graphic elements in the viewer:
1893   * Groups of graphic attributes;
1894   * Edges, lines, background;
1895   * Window;
1896   * Driver;
1897   * Enumerations for many of the above.
1898
1899 @subsection occt_visu_4_4 3D view facilities
1900
1901 @subsubsection occt_visu_4_4_1 Overview
1902
1903 The *V3d* package provides the resources to define a 3D  viewer and the views attached to this viewer (orthographic, perspective). This  package provides the commands to manipulate the graphic scene of any 3D object  visualized in a view on screen.  
1904
1905 A set of high-level commands allows the separate  manipulation of parameters and the result of a projection (Rotations, Zoom,  Panning, etc.) as well as the visualization attributes (Mode, Lighting,  Clipping, Depth-cueing, etc.) in any particular view.  
1906
1907 The *V3d* package is basically a set of tools directed by  commands from the viewer front-end. This tool set contains methods for creating  and editing classes of the viewer such as:  
1908   * Default parameters of the viewer, 
1909   * Views (orthographic, perspective), 
1910   * Lighting (positional, directional, ambient, spot, headlight), 
1911   * Clipping planes (note that only Z-clipping planes can work with  the Phigs interface), 
1912   * Instantiated sequences of views, planes, light sources, graphic  structures, and picks, 
1913   * Various package methods. 
1914
1915 @subsubsection occt_visu_4_4_2 A programming example
1916
1917 This sample TEST program for the *V3d* Package uses primary  packages *Xw* and *Graphic3d* and secondary packages *Visual3d, Aspect, Quantity,  Phigs* and *math*.  
1918
1919 ~~~~~
1920 //Create a default display  connection
1921 Handle(Aspect_DisplayConnection)  aDisplayConnection = new  Aspect_DisplayConnection(); 
1922
1923 //Create a Graphic Driver from  the default Aspect_DisplayConnection
1924 Handle(OpenGl_GraphicDriver)  GD = new OpenGl_GraphicDriver (aDisplayConnection);
1925
1926 //Create a Viewer to this Driver 
1927 Handle(V3d_Viewer)  VM = new V3d_Viewer(GD, 400.,  
1928         // Space size  
1929         V3d_Xpos,
1930         // Default projection  
1931         Quantity_NOC_DARKVIOLET, 
1932         // Default  background  
1933         V3d_ZBUFFER, 
1934         // Type of  visualization  
1935         V3d_GOURAUD, 
1936         // Shading  model  
1937         V3d_WAIT); 
1938         // Update mode   
1939 // Create a structure in this  Viewer 
1940 Handle(Graphic3d_Structure) S =  new  Graphic3d_Structure(VM->Viewer()) ;  
1941
1942 // Type of structure 
1943 S->SetVisual (Graphic3d_TOS_SHADING);  
1944
1945 // Create a group of primitives  in this structure
1946 Handle(Graphic3d_Group) G = new Graphic3d_Group(S) ;  
1947
1948 // Fill this group with  one polygon of size 100  
1949 Graphic3d_Array1OfVertex Points(0,3) ;  
1950 Points(0).SetCoord(-100./2.,-100./2.,-100./2.) ;  
1951 Points(1).SetCoord(-100./2., 100./2.,-100./2.) ;  
1952 Points(2).SetCoord( 100./2., 100./2.,-100./2.) ;  
1953 Points(3).SetCoord( 100./2.,-100./2.,-100./2.) ;  
1954 Normal.SetCoord(0.,0.,1.) ;  
1955 G->Polygon(Points,Normal) ;  
1956
1957 //  Create Ambient and Infinite Lights in this Viewer
1958 Handle(V3d_AmbientLight) L1  = new V3d_AmbientLight  
1959         (VM,Quantity_NOC_GRAY50)  ;  
1960 Handle(V3d_DirectionalLight)  L2 = new V3d_DirectionalLight  
1961         (VM,V3d_XnegYnegZneg,Quantity_NOC_WHITE)  ;  
1962
1963 // Create a 3D quality  Window with the same DisplayConnection
1964 Handle(Xw_Window) W =  new Xw_Window(aDisplayConnection,"Test  V3d",0.5,0.5,0.5,0.5) ;  
1965
1966 // Map this Window to  this screen
1967 W->Map() ;  
1968
1969 // Create a Perspective  View in this Viewer
1970 Handle(V3d_View) aView = new V3d_View(VM);
1971 aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Perspective);
1972 // Associate this View with the Window
1973 aView ->SetWindow(W);
1974 // Display ALL structures in this View
1975 VM->Viewer()->Display();
1976 // Finally update the Visualization in this View
1977 aView->Update();
1978 ~~~~~
1979
1980 As an alternative to manual setting of perspective parameters the *V3d_View::ZfitAll()* and *V3d_View::FitAll()* functions can be used:
1981
1982 ~~~~~
1983 // Display shape in Viewer VM
1984 Handle(AIS_InteractiveContext) aContext = new AIS_InteractiveContext (VM);
1985 aContext->Display(shape);
1986 // Create a Perspective View in Viewer VM
1987 Handle(V3d_View) V = new V3d_View (VM);
1988 aview->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Perspective);
1989 // Change Z-min and Z-max planes of projection volume to match the displayed objects
1990 V->ZFitAll();
1991 // Fit view to object size
1992 V->FitAll();
1993 ~~~~~
1994
1995 @subsubsection occt_visu_4_4_3 Define viewing parameters
1996
1997 View projection and orientation in OCCT *v3d* view are driven by camera. The camera calculates and supplies projection and view orientation matrices for rendering by OpenGL. The allows to the user to control all projection parameters. The camera is defined by the following properties:
1998
1999 * **Eye** -- defines the observer (camera) position. Make sure the Eye point never gets between the Front and Back clipping planes.
2000
2001 * **Center** -- defines the origin of View Reference Coordinates (where camera is aimed at).
2002
2003 * **Direction** -- defines the direction of camera view (from the Eye to the Center).
2004
2005 * **Distance** -- defines the distance between the Eye and the Center.
2006
2007 * **Front** Plane -- defines the position of the front clipping plane in View Reference Coordinates system.
2008
2009 * **Back** Plane -- defines the position of the back clipping plane in View Reference Coordinates system.
2010
2011 * **ZNear** -- defines the distance between the Eye and the Front plane.
2012
2013 * **ZFar** -- defines the distance between the Eye and the Back plane.
2014
2015 Most common view manipulations (panning, zooming, rotation) are implemented as convenience methods of *V3d_View* class, however *Graphic3d_Camera* class can also be used directly by application developers:
2016
2017 Example:
2018 ~~~~~
2019 // rotate camera by X axis on 30.0 degrees
2020 gp_Trsf aTrsf;
2021 aTrsf.SetRotation (gp_Ax1 (gp_Pnt (0.0, 0.0, 0.0), gp_Dir (1.0, 0.0, 0.0)), 30.0);
2022 aView->Camera()->Transform (aTrsf);
2023 ~~~~~
2024
2025 @subsubsection occt_visu_4_4_4 Orthographic Projection
2026
2027 @image html view_frustum.png "Perspective and orthographic projection"
2028
2029 The following code configures the camera for orthographic rendering:
2030
2031 ~~~~~
2032 // Create an orthographic View in this Viewer
2033 Handle(V3d_View) aView = new V3d_View (VM);
2034 aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Orthographic);
2035 // update the Visualization in this View
2036 aView->Update();
2037 ~~~~~
2038
2039 @subsubsection occt_visu_4_4_5 Perspective Projection
2040
2041 **Field of view (FOVy)** -- defines the field of camera view by y axis in degrees (45° is default).
2042
2043 @image html camera_perspective.png "Perspective frustum"
2044
2045 The following code configures the camera for perspective rendering:
2046
2047 ~~~~~
2048 // Create a perspective View in this Viewer
2049 Handle(V3d_View) aView = new V3d_View(VM);
2050 aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Perspective);
2051 aView->Update();
2052 ~~~~~
2053
2054
2055 @subsubsection occt_visu_4_4_6 Stereographic Projection
2056
2057 **IOD** -- defines the intraocular distance (in world space units).
2058
2059 There are two types of IOD:
2060 * _IODType_Absolute_ : Intraocular distance is defined as an absolute value.
2061 * _IODType_Relative_ : Intraocular distance is defined relative to the camera focal length (as its coefficient).
2062
2063 **Field of view (FOV)** -- defines the field of camera view by y axis in degrees (45° is default).
2064
2065 **ZFocus** -- defines the distance to the point of stereographic focus.
2066
2067 @image html stereo.png "Stereographic projection"
2068
2069 To enable stereo projection, your workstation should meet the following requirements:
2070
2071 * The graphic card should support quad buffering.
2072 * You need active 3D glasses (LCD shutter glasses).
2073 * 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.
2074
2075 In 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.
2076
2077 To enable quad buffering support you should provide the following settings to the graphic driver *opengl_caps*:
2078
2079 ~~~~~
2080 Handle(OpenGl_GraphicDriver) aDriver = new OpenGl_GraphicDriver();
2081 OpenGl_Caps& aCaps = aDriver->ChangeOptions();
2082 aCaps.contextStereo = Standard_True;
2083 ~~~~~
2084
2085 The following code configures the camera for stereographic rendering:
2086
2087 ~~~~~
2088 // Create a Stereographic View in this Viewer
2089 Handle(V3d_View) aView = new V3d_View(VM);
2090 aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Stereo);
2091 // Change stereo parameters
2092 aView->Camera()->SetIOD (IODType_Absolute, 5.0);
2093 // Finally update the Visualization in this View
2094 aView->Update();
2095 ~~~~~
2096
2097 @subsubsection occt_visu_4_4_7 View frustum culling
2098
2099 The 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:
2100 * *Graphic3d_Structure::CalculateBoundBox()* is used to calculate axis-aligned bounding box of a presentation considering its transformation.
2101 * *V3d_View::SetFrustumCulling* enables or disables frustum culling for the specified view.
2102 * Classes *OpenGl_BVHClipPrimitiveSet* and *OpenGl_BVHTreeSelector* handle the detection of outer objects and usage of acceleration structure for frustum culling.
2103 * *BVH_BinnedBuilder* class splits several objects with null bounding box.
2104
2105 @subsubsection occt_visu_4_4_8 Underlay and overlay layers management
2106
2107 In addition to interactive 3d graphics displayed in the view  you can display underlying and overlying graphics: text, color scales and drawings.
2108
2109 All *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.  
2110
2111 The method *V3d_View::SetLayerMgr(const Handle (V3d_LayerMgr)& aMgr)* allows assigning a custom layer manager to the *V3d* view.
2112
2113 There 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:
2114
2115 ~~~~~
2116    void  V3d_LayerMgr::Begin ()
2117    void  V3d_LayerMgr::Redraw ()
2118    void V3d_LayerMgr::End  ()
2119 ~~~~~
2120
2121 The layer manager controls layers (*Visual3d_Layer*)  and layer items (*Visual3d_LayerItem*). Both the overlay and  underlay layers can be created by the layer manager.  
2122
2123 The layer entity is presented by the *Visual3d_Layer* class. This entity provides drawing services in the layer, for example:
2124 ~~~~~ 
2125    void  Visual3d_Layer::DrawText
2126    void Visual3d_Layer::DrawRectangle
2127    void  Visual3d_Layer::SetColor
2128    void  Visual3d_Layer::SetViewport
2129 ~~~~~
2130
2131 The following example demonstrates how to draw overlay graphics by the *V3d_LayerMgr*:
2132
2133 ~~~~~
2134 // redefined method of  V3d_LayerMgr
2135 void  MyLayerMgr::Redraw () 
2136
2137    Quantity_Color aRed (Quantity_NOC_RED); 
2138    myOverlayLayer->SetColor (aRed); 
2139    myOverlayLayer->DrawRectangle (0, 0, 100, 100); 
2140
2141 ~~~~~
2142
2143 The 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: 
2144
2145 ~~~~~
2146    void  Visual3d_Layer::AddLayerItem (const Handle (Visual3d_LayerItem)&  Item)  
2147    void  Visual3d_Layer::RemoveLayerItem (const Handle (Visual3d_LayerItem)&  Item)   
2148    void  Visual3d_Layer::RemoveAllLayerItems ()
2149    const  Visual3d_NListOfLayerItem& Visual3d_Layer::GetLayerItemList ()    
2150 ~~~~~
2151 The layer's items are rendered when the method *void  Visual3d_Layer::RenderLayerItems()* is  called by the graphical driver.
2152
2153 The *Visual3d_LayerItem* has virtual methods that are  used to render the item: 
2154 ~~~~~
2155    void  Visual3d_LayerItem::RedrawLayerPrs () 
2156    void  Visual3d_LayerItem::ComputeLayerPrs () 
2157 ~~~~~
2158
2159 The 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: 
2160 ~~~~~
2161    void  Visual3d_LayerItem::SetNeedToRecompute (const Standard_Boolean NeedToRecompute)  
2162    Standard_Boolean  Visual3d_LayerItem::IsNeedToRecompute 
2163 ~~~~~
2164
2165 An example of *Visual3d_LayerItem* is *V3d_ColorScaleLayerItem*  that represents the color scale entity as the layer's item.  
2166 The *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: 
2167
2168 <h4>Example </h4>
2169
2170 ~~~~~
2171 // tell V3d_ColorScale to draw itself
2172 void  V3d_ColorScaleLayerItem::RedrawLayerPrs () 
2173
2174    Visual3d_LayerItem::RedrawLayerPrs () 
2175   if  (!MyColorScale.IsNull ()) 
2176     MyColorScale->DrawScale  (); 
2177
2178
2179 // V3d_ColorScale has a reference to a LayerMgr
2180 void  V3d_ColorScale::DrawScale () 
2181
2182     // calls V3d_ColorScale::PaintRect,  V3d_ColorScale::PaintText, etc. 
2183
2184
2185 // PaintRect method uses overlay layer of LayerMgr to  draw a rectangle 
2186 void V3d_ColorScale::PaintRect   
2187        (const  Standard_Integer X, const Standard_Integer Y, 
2188         const  Standard_Integer W, const Standard_Integer H, 
2189         const  Quantity_Color aColor, 
2190         const  Standard_Boolean aFilled) 
2191
2192   const Handle  (Visual3d_Layer)& theLayer = myLayerMgr->Overlay (); 
2193    ...
2194    theLayer->SetColor (aColor); 
2195    theLayer->DrawRectangle (X, Y, W, H); 
2196    ... 
2197
2198 ~~~~~
2199
2200 @subsubsection occt_visu_4_4_9 View background styles
2201 There are three types of  background styles available for *V3d_view*: solid color, gradient color and  image.  
2202
2203 To set solid color for  the background you can use the following methods: 
2204 ~~~~~
2205    void  V3d_View::SetBackgroundColor
2206                 (const Quantity_TypeOfColor Type,  
2207                  const Quantity_Parameter V1, 
2208                  const Quantity_Parameter V2, 
2209                  const Quantity_Parameter V3) 
2210 ~~~~~
2211
2212 This 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*. 
2213
2214 **Note** that the color  value parameters *V1,V2,V3* should be in the range between *0.0-1.0.* 
2215
2216 ~~~~~
2217   void  V3d_View::SetBackgroundColor(const Quantity_Color &Color)  
2218   void  V3d_View::SetBackgroundColor(const Quantity_NameOfColor Name)  
2219 ~~~~~
2220
2221 The gradient background  style could be set up with the following methods: 
2222 ~~~~~
2223   void  V3d_View::SetBgGradientColors
2224                 (const Quantity_Color& Color1,  
2225                  const Quantity_Color& Color2, 
2226                  const Aspect_GradientFillMethod  FillStyle, 
2227                  const Standard_Boolean update) 
2228                 
2229    void  V3d_View::SetBgGradientColors
2230                 (const Quantity_NameOfColor Color1,  
2231                  const Quantity_NameOfColor Color2, 
2232                  const Aspect_GradientFillMethod  FillStyle, 
2233                  const Standard_Boolean update) 
2234 ~~~~~
2235
2236 The *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.  
2237
2238 The fill style can be also set with the method *void  V3d_View::SetBgGradientStyle(const Aspect_GradientFillMethod AMethod, const Standard_Boolean update)*. 
2239
2240 To get the current  background color you can use the following methods: 
2241 ~~~~~
2242    void  V3d_View::BackgroundColor
2243                 (const Quantity_TypeOfColor Type,  
2244                  Quantity_Parameter &V1, 
2245                  Quantity_Parameter &V2, 
2246                  Quantity_Parameter &V3) 
2247    Quantity_Color  V3d_View::BackgroundColor()
2248    void V3d_View::GradientBackgroundColors(Quantity_Color& Color1, Quantity_Color& Color2) 
2249    Aspect_GradientBackground  GradientBackground()
2250 ~~~~~
2251    
2252 To set the image as a  background and change the background image style you can use the following  methods: 
2253 ~~~~~  
2254   void V3d_View::SetBackgroundImage
2255                 (const Standard_CString FileName,  
2256                  const Aspect_FillMethod FillStyle, 
2257                  const Standard_Boolean update) 
2258   void  V3d_View::SetBgImageStyle
2259                 (const Aspect_FillMethod FillStyle,  
2260                  const Standard_Boolean update) 
2261 ~~~~~
2262
2263 The *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:  
2264   * *Aspect_FM_NONE* --  draws the image in the default position;
2265   * *Aspect_FM_CENTERED* -- draws the image at the center of the view;
2266   * *Aspect_FM_TILED* -- tiles the view with the image;
2267   * *Aspect_FM_STRETCH* -- stretches the image over the view.
2268
2269
2270 @subsubsection occt_visu_4_4_10 Dumping a 3D scene into an image file
2271
2272 The 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).
2273
2274 The *V3d_View* has the following methods for  dumping the 3D scene: 
2275 ~~~~
2276 Standard_Boolean  V3d_View::Dump 
2277         (const Standard_CString theFile, 
2278          const Image_TypeOfImage theBufferType)
2279 ~~~~
2280 Dumps the scene into an image file with the view  dimensions.
2281
2282 ~~~~
2283 Standard_Boolean  V3d_View::Dump 
2284         (const Standard_CString theFile, 
2285          const Aspect_FormatOfSheetPaper  theFormat, 
2286          const Image_TypeOfImage theBufferType)
2287 ~~~~
2288 Makes the dimensions of the output image compatible to a certain format of printing paper passed by *theFormat* argument.  
2289   
2290 These methods dump the 3D scene into an image file passed by its name  and path as theFile.  
2291
2292 The raster image data handling algorithm is based on the *Image_PixMap* class. The supported extensions are ".png", ".bmp", ".png", ".png".
2293
2294 The 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.  
2295
2296 There is also class *Image_AlienPixMap* providing import / export from / to external image files in formats supported by **FreeImage** library.
2297
2298 **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. 
2299
2300 ~~~~
2301 Handle_Image_PixMap  V3d_View::ToPixMap 
2302         (const Standard_Integer theWidth, 
2303         const Standard_Integer theHeight, 
2304         const Image_TypeOfImage theBufferType, 
2305         const Standard_Boolean theForceCentered) 
2306 ~~~~
2307 Dumps the displayed 3d scene into a pixmap  with a width and height passed as *theWidth* and theHeight arguments.  
2308
2309 The 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. 
2310
2311 All 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: 
2312 * Create display connection; 
2313 * Initialize graphic driver; 
2314 * Create a window; 
2315 * Set up the window as virtual, *Aspect_Window::SetVirtual()* ; 
2316 * Create a view and an interactive context; 
2317 * Assign the virtual window to the view; 
2318 * Display a 3D scene; 
2319 *  Use one of the functions described above to dump the 3D scene. 
2320
2321 The following example demonstrates this  procedure for *WNT_Window* : 
2322
2323 ~~~~~
2324 // create a dummy display  connection
2325 Handle(Aspect_DisplayConnection)  aDisplayConnection;
2326
2327 // create a graphic driver
2328 Handle  (Graphic3d_GraphicDriver) aDriver = Graphic3d::InitGraphicDriver (aDisplayConnection); 
2329
2330 // create a window
2331 Standard_Integer  aDefWidth  = 800; 
2332 Standard_Integer  aDefHeight = 600; 
2333 Handle  (WNT_WClass) aWClass =  new WNT_WClass ("Virtual Class",DefWindowProc, 
2334                               CS_VREDRAW | CS_HREDRAW, 0, 0,  
2335                               ::LoadCursor (NULL, IDC_ARROW)); 
2336 Handle  (WNT_Window) aWindow =  new WNT_Window ("VirtualWnd",  aWClass,  
2337                               WS_OVERLAPPEDWINDOW, 0, 0,  
2338                               aDefWidth, aDefHeight); 
2339
2340 // set up the window as  virtual
2341 aWindow->SetVirtual  (Standard_True); 
2342
2343 // create a view and an  interactive context
2344 Handle  (V3d_Viewer) aViewer =  new V3d_Viewer (aDriver, 
2345                               Standard_ExtString ("Virtual")); 
2346 Handle  (AIS_InteractiveContext) aContext = new AIS_InteractiveContext (aViewer); 
2347 Handle  (V3d_View) aView = aViewer->CreateView (); 
2348
2349 // assign the virtual window  to the view
2350 aView->SetWindow  (aWindow); 
2351
2352 // display a 3D scene
2353 Handle (AIS_Shape) aBox = new AIS_Shape (BRepPrimAPI_MakeBox (5, 5, 5)); 
2354 aContext->Display  (aBox); 
2355 aView->FitAll(); 
2356
2357 // dump the 3D scene into an  image file
2358 aView->Dump  ("3dscene.png"); 
2359 ~~~~~
2360
2361 @subsubsection occt_visu_4_4_11 Printing a 3D scene
2362
2363 The 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.  
2364
2365 The 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: 
2366
2367 *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.  
2368
2369 You can define  the filename for the printer driver if you want to print out the result into a  file.  
2370 If you do not want to print the  background, you can pass *Standard_False* as the *showBackground* argument. 
2371 The *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*
2372
2373 The 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. 
2374
2375 **Note** that at the moment the printing is implemented only for Windows.
2376
2377 @subsubsection occt_visu_4_4_12 Vector image export
2378
2379 The 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).  
2380
2381 The 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: 
2382
2383 The *FileName*  defines the output image file name and the *Format* argument defines the output  file format:  
2384   * *Graphic3d_EF_PostScript  (PS)*,
2385   * *Graphic3d_EF_EhnPostScript  (EPS)*,
2386   * *Graphic3d_EF_TEX  (TEX)*,
2387   * *Graphic3d_EF_PDF  (PDF)*,
2388   * *Graphic3d_EF_SVG  (SVG)*,
2389   * *Graphic3d_EF_PGF  (PGF)*.
2390
2391 The *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. 
2392
2393 The *Export* method supports only basic 3d  graphics and has several limitations: 
2394   * Rendering large scenes could be slow and  can lead to large output files;
2395   * Transparency is only supported for PDF and  SVG output;
2396   * Textures and some effects are not supported by the *GL2PS* library.
2397
2398 @subsubsection occt_visu_4_4_13 Ray tracing support
2399
2400 OCCT 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:
2401 * Hard shadows
2402 * Refractions
2403 * Reflection
2404 * Transparency
2405 * Texturing
2406 * Support of non-polygon objects, such as lines, text, highlighting, selection.
2407 * Performance optimization using 2-level bounding volume hierarchy (BVH).
2408
2409 The 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.
2410 To make the BVH reusable it has been added into an individual reusable OCCT package *TKMath/BVH*.
2411
2412 There are several ray-tracing options that user can switch on/off:
2413 * Maximum ray tracing depth
2414 * Shadows rendering
2415 * Specular reflections
2416 * Adaptive anti aliasing
2417 * Transparency shadow effects
2418
2419 Example:
2420 ~~~~~
2421 Graphic3d_RenderingParams& aParams = aView->ChangeRenderingParams();
2422 // specifies rendering mode
2423 aParams.Method = Graphic3d_RM_RAYTRACING;
2424 // maximum ray-tracing depth
2425 aParams.RaytracingDepth = 3;
2426 // enable shadows rendering
2427 aParams.IsShadowEnabled = Standard_True;
2428 // enable specular reflections.
2429 aParams.IsReflectionEnabled = Standard_True;
2430 // enable adaptive anti-aliasing
2431 aParams.IsAntialiasingEnabled = Standard_True;
2432 // enable light propagation through transparent media.
2433 aParams.IsTransparentShadowEnabled = Standard_True;
2434 // update the view
2435 aView->Update();
2436 ~~~~~
2437
2438 @subsubsection occt_visu_4_4_14 Display priorities
2439
2440 Structure 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.
2441
2442 @subsubsection occt_visu_4_4_15 Z-layer support
2443
2444 OCCT 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.
2445
2446 Example:
2447
2448 ~~~~~
2449 // set z-layer to an interactive object
2450 Handle(AIS_InteractiveContext) aContext = ...
2451 Handle(AIS_InteractiveObject) anInterObj = ...
2452 Standard_Integer anId = 3;
2453 aViewer->AddZLayer (anId);
2454 aContext->SetZLayer (anInterObj, anId);
2455 ~~~~~
2456
2457 For each z-layer, it is allowed to:
2458 * Enable / disable depth test for layer.
2459 * Enable / disable depth write for layer.
2460 * Enable / disable depth buffer clearing.
2461 * Enable / disable polygon offset.
2462
2463 The 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*.
2464
2465 Example:
2466 ~~~~~
2467 // change z-layer settings
2468 Graphic3d_ZLayerSettings aSettings = aViewer->ZLayerSettings (anId);
2469 aSettings.EnableSetting (Graphic3d_ZLayerDepthTest);
2470 aSettings.EnableSetting (Graphic3d_ZLayerDepthWrite);
2471 aSettings.EnableSetting (Graphic3d_ZLayerDepthClear);
2472 aSettings.EnableSetting (Graphic3d_ZLayerDepthOffset);
2473 aViewer->SetZLayerSettings (anId, aSettings);
2474 ~~~~~
2475
2476
2477 @subsubsection occt_visu_4_4_16 Clipping planes
2478
2479 The ability to define custom clipping planes could be very useful for some tasks. OCCT provides such an opportunity.
2480
2481 The *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:
2482
2483 ~~~~~
2484 Graphic3d_ClipPlane::Graphic3d_ClipPlane(const gp_Pln& thePlane)
2485 void Graphic3d_ClipPlane::SetEquation (const gp_Pln& thePlane)
2486 Graphic3d_ClipPlane::Graphic3d_ClipPlane(const Equation& theEquation)
2487 void Graphic3d_ClipPlane::SetEquation (const Equation& theEquation)
2488 gp_Pln Graphic3d_ClipPlane::ToPlane() const
2489 ~~~~~
2490
2491 The clipping planes can be activated with the following method:
2492 ~~~~~
2493 void Graphic3d_ClipPlane::SetOn (const Standard_Boolean theIsOn)
2494 ~~~~~
2495
2496 The number of clipping planes is limited. You can check the limit value via method *Graphic3d_GraphicDriver::InquirePlaneLimit()*;
2497
2498 ~~~~~
2499 // get the limit of clipping planes for the current view
2500 Standard_Integer aMaxClipPlanes = aView->Viewer()->Driver()->InquirePlaneLimit();
2501 ~~~~~
2502
2503 Let us see for example how to create a new clipping plane with custom parameters and add it to a view or to an object:
2504 ~~~~~
2505 // create a new clipping plane
2506 const Handle(Graphic3d_ClipPlane)& aClipPlane = new Graphic3d_ClipPlane();
2507 // change equation of the clipping plane
2508 Standard_Real aCoeffA = ...
2509 Standard_Real aCoeffB = ...
2510 Standard_Real aCoeffC = ...
2511 Standard_Real aCoeffD = ...
2512 aClipPlane->SetEquation (gp_Pln (aCoeffA, aCoeffB, aCoeffC, aCoeffD));
2513 // set capping
2514 aClipPlane->SetCapping (aCappingArg == "on");
2515 // set the material with red color of clipping plane
2516 Graphic3d_MaterialAspect aMat = aClipPlane->CappingMaterial();
2517 Quantity_Color aColor (1.0, 0.0, 0.0, Quantity_TOC_RGB);
2518 aMat.SetAmbientColor (aColor);
2519 aMat.SetDiffuseColor (aColor);
2520 aClipPlane->SetCappingMaterial (aMat);
2521 // set the texture of clipping plane
2522 Handle(Graphic3d_Texture2Dmanual) aTexture = ...
2523 aTexture->EnableModulate();
2524 aTexture->EnableRepeat();
2525 aClipPlane->SetCappingTexture (aTexture);
2526 // add the clipping plane to an interactive object
2527 Handle(AIS_InteractiveObject) aIObj = ...
2528 aIObj->AddClipPlane (aClipPlane);
2529 // or to the whole view
2530 aView->AddClipPlane (aClipPlane);
2531 // activate the clipping plane
2532 aClipPlane->SetOn(Standard_True);
2533 // update the view
2534 aView->Update();
2535 ~~~~~
2536
2537
2538 @subsubsection occt_visu_4_4_17 Automatic back face culling
2539
2540 Back 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()*.
2541
2542 The following features are applied in *StdPrs_ToolShadedShape::IsClosed()*, which is used for definition of back face culling in *ShadingAspect*:
2543 * disable culling for free closed Shells (not inside the Solid) since reversed orientation of a free Shell is a valid case;
2544 * enable culling for Solids packed into a compound;
2545 * ignore Solids with incomplete triangulation.
2546
2547 Back face culling is turned off at TKOpenGl level in the following cases:
2548 * clipping/capping planes are in effect;
2549 * for translucent objects;
2550 * with hatching presentation style.
2551
2552 @subsection occt_visu_4_5 Examples: creating a 3D scene
2553
2554 To create 3D graphic objects and display them in the screen,  follow the procedure below:
2555 1. Create attributes.
2556 2. Create a 3D viewer.
2557 3. Create a view.
2558 4. Create an interactive context.
2559 5. Create interactive objects.
2560 6. Create primitives in the interactive  object.
2561 7. Display the interactive object.
2562
2563 @subsubsection occt_visu_4_5_1 Create attributes
2564
2565 Create colors.
2566
2567 ~~~~~
2568 Quantity_Color aBlack (Quantity_NOC_BLACK);
2569 Quantity_Color aBlue (Quantity_NOC_MATRABLUE);
2570 Quantity_Color aBrown (Quantity_NOC_BROWN4);
2571 Quantity_Color aFirebrick (Quantity_NOC_FIREBRICK);
2572 Quantity_Color aForest (Quantity_NOC_FORESTGREEN);
2573 Quantity_Color aGray (Quantity_NOC_GRAY70);
2574 Quantity_Color aMyColor (0.99, 0.65, 0.31, Quantity_TOC_RGB);
2575 Quantity_Color aBeet (Quantity_NOC_BEET);
2576 Quantity_Color aWhite (Quantity_NOC_WHITE);
2577 ~~~~~
2578
2579 Create line attributes.
2580
2581 ~~~~~
2582 Handle(Graphic3d_AspectLine3d) anAspectBrown = new Graphic3d_AspectLine3d();
2583 Handle(Graphic3d_AspectLine3d) anAspectBlue = new Graphic3d_AspectLine3d();
2584 Handle(Graphic3d_AspectLine3d) anAspectWhite = new Graphic3d_AspectLine3d();
2585 anAspectBrown->SetColor (aBrown);
2586 anAspectBlue ->SetColor (aBlue);
2587 anAspectWhite->SetColor (aWhite);
2588 ~~~~~
2589
2590 Create marker attributes.
2591 ~~~~~
2592 Handle(Graphic3d_AspectMarker3d aFirebrickMarker = new Graphic3d_AspectMarker3d();
2593 // marker attributes
2594 aFirebrickMarker->SetColor (Firebrick);
2595 aFirebrickMarker->SetScale (1.0);
2596 aFirebrickMarker->SetType (Aspect_TOM_BALL);
2597 // or this
2598 // it is a preferred way (supports full-color images on modern hardware).
2599 aFirebrickMarker->SetMarkerImage (theImage)
2600 ~~~~~
2601
2602 Create facet attributes.
2603 ~~~~~
2604 Handle(Graphic3d_AspectFillArea3d) aFaceAspect =  new Graphic3d_AspectFillArea3d();
2605 Graphic3d_MaterialAspect aBrassMaterial (Graphic3d_NOM_BRASS);
2606 Graphic3d_MaterialAspect aGoldMaterial  (Graphic3d_NOM_GOLD);
2607 aFaceAspect->SetInteriorStyle (Aspect_IS_SOLID);
2608 aFaceAspect->SetInteriorColor (aMyColor);
2609 aFaceAspect->SetDistinguishOn ();
2610 aFaceAspect->SetFrontMaterial (aGoldMaterial);
2611 aFaceAspect->SetBackMaterial  (aBrassMaterial);
2612 aFaceAspect->SetEdgeOn();
2613 ~~~~~
2614
2615 Create text attributes.
2616 ~~~~~
2617 Handle(Graphic3d_AspectText3d) aTextAspect = new Graphic3d_AspectText3d (aForest, Graphic3d_NOF_ASCII_MONO, 1.0, 0.0);
2618 ~~~~~
2619
2620 @subsubsection occt_visu_4_5_2 Create a 3D Viewer (a Windows example)
2621
2622 ~~~~~
2623 // create a default connection
2624 Handle(Aspect_DisplayConnection) aDisplayConnection;
2625 // create a graphic driver from default connection
2626 Handle(OpenGl_GraphicDriver) aGraphicDriver = new OpenGl_GraphicDriver (GetDisplayConnection());
2627 // create a viewer
2628 TCollection_ExtendedString aName ("3DV");
2629 myViewer = new V3d_Viewer (aGraphicDriver,aName.ToExtString(), "");
2630 // set parameters for V3d_Viewer
2631 // defines default lights -
2632 //   positional-light 0.3 0.0 0.0
2633 //   directional-light V3d_XnegYposZpos
2634 //   directional-light V3d_XnegYneg
2635 //   ambient-light
2636 a3DViewer->SetDefaultLights();
2637 // activates all the lights defined in this viewer
2638 a3DViewer->SetLightOn();
2639 // set background color to black
2640 a3DViewer->SetDefaultBackgroundColor (Quantity_NOC_BLACK);
2641 ~~~~~
2642
2643
2644 @subsubsection occt_visu_4_5_3 Create a 3D view (a Windows example)
2645
2646 It is assumed that a valid Windows window may already be  accessed via the method *GetSafeHwnd()*.
2647 ~~~~~
2648 Handle (WNT_Window) aWNTWindow = new WNT_Window (GetSafeHwnd());
2649 myView = myViewer->CreateView();
2650 myView->SetWindow (aWNTWindow);
2651 ~~~~~
2652
2653 @subsubsection occt_visu_4_5_4 Create an interactive context
2654
2655 ~~~~~
2656 myAISContext = new AIS_InteractiveContext (myViewer);
2657 ~~~~~
2658
2659 You are now able to display interactive objects such as an *AIS_Shape*.
2660
2661 ~~~~~
2662 TopoDS_Shape aShape = BRepAPI_MakeBox (10, 20, 30).Solid();
2663 Handle(AIS_Shape) anAISShape = new AIS_Shape(aShape);
2664 myAISContext->Display (anAISShape);
2665 ~~~~~
2666
2667 @subsubsection occt_visu_4_5_5 Create your own interactive object
2668
2669 Follow the procedure below to compute the presentable object:
2670
2671 1. Build a presentable object inheriting from *AIS_InteractiveObject* (refer to the Chapter on @ref occt_visu_2_1 "Presentable Objects").
2672 2. Reuse the *Prs3d_Presentation* provided as an argument of the compute methods.
2673
2674 **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.
2675
2676
2677 Let us look at the example of compute methods
2678
2679 ~~~~~
2680 Void
2681 myPresentableObject::Compute
2682   (const Handle(PrsMgr_PresentationManager3d)& thePrsManager,
2683    const Handle(Prs3d_Presentation)& thePrs,
2684    const Standard_Integer theMode)
2685 (
2686   //...
2687 )
2688
2689 void
2690 myPresentableObject::Compute (const Handle(Prs3d_Projector)& ,
2691                               const Handle(Prs3d_Presentation)& thePrs)
2692 (
2693   //...
2694 )
2695 ~~~~~
2696
2697 @subsubsection occt_visu_4_5_6 Create primitives in the interactive object
2698
2699 Get the group used in *Prs3d_Presentation*.
2700
2701 ~~~~~
2702 Handle(Graphic3d_Group) aGroup = Prs3d_Root::CurrentGroup (thePrs);
2703 ~~~~~
2704
2705 Update the group attributes.
2706
2707 ~~~~~
2708 aGroup->SetPrimitivesAspect (anAspectBlue);
2709 ~~~~~
2710
2711 Create two triangles in *aGroup*.
2712
2713 ~~~~~
2714 Standard_Integer aNbTria = 2;
2715 Handle(Graphic3d_ArrayOfTriangles) aTriangles = new Graphic3d_ArrayOfTriangles (3 * aNbTria, 0, Standard_True);
2716 Standard_Integer anIndex;
2717 for (anIndex = 1; anIndex <= aNbTria; nt++)
2718 {
2719   aTriangles->AddVertex (anIndex * 5.,      0., 0., 1., 1., 1.);
2720   aTriangles->AddVertex (anIndex * 5 + 5,   0., 0., 1., 1., 1.);
2721   aTriangles->AddVertex (anIndex * 5 + 2.5, 5., 0., 1., 1., 1.);
2722 }
2723 aGroup->BeginPrimitives();
2724 aGroup->AddPrimitiveArray (aTriangles);
2725 aGroup->EndPrimitives();
2726 ~~~~~
2727
2728 The methods *BeginPrimitives()* and *EndPrimitives()* are used  when creating a set of various primitives in the same group.
2729 Use the polyline function to create a boundary box for the *thePrs* structure in group *aGroup*.
2730
2731 ~~~~~
2732 Standard_Real Xm, Ym, Zm, XM, YM, ZM;
2733 thePrs->MinMaxValues (Xm, Ym, Zm, XM, YM, ZM);
2734
2735 Handle(Graphic3d_ArrayOfPolylines) aPolylines = new Graphic3d_ArrayOfPolylines (16, 4);
2736 aPolylines->AddBound (4);
2737 aPolylines->AddVertex (Xm,  Ym, Zm);
2738 aPolylines->AddVertex (Xm,  Ym, ZM);
2739 aPolylines->AddVertex (Xm,  YM, ZM);
2740 aPolylines->AddVertex (Xm,  YM, Zm);
2741 aPolylines->AddBound (4);
2742 aPolylines->AddVertex (Xm,  Ym, Zm);
2743 aPolylines->AddVertex (XM,  Ym, Zm);
2744 aPolylines->AddVertex (XM,  Ym, ZM);
2745 aPolylines->AddVertex (XM,  YM, ZM);
2746 aPolylines->AddBound (4);
2747 aPolylines->AddVertex (XM,  YM, Zm);
2748 aPolylines->AddVertex (XM,  Ym, Zm);
2749 aPolylines->AddVertex (XM,  YM, Zm);
2750 aPolylines->AddVertex (Xm,  YM, Zm);
2751 aPolylines->AddBound (4);
2752 aPolylines->AddVertex (Xm,  YM, ZM);
2753 aPolylines->AddVertex (XM,  YM, ZM);
2754 aPolylines->AddVertex (XM,  Ym, ZM);
2755 aPolylines->AddVertex (Xm,  Ym, ZM);
2756
2757 aGroup->BeginPrimitives();
2758 aGroup->AddPrimitiveArray(aPolylines);
2759 aGroup->EndPrimitives();
2760 ~~~~~
2761
2762 Create text and markers in group *aGroup*.
2763
2764 ~~~~~
2765 static char* texte[3] =
2766 {
2767   "Application title",
2768   "My company",
2769   "My company address."
2770 };
2771 Handle(Graphic3d_ArrayOfPoints) aPtsArr = new Graphic3d_ArrayOfPoints (2, 1);
2772 aPtsArr->AddVertex (-40.0, -40.0, -40.0);
2773 aPtsArr->AddVertex (40.0, 40.0, 40.0);
2774 aGroup->BeginPrimitives();
2775 aGroup->AddPrimitiveArray (aPtsArr);
2776 aGroup->EndPrimitives();
2777
2778 Graphic3d_Vertex aMarker (0.0, 0.0, 0.0);
2779 for (i=0; i <= 2; i++)
2780 {
2781   aMarker.SetCoord (-(Standard_Real )i * 4 + 30,
2782                      (Standard_Real )i * 4,
2783                     -(Standard_Real )i * 4);
2784   aGroup->Text (texte[i], Marker, 20.);
2785 }
2786
2787 ~~~~~
2788
2789 @section occt_visu_5 Mesh Visualization Services
2790
2791 <i>MeshVS</i> (Mesh Visualization Service) component extends 3D visualization capabilities of Open CASCADE Technology. It provides flexible means of displaying meshes along with associated pre- and post-processor data.
2792
2793 From a developer's point of view, it is easy to integrate the *MeshVS* component into any mesh-related application with the following guidelines:
2794
2795 * Derive a data source class from the *MeshVS_DataSource* class.
2796 * Re-implement its virtual methods, so as to give the <i>MeshVS</i> component access to the application data model. This is the most important part of the job, since visualization performance is affected by performance of data retrieval methods of your data source class.
2797 * Create an instance of <i>MeshVS_Mesh</i> class.
2798 * Create an instance of your data source class and pass it to a <i>MeshVS_Mesh</i> object through the <i>SetDataSource()</i> method.
2799 * Create one or several objects of <i>MeshVS_PrsBuilder</i>-derived classes (standard, included in the <i>MeshVS</i> package, or your custom ones).
2800 * Each <i>PrsBuilder</i> is responsible for drawing a <i> MeshVS_Mesh</i> presentation in a certain display mode(s) specified as a <i>PrsBuilder</i> constructor's argument. Display mode is treated by <i>MeshVS</i> classes as a combination of bit flags (two least significant bits are used to encode standard display modes: wireframe, shading and shrink).
2801 * Pass these objects to the <i>MeshVS_Mesh::AddBuilder()</i> method. <i>MeshVS_Mesh</i> takes advantage of improved selection highlighting mechanism: it highlights its selected entities itself, with the help of so called "highlighter" object. You can set one of <i>PrsBuilder</i> objects to act as a highlighter with the help of a corresponding argument of the <i>AddBuilder()</i> method.
2802
2803 Visual attributes of the <i>MeshVS_Mesh</i> object (such as shading color, shrink coefficient and so on)  are controlled through <i>MeshVS_Drawer</i> object. It maintains a map "Attribute ID --> attribute value" and can be easily extended with any number of custom attributes.
2804
2805 In all other respects, <i>MeshVS_Mesh</i> is very similar to any other class derived from <i>AIS_InteractiveObject</i> and it should be used accordingly (refer to the description of <i>AIS package</i> in the documentation).