0024602: Documentation Code Snippets missing sign
[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 This manual provides basic documentation on setting up and using  Visualization. For advanced information on Visualization and its applications,  see our offerings on our web site (Training and E-Learning) at http://www.opencascade.org/support/training/
8
9 Visualization in Open CASCADE Technology is based on the  separation of:  
10   * on the one hand - the data which stores the geometry and topology  of the entities you want to display and select, and 
11   * 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). 
12
13 @subsection occt_visu_1_1 Open CASCADE Technology Visualization and the Organization of this guide 
14
15 Presentations are managed through the Presentation  component, and selection through the Selection component.  
16
17 To make management of these functionalities in 3D more  intuitive and consequently, more transparent, *Application Interactive Services* have been created. *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.  
18
19 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.  
20
21 The the following packages are used to display 3D objects :  
22   * *AIS*; 
23   * *StdPrs*; 
24   * *Prs3d*; 
25   * *PrsMgr*; 
26   * *V3d*; 
27   * *Graphic3d*.
28
29 If you are concerned with 2D visualization, you must familiarize yourself  with the fundamental concepts of  presentation as outlined in the section on this subject in chapter Fundamental Concepts.   In brief, the packages used to display 3D objects are  applicable for visualization of 2D objects too. 
30
31 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. 
32
33 @image html visualization_image003.png "Key concepts and packages in visualization"
34 @image latex visualization_image003.png "Key concepts and packages in visualization"
35
36 To answer different needs of CASCADE users, this user’s  guide offers the following three paths in reading it. 
37   
38   * If the 3D services proposed in AIS meet your requirements, you  need only read chapter 3 <a href="#occt_visu_3">AIS: Application Interactive Services</a>.   
39   * If you need more detail, for example, a selection filter on another type of entity - you should  read chapter 2 <a href="#occt_visu_2">Fundamental Concepts</a>, chapter 3 <a href="#occt_visu_3">AIS: Application Interactive Services</a>, and possibly chapters 4  <a href="#occt_visu_4">3D Presentations</a> and 5 <a href="#occt_visu_5">3D Resources</a>. You may want to begin with the chapter presenting AIS. 
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 * *AIS* package provides all  classes to implement interactive objects (presentable and selectable entities).  
71 * *PrsMgr* package  provides all the classes needed to implement the presentation process: the *Presentation*  and *PresentableObject* abstract classes and *PresentationManager3d* concrete class.  
72 * *StdPrs* package  provides ready-to-use standard presentation algorithms of points, curves and  shapes of the geometry and topology toolkits.  
73 * *V3d* package provides  the services supported by the 3D viewer.  
74 * *Prs3d* package provides  some 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, and so on. 
75 * *Graphic3d* package provides resources to create 3D graphic structures.  
76
77 @subsubsection occt_visu_2_1_3 A Basic Example: How to display a 3D object 
78
79 ~~~~~
80 Void Standard_Real dx  = ...; //Parameters   
81 Void Standard_Real dy  = ...; //to build  a wedge  
82 Void Standard_Real dz  = ...;  
83 Void Standard_Real ltx = ...; 
84
85 Handle(V3d_Viewer)aViewer = ...;  
86 Handle(AIS_InteractiveContext)aContext;  
87 aContext = new AIS_InteractiveContext(aViewer);     
88
89 BRepPrimAPI_MakeWedge w(dx, dy, dz, ltx);  
90 TopoDS_Solid & = w.Solid();  
91 Handle(AIS_Shape) anAis = new AIS_Shape(S);  
92 //creation of the presentable  object  
93 aContext -> Display(anAis);  
94 //Display the presentable  object in the 3d viewer. 
95 ~~~~~
96
97 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.  
98
99 @image html visualization_image004.png "Processes involved in displaying a presentable shape"
100 @image latex visualization_image004.png "Processes involved in displaying a presentable shape"
101
102 @subsection occt_visu_2_2 Selection 
103
104 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.  
105   
106 @image html visualization_image006.png "A model"  
107 @image latex visualization_image006.png "A model"  
108
109 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.  
110
111 @image html visualization_image007.png "Modeling faces with sensitive primitives"
112 @image latex visualization_image007.png "Modeling faces with sensitive primitives"
113
114 @image html visualization_image008.png "In a dynamic selection, each sensitive polygon is represented by its  bounding rectangle"   
115 @image latex visualization_image008.png "In a dynamic selection, each sensitive polygon is represented by its  bounding rectangle"
116
117 @image html visualization_image009.png "Reference to the sensitive primitive, then to the owner"
118 @image latex visualization_image009.png "Reference to the sensitive primitive, then to the owner"
119
120
121 @subsubsection occt_visu_2_2_1 The Sensitive Primitive  
122
123 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.
124
125 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.
126
127 @image html visualization_image010.png "Example of sensitive primitives"
128 @image latex visualization_image010.png "Example of sensitive primitives"  
129
130 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.  
131
132 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.  
133
134 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. 
135
136 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. 
137
138
139 @subsubsection occt_visu_2_2_2 Dynamic Selection 
140
141 Dynamic selection causes objects in a view to be  automatically highlighted 
142 as the mouse cursor moves over them. This allows the  user to be certain that the picked object
143  is the correct one. Dynamic Selection  is based on the following two concepts:  
144
145   * a Selectable Object (*AIS_InteractiveObject*) 
146   * an Interactive Context
147   
148 <h4>Selectable Object</h4>
149
150 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.  
151
152 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.
153
154 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.)  
155
156 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.  
157
158 <h4>Interactive Context</h4>
159
160 The interactive context is used to manage both selectable  objects and selection processes.  
161
162 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. 
163
164 See also <a href="#occt_visu_3">AIS: Application Interactive Services</a>.
165
166 Let us consider, for example, a 3D selectable shape object, which  corresponds to a topological shape.  
167
168 For this class, seven selection modes can be defined:  
169 * mode 0 - selection of the shape itself  
170 * mode 1 - selection of vertices  
171 * mode 2 - selection of edges  
172 * mode 3 - selection of wires  
173 * mode 4 - selection of faces  
174 * mode 5 - selection of shells  
175 * mode 6 - selection of solids  
176 * mode 7 - selection of compsolids 
177 * mode 8 - selection of compounds  
178
179 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.  
180
181 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.  
182
183 To deactivate selection mode 3 remove all those 2D areas. 
184
185
186 @subsubsection occt_visu_2_2_3  Selection Packages
187
188 The following selection packages exist : *SelectBasics*,  *SelectMgr*, *Select3D*, *StdSelect*.  
189
190 *SelectBasics* package contains the basic classes  of the selection:  
191   * the main definition of a sensitive primitive: *SensitiveEntity* 
192   * the definition of a sensitive primitive owner: *EntityOwner* 
193   * the algorithm used for sorting sensitive boxes: *SortAlgo* 
194
195 *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*. 
196
197 *SelectMgr* package is used to manage the whole  dynamic selection process. It contains the *SelectableObject*, Entity  Owner containing a link to its *SelectableObject*, *Selection*, *SelectionManager*,  and *ViewSelector* classes.  
198 There are also implementations of *ViewerSelector*  interface for 3D selection in *StdSelect* package: *ViewerSelector3d*. 
199
200 *Select3D* package contains 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.  
201
202 *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 means for selection of topological objects (shapes). 
203
204 @subsubsection occt_visu_2_2_4 How to use dynamic selection
205
206 Several operations must be performed prior to using dynamic  selection:  
207 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.  
208 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.  
209 3. Install the process, which provides the  user with the identity of the owner of the detected entities in the selection  loop.  
210
211 When all these steps have been carried out, follow the  procedure below:  
212 1. Create an interactive context.  
213 2. Create the selectable objects and  calculate their various possible selections.  
214 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.  
215 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.  
216
217 At this stage, the selection of selectable entities in the  selectors is available.  
218 The selection loop informs constantly the selectors with the  position of the mouse and questions them about the detected entities.  
219
220 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.  
221 You define a selectable object called *House* and  propose four possible selection modes for this object:  
222 1. selection of the house itself; 
223 2. selection of the rooms  
224 3. selection of the walls  
225 4. selection of the doors.  
226
227 You have to write the method, which calculates the four  selections above, i.e. the sensitive primitives which are activated when the  mode is.  
228 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*.   
229 For example, let us consider a house with the following  representation:  
230
231 @image html visualization_image011.png "Selection of rooms in a house"
232 @image latex visualization_image011.png "Selection of rooms in a house"
233
234 To build the selection, which corresponds to the mode "selection  of the rooms" 
235 (selection 2 in the list of selection modes), use the following  procedure:  
236
237 ~~~~~
238
239 Void House::ComputeSelection 
240         (Const  Handle(SelectMgr_Selection)& Sel, 
241          const Standard_Integer mode { 
242                  switch(mode){   
243                 case 0: //Selection of the rooms  
244                 {   
245                 for(Standard_Integer i = 1; i <= myNbRooms; i++)   
246                 { 
247                 //for every room, create an instance of the owner, the given room  and its name. 
248                 Handle(RoomOwner) aRoomOwner = new RoomOwner (Room(i),  NameRoom(i)); 
249                 //Room() returns a room and NameRoom() returns its name.  
250         Handle(Select3d_SensitiveBox) aSensitiveBox; 
251         aSensitiveBox = new Select3d_SensitiveBox  
252                 (aRoomOwner, Xmin, Ymin, Zmin,  Xmax, Ymax, Zmax); 
253                  Sel -> Add(aSensitiveBox);   
254                 }   
255                 break;   
256                 Case 1: ... //Selection of the doors   
257                 } //Switch     
258 ) // ComputeSelection  
259 ~~~~~
260
261 @image html visualization_image012.png "Activated sensitive boxes  corresponding to selection mode 0 (selection of rooms)"
262 @image latex visualization_image012.png "Activated sensitive boxes  corresponding to selection mode 0 (selection of rooms)"
263
264 @image html visualization_image013.png "Activated sensitive rectangles in the selector during dynamic selection in view 1"
265 @image latex visualization_image013.png "Activated sensitive rectangles in the selector during dynamic selection in view 1"
266
267 @image html visualization_image014.png "Activated sensitive polygons corresponding  to selection mode 1 (selection of doors)"
268 @image latex visualization_image014.png "Activated sensitive polygons corresponding  to selection mode 1 (selection of doors)"
269
270 @image html visualization_image015.png "Sensitive rectangles in the selector during  dynamic selection in view 2"
271 @image latex visualization_image015.png "Sensitive rectangles in the selector during  dynamic selection in view 2"
272
273 @section occt_visu_3 Application Interactive Services 
274 @subsection occt_visu_3_1 Introduction 
275
276 Application Interactive Services allow managing presentations and dynamic selection in a viewer in a simple and  transparent manner. 
277
278 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. 
279
280 The neutral point, which is the  default mode, allows easily visualizing and selecting interactive objects loaded into the context. 
281
282 **Local Contexts** can be opened to prepare and use a temporary selection environment without disturbing
283 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. 
284
285 When the operation is finished, you close the current local context and return to the state 
286 in which you were before opening it (neutral point or previous local context).  
287
288 **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.  
289
290 @image html visualization_image016.png 
291 @image latex visualization_image016.png 
292
293 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. 
294
295 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. 
296
297 @image html visualization_image017.png 
298 @image latex visualization_image017.png 
299
300 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.  
301
302 @subsection occt_visu_3_2 Interactive objects
303
304 @subsubsection occt_visu_3_2_1 Presentations
305
306 An interactive object can have as many  presentations as its creator wants to give it. 
307
308 3D presentations are managed by PresentationManager3D. As this is  transparent in AIS, the user does not have to worry about it. 
309
310 A presentation is identified by an index and by the reference to  the Presentation Manager which it depends on. 
311
312 By convention, the default mode of  representation for the Interactive Object has index 0. 
313
314 @image html visualization_image018.png 
315 @image latex visualization_image018.png 
316
317 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.  
318
319 If you are creating your own type of interactive object, you  must implement the Compute function in one of the following ways:  
320
321 #### For 3D:
322
323 ~~~~~
324 void PackageName_ClassName::Compute  
325         (const  Handle(PrsMgr_PresentationManager3d)& aPresentationManager,   
326          const  Handle(Prs3d_Presentation)& aPresentation,  
327          const Standard_Integer aMode =  0);  
328 ~~~~~
329
330 ####  For hidden line removal (HLR) mode in 3D:
331 ~~~~~
332 void PackageName_ClassName::Compute  
333         (const  Handle(Prs3d_Projector)& aProjector,  
334          const  Handle(Prs3d_Presentation)& aPresentation);  
335 ~~~~~
336
337 @subsubsection occt_visu_3_2_2 Hidden Line Removal
338
339 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. 
340
341 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:
342
343 * Initially by using one of the values of the enumeration  *PrsMgr_TypeOfPresentation*: 
344   * *PrsMgr_TOP_AllView*,
345   * *PrsMgr_TOP_ProjectorDependant*
346
347 * Later by using the function *PrsMgr_PresentableObject::SetTypeOfPresentation* 
348
349 *AIS_Shape* class is an example of an interactive object that supports  HLR representation. It supports two types of the HLR algorithm:  
350 * the  polygonal algorithm based on the shape’s triangulation; 
351 * the  exact algorithm that works with the shape’s real geometry. 
352
353 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: 
354         * *Prs3d_TOH_PolyAlgo* for a polygonal algorithm; 
355         * *Prs3d_TOH_Algo*  for an exact algorithm; 
356         * *Prs3d_TOH_NotSet*  if the type of algorithm is not set for the given interactive object instance. 
357
358 The type of the HLR algorithm used for *AIS_Shape* can be changed by calling the *AIS_Shape::SetTypeOfHLR()* method. 
359
360 The current  HLR algorithm type can be obtained using *AIS_Shape::TypeOfHLR()* method  is to be used. 
361
362 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*.
363
364 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. 
365
366 @subsubsection occt_visu_3_2_3 Presentation modes
367
368 There are four types of interactive objects in AIS:  
369   * the "construction element" or Datum, 
370   * the Relation (dimensions and constraints) 
371   * the Object 
372   * the None type (when the object is  of an unknown type). 
373
374 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:  
375   * *AIS_InteractiveObject::Type*  
376   * *AIS_InteractiveObject::Signature*.  
377
378 **Note** that some signatures are already used by "standard" objects provided in AIS (see the <a href="#occt_visu_3_5">list of Standard Interactive Object Classes</a>).  
379
380 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. 
381
382 Consequently, to get information about this class it is necessary to use virtual  function *AIS_InteractiveObject::AcceptDisplayMode*.  
383
384 #### Display Mode
385
386 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.
387
388 #### Highlight Mode
389
390 At dynamic detection, the presentation echoed  by the Interactive Context, is by default the presentation already on the screen. 
391
392 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. 
393
394 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). 
395
396 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.  
397
398 #### Infinite Status
399 If you don’t 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. 
400
401 Let us take for example the class called *IShape* representing  an interactive object :
402
403 ~~~~~ 
404 myPk_IShape::myPK_IShape  
405         (const TopoDS_Shape& SH,  PrsMgr_TypeOfPresentation aType):  
406         AIS_InteractiveObject(aType), myShape(SH), myDrwr(new AIS_Drawer())  {SetHilightMode(0);}   
407 void myPk_IShape::Compute  
408         (const Handle(PrsMgr_PresentationManager3d)  & PM,  
409          const Handle(Prs3d_Presentation)& P,   
410          const Standard_Integer TheMode) 
411
412         switch (TheMode){  
413         case 0: 
414         StdPrs_WFDeflectionShape::Add  (P,myShape,myDrwr);  //algo for  calculation of wireframe presentation break;  
415         case 1: 
416         StdPrs_ShadedShape::Add  (P,myShape,myDrwr);   //algo for calculation of shading presentation.  
417         break; 
418         }  
419 }  
420 void myPk_IsShape::Compute  
421         (const  Handle(Prs3d_Projector)& Prj,  
422         const  Handle(Prs3d_Presentation) P)  
423
424         StdPrs_HLRPolyShape::Add(P,myShape,myDrwr); 
425         //Hidden line mode calculation algorithm  
426 }  
427 ~~~~~
428
429 @subsubsection occt_visu_3_2_4 Selection 
430
431 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 <a href="#occt_visu_3_6"> Dynamic Selection</a> chapter).  
432
433 The set of sensitive primitives, which correspond to a given  mode, is stocked in a SELECTION (*SelectMgr_Selection*). 
434
435 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*.  
436
437 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*.  
438
439 A detailed explanation of the mechanism and the manner of  implementing this function has been given in <a href="#occt_visu_3_6"> Dynamic Selection</a> chapter.  
440
441 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*.  
442
443 You can change the default selection mode index of an  Interactive Object using the following functions: 
444   * *AIS_InteractiveObject::HasSelectionMode* checks if there is a selection mode; 
445   * *AIS_InteractiveObject::SelectionMode* check the current selection mode; 
446   * *AIS_InteractiveContext::SetSelectionMode* sets a selection mode; 
447   * *AIS_InteractiveContext::UnsetSelectionMode* unsets a selection mode.
448   
449 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: 
450   * *AIS_InteractiveObject::HasSelectionPriority* checks if there is a selection priority setting for the  owner; 
451   * *AIS_InteractiveObject::SelectionPriority* checks the current priority; 
452   * *AIS_InteractiveObject::SetSelectionPriority* sets a priority; 
453   * *AIS_InteractiveObject::UnsetSelectionPriority* unsets the priority.
454   
455     
456 @subsubsection occt_visu_3_2_5 Graphic attributes
457
458 Keep  in mind the following points concerning graphic attributes:  
459   * Each interactive object can have its own visualization  attributes.
460   * 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 
461   * 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.) 
462   * 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. 
463
464
465 @image html visualization_image019.png "Figure 13. Redefinition of virtual functions for changes in AIS_Point"
466 @image latex visualization_image019.png "Figure 13. Redefinition of virtual functions for changes in AIS_Point"
467
468 @image html visualization_image020.png "Figure 14. Redefinition of virtual functions for changes in AIS_Shape."
469 @image latex visualization_image020.png "Figure 14. Redefinition of virtual functions for changes in AIS_Shape."
470
471 The  following virtual functions provide settings for color, width, material and transparency:  
472   * *AIS_InteractiveObject::UnsetColor* 
473   * *AIS_InteractiveObject::SetWidth* 
474   * *AIS_InteractiveObject::UnsetWidth* 
475   * *AIS_InteractiveObject::SetMaterial   (const Graphic3d_NameOfPhysicalMaterial & aName)* 
476   * *AIS_InteractiveObject::SetMaterial   (const Graphic3d_MaterialAspect & aMat)* 
477   * *AIS_InteractiveObject::UnsetMaterial* 
478   * *AIS_InteractiveObject::SetTransparency* 
479   * *AIS_InteractiveObject::UnsetTransparency* 
480
481 For other types of attribute, it is  appropriate to change the Drawer of the object directly using:  
482   * *AIS_InteractiveObject::SetAttributes*
483   * *AIS_InteractiveObject::UnsetAttributes*
484
485 It is important to know which functions may imply the recalculation of  presentations of the object. 
486
487 If the presentation mode of an interactive object is to be updated, a flag from *PrsMgr_PresentableObject*  indicates this. 
488
489 The mode can be updated using the functions *Display*  and *Redisplay* in *AIS_InteractiveContext*.  
490
491 @subsubsection occt_visu_3_2_6 Complementary  Services
492
493 When you use complementary services for interactive objects, pay special attention to the cases mentioned below. 
494
495 #### Change the location of an interactive object
496
497 The following functions  allow temporarily "moving" the representation and selection of  Interactive Objects in a view without recalculation.  
498   * *AIS_InteractiveContext::SetLocation*  
499   * *AIS_InteractiveContext::ResetLocation*  
500   * *AIS_InteractiveContext::HasLocation*  
501   * *AIS_InteractiveContext::Location*  
502  
503 #### Connect an interactive object to an applicative  entity
504
505 Each Interactive Object has functions that allow attributing it an *Owner* in form of a *Transient*.  
506   * *AIS_InteractiveObject::SetOwner*  
507   * *AIS_InteractiveObject::HasOwner*  
508   * *AIS_InteractiveObject::Owner*  
509
510 An interactive object can therefore be associated or not with an applicative entity, without affecting its behavior. 
511
512 #### Resolving coincident topology
513
514 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. 
515
516 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. 
517
518 The method *AIS_InteractiveObject::SetPolygonOffsets (const Standard_Integer aMode, const Standard_Real aFactor, const Standard_Real aUnits)* allows setting up the polygon  offsets.
519
520 The  parameter *aMode* can contain various combinations of *Aspect_PolygonOffsetMode* enumeration elements: 
521   * *Aspect_POM_None*
522   * *Aspect_POM_Off*
523   * *Aspect_POM_Fill*
524   * *Aspect_POM_Line*
525   * *Aspect_POM_Point*
526   * *Aspect_POM_All*
527
528 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: 
529 ~~~~~
530  offset  = aFactor * m + aUnits * r
531 ~~~~~
532 where  *m* is the maximum depth slope for the currently displayed polygons, r is the minimum  depth resolution (implementation-specific). 
533
534 Negative  offset values move polygons closer to the viewer while positive values shift  polygons away. 
535
536 **Warning**
537  
538 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. 
539
540 You can use the following  functions to obtain the current settings for polygon offsets: 
541 ~~~~~
542   void  AIS_InteractiveObject::PolygonOffsets
543                 (Standard_Integer &aMode, 
544                  Standard_Real &aFactor, 
545                  Standard_Real &aUnits) 
546   Standard_Boolean AIS_InteractiveObject::HasPolygonOffsets() 
547 ~~~~~
548
549 The same  operation could be performed for the interactive object known by the *AIS_InteractiveContext* with the following methods: 
550 ~~~~~
551 void  AIS_InteractiveContext::SetPolygonOffsets
552         (const Handle(AIS_InteractiveObject) &anObj, 
553          const Standard_Integer aMode,  
554          const Standard_Real aFactor, 
555          const Standard_Real aUnits) 
556 void  AIS_InteractiveContext::PolygonOffsets
557         (const Handle(AIS_InteractiveObject) &anObj, 
558          Standard_Integer &aMode,  
559          Standard_Real &aFactor, 
560          Standard_Real &aUnits) 
561 Standard_Boolean      AIS_InteractiveContext::HasPolygonOffsets
562         (const Handle(AIS_InteractiveObject) &anObj) 
563 ~~~~~
564
565 @subsection occt_visu_3_3 Interactive Context 
566
567 @subsubsection occt_visu_3_3_1 Rules 
568
569 The Interactive Context allows us to manage in a transparent  way, the graphic and "selectable" behavior of interactive objects in one or  more viewers. Most functions which allow us to modify the attributes of  interactive objects, and which were presented in the preceding chapter, will be  looked at again here.  
570
571 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.  
572
573 ~~~~~
574 Handle (AIS_Shape) TheAISShape = new AIS_Shape (ashape);  
575         myIntContext->Display(TheAISShape);  
576         myIntContext->SetDisplayMode(TheAISShape ,1);  
577         myIntContext->SetColor(TheAISShape,Quantity_NOC_RED);  
578 ~~~~~
579
580 You can also write  
581
582 ~~~~~
583 Handle (AIS_Shape) TheAISShape = new AIS_Shape (ashape);  
584         TheAISShape->SetColor(Quantity_NOC_RED);  
585         TheAISShape->SetDisplayMode(1);  
586         myIntContext->Display(TheAISShape);  
587 ~~~~~
588
589 @subsubsection occt_visu_3_3_2 Groups of functions 
590
591 You must distinguish two states in the Interactive Context:  
592 *  No Open Local Context; which will be referred to as Neutral  Point.  
593 *  One or several open local contexts, each representing a temporary  state of selection and presentation.  
594
595 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.  
596
597 The Interactive Context is composed of many  functions, which can be conveniently grouped according to the theme:  
598   * management proper to the context; 
599   * management in the local context; 
600   * presentations and selection in open/closed context; 
601   * selection strictly speaking. 
602
603
604 @subsubsection occt_visu_3_3_3 Management of the Interactive Context 
605
606 The Interactive Context is made up of a Principal Viewer  and, optionally, a trash bin or "Collector" Viewer. It also has a group of  adjustable settings allowing you to personalize the behavior of presentations  and selections:  
607   * Default Drawer, containing all the color and line attributes  which can be used by interactive objects, which do not have their own  attributes. 
608   * Default Visualization Mode for interactive objects.  By default: *mode  0* ;  
609   * Highlight color of entities detected by mouse movement. By default: *Quantity_NOC_CYAN1*;  
610   * Pre-selection color. By default:  *Quantity_NOC_GREEN*;  
611   * Selection color (when you click on a detected object). By default:  *Quantity_NOC_GRAY80*;  
612   * Sub-Intensity color. By default:  *Quantity_NOC_GRAY40*.  
613
614 All of these settings can be modified by functions proper to  the Context.  
615
616 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.  
617
618 Let us examine the case of two interactive objects: *obj1* and *obj2*:  
619
620 ~~~~~
621 TheCtx->Display(obj1,Standard_False); // False = no viewer update 
622 TheCtx->Display(obj2,Standard_True); // True = viewer update  
623 TheCtx->SetDisplayMode(obj1,3,Standard_False); 
624 TheCtx->SetDisplayMode(2); 
625 // obj2 is visualised in mode 2 (if it accepts this mode) 
626 // obj1 stays visualised in its mode 3.  
627 ~~~~~
628
629 *PresentationManager3D*  and a *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. 
630
631 @subsection occt_visu_3_4 Local Context 
632 @subsubsection occt_visu_3_4_1 Rules and Conventions 
633
634   * Opening a local context allows preparing an environment for  temporary presentations and selections, which will disappear once the local  context is closed. 
635   * It is possible to open several local contexts, but only the last  one will be active. 
636   * 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. 
637   * Each local context has an index created when the context opens. You  should close the local context, which you have opened. 
638
639 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*.   
640   * 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. 
641   * The state of a temporary interactive object in a local context  can only be modified while another local context is open. 
642
643 **Warning**
644
645 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.  
646
647 @subsubsection occt_visu_3_4_2 Management of Local Context
648
649 The local context can be opened using method *AIS_InteractiveContext::OpenLocalContext*. The following options are available:
650   * *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. 
651   * *AllowShapeDecomposition*: *AIS_Shape* allows or prevents  decomposition in standard shape location mode of objects at Neutral Point,  which are type-privileged (see <a href="#occt_visu_3_2_4"> Selection</a> chapter). This Flag is only taken  into account when *UseDisplayedObjects* is *TRUE*. 
652   * *AcceptEraseOfObjects*: authorises other local contexts to erase  the interactive objects present in this context. This option is rarely used.  The last option has no current use. 
653
654 This function returns the index of the created local context.  It should be kept and used when the context is closed.  
655
656 To load objects visualized at Neutral Point into a local  context or remove them from it use methods
657 ~~~~~ 
658   AIS_InteractiveContext::UseDisplayedObjects  
659   AIS_InteractiveContext::NotUseDisplayedObjects  
660 ~~~~~
661 Closing Local Contexts is done by:  
662 ~~~~~
663   AIS_InteractiveContext::CloseLocalContext  
664   AIS_InteractiveContext::CloseAllContexts  
665 ~~~~~
666
667 *Warning* 
668 When the index isn’t 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. 
669
670 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.  
671
672 When you close a local context, all temporary interactive  objects are deleted, all selection modes concerning the context are  cancelled, and all content filters are emptied.  
673
674
675 @subsubsection occt_visu_3_4_3 Presentation in a Neutral Point 
676
677 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.
678
679 Neutral Point should be used to visualize the interactive  objects, which represent and select an applicative entity. Visualization and  Erasing orders are straightforward: 
680
681 ~~~~~
682 AIS_InteractiveContext::Display  
683         (const  Handle(AIS_InteractiveObject)& anIobj, 
684          const  Standard_Boolean updateviewer=Standard_True);  
685
686 AIS_InteractiveContext::Display  
687         (const  Handle(AIS_InteractiveObject)& anIobj,  
688          const  Standard_Integer amode, 
689          const  Standard_Integer aSelectionMode, 
690          const  Standard_Boolean updateviewer = Standard_True,  
691          const  Standard_Boolean allowdecomposition =  Standard_True);  
692
693   AIS_InteractiveContext::Erase  
694   AIS_InteractiveContext::EraseMode  
695   AIS_InteractiveContext::ClearPrs  
696   AIS_InteractiveContext::Redisplay  
697   AIS_InteractiveContext::Remove  
698   AIS_InteractiveContext::EraseAll  
699   AIS_InteractiveContext::Hilight  
700   AIS_InteractiveContext::HilightWithColor  
701 ~~~~~
702   
703 Bear in mind the following points:  
704   * It is recommended to display and erase interactive objects when  no local context is opened, and open a local context for local selection only.
705   * 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). 
706   * 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.
707   * 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. 
708   * 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. 
709   * 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. 
710   * *Erase()* with *putInCollector = Standard_True*  might be slow as it computes again the object presentation in the Collector. Set *putInCollector* to *Standard_False* if you simply want to hide the object’s  presentation temporarily.
711   * 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. 
712   * 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.
713
714 @subsubsection occt_visu_3_4_4 Presentation in Local Context 
715
716 In open local context, the *Display* functions presented above can be as well.  
717
718 **WARNING** 
719
720 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*.  
721
722 You can activate or deactivate specific selection modes in the local open context in several different ways:  
723 Use the Display functions with the appropriate modes.
724    
725 ~~~~~
726   AIS_InteractiveContext::ActivateStandardMode
727   //can be used only if a  Local Context is opened.   
728   AIS_InteractiveContext::DeactivateStandardMode  
729   AIS_InteractiveContext::ActivatedStandardModes  
730   AIS_InteractiveContext::SetShapeDecomposition  
731 ~~~~~
732
733 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.  
734
735 **WARNING**
736
737 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)*.  
738
739 Load an interactive object by the function *AIS_InteractiveContext::Load*.  
740
741 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.  
742
743 Use *AIS_InteractiveContext::Activate* and *AIS_InteractiveContext::Deactivate* to directly activate/deactivate selection modes on an object.
744
745 @subsubsection occt_visu_3_4_5 Filters 
746
747 When Interactive objects have been "prepared" in the local  context, you can add rejection filters. 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.  
748
749 You can create a custom class of filter objects by  implementing the deferred function *IsOk()*:  
750
751 ~~~~~
752 class MyFilter : public SelectMgr_Filter { };  
753 virtual Standard_Boolean MyFilter::IsOk  
754         (const Handle(SelectMgr_EntityOwner)&  anObj) const = 0; 
755 ~~~~~
756
757 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*).  
758
759 There are Standard filters, which have already been  implemented in several packages:  
760   * *StdSelect_EdgeFilter* - for edges, such as lines and circles;  
761   * *StdSelect_FaceFilter* - for faces, such as planes, cylinders and spheres;  
762   * *StdSelect_ShapeTypeFilter* - for shape types, such as compounds, solids, shells and wires;  
763   * *AIS_TypeFilter* - for types  of interactive objects;  
764   * *AIS_SignatureFilter* - for types  and signatures of interactive objects; 
765   * *AIS_AttributeFilter* - for attributes of Interactive Objects, such as color and width.  
766
767 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*.  
768
769 **WARNING**
770  
771 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.  
772
773 There are several functions to manipulate filters:  
774 * *AIS_InteractiveContext::AddFilter* adds a filter passed as an argument.  
775 * *AIS_InteractiveContext::RemoveFilter* removes a filter passed as an argument.  
776 * *AIS_InteractiveContext::RemoveFilters* removes all present filters.  
777 * *AIS_InteractiveContext::Filters* gets the list of filters active in a local context.  
778   
779 <h4>Example </h4>
780
781 ~~~~~
782 myContext->OpenLocalContext(Standard_False);  
783 // no object in neutral point is  loaded  
784
785 myContext->ActivateStandardMode(TopAbs_Face);  
786 //activates decomposition of  shapes into faces.  
787 Handle (AIS_Shape) myAIShape = new AIS_Shape (  ATopoShape);  
788
789 myContext->Display(myAIShape,1,-1,Standard_True,Standard_True);  
790
791 //shading visualization mode,  no specific mode, authorization for decomposition into sub-shapes. At this  Stage, myAIShape is decomposed into faces...  
792
793 Handle(StdSelect_FaceFilter) Fil1= new  
794         StdSelect_FaceFilter(StdSelect_Revol);   
795 Handle(StdSelect_FaceFilter) Fil2= new 
796       StdSelect_FaceFilter(StdSelect_Plane);  
797
798 myContext->AddFilter(Fil1);   
799 myContext->AddFilter(Fil2);  
800
801 //only faces of revolution or  planar faces will be selected 
802       
803 myContext->MoveTo( xpix,ypix,Vue);  
804 // detects the mouse position  
805 ~~~~~
806
807 @subsubsection occt_visu_3_4_6 Selection in the Local Context
808  
809 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:   
810   * *AIS_InteractiveContext::MoveTo* - passes  mouse position to Interactive Context selectors  
811   * *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  
812   * *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.  
813   * *AIS_InteractiveContext::Select* selects  everything found in the surrounding area.  
814   * *AIS_InteractiveContext::ShiftSelect* selects  what was not previously in the list of selected, deselects those already present.  
815
816 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 :  
817 ~~~~~
818   AIS_InteractiveContext::SetAutomaticHilight  
819   AIS_InteractiveContext::AutomaticHilight  
820 ~~~~~
821
822 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.  
823
824 **WARNING**
825
826 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. 
827
828 You can  question the Interactive context by moving the mouse. The following functions can be used:  
829   * *AIS_InteractiveContext::HasDetected* informs if something has been detected; 
830   * *AIS_InteractiveContext::HasDetectedShape* informs if it is a shape; 
831   * *AIS_InteractiveContext::DetectedShape* gets the shape if the detected entity is an object;
832   * *AIS_InteractiveContext::DetectedInteractive* gets the interactive object if the detected entity is an object. 
833
834 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:    
835   * *AIS_InteractiveContext::InitCurrent* initiates a scan of this list; 
836   * *AIS_InteractiveContext::MoreCurrent* extends the scan; 
837   * *AIS_InteractiveContext::NextCurrent* resumes the scan; 
838   * *AIS_InteractiveContext::Current* gets the name of the current object  detected in the scan; 
839   * *AIS_InteractiveContext::FirstCurrentObject* gets the first current interactive object; 
840   * *AIS_InteractiveContext::HilightCurrents* highlights current objects; 
841   * *AIS_InteractiveContext::UnhilightCurrents* removes highlight from current objects; 
842   * *AIS_InteractiveContext::ClearCurrents* empties the list of current objects in order to update it; 
843   * *AIS_InteractiveContext::IsCurrent* finds the current object. 
844
845 In the Local Context, you can explore the list of selected  objects available. The following functions can be used:    
846   * *AIS_InteractiveContext::InitSelected* initiates the list of objects; 
847   * *AIS_InteractiveContext::MoreSelected* extends the list of objects; 
848   * *AIS_InteractiveContext::NextSelected* resumes a scan;
849   * *AIS_InteractiveContext::SelectedShape* gets the name of the selected object; 
850   * *AIS_InteractiveContext::HasSelectedShape* checks if the selected shape is obtained; 
851   * *AIS_InteractiveContext::Interactive* gets the picked interactive object; 
852   * *AIS_InteractiveContext::HasApplicative* checks if the applicative object has an owner from  Interactive attributed to it; 
853   * *AIS_InteractiveContext::Applicative* gets the owner of the detected applicative entity; 
854   * *AIS_InteractiveContext::IsSelected* gets the name of the selected object. 
855
856
857 <h4>Example </h4>
858 ~~~~~
859 myAISCtx->InitSelected();  
860 while (myAISCtx->MoreSelected())  
861         { 
862         if  (myAISCtx->HasSelectedShape) 
863                 { 
864                 TopoDS_Shape  ashape = myAISCtx->SelectedShape(); 
865                         // to be able  to use the picked shape 
866                                     }  
867                 else  
868                 { 
869                 Handle_AIS_InteractiveObject  anyobj = myAISCtx->Interactive(); 
870                 // to be able to use the picked interactive object  
871                 }  
872 myAISCtx->NextSelected();  
873 }     
874 ~~~~~
875
876 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:  
877   * *AIS_InteractiveContext::EraseSelected* erases the selected objects; 
878   * *AIS_InteractiveContext::DisplaySelected* displays them; 
879   * *AIS_InteractiveContext::SetSelected* puts the objects in the list of  selections;
880   * *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;
881   * *AIS_InteractiveContext::AddOrRemoveSelected* adds or removes an object from the list of selected entities; 
882   * *AIS_InteractiveContext::HilightSelected* highlights the selected object;
883   * *AIS_InteractiveContext::UnhilightSelected* removes highlighting from the selected object; 
884   * *AIS_InteractiveContext::ClearSelected* empties the list of selected objects. 
885
886
887 You can highlight and remove highlighting from a current  object, and empty the list of current objects using the following functions:  
888 ~~~~~
889   AIS_InteractiveContext::HilightCurrents  
890   AIS_InteractiveContext::UnhilightCurrents  
891   AIS_InteractiveContext::ClearCurrents  
892 ~~~~~
893 When you are in an open Local Context, you may need to keep  "temporary" interactive objects. This is possible using the following functions: 
894   * *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.  
895   * *AIS_InteractiveContext::SetSelectedCurrent* allows the selected object to become the current object when you  close the local context.  
896
897 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). 
898
899 @subsubsection occt_visu_3_4_7 Recommendations 
900
901 The possibilities of use for local contexts are numerous  depending on the type of operation that you want to perform:  
902   * working on all visualized interactive objects, 
903   * working on only a few objects, 
904   * working on a single object. 
905
906 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:  
907
908 ~~~~~
909 AIS_InteractiveContext::DisplayedObjects (AIS_ListOfInteractive&  aListOfIO) const;  
910 AIS_InteractiveContext::DisplayedObjects (const AIS_KindOfInteractive  WhichKind, const Standard_Integer  WhichSignature;
911 AIS_ListOfInteractive&  aListOfIO) const;  
912 ~~~~~
913
914 At this stage, you only have to load the functions *Load, Activate,* and so on.  
915
916 When you open a Local Context with default options, you  must keep the following points in mind:  
917 * 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.  
918 * The Shape Type  Interactive Objects are automatically decomposed into sub-shapes when standard  activation modes are launched.  
919 * 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.  
920
921 The stages could be the following:
922   1. Open  a Local Context with the right options;  
923   2. Load/Visualize  the required complementary objects with the desired activation modes.  
924   3. Activate  Standard modes if necessary  
925   4. Create  its filters and add them to the Local Context  
926   5. Detect/Select/recover  the desired entities  
927   6. Close  the Local Context with the adequate index.  
928
929 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. 
930  
931 Let us assume that you have visualized several types of interactive objects: *AIS_Points*,  *AIS_Axes*, *AIS_Trihedrons*, and *AIS_Shapes*.  
932
933 For your applicative function, you need an axis to create a  revolved object. You could obtain this axis by identifying:  
934   * an axis which is already visualized,
935   * 2 points,
936   * a rectilinear edge on the shapes which are present,
937   * a cylindrical face on the shapes (You will take the axis of this  face) 
938
939 ~~~~~
940 myIHMEditor::myIHMEditor  
941         (const  Handle(AIS_InteractiveContext)& Ctx, 
942          ....) : 
943          myCtx(Ctx),  
944         ...  
945
946
947
948 myIHMEditor::PrepareContext() 
949
950 myIndex =myCtx->OpenLocalContext();  
951
952 //the filters  
953
954 Handle(AIS_SignatureFilter) F1 = new  AIS_SignatureFilter(AIS_KOI_Datum,AIS_SD_Point);   
955 //filter on the points  
956
957 Handle(AIS_SignatureFilter) F2 = new AIS_SignatureFilter(AIS_KOI_Datum,AIS_SD_Axis);   
958 //filters on the axes.  
959
960 Handle(StdSelect_FaceFilter) F3 = new StdSelect_FaceFilter(AIS_Cylinder);   
961 //cylindrical face filters  
962 //... 
963 // activation of standard modes  on the shapes..  
964 myCtx->ActivateStandardMode(TopAbs_FACE); 
965 myCtx->ActivateStandardMode(TopAbs_VERTEX); 
966 myCTX->Add(F1); 
967 myCTX->Add(F2); 
968 myCTX->Add(F3);  
969
970 // at  this point, you can call the selection/detection function  
971
972
973 void myIHMEditor::MoveTo(xpix,ypix,Vue) 
974
975 {  myCTX->MoveTo(xpix,ypix,vue);  
976 // the highlight of what is  detected is automatic.  
977 }      
978 Standard_Boolean myIHMEditor::Select()  
979 {
980 // returns true if you should  continue the selection      
981                 myCTX->Select();   
982                 myCTX->InitSelected();  
983                 if(myCTX->MoreSelected()) 
984                  {
985                  if(myCTX->HasSelectedShape())     
986                 { const  TopoDS_Shape& sh = myCTX->SelectedShape(); 
987                 if(  vertex){  
988                         if(myFirstV...)   
989                         {  
990                         //if it is the  first vertex, you stock it, then you deactivate the faces and only keep the  filter on the points: 
991                         mypoint1 =  ....; 
992                         myCtx->RemoveFilters(); 
993                         myCTX->DeactivateStandardMode(TopAbs_FACE);   
994                         myCtx->Add(F1);   
995                         // the filter  on the AIS_Points  
996                         myFirstV = Standard_False;  
997                         return Standard_True;  
998                          }
999                         else
1000                          { 
1001                         mypoint2 =...;  
1002                         //  construction of the axis return Standard_False;  
1003                         } 
1004                  } 
1005                  else  
1006                   {  
1007                 //it is a  cylindrical face : you recover the axis; visualize it; and stock it.  
1008                 return  Standard_False;  
1009                 }  
1010                   }  
1011                 // it is not  a shape but is no doubt a point.  
1012                 else  
1013                 {  
1014                 Handle(AIS_InteractiveObject)   
1015                 SelObj =  myCTX->SelectedInteractive(); 
1016                 if(SelObj->Type()==AIS_KOI_Datum)   
1017                 { 
1018                         if(SelObj->Signature()==1)   
1019                         { 
1020                                 if  (firstPoint) 
1021                                 { 
1022                                 mypoint1  =...  
1023                                 return  Standard_True;  
1024                                 } 
1025                                 else 
1026                                 {  
1027                                 mypoint2 =  ...;  
1028                                 //construction  of the axis, visualization, stocking  
1029                                 return  Standard_False;  
1030                 } 
1031                 } 
1032
1033                 else  
1034                 {  
1035                 // you have  selected an axis; stock the axis  
1036                 return  Standard_False; 
1037                 } 
1038                 } 
1039                 } 
1040                 } 
1041                 }  
1042 void myIHMEditor::Terminate()
1043 {
1044 myCtx->CloseLocalContext(myIndex); 
1045 ...
1046 }
1047 ~~~~~
1048
1049 @subsection occt_visu_3_5 Standard Interactive Object Classes 
1050
1051 @subsubsection occt_visu_3_5_1 Datums
1052   
1053 *AIS_Point,  AIS_Axis,  AIS_Line,  AIS_Circle,  AIS_Plane* and *AIS_Trihedron* have four selection modes: 
1054   * mode 0 : selection of a trihedron; 
1055   * mode 1 : selection of the origin of the trihedron; 
1056   * mode 2 : selection of the axes; 
1057   * mode 3 : selection of the planes XOY, YOZ, XOZ. 
1058
1059 when you activate one of modes: 1 2 3 4, you pick AIS  objects of type:  
1060   * *AIS_Point* 
1061   * *AIS_Axis* (and information on the type of axis) 
1062   * *AIS_Plane* (and information on the type of plane). 
1063
1064 *AIS_PlaneTrihedron* offers three selection modes:  
1065   * mode 0 : selection of the whole trihedron; 
1066   * mode 1 : selection of the origin of the trihedron; 
1067   * mode 2 : selection of the axes - same remarks as for the  Trihedron. 
1068
1069 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.  
1070
1071 @subsubsection occt_visu_3_5_2 Objects 
1072
1073 *AIS_Shape* has three visualization modes :
1074   * mode 0 : Line (default mode) 
1075   * mode 1 : Shading (depending on the type of shape) 
1076   * mode 2 : Bounding Box 
1077
1078 And at maximum seven selection modes, depending on the shape complexity:
1079   * mode 0 : selection of the *AIS_Shape*; 
1080   * mode 1 : selection of the vertices; 
1081   * mode 2 : selection of the edges; 
1082   * mode 3 : selection of the wires; 
1083   * mode 4 : selection of the faces; 
1084   * mode 5 : selection of the shells; 
1085   * mode 6 : selection of the constituent solids. 
1086
1087   * *AIS_Triangulation* is a simple interactive object for displaying  triangular mesh contained in *Poly_Triangulation* container. 
1088   * *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.  
1089   * *AIS_ConnectedShape* is an object connected to interactive objects  having a shape; this class has the same decompositions as *AIS_Shape*. What’s  more, it allows a presentation of hidden parts, which are calculated  automatically from the shape of its reference.  
1090   * *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) 
1091   * *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.  
1092   * *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. 
1093   * *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. 
1094
1095 @subsubsection occt_visu_3_5_3 Relations 
1096   * *AIS_ConcentricRelation* 
1097   * *AIS_FixRelation*
1098   * *AIS_IdenticRelation* 
1099   * *AIS_ParallelRelation*
1100   * *AIS_PerpendicularRelation*
1101   * *AIS_Relation*
1102   * *AIS_SymmetricRelation*
1103   * *AIS_TangentRelation*
1104
1105 The list of relations is not exhaustive.    
1106
1107 @subsubsection occt_visu_3_5_4 Dimensions
1108   * *AIS_AngleDimension* 
1109   * *AIS_Chamf3dDimension* 
1110   * *AIS_DiameterDimension* 
1111   * *AIS_DimensionOwner*
1112   * *AIS_LengthDimension*
1113   * *AIS_OffsetDimension*
1114   * *AIS_RadiusDimension*
1115
1116   @subsubsection occt_visu_3_5_5 MeshVS_Mesh
1117
1118 *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.  
1119
1120 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.  
1121
1122 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. 
1123
1124 You can add/remove builders using the following methods: 
1125 ~~~~~
1126   MeshVS_Mesh::AddBuilder (const Handle (MeshVS_PrsBuilder) &Builder, Standard_Boolean TreatAsHilighter) 
1127   MeshVS_Mesh::RemoveBuilder (const Standard_Integer  Index) 
1128   MeshVS_Mesh::RemoveBuilderById (const Standard_Integer Id) 
1129 ~~~~~
1130
1131 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: 
1132 ~~~~~
1133   MeshVS_DMF_WireFrame
1134   MeshVS_DMF_Shading
1135   MeshVS_DMF_Shrink
1136 ~~~~~  
1137
1138 It is also possible to display  deformed mesh in wireframe, shading or shrink modes usung :  
1139 ~~~~~
1140         MeshVS_DMF_DeformedPrsWireFrame
1141         MeshVS_DMF_DeformedPrsShading  
1142         MeshVS_DMF_DeformedPrsShrink
1143 ~~~~~  
1144
1145 The following methods represent  different kinds of data :
1146 ~~~~~
1147   MeshVS_DMF_VectorDataPrs  
1148   MeshVS_DMF_NodalColorDataPrs
1149   MeshVS_DMF_ElementalColorDataPrs
1150   MeshVS_DMF_TextDataPrs
1151   MeshVS_DMF_EntitiesWithData
1152 ~~~~~  
1153
1154 The following methods provide selection  and highlighting :
1155 ~~~~~
1156   MeshVS_DMF_SelectionPrs
1157   MeshVS_DMF_HilightPrs
1158 ~~~~~  
1159
1160 *MeshVS_DMF_User* is a user-defined  mode.  
1161
1162 These values will be used by the  presentation builder. 
1163 There is also a set of selection modes flags that can be grouped in a combination of bits: 
1164   * *MeshVS_SMF_0D*
1165   * *MeshVS_SMF_Link*
1166   * *MeshVS_SMF_Face*
1167   * *MeshVS_SMF_Volume*
1168   * *MeshVS_SMF_Element* - groups *0D, Link, Face* and *Volume*  as a bit mask ;
1169   * *MeshVS_SMF_Node*
1170   * *MeshVS_SMF_All* - groups *Element* and *Node* as a bit mask; 
1171   * *MeshVS_SMF_Mesh*
1172   * *MeshVS_SMF_Group*
1173
1174 Such an object, for example, can be used for displaying the object and stored in the STL file format: 
1175
1176 ~~~~~
1177 // read the data and create a data source
1178 Handle  (StlMesh_Mesh) aSTLMesh = RWStl::ReadFile (aFileName); 
1179 Handle  (XSDRAWSTLVRML_DataSource) aDataSource = new XSDRAWSTLVRML_DataSource (aSTLMesh); 
1180
1181 // create mesh 
1182 Handle  (MeshVS_Mesh) aMesh = new MeshVS(); 
1183 aMesh->SetDataSource  (aDataSource); 
1184
1185 // use default presentation builder
1186 Handle  (MeshVS_MeshPrsBuilder) aBuilder =  new  MeshVS_MeshPrsBuilder (aMesh); 
1187 aMesh->AddBuilder  (aBuilder, Standard_True); 
1188 ~~~~~
1189
1190 *MeshVS_NodalColorPrsBuilder* allows representing a mesh  with a color scaled texture mapped on it. 
1191 To do this you should define a color  map for the color scale, pass this map to the presentation builder, 
1192 and define an appropriate value in the range of 0.0 – 1.0 for every node. 
1193
1194 The following example demonstrates how you can do this (check if the view has been set up to display textures): 
1195
1196 ~~~~~
1197 // assign nodal builder to the mesh
1198 Handle  (MeshVS_NodalColorPrsBuilder) aBuilder = new MeshVS_NodalColorPrsBuilder 
1199      (aMesh,MeshVS_DMF_NodalColorDataPrs | MeshVS_DMF_OCCMask); 
1200 aBuilder->UseTexture  (Standard_True); 
1201
1202 // prepare color map
1203 Aspect_SequenceOfColor  aColorMap; 
1204 aColorMap.Append  ((Quantity_NameOfColor) Quantity_NOC_RED); 
1205 aColorMap.Append  ((Quantity_NameOfColor) Quantity_NOC_BLUE1); 
1206
1207 // assign color scale map  values (0..1) to nodes
1208 TColStd_DataMapOfIntegerReal  aScaleMap; 
1209
1210 // iterate through the  nodes and add an node id and an appropriate value to the map
1211 aScaleMap.Bind  (anId, aValue); 
1212   
1213 // pass color map and color scale values to the builder
1214 aBuilder->SetColorMap  (aColorMap); 
1215 aBuilder->SetInvalidColor  (Quantity_NOC_BLACK); 
1216 aBuilder->SetTextureCoords  (aScaleMap); 
1217 aMesh->AddBuilder  (aBuilder, Standard_True); 
1218 ~~~~~
1219
1220 @subsection occt_visu_3_6 Dynamic Selection 
1221
1222 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. 
1223 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.  
1224
1225 @subsubsection occt_visu_3_6_1 How to go from the objects to 2D boxes 
1226
1227
1228 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.  
1229
1230 The sensitive primitive is capable of:  
1231   * giving a 2D bounding box to the selector. 
1232   * answering the rejection criteria positively or negatively by a  "Matches" function. 
1233   * being projected from 3D in the 2D space of the view if need be. 
1234   * returning the owner which it will represent in terms of  selection. 
1235
1236 A set of standard sensitive primitives exists in Select3D  packages for 3D primitives.  
1237
1238 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.  
1239
1240 @image html visualization_image021.png 
1241 @image latex visualization_image021.png 
1242
1243 @subsubsection occt_visu_3_6_2 Implementation in an interactive/selectable object 
1244    
1245 Define the number of selection modes possible, i.e. what  you want to identify by activating each of the selection modes. 
1246
1247 For example: for an  interactive object representing a topological shape:  
1248 * mode 0: selection of the interactive object itself;  
1249 * mode 1: selection of the vertices; 
1250 * mode 2: selection of the edges;  
1251 * mode 3: selection of the wires;  
1252 * mode 4: selection of the detectable faces. 
1253
1254 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.  
1255
1256 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.  
1257
1258 The set of sensitive primitives which has been calculated  for a given mode is stocked in *SelectMgr_Selection*.  
1259
1260 For an Interactive object, the modeling is done in the *ComputeSelection* virtual function.  
1261
1262 Let us consider an example of an interactive object representing a box. 
1263
1264 We are interested in two location modes: 
1265   * mode 0: location of the whole box.  
1266   * mode 1: location of the edges on the box. 
1267
1268 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*. 
1269
1270 The *ComputeSelection*  function for the interactive box can have the following form:  
1271
1272 ~~~~~
1273 void InteractiveBox::ComputeSelection  
1274         (const  Handle(SelectMgr_Selection)& Sel, 
1275          const Standard_Integer Mode)  
1276
1277         switch(Mode) 
1278                 {  case 0:   //locating the whole box by  making its faces sensitive...  
1279                 { 
1280         Handle(SelectMgr_EntityOwner)  Ownr = new SelectMgr_EntityOwner(this,5);   
1281         for(Standard_Integer  I=1;I<=Nbfaces;I++)  
1282         {  
1283         //Array is a  TColgp_Array1OfPnt: which represents the array of vertices. Sensitivity is  
1284         Select3D_TypeOfSensitivity value 
1285         Sel->Add(new  Select3D_SensitiveFace(Ownr,Array,Sensitivity));  
1286                         } 
1287                         break;  
1288            } 
1289           case 1:  
1290         // locates the edges  {  
1291         for(Standard_Integer i=1;i<=12;i++)  
1292                         { 
1293                                 // 1 owner  per edge... 
1294                                 Handle(mypk_EdgeOwner)  Ownr = new  mypk_EdgeOwner(this,i,6); 
1295                                         //6->priority 
1296                                         Sel->Add(new  Select3D_SensitiveSegment (Ownr,firstpt(i),lastpt(i)));  
1297                                         } 
1298                                 break;  
1299                         } 
1300                 } 
1301         } 
1302 ~~~~~
1303
1304 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. 
1305
1306 NOTE: This procedure is completely hidden if you use the <a href="#occt_visu_3_3"> AIS Interactive Context </a>
1307
1308 <h4>Example </h4>
1309 ~~~~~
1310 //We have several " interactive boxes " box1, box2, box3;  
1311         Handle(SelectMgr_SelectionManager) SM = new  SelectMgr_SelectionManager();  
1312         Handle(StdSelect_ViewerSelector3d) VS = new  StdSelect_ViewerSelector3d();  
1313                 SM->Add(VS); 
1314                 SM->Load(box1);SM->Load(box2);SM->Load(box3); 
1315                 // box load.  
1316                 SM->Activate(box1,0,VS); 
1317                 // activates  mode 0 of box 1 in the selector VS 
1318                 SM->Activate(box1,1,VS);   
1319                 M->Activate(box3,1,VS);   
1320 VS->Pick(xpix,ypix,vue3d)  
1321 // detection of primitives by mouse position.  
1322 Handle(EntityOwner)  POwnr = VS->OnePicked();  
1323 // picking of the "best" owner detected  
1324 for(VS->Init();VS->More();VS->Next())   
1325         { 
1326         VS->Picked();   
1327         // picking of all owners  detected  
1328           } 
1329         SM->Deactivate(box1);   
1330         // deactivate all active modes  of box1  
1331 ~~~~~
1332
1333 @section occt_visu_4 3D Presentations
1334
1335 @subsection occt_visu_4_1 Glossary of 3D terms 
1336
1337 * **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.
1338 * **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.
1339 * **Group**     - a set of primitives and attributes on those primitives. Primitives and attributes may be added to a group but cannot be removed from a group, except by erasing them globally. A group can have a pick identity.
1340 * **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.
1341 * **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.
1342 * **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. 
1343 * **View**      - is defined by a view orientation, a view mapping, and a context view.
1344 * **Viewer** - manages a set of views.
1345 * **View orientation** - defines the manner in which the observer looks at the scene in terms of View Reference Coordinates.
1346 * **View mapping** - defines the transformation from View Reference Coordinates to the Normalized Projection Coordinates. This follows the Phigs scheme.
1347 * **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.
1348
1349 @subsection occt_visu_4_2 Creating a 3D scene 
1350
1351 To create 3D graphic objects and display them on the screen,  follow the procedure below:  
1352 1. Create attributes.  
1353 2. Create a 3D viewer..  
1354 3. Create a view.  
1355 4. Create an interactive context.  
1356 5. Create interactive objects.  
1357 6. Create primitives in the interactive  object  
1358 7. Display the interactive object.  
1359
1360 @subsubsection occt_visu_4_2_1 Create attributes 
1361
1362 Create colors.  
1363
1364 ~~~~~
1365 Quantity_Color Black (Quantity_NOC_BLACK);  
1366 Quantity_Color Blue (Quantity_NOC_MATRABLUE);  
1367 Quantity_Color Brown (Quantity_NOC_BROWN4);  
1368 Quantity_Color Firebrick (Quantity_NOC_FIREBRICK);  
1369 Quantity_Color Forest (Quantity_NOC_FORESTGREEN);  
1370 Quantity_Color Gray (Quantity_NOC_GRAY70);  
1371 Quantity_Color MyColor (0.99, 0.65, 0.31,  Quantity_TOC_RGB);  
1372 Quantity_Color Beet (Quantity_NOC_BEET);  
1373 Quantity_Color White (Quantity_NOC_WHITE);  
1374 ~~~~~
1375
1376
1377 Create line attributes.  
1378
1379 ~~~~~
1380 Handle(Graphic3d_AspectLine3d)  CTXLBROWN =  new Graphic3d_AspectLine3d ();  
1381 Handle(Graphic3d_AspectLine3d)  CTXLBLUE =  new Graphic3d_AspectLine3d ();  
1382 Handle(Graphic3d_AspectLine3d)  CTXLWHITE = new Graphic3d_AspectLine3d();  
1383                                                                 CTXLBROWN->SetColor (Brown);  
1384                                                                 CTXLBLUE->SetColor (Blue);  
1385                                                                 CTXLWHITE->SetColor (White);  
1386 ~~~~~
1387
1388 Create marker attributes.  
1389 ~~~~~
1390 Handle(Graphic3d_AspectMarker3d) CTXMFIREBRICK =  new Graphic3d_AspectMarker3d();   
1391                                                                  CTXMFIREBRICK->SetColor (Firebrick);  
1392                                                                  CTXMFIREBRICK->SetScale (1.0);  
1393                                                                  CTXMFIREBRICK->SetType (Aspect_TOM_BALL);  
1394 ~~~~~
1395
1396 Create facet attributes.  
1397 ~~~~~
1398 Handle(Graphic3d_AspectFillArea3d) CTXF =  new Graphic3d_AspectFillArea3d  ();  
1399 Graphic3d_MaterialAspect BrassMaterial  (Graphic3d_NOM_BRASS);  
1400 Graphic3d_MaterialAspect GoldMaterial  (Graphic3d_NOM_GOLD);  
1401         CTXF->SetInteriorStyle (Aspect_IS_SOLID);  
1402         CTXF->SetInteriorColor (MyColor);  
1403         CTXF->SetDistinguishOn ();  
1404         CTXF->SetFrontMaterial (GoldMaterial);  
1405         CTXF->SetBackMaterial (BrassMaterial);  
1406         CTXF->SetEdgeOn ();  
1407 ~~~~~
1408
1409 Create text attributes.  
1410 ~~~~~
1411 Handle(Graphic3d_AspectText3d) CTXT =  new  Graphic3d_AspectText3d  (Forest,  Graphic3d_NOF_ASCII_MONO, 1., 0.);  
1412 ~~~~~
1413
1414 @subsubsection occt_visu_4_2_2 Create a 3D Viewer (a Windows example) 
1415
1416 ~~~~~
1417 Handle(Aspect_DisplayConnection) aDisplayConnection; 
1418 Handle(Graphic3d_GraphicDriver) aGraphicDriver =  Graphic3d::InitGraphicDriver (aDisplayConnection); 
1419 TCollection_ExtendedString aName("3DV"); 
1420 myViewer = new V3d_Viewer (aGraphicDriver,aName.ToExtString  (), ""); 
1421 myViewer -> SetDefaultLights ();  
1422 myViewer -> SetLightOn ();  
1423 ~~~~~
1424
1425 @subsubsection occt_visu_4_2_3 Create a 3D view (a Windows example) 
1426
1427 It is assumed that a valid Windows window may already be  accessed via the method *GetSafeHwnd()*.  
1428 ~~~~~
1429 Handle (WNT_Window) aWNTWindow;
1430 aWNTWindow = new WNT_Window (GetSafeHwnd());
1431 myView = myViewer -> CreateView();
1432 myView -> SetWindow (a WNTWindow);
1433 ~~~~~
1434
1435 @subsubsection occt_visu_4_2_4 Create an interactive context 
1436
1437 ~~~~~
1438 myAISContext = new AIS_InteractiveContext (myViewer);  
1439 ~~~~~
1440
1441 You are now able to display interactive objects such as an  *AIS_Shape*.  
1442
1443 ~~~~~
1444 TopoDS_Shape aShape = BRepAPI_MakeBox(10,20,30)_Solid();  
1445 Handle (AIS_Shape) aAISShape = new AIS_Shape(aShape);  
1446 myAISContext -> Display (aAISShape);  
1447 ~~~~~
1448
1449 @subsubsection occt_visu_4_2_5 Create your own interactive object 
1450
1451 Follow the procedure below to compute the  presentable object:  
1452
1453 1. Build  a presentable object inheriting from *AIS_InteractiveObject* (refer to the  Chapter on Presentable Objects).  
1454 2. Reuse  the *Prs3d_Presentation* provided as an argument of the compute methods.  
1455
1456 **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.
1457
1458
1459 Let us look at the example of compute methods
1460
1461 ~~~~~
1462 Void 
1463 myPresentableObject::Compute  
1464         (const  Handle(PrsMgr_PresentationManager3d)&  
1465                 aPresentationManager,   
1466                 const  Handle(Prs3d_Presentation)& aPrs,  
1467                 const  Standard_Integer aMode) 
1468
1469 //...  
1470 )  
1471
1472 void 
1473 myPresentableObject::Compute  
1474                 (const  Handle(Prs3d_Projector)&,  
1475                 const Handle(Prs3d_Presentation)&  aPrs)  
1476 (  
1477 //...  
1478 )  
1479 ~~~~~
1480
1481 @subsubsection occt_visu_4_2_6 Create primitives in the interactive object 
1482
1483 Get the group used in *Prs3d_Presentation*.  
1484
1485 ~~~~~
1486 Handle(Graphic3d_Group) TheGroup =  Prs3d_Root::CurrentGroup(aPrs);  
1487 ~~~~~
1488
1489 Update the group attributes.  
1490
1491 ~~~~~
1492 TheGroup -> SetPrimitivesAspect(CTXLBLUE);  
1493 ~~~~~
1494
1495 Create two triangles in *TheGroup*.  
1496
1497 ~~~~~
1498 Standard_Integer aNbTria = 2; 
1499 Handle(Graphic3d_ArrayOfTriangles) aTriangles = new  Graphic3d_ArrayOfTriangles(3 * aNbTria, 0, Standard_True); 
1500 Standard_Integer anIndex; 
1501 for (anIndex = 1; anIndex <= aNbTria; nt++) 
1502
1503   aTriangles->AddVertex(anIndex * 5., 0., 0., 1., 1.,  1.); 
1504   aTriangles->AddVertex(anIndex * 5 + 5, 0., 0., 1.,  1., 1.); 
1505   aTriangles->AddVertex(anIndex * 5 + 2.5, 5., 0., 1.,  1., 1.); 
1506
1507 TheGroup->BeginPrimitives (); 
1508 mygroup->AddPrimitiveArray(aTriangles); 
1509 TheGroup->EndPrimitives (); 
1510 ~~~~~
1511
1512 The *BeginPrimitives()* and *EndPrimitives()* methods are used  when creating a set of various primitives in the same group.  
1513 Use the polyline function to create a boundary box for the *Struct* structure in group *TheGroup*.  
1514
1515 ~~~~~
1516 Standard_Real Xm, Ym, Zm, XM, YM, ZM;  
1517 Struct->MinMaxValues (Xm, Ym, Zm, XM, YM, ZM);   
1518
1519 Handle(Graphic3d_ArrayOfPolylines)  aPolylines = new Graphic3d_ArrayOfPolylines(16, 4); 
1520 aPolylines->AddBound (4); 
1521 aPolylines->AddVertex (Xm,  Ym, Zm); 
1522 aPolylines->AddVertex (Xm,  Ym, ZM); 
1523 aPolylines->AddVertex (Xm,  YM, ZM); 
1524 aPolylines->AddVertex (Xm,  YM, Zm); 
1525 aPolylines->AddBound (4); 
1526 aPolylines->AddVertex (Xm,  Ym, Zm); 
1527 aPolylines->AddVertex (XM,  Ym, Zm); 
1528 aPolylines->AddVertex (XM,  Ym, ZM); 
1529 aPolylines->AddVertex (XM,  YM, ZM); 
1530 aPolylines->AddBound (4); 
1531 aPolylines->AddVertex (XM,  YM, Zm); 
1532 aPolylines->AddVertex (XM,  Ym, Zm); 
1533 aPolylines->AddVertex (XM,  YM, Zm); 
1534 aPolylines->AddVertex (Xm,  YM, Zm); 
1535 aPolylines->AddBound (4); 
1536 aPolylines->AddVertex (Xm,  YM, ZM); 
1537 aPolylines->AddVertex (XM,  YM, ZM); 
1538 aPolylines->AddVertex (XM,  Ym, ZM); 
1539 aPolylines->AddVertex (Xm,  Ym, ZM); 
1540
1541 TheGroup->BeginPrimitives  (); 
1542 TheGroup->AddPrimitiveArray(aPolylines); 
1543 TheGroup->EndPrimitives  (); 
1544 ~~~~~
1545
1546 Create text and markers in group *TheGroup*.  
1547
1548 ~~~~~
1549 static char *texte[3] = {   "Application title",  
1550                                                         "My  company",  
1551                                                         "My company address." };  
1552 Graphic3d_Array1OfVertex Tpts8 (0, 1);  
1553 Tpts8(0).SetCoord (-40.0, -40.0, -40.0);  
1554 Tpts8(1).SetCoord (40.0, 40.0, 40.0);  
1555 TheGroup->MarkerSet (Tpts8);  
1556 Graphic3d_Vertex Marker (0.0, 0.0, 0.0);  
1557
1558 for (i=0; i<=2; i++) {  
1559   Marker.SetCoord (-(Standard_Real)i*4 + 30, 
1560                     (Standard_Real)i*4, 
1561                    -(Standard_Real)i*4);  
1562   TheGroup->Text (texte[i], Marker, 20.); 
1563 }  
1564 ~~~~~
1565
1566 @section occt_visu_5 3D Resources
1567
1568 The 3D resources include the *Graphic3d* and *V3d* packages.  
1569
1570 @subsection occt_visu_5_1 Graphic3D Package
1571
1572 @subsubsection occt_visu_5_1_1 Overview 
1573
1574 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. 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.  
1575
1576 @subsubsection occt_visu_5_1_2 Provided services 
1577
1578 Graphic structures can be:  
1579   * Displayed, 
1580   * Highlighted, 
1581   * Erased, 
1582   * Transformed, 
1583   * Connected to form a tree.
1584   
1585 There are classes for: 
1586   * Visual attributes for lines, faces, markers, text, materials, 
1587   * Vectors and vertices, 
1588   * Graphic objects, groups, and structures. 
1589
1590 @subsubsection occt_visu_5_1_3 About the primitives 
1591
1592 * **Markers** 
1593   * Have one or more vertices, 
1594   * Have a type, a scale factor, and a color, 
1595   * Have a size, shape, and orientation independent of  transformations. 
1596 * **Polygons** 
1597   * Have one closed boundary, 
1598   * Have at least three vertices, 
1599   * Are planar and have a normal, 
1600   * Have interior attributes - style, color, front and back material,  texture and reflection ratio, 
1601   * Have a boundary with the following attributes - type, width scale  factor, color. The boundary is only drawn when the interior style is hollow. 
1602
1603 * **Polygons with holes** 
1604   * Have multiple closed boundaries, each one with at least three  vertices, 
1605   * Are planar and have a normal, 
1606   * Have interior attributes - style, color, front and back material,  
1607   * Have a boundary with the following attributes - type, width scale  factor, color. The boundary is only drawn when the interior style is hollow. 
1608
1609 * **Polylines** 
1610   * Have two or more vertices, 
1611   * Have the following attributes - type, width scale factor, color. 
1612
1613 * **Text** 
1614   * Has geometric and non-geometric attributes, 
1615   * Geometric attributes - character height, character up vector,  text path, horizontal and vertical alignment, orientation, three-dimensional  position, zoomable flag
1616   * Non-geometric attributes - text font, character spacing,  character expansion factor, color. 
1617
1618 @subsubsection occt_visu_5_1_4 Primitive  arrays
1619
1620 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. 
1621
1622 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.  
1623
1624 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: 
1625   
1626 The following example shows how to disable the VBO support:  
1627
1628 ~~~~~
1629 // get the graphic  driver
1630 Handle (Graphic3d_GraphicDriver) aDriver =  
1631   myAISContext->CurrentViewer()->Driver(); 
1632
1633 // disable VBO support
1634 aDriver->EnableVBO (Standard_False); 
1635 ~~~~~
1636
1637 **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*. 
1638
1639 The different types of primitives could be presented with  the following primitive arrays: 
1640   * *Graphic3d_ArrayOfPoints,*
1641   * *Graphic3d_ArrayOfPolygons,*
1642   * *Graphic3d_ArrayOfPolylines,*
1643   * *Graphic3d_ArrayOfQuadrangles,*
1644   * *Graphic3d_ArrayOfQuadrangleStrips,*
1645   * *Graphic3d_ArrayOfSegments,*
1646   * *Graphic3d_ArrayOfTriangleFans,*
1647   * *Graphic3d_ArrayOfTriangles,*
1648   * *Graphic3d_ArrayOfTriangleStrips.*
1649
1650 The *Graphic3d_ArrayOfPrimitives* is a base class for these  primitive arrays. 
1651
1652 Method *Graphic3d_ArrayOfPrimitives::AddVertex* allows adding There is a set of similar methods to add vertices to the  primitive array.
1653
1654 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. 
1655
1656 You can also modify the values assigned to the vertex or  query these values by the vertex index: 
1657   * *void Graphic3d_ArrayOfPrimitives::SetVertice*
1658   * *void  Graphic3d_ArrayOfPrimitives::SetVertexColor*
1659   * *void  Graphic3d_ArrayOfPrimitives::SetVertexNormal*
1660   * *void  Graphic3d_ArrayOfPrimitives::SetVertexTexel*
1661   * *gp_Pnt  Graphic3d_ArrayOfPrimitives::Vertices*
1662   * *gp_Dir   Graphic3d_ArrayOfPrimitives::VertexNormal*
1663   * *gp_Pnt3d  Graphic3d_ArrayOfPrimitives::VertexTexel*
1664   * *Quantity_Color  Graphic3d_ArrayOfPrimitives::VertexColor*
1665   * *void  Graphic3d_ArrayOfPrimitives::Vertices*
1666   * *void  Graphic3d_ArrayOfPrimitives::VertexNormal*
1667   * *void  Graphic3d_ArrayOfPrimitives::VertexTexel*
1668   * *void  Graphic3d_ArrayOfPrimitives::VertexColor*
1669
1670 The following example shows how to define an array of  points: 
1671
1672 ~~~~~
1673 // create an array
1674 Handle (Graphic3d_ArrayOfPoints) anArray = new Graphic3d_ArrayOfPoints (aVerticiesMaxCount); 
1675
1676 // add vertices to the array
1677 anArray->AddVertex  (10.0, 10.0, 10.0); 
1678 anArray->AddVertex  (0.0, 10.0, 10.0); 
1679
1680 // add the array to the structure
1681 Handle (Graphic3d_Group) aGroup  =  Prs3d_Root::CurrentGroup (aPrs); 
1682 aGroup->BeginPrimitives (); 
1683 aGroup->AddPrimitiveArray (anArray); 
1684 aGroup->EndPrimitives (); 
1685 ~~~~~
1686
1687 If the primitives share the same vertices (polygons,  triangles, etc.) then you can define them as indices of the vertices array. 
1688
1689 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. 
1690
1691 It is also possible to query the vertex defined by an edge using method *Graphic3d_ArrayOfPrimitives::Edge*
1692
1693 The following example shows how to define an array of  triangles: 
1694
1695 ~~~~~
1696 // create an array
1697 Standard_Boolean  IsNormals     = Standard_False;  
1698 Standard_Boolean  IsColors      = Standard_False; 
1699 Standard_Boolean  IsTextureCrds = Standard_False; 
1700 Handle (Graphic3d_ArrayOfTriangles) anArray =  
1701           new Graphic3d_ArrayOfTriangles (aVerticesMaxCount, 
1702                                           aEdgesMaxCount, 
1703                                           IsNormals, 
1704                                           IsColors, 
1705                                           IsTextureCrds); 
1706 // add vertices to the array
1707 anArray->AddVertex  (-1.0, 0.0, 0.0);   // vertex 1
1708 anArray->AddVertex  ( 1.0, 0.0, 0.0);   // vertex 2
1709 anArray->AddVertex  ( 0.0, 1.0, 0.0);   // vertex 3 
1710 anArray->AddVertex  ( 0.0,-1.0, 0.0);   // vertex 4 
1711
1712 // add edges to the array
1713 anArray->AddEdge  (1);  // first triangle
1714 anArray->AddEdge  (2); 
1715 anArray->AddEdge  (3); 
1716 anArray->AddEdge  (1);  // second triangle
1717 anArray->AddEdge  (2); 
1718 anArray->AddEdge  (4); 
1719
1720 // add the array to the structure
1721 Handle  (Graphic3d_Group) aGroup =  Prs3d_Root::CurrentGroup (aPrs); 
1722 aGroup->BeginPrimitives  (); 
1723 aGroup->AddPrimitiveArray  (anArray); 
1724 aGroup->EndPrimitives  (); 
1725 ~~~~~
1726
1727 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. 
1728
1729 It is also possible to set the color and query the number of  edges in the bound and bound color. 
1730 ~~~~~
1731   Standard_Integer  Graphic3d_ArrayOfPrimitives::Bound
1732   Quantity_Color  Graphic3d_ArrayOfPrimitives::BoundColor
1733   void  Graphic3d_ArrayOfPrimitives::BoundColor
1734 ~~~~~
1735
1736 The following example shows how to define an array of  polygons: 
1737
1738 ~~~~~
1739 // create an array
1740 Standard_Boolean  IsNormals      = Standard_False;  
1741 Standard_Boolean  IsVertexColors = Standard_False; 
1742 Standard_Boolean  IsFaceColors   = Standard_False; 
1743 Standard_Boolean  IsTextureCrds  = Standard_False; 
1744 Handle (Graphic3d_ArrayOfPolygons) anArray =  
1745           new Graphic3d_ArrayOfPolygons (aVerticesMaxCount, 
1746                                          aBoundsMaxCount, 
1747                                          aEdgesMaxCount, 
1748                                          IsNormals, 
1749                                          IsVertexColors, 
1750                                          IsFaceColors, 
1751                                          IsTextureCrds); 
1752
1753 // add bounds to the array, first polygon
1754 anArray->AddBound (3);  
1755 anArray->AddVertex (-1.0,  0.0, 0.0);    
1756 anArray->AddVertex  ( 1.0, 0.0, 0.0);    
1757 anArray->AddVertex  ( 0.0, 1.0, 0.0);    
1758
1759 // add bounds to the array, second polygon
1760 anArray->AddBound (4); 
1761 anArray->AddVertex (-1.0,  0.0, 0.0);    
1762 anArray->AddVertex  ( 1.0, 0.0, 0.0);    
1763 anArray->AddVertex  ( 1.0,-1.0, 0.0);    
1764 anArray->AddVertex  (-1.0,-1.0, 0.0);    
1765
1766 // add the array to the structure 
1767 Handle  (Graphic3d_Group) aGroup = Prs3d_Root::CurrentGroup  (aPrs); 
1768 aGroup->BeginPrimitives  (); 
1769 aGroup->AddPrimitiveArray  (anArray); 
1770 aGroup->EndPrimitives  (); 
1771 ~~~~~
1772
1773 There are also several helper methods. You can get the type  of the primitive array: 
1774 ~~~~~
1775   Graphic3d_TypeOfPrimitiveArray 
1776   Graphic3d_ArrayOfPrimitives::Type
1777   Standard_CString  Graphic3d_ArrayOfPrimitives::StringType
1778 ~~~~~
1779
1780 and check if the primitive array provides normals, vertex colors and vertex texels (texture coordinates): 
1781
1782 ~~~~~
1783   Standard_Boolean Graphic3d_ArrayOfPrimitives::HasVertexNormals
1784   Standard_Boolean Graphic3d_ArrayOfPrimitives::HasVertexColors
1785   Standard_Boolean Graphic3d_ArrayOfPrimitives::HasVertexTexels
1786 ~~~~~
1787 or get the number of vertices, edges and bounds: 
1788 ~~~~~
1789   Standard_Integer Graphic3d_ArrayOfPrimitives::VertexNumber
1790   Standard_Integer Graphic3d_ArrayOfPrimitives::EdgeNumber
1791   Standard_Integer Graphic3d_ArrayOfPrimitives::BoundNumber
1792 ~~~~~
1793   
1794 @subsubsection occt_visu_5_1_5 Materials 
1795
1796 A *material* is defined by :  
1797   * Transparency, 
1798   * Diffuse reflection - a component of the object color;
1799   * Ambient reflection;
1800   * Specular reflection - a component of the color of the light source.
1801
1802 The following items are  required to determine the three colors of reflection:  
1803   * Color, 
1804   * Coefficient of diffuse reflection, 
1805   * Coefficient of ambient reflection, 
1806   * Coefficient of specular reflection. 
1807
1808 @subsubsection occt_visu_5_1_6 Textures 
1809
1810 A *texture* is defined by a name.  
1811 Three types of texture are available:  
1812   * 1D, 
1813   * 2D, 
1814   * Environment mapping. 
1815
1816 @subsubsection occt_visu_5_1_7 Graphic3d text  
1817
1818 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.  
1819 *Graphic3d* text primitives have the following features: 
1820   * fixed size (non-zoomable) or zoomable, 
1821   * can be rotated to any angle in the view plane,
1822   * support unicode charset.
1823
1824 The text attributes for the group could be defined with the *Graphic3d_AspectText3d* attributes group. 
1825 To add any text to the graphic structure you can use the  following methods: 
1826 ~~~~~
1827  void Graphic3d_Group::Text
1828                         (const Standard_CString AText, 
1829                          const Graphic3d_Vertex& APoint, 
1830                          const Standard_Real AHeight, 
1831                          const Quantity_PlaneAngle AAngle, 
1832                          const Graphic3d_TextPath ATp, 
1833                          const Graphic3d_HorizontalTextAlignment  AHta, 
1834                          const Graphic3d_VerticalTextAlignment  AVta, 
1835                          const Standard_Boolean EvalMinMax), 
1836 ~~~~~                   
1837 *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). 
1838
1839 *ATp* parameter defines the text path, *AHta* is the horizontal alignment of the text,  *AVta* is the vertical alignment of the text. 
1840
1841 You can  pass *Standard_False* as *EvalMinMax* if you don’t want the graphic3d structure  boundaries to be affected by the text position.  
1842
1843 **Note** that the text orientation angle can be defined by *Graphic3d_AspectText3d* attributes. 
1844 ~~~~~
1845   void  Graphic3d_Group::Text
1846                         (const Standard_CString AText, 
1847                          const Graphic3d_Vertex& APoint, 
1848                          const Standard_Real AHeight, 
1849                          const Standard_Boolean EvalMinMax) 
1850   void  Graphic3d_Group::Text
1851                         (const TCcollection_ExtendedString  &AText,  
1852                          const Graphic3d_Vertex& APoint, 
1853                          const Standard_Real AHeight, 
1854                          const Quantity_PlaneAngle AAngle, 
1855                          const Graphic3d_TextPath ATp, 
1856                          const Graphic3d_HorizontalTextAlignment  AHta, 
1857                          const Graphic3d_VerticalTextAlignment  AVta, 
1858                          const Standard_Boolean EvalMinMax) 
1859   void  Graphic3d_Group::Text
1860                         (const TCcollection_ExtendedString  &AText,  
1861                          const Graphic3d_Vertex& APoint, 
1862                          const Standard_Real AHeight, 
1863                          const Standard_Boolean EvalMinMax) 
1864 ~~~~~
1865
1866 See the example:
1867 ~~~~~
1868 // get the group
1869 Handle (Graphic3d_Group) aGroup =  Prs3d_Root::CurrentGroup  (aPrs);  
1870
1871 // change the text  aspect
1872 Handle(Graphic3d_AspectText3d) aTextAspect =  new Graphic3d_AspectText3d (); 
1873 aTextAspect->SetTextZoomable  (Standard_True); 
1874 aTextAspect->SetTextAngle  (45.0); 
1875 aGroup->SetPrimitivesAspect (aTextAspect);   
1876
1877 // add a text primitive  to the structure
1878 Graphic3d_Vertex aPoint (1, 1, 1); 
1879 aGroup->Text (Standard_CString ("Text"), aPoint, 16.0); 
1880 ~~~~~
1881
1882 @subsubsection occt_visu_5_1_8 Display priorities 
1883
1884 Structure display priorities control the order in which  structures are drawn. When you display a structure you specify its priority.  The lower the value, the lower the display priority. When the display is  regenerated the structures with the lowest priority are drawn first. For  structures with the same display priority the order in which they were  displayed determines the drawing order. OCCT supports eleven structure  display priorities.  
1885
1886 @subsubsection occt_visu_5_1_9 About structure hierarchies 
1887
1888 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.  
1889
1890 @subsection occt_visu_5_2 V3d Package
1891
1892 @subsubsection occt_visu_5_2_1 Overview 
1893
1894 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.  
1895
1896 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.  
1897
1898 @subsubsection occt_visu_5_2_2 Provided services 
1899
1900 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:  
1901   * Default parameters of the viewer, 
1902   * Views (orthographic, perspective), 
1903   * Lighting (positional, directional, ambient, spot, headlight), 
1904   * Clipping planes (note that only Z-clipping planes can work with  the Phigs interface), 
1905   * Instantiated sequences of views, planes, light sources, graphic  structures, and picks, 
1906   * Various package methods. 
1907
1908 @subsubsection occt_visu_5_2_3 A programming example 
1909
1910 This sample TEST program for the *V3d* Package uses primary  packages *Xw* and *Graphic3d* and secondary packages *Visual3d, Aspect, Quantity,  Phigs* and *math*.  
1911
1912 ~~~~~
1913 //Create a default display  connection
1914 Handle(Aspect_DisplayConnection)  aDisplayConnection = new  Aspect_DisplayConnection(); 
1915
1916 //Create a Graphic Driver from  the default Aspect_DisplayConnection
1917 Handle(Graphic3d_GraphicDriver)  GD = Graphic3d::InitGraphicDriver (aDisplayConnection);   
1918
1919 //Create a Viewer to this Driver 
1920 Handle(V3d_Viewer)  VM = new V3d_Viewer(GD, 400.,  
1921         // Space size  
1922         V3d_Xpos,
1923         // Default projection  
1924         Quantity_NOC_DARKVIOLET, 
1925         // Default  background  
1926         V3d_ZBUFFER, 
1927         // Type of  visualization  
1928         V3d_GOURAUD, 
1929         // Shading  model  
1930         V3d_WAIT); 
1931         // Update mode   
1932 // Create a structure in this  Viewer 
1933 Handle(Graphic3d_Structure) S =  new  Graphic3d_Structure(VM->Viewer()) ;  
1934
1935 // Type of structure 
1936 S->SetVisual (Graphic3d_TOS_SHADING);  
1937
1938 // Create a group of primitives  in this structure
1939 Handle(Graphic3d_Group) G = new Graphic3d_Group(S) ;  
1940
1941 // Fill this group with  one polygon of size 100  
1942 Graphic3d_Array1OfVertex Points(0,3) ;  
1943 Points(0).SetCoord(-100./2.,-100./2.,-100./2.) ;  
1944 Points(1).SetCoord(-100./2., 100./2.,-100./2.) ;  
1945 Points(2).SetCoord( 100./2., 100./2.,-100./2.) ;  
1946 Points(3).SetCoord( 100./2.,-100./2.,-100./2.) ;  
1947 Normal.SetCoord(0.,0.,1.) ;  
1948 G->Polygon(Points,Normal) ;  
1949
1950 //  Create Ambient and Infinite Lights in this Viewer
1951 Handle(V3d_AmbientLight) L1  = new V3d_AmbientLight  
1952         (VM,Quantity_NOC_GRAY50)  ;  
1953 Handle(V3d_DirectionalLight)  L2 = new V3d_DirectionalLight  
1954         (VM,V3d_XnegYnegZneg,Quantity_NOC_WHITE)  ;  
1955
1956 // Create a 3D quality  Window with the same DisplayConnection
1957 Handle(Xw_Window) W =  new Xw_Window(aDisplayConnection,"Test  V3d",0.5,0.5,0.5,0.5) ;  
1958
1959 // Map this Window to  this screen
1960 W->Map() ;  
1961
1962 // Create a Perspective  View in this Viewer
1963 Handle(V3d_PerspectiveView) V =  new V3d_PerspectiveView(VM);  
1964
1965 // Set the Eye position
1966 V->SetEye(100.,100.,100.) ;  
1967
1968 // Associate this View  with the Window 
1969 V->SetWindow(W) ;  
1970
1971 // Activate ALL defined  Lights in this View 
1972 V->SetLightOn() ;  
1973
1974 // Display ALL  structures in this View 
1975 (VM-Viewer())->Display() ;  
1976
1977 // Finally update the  Visualization in this View 
1978 V->Update() ;  
1979 ~~~~~
1980
1981 @subsubsection occt_visu_5_2_4 Glossary of  view transformations 
1982
1983 The following terms are used to define view orientation,  i.e. transformation from World Coordinates (WC) to the View Reference  Coordinates system (VRC): 
1984 * **View Reference Point (VRP)** - defines the origin of View Reference Coordinates.
1985 * **View Reference Plane Normal (VPN)** - defines the normal of projection plane of the view.
1986 * **View Reference Up Vector (VUP)** - defines the vertical of observer of the view.
1987
1988 The following terms are used to define view mapping, i.e.  transformation from View Reference Coordinates (VRC) to the Normalized  Projection Coordinates (NPC): 
1989 * **Projection type** - Orthographic or perspective.
1990 * **Projection Reference Point (PRP)** -        Defines the observer position. 
1991 * **Front Plane Distance (FPD)** -      Defines the position of the front clipping plane in View Reference Coordinates system.
1992 * **Back Plane Distance (BPD)** Defines the position of the back clipping plane in View Reference Coordinates system.
1993 * **View Plane Distance (VPD)** Defines the position of the view projection plane in View Reference Coordinates system. View plane must be located between front and back clipping planes. 
1994 * **Window Limits**     Defines the visible part of the view projection plane (left, right, top and bottom boundaries: *Umin, Umax, Vmax* and *Vmin* respectively) in View Reference Coordinates.
1995
1996 The *V3d_View* API uses the following terms to define view  orientation and mapping: 
1997 * **At** -      Position of View Reference Point (VRP) in World Coordinates
1998 * **Eye** -     Position of the observer (projection reference point) in World Coordinates. Influences to the view projection vector and depth value. 
1999 * **Proj** -    View projection vector (VPN)
2000 * **Up** -      Position of the high point / view up vector (VUP)
2001 * **Depth** - Distance between Eye and At point
2002 * **ZSize** - Distance between front and back clipping planes
2003 * **Size** - Window size in View Reference Coordinates 
2004 * **Focal Reference point** -   Position of Projection Reference Point (PRP) in World Coordinates
2005 * **Focale** -  Distance between Projection Reference Point (PRP) and View projection plane
2006
2007
2008 @subsubsection occt_visu_5_2_5 Management of  perspective projection 
2009
2010 The perspective projection allows definition of viewing  volume as a truncated pyramid (frustum) with apex at the Projection Reference  Point. In the View Reference Coordinate system it can be presented by the  following picture: 
2011
2012 @image html visualization_image023.png "View Reference Coordinate System, perspective viewing volume and view mapping parameter"
2013 @image latex visualization_image023.png "View Reference Coordinate System, perspective viewing volume and view mapping parameter"
2014   
2015 During panning, window limits are changed, as if a sort of  "frame" through which the user sees a portion of the view plane was moved over  the view. The perspective frustum itself remains unchanged.  
2016
2017 The perspective projection is defined by two parameters: 
2018   * *Depth* value defines distance between Projection Reference  Point and the nearest (front) clipping plane. 
2019   * *ZSize* defines distance between Front and Back clipping  planes. The influence of this parameter is caused by the OCCT specific to  center viewing volume around View Reference Point so the front and back plane  distances were the same: *FPD = BPD = ZSize / 2*.
2020   
2021 **Note** that the closer the displayed object to the  Projection Reference Point the more visible its perspective distortion. Thus,  in order to get a good perspective it is recommended to set **ZSize** value  comparable with the expected model size and small Depth value. 
2022
2023 However, very small  Depth values might lead to inaccuracy of "fit all" operation and to  non-realistic perspective distortion.  
2024
2025 Let us see the example:
2026 ~~~~~
2027 // Create a Perspective  View in Viewer VM
2028 Handle(V3d_PerspectiveView) V =  new V3d_PerspectiveView(VM);  
2029
2030 // Set the ZSize 
2031 V->SetZSize(2000.) ;  
2032
2033 // Set the Depth value
2034 V->SetDepth(20.) ;  
2035
2036 // Set the current  mapping as default to be used by  Reset() operation
2037 V->SetViewMappingDefault() ;  
2038 ~~~~~
2039
2040 As an alternative to  manual setting of perspective parameters the *V3d_View::DepthFitAll* function  can be used.  
2041
2042 ~~~~~
2043 // Display  shape in  Viewer VM
2044 Handle(AIS_InteractiveContext) aContext = new AIS_InteractiveContext(VM);   
2045 aContext->Display(shape); 
2046
2047 // Create a Perspective  View in Viewer VM
2048 Handle(V3d_PerspectiveView) V =  new V3d_PerspectiveView(VM);  
2049
2050 // Set automatically  the perspective parameters
2051 V->DepthFitAll() ;  
2052
2053 // Fit view to object  size 
2054 V->FitAll(); 
2055
2056 // Set the current  mapping as default to be used by  Reset() operation
2057 V->SetViewMappingDefault() ;  
2058 ~~~~~
2059
2060 It is necessary to take  into account that during rotation Z size of the view might be modified  automatically to fit the model into the viewing volume.  
2061
2062 Make sure the Eye point  never gets between the Front and Back clipping planes.  
2063
2064 In perspective view,  changing Z size results in changed perspective effect. To avoid this, an  application should specify the maximum expected Z size using *V3d_View::SetZSize()* method in advance.  
2065
2066 *V3d_View::FitAll()*  with *FitZ = Standard_True* and *V3d_View::ZFitAll()* also change the perspective effect  and should therefore be used with precautions similar to those for rotation. 
2067
2068 @subsubsection occt_visu_5_2_6 Underlay and overlay layers management
2069
2070 In addition to interactive 3d graphics displayed in the view  you can display an underlying and overlying graphics: text, color scales,  drawings.  
2071
2072 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.  
2073
2074 The method *V3d_View::SetLayerMgr(const Handle (V3d_LayerMgr)& aMgr)* allows assigning a custom layer manager to the *V3d* view.
2075
2076 There are three virtual methods to prepare graphics in the  manager for further drawing (set up layer dimensions, draw static graphics).  These methods can be redefined: 
2077 ~~~~~
2078    void  V3d_LayerMgr::Begin ()
2079    void  V3d_LayerMgr::Redraw ()
2080    void V3d_LayerMgr::End  ()
2081 ~~~~~
2082
2083 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.  
2084
2085 The layer entity is presented by the *Visual3d_Layer*  class. This entity provides drawing services in the layer, for example:
2086 ~~~~~ 
2087    void  Visual3d_Layer::DrawText
2088    void Visual3d_Layer::DrawRectangle
2089    void  Visual3d_Layer::SetColor
2090    void  Visual3d_Layer::SetViewport
2091 ~~~~~
2092 The following example demonstrates how to  draw overlay graphics by the *V3d_LayerMgr*: 
2093
2094 ~~~~~
2095 // redefined method of  V3d_LayerMgr
2096 void  MyLayerMgr::Redraw () 
2097
2098    Quantity_Color aRed (Quantity_NOC_RED); 
2099    myOverlayLayer->SetColor (aRed); 
2100    myOverlayLayer->DrawRectangle (0, 0, 100, 100); 
2101
2102 ~~~~~
2103
2104 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: 
2105
2106 ~~~~~
2107    void  Visual3d_Layer::AddLayerItem (const Handle (Visual3d_LayerItem)&  Item)  
2108    void  Visual3d_Layer::RemoveLayerItem (const Handle (Visual3d_LayerItem)&  Item)   
2109    void  Visual3d_Layer::RemoveAllLayerItems ()
2110    const  Visual3d_NListOfLayerItem& Visual3d_Layer::GetLayerItemList ()    
2111 ~~~~~
2112 The layer’s items are rendered when the method *void  Visual3d_Layer::RenderLayerItems()* is  called by the graphical driver.
2113
2114 The *Visual3d_LayerItem* has virtual methods that are  used to render the item: 
2115 ~~~~~
2116    void  Visual3d_LayerItem::RedrawLayerPrs () 
2117    void  Visual3d_LayerItem::ComputeLayerPrs () 
2118 ~~~~~
2119
2120 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: 
2121 ~~~~~
2122    void  Visual3d_LayerItem::SetNeedToRecompute (const Standard_Boolean NeedToRecompute)  
2123    Standard_Boolean  Visual3d_LayerItem::IsNeedToRecompute 
2124 ~~~~~
2125
2126 An example of *Visual3d_LayerItem* is *V3d_ColorScaleLayerItem*  that represents the color scale entity as the layer’s item.  
2127 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: 
2128
2129 <h4>Example </h4>
2130
2131 ~~~~~
2132 // tell V3d_ColorScale to draw itself
2133 void  V3d_ColorScaleLayerItem::RedrawLayerPrs () 
2134
2135    Visual3d_LayerItem::RedrawLayerPrs () 
2136   if  (!MyColorScale.IsNull ()) 
2137     MyColorScale->DrawScale  (); 
2138
2139
2140 // V3d_ColorScale has a reference to a LayerMgr
2141 void  V3d_ColorScale::DrawScale () 
2142
2143     // calls V3d_ColorScale::PaintRect,  V3d_ColorScale::PaintText, etc … 
2144
2145
2146 // PaintRect method uses overlay layer of LayerMgr to  draw a rectangle 
2147 void V3d_ColorScale::PaintRect   
2148        (const  Standard_Integer X, const Standard_Integer Y, 
2149         const  Standard_Integer W, const Standard_Integer H, 
2150         const  Quantity_Color aColor, 
2151         const  Standard_Boolean aFilled) 
2152
2153   const Handle  (Visual3d_Layer)& theLayer = myLayerMgr->Overlay (); 
2154    ...
2155    theLayer->SetColor (aColor); 
2156    theLayer->DrawRectangle (X, Y, W, H); 
2157    ... 
2158
2159 ~~~~~
2160
2161 @subsubsection occt_visu_5_2_7 View background styles 
2162 There are three types of  background styles available for *V3d_view*: solid color, gradient color and  image.  
2163
2164 To set solid color for  the background you can use the following methods: 
2165 ~~~~~
2166    void  V3d_View::SetBackgroundColor
2167                 (const Quantity_TypeOfColor Type,  
2168                  const Quantity_Parameter V1, 
2169                  const Quantity_Parameter V2, 
2170                  const Quantity_Parameter V3) 
2171 ~~~~~
2172
2173 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*. 
2174
2175 **Note** that the color  value parameters *V1,V2,V3* should be in the range between *0.0-1.0.* 
2176
2177 ~~~~~
2178   void  V3d_View::SetBackgroundColor(const Quantity_Color &Color)  
2179   void  V3d_View::SetBackgroundColor(const Quantity_NameOfColor Name)  
2180 ~~~~~
2181
2182 The gradient background  style could be set up with the following methods: 
2183 ~~~~~
2184   void  V3d_View::SetBgGradientColors
2185                 (const Quantity_Color& Color1,  
2186                  const Quantity_Color& Color2, 
2187                  const Aspect_GradientFillMethod  FillStyle, 
2188                  const Standard_Boolean update) 
2189                 
2190    void  V3d_View::SetBgGradientColors
2191                 (const Quantity_NameOfColor Color1,  
2192                  const Quantity_NameOfColor Color2, 
2193                  const Aspect_GradientFillMethod  FillStyle, 
2194                  const Standard_Boolean update) 
2195 ~~~~~
2196
2197 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.  
2198
2199 The fill style can be also set with the method *void  V3d_View::SetBgGradientStyle(const Aspect_GradientFillMethod AMethod, const Standard_Boolean update)*. 
2200
2201 To get the current  background color you can use the following methods: 
2202 ~~~~~
2203    void  V3d_View::BackgroundColor
2204                 (const Quantity_TypeOfColor Type,  
2205                  Quantity_Parameter &V1, 
2206                  Quantity_Parameter &V2, 
2207                  Quantity_Parameter &V3) 
2208    Quantity_Color  V3d_View::BackgroundColor()
2209    void V3d_View::GradientBackgroundColors(Quantity_Color& Color1, Quantity_Color& Color2) 
2210    Aspect_GradientBackground  GradientBackground()
2211 ~~~~~
2212    
2213 To set the image as a  background and change the background image style you can use the following  methods: 
2214 ~~~~~  
2215   void V3d_View::SetBackgroundImage
2216                 (const Standard_CString FileName,  
2217                  const Aspect_FillMethod FillStyle, 
2218                  const Standard_Boolean update) 
2219   void  V3d_View::SetBgImageStyle
2220                 (const Aspect_FillMethod FillStyle,  
2221                  const Standard_Boolean update) 
2222 ~~~~~
2223
2224 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:  
2225   * *Aspect_FM_NONE* -  draws the image in the default position;
2226   * *Aspect_FM_CENTERED* - draws the image at the center of the view;
2227   * *Aspect_FM_TILED* tiles the view with the image;
2228   * *Aspect_FM_STRETCH* stretches the image over the view.
2229
2230 @subsubsection occt_visu_5_2_8 User-defined  clipping planes
2231 The ability to define  custom clipping planes could be very useful for some tasks. The *V3d* view provides such an  opportunity.  
2232
2233 The *V3d_Plane* class provides the services of 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: 
2234 ~~~~~
2235   void  V3d_Plane::SetPlane
2236                 (const Quantity_Parameter A,  
2237                  const Quantity_Parameter B, 
2238                  const Quantity_Parameter C, 
2239                  const Quantity_Parameter D) 
2240   void V3d_Plane::Plane
2241                 (Quantity_Parameter& A,  
2242                  Quantity_Parameter& B, 
2243                  Quantity_Parameter& C, 
2244                  Quantity_Parameter& D) 
2245 ~~~~~
2246
2247 *V3d_Plane* also provides display services: 
2248
2249 ~~~~~
2250   void  V3d_Plane::Display
2251                 (const Handle(V3d_View)& aView,  
2252                  const Quantity_Color& aColor) 
2253   void V3d_Plane::Erase  ()
2254   Standard_Boolean  V3d_Plane::IsDisplayed ()
2255 ~~~~~  
2256 The *Display*  method could be redefined to provide custom representation of the clipping  plane. 
2257
2258 The clipping planes could be activated with the methods *void  V3d_View::SetPlaneOn (const Handle(V3d_Plane)& MyPlane)*  and *void  V3d_View::SetPlaneOn()* 
2259
2260 The first method  appends the given *V3d_Plane* to the internal list of user-defined clipping  planes of a view and activates it. If the plane is already in the list, it  becomes activated. The second method activates all of the planes defined for  the view.  
2261
2262 The clipping planes could be deactivated  with the similar methods *void V3d_View::SetPlaneOff(const Handle(V3d_Plane)& MyPlane)* and *void  V3d_View::SetPlaneOff()*
2263
2264 The only difference is that these methods  remove the user-defined clipping planes from the internal list. Thus, the view  retains only active clipping planes.  
2265
2266 You can iterate through the active planes  using the following methods: 
2267   * *void  V3d_View::InitActivePlanes()* - sets  the iterator to the beginning of the internal list of clipping planes; 
2268   * *Standard_Boolean  V3d_View::MoreActivePlanes()* returns *Standard_True* if there are more active planes to return; 
2269   * *void  V3d_View::NextActivePlanes()* sets the iterator to the next active plane in the list; 
2270   * *Handle(V3d_Plane)  V3d_View::ActivePlane()* returns the active plane 
2271
2272 or check if a certain clipping plane has  been activated with method *Standard_Boolean V3d_View::IsActivePlane  (const  Handle (V3d_Plane)& aPlane)*
2273   
2274 The number of clipping  planes is limited. The method *Standard_Boolean V3d_View::IfMorePlanes()* allows checking if it is possible to activate at least one more plane  in the view or the limit has been reached.
2275   
2276 <h4>Example </h4>
2277
2278 ~~~~~
2279 // try to use an existing  clipping plane or create a new one
2280 Handle(V3d_Plane)  aCustomPlane; 
2281 myView->InitActivePlanes  (); 
2282 if  (myView->MoreActivePlanes ()) 
2283    aCustomPlane = myView->ActivePlane (); 
2284 else 
2285    aCustomPlane = new V3d_Plane (); 
2286
2287 // calculate new coefficients
2288 Standard_Real  a, b, c, d; 
2289 Standard_Real  x = 0.0, y = 0.0, z = 10.0; 
2290 Standard_Real  dx = 0.0, dy = 0.0, dz = 1.0; 
2291 gp_Pln  aPln (gp_Pnt (x, y, z), gp_Dir (dx, dy, dz)); 
2292 aPln.Coefficients  (a, b, c, d); 
2293
2294 // update plane
2295 aCustomPlane->SetPlane (a, b, c, d); 
2296 myView->SetPlaneOn  (aCustomPlane); 
2297 ~~~~~
2298
2299 @subsubsection occt_visu_5_2_9 Dumping a 3D scene into an image file
2300 The 3D scene displayed in the view could 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). 
2301
2302 The *V3d_View* has the following methods for  dumping the 3D scene: 
2303 ~~~~
2304 Standard_Boolean  V3d_View::Dump 
2305         (const Standard_CString theFile, 
2306          const Image_TypeOfImage theBufferType)
2307 ~~~~
2308 Dumps the scene into an image file with the view  dimensions.
2309
2310 ~~~~
2311 Standard_Boolean  V3d_View::Dump 
2312         (const Standard_CString theFile, 
2313          const Aspect_FormatOfSheetPaper  theFormat, 
2314          const Image_TypeOfImage theBufferType)
2315 ~~~~
2316 Makes the dimensions of the output image compatible to a certain format of printing paper passed by *theFormat* argument.  
2317   
2318 These methods dump the 3D scene into an image file passed by its name  and path as theFile.  
2319
2320 The raster image data handling algorithm is based on the Image_PixMap  class. The supported extensions are ".png", ".bmp", ".png", ".png".  
2321
2322 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.  
2323
2324 **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. 
2325
2326 ~~~~
2327 Handle_Image_PixMap  V3d_View::ToPixMap 
2328         (const Standard_Integer theWidth, 
2329         const Standard_Integer theHeight, 
2330         const Image_TypeOfImage theBufferType, 
2331         const Standard_Boolean theForceCentered) 
2332 ~~~~
2333 Dumps the displayed 3d scene into a pixmap  with a width and height passed as *theWidth* and theHeight arguments.  
2334
2335 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. 
2336
2337 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: 
2338 * Create display connection; 
2339 * Initialize graphic driver; 
2340 * Create a window; 
2341 * Set up the window as virtual, *Aspect_Window::SetVirtual()* ; 
2342 * Create a view and an interactive context; 
2343 * Assign the virtual window to the view; 
2344 * Display a 3D scene; 
2345 *  Use one of the functions described above to dump the 3D scene. 
2346
2347 The following example demonstrates this  procedure for *WNT_Window* : 
2348
2349 ~~~~~
2350 // create a dummy display  connection
2351 Handle(Aspect_DisplayConnection)  aDisplayConnection;
2352
2353 // create a graphic driver
2354 Handle  (Graphic3d_GraphicDriver) aDriver = Graphic3d::InitGraphicDriver (aDisplayConnection); 
2355
2356 // create a window
2357 Standard_Integer  aDefWidth  = 800; 
2358 Standard_Integer  aDefHeight = 600; 
2359 Handle  (WNT_WClass) aWClass =  new WNT_WClass ("Virtual Class",DefWindowProc, 
2360                               CS_VREDRAW | CS_HREDRAW, 0, 0,  
2361                               ::LoadCursor (NULL, IDC_ARROW)); 
2362 Handle  (WNT_Window) aWindow =  new WNT_Window ("VirtualWnd",  aWClass,  
2363                               WS_OVERLAPPEDWINDOW, 0, 0,  
2364                               aDefWidth, aDefHeight); 
2365
2366 // set up the window as  virtual
2367 aWindow->SetVirtual  (Standard_True); 
2368
2369 // create a view and an  interactive context
2370 Handle  (V3d_Viewer) aViewer =  new V3d_Viewer (aDriver, 
2371                               Standard_ExtString ("Virtual")); 
2372 Handle  (AIS_InteractiveContext) aContext = new AIS_InteractiveContext (aViewer); 
2373 Handle  (V3d_View) aView = aViewer->CreateView (); 
2374
2375 // assign the virtual window  to the view
2376 aView->SetWindow  (aWindow); 
2377
2378 // display a 3D scene
2379 Handle (AIS_Shape) aBox = new AIS_Shape (BRepPrimAPI_MakeBox (5, 5, 5)); 
2380 aContext->Display  (aBox); 
2381 aView->FitAll(); 
2382
2383 // dump the 3D scene into an  image file
2384 aView->Dump  ("3dscene.png"); 
2385 ~~~~~
2386
2387 @subsubsection occt_visu_5_2_10 Printing a 3D scene
2388
2389 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.  
2390
2391 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: 
2392
2393 *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.  
2394
2395 You can define  the filename for the printer driver if you want to print out the result into a  file.  
2396 If you do not want to print the  background, you can pass *Standard_False* as the *showBackground* argument. 
2397 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*
2398
2399 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. 
2400
2401 **Note** that at the moment printing is implemented only for Windows. 
2402
2403 @subsubsection occt_visu_5_2_11 Vector image export
2404
2405 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 your 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).  
2406
2407 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: 
2408
2409 The *FileName*  defines the output image file name and the *Format* argument defines the output  file format:  
2410   * Graphic3d_EF_PostScript  (PS),
2411   * Graphic3d_EF_EhnPostScript  (EPS),
2412   * Graphic3d_EF_TEX  (TEX), 
2413   * Graphic3d_EF_PDF  (PDF),
2414   * Graphic3d_EF_SVG  (SVG),
2415   * Graphic3d_EF_PGF  (PGF)
2416
2417 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. 
2418
2419 The *Export* method supports only basic 3d  graphics and has several limitations: 
2420   * Rendering large scenes could be slow and  can lead to large output files;
2421   * Transparency is only supported for PDF and  SVG output;
2422   * Textures and some effects are not supported by  the GL2PS library.
2423
2424 @section occt_visu_6 Graphic Attributes
2425
2426 @subsection occt_visu_6_1 Aspect Package
2427
2428 The *Aspect* package provides classes for the graphic elements in the viewer:
2429   * Color maps,  
2430   * Pixels,  
2431   * Groups of graphic attributes,  
2432   * Edges, lines, background,  
2433   * Font classes,  
2434   * Width map classes,  
2435   * Marker map classes,  
2436   * Type of Line map classes,  
2437   * Window,  
2438   * Driver, PlotterDriver (inherited by  PS_Driver), WindowDriver,  
2439   * Enumerations for many of the above,  
2440   * Array instantiations for edges,  
2441   * Array instantiations for map entries for  color, type, font, width, and marker. 
2442
2443