0024346: Documentation - provide Coding Rules document
[occt.git] / dox / user_guides / visualization / visualization.md
1 Visualization  {#user_guides__visualization}
2 ===================
3
4 @tableofcontents
5  
6 @section occt_1621831385_591811643 Introduction
7
8
9 This manual explains how to use Open CASCADE Technology Visualization. It provides basic documentation on setting up and using Visualization. For advanced information on Visualization and its applications, see our offerings on our web site 
10 (Training and E-Learning) at <a href="http://www.opencascade.org/support/training/">http://www.opencascade.org/support/training/</a>   
11
12 Visualization in Open CASCADE Technology is based on the separation of: 
13   * on the one hand - the data which stores the geometry and topology of the entities you want to display and select, and 
14   * 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 in order to apply some application-defined operations to the selected entities). 
15
16 @subsection occt_1621831385_5918116431 Open CASCADE Technology Visualization and the Organization of this guide 
17
18 Presentations are managed through the Presentation component, and selection through the Selection component. 
19
20 To make management of these functionalities in 3D more intuitive and consequently, more transparent, **Application Interactive Services** have been created. **AIS** use 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. 
21
22 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. 
23
24 The packages used to display 3D objects are the following: 
25   * AIS 
26   * StdPrs 
27   * Prs3d 
28   * PrsMgr 
29   * V3d 
30   * Graphic3d 
31
32 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 1, Fundamental Concepts. In brief, the packages used to display 2D objects are the following: 
33   * AIS2D
34   * Prs2d
35   * PrsMgr 
36   * V2d 
37   * Graphic2d. 
38
39 Figure 1 below presents a schematic overview of the relations between the key concepts and packages in visualization. AIS stands for both AIS and AIS2D packages. Naturally, *Geometry &amp; 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. 
40
41 @image html /user_guides/visualization/images/visualization_image003.png
42 @image latex /user_guides/visualization/images/visualization_image003.png
43 **Figure 1. Key concepts and packages in visualization** 
44
45 To answer different needs of CASCADE users, this user’s guide offers the following three paths in reading it. 
46   
47   * If the 3D services proposed in AIS meet your requirements, you need only read chapter 3, *AIS: Application Interactive Services*. 
48
49   * If the services provided do not satisfy your requirements - if for example, you need a selection filter on another type of entity - you should read chapter 2 *Fundamental Concepts*, chapter 3 *AIS: Application Interactive Services*, and possibly chapters 4 and 5 *3D Presentations *and *3D Resources*. You may want to begin with the chapter presenting AIS. 
50
51   * If your display will be in 2D, you should read chapter 1 *Fundamental Concepts*, chapter 6 *2D Presentations* and chapter 7 *2D Resources*. 
52
53   
54 @section occt_1621831385_1633708282  Fundamental Concepts
55
56 @subsection occt_1621831385_16337082821 Presentation 
57
58 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. 
59
60 @subsubsection occt_1621831385_163370828211 Key difference in implementation of 2D and 3D visualization
61 Current implementation of 3D visualization services is based on OpenGL. 
62 2D visualization packages use native window system API (Win32 GDI API on Windows, Xlib API on Unix and Linux). 
63 @subsubsection occt_1621831385_163370828212 Structure of the Presentation     
64
65 Displaying an object on the screen involves three kinds of entity: 
66   * a presentable object, the *AIS_InteractiveObject *
67   * a viewer 
68   * an interactive context, the *AIS_InteractiveContext*. 
69
70 <h4>The presentable object </h4>
71 The purpose of a presentable object is to provide  the graphical representation of an object in the form of Graphic2d or Graphic3d structure. On the first display request, it creates this structure by calling the appropriate algorithm and retaining this framework for further display. 
72 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 Graphic2d or Graphic3d packages. You can also create several presentations of a single presentable object: one for each visualization mode supported by your application. 
73 Each object to be presented individually must be presentable or associated with a presentable object. 
74
75 <h4>The viewer </h4>
76 The viewer allows you to interactively manipulate 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 Graphic2d and Graphic3d structures in your presentation algorithms allows you to use the 2D and 3D viewers provided in Open CASCADE Technology. 
77
78 <h4>The Interactive Context </h4>
79 (see chapter 2, AIS: Application Interactive Services) 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. 
80
81 <h4>Presentation packages </h4>
82 Presentation involves at least the AIS, AIS2D, PrsMgr, StdPrs, V3d and V2d packages. Additional packages such as Prs3d, Prs2d, Graphic3d and Graphic2d may be used if you need to implement your own presentation algorithms. 
83
84 <h4>AIS and AIS2D</h4>
85 See chapter 2, **AIS: Application Interactive Services **The *AIS* package provides all classes to implement interactive objects (presentable and selectable 2D or 3D entities). 
86
87 <h4>PrsMgr </h4>
88 The *PrsMgr* package provides all the classes needed to implement the presentation process: the *Presentation* and *PresentableObject* abstract classes and the *PresentationManager2d* and *PresentationManager3d* concrete classes. 
89
90 <h4>StdPrs </h4>
91 The *StdPrs* package provides ready-to-use standard presentation algorithms of points, curves and shapes of the geometry and topology toolkits. 
92
93 <h4>V2d and V3d </h4>
94 The *V2d* and *V3d* packages provide the services supported by the 2D and 3D viewers. 
95
96 <h4>Prs3d and Prs2d</h4>
97 The *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. 
98
99 <h4>Graphic2d and Graphic3d </h4>
100 The *Graphic2d* and *Graphic3d* packages provide resources to create 2D and 3D graphic structures (please refer to chapters on 3D Resources and 2D Resources  for more information). 
101
102
103 @subsubsection occt_1621831385_163370828213 A Basic Example: How to display a 3D object 
104 <h4>Example </h4>
105
106 Void Standard_Real dx  = ...; //Parameters  Void Standard_Real dy  = ...; //to build a wedge Void Standard_Real dz  = ...; Void Standard_Real ltx = ...; 
107
108 Handle(V3d_Viewer)aViewer = ...; Handle(AIS_InteractiveContext)aContext; aContext = new AIS_InteractiveContext(aViewer);   
109 BRepPrimAPI_MakeWedge w(dx, dy, dz, ltx); TopoDS_Solid &amp; = w.Solid(); Handle(AIS_Shape) anAis = new AIS_Shape(S); //creation of the presentable object aContext - Display(anAis); //Display the presentable object in the 3d viewer. 
110
111 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 2 below. 
112
113 ** ** 
114
115
116
117
118
119
120
121 @image html /user_guides/visualization/images/visualization_image004.png
122 @image latex /user_guides/visualization/images/visualization_image004.png
123
124 @image html /user_guides/visualization/images/visualization_image005.png
125 @image latex /user_guides/visualization/images/visualization_image005.png
126 **Figure 2. Processes involved in displaying a presentable shape** 
127
128 @subsection occt_1621831385_16337082822 Selection 
129 This chapter deals with the process used for selecting entities, which are displayed in the 2D space of the selection view. 
130
131 @subsubsection occt_1621831385_163370828221 The Selection Principle 
132
133 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. 
134 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 element detected. 
135
136 @image html /user_guides/visualization/images/visualization_image006.png
137 @image latex /user_guides/visualization/images/visualization_image006.png
138 **Figure 3. A model ** 
139
140 @image html /user_guides/visualization/images/visualization_image007.png
141 @image latex /user_guides/visualization/images/visualization_image007.png
142 **Figure 4. Modeling faces with sensitive primitives **
143
144 @image html /user_guides/visualization/images/visualization_image008.png
145 @image latex /user_guides/visualization/images/visualization_image008.png
146 **Figure  5. In a dynamic selection, each sensitive polygon is represented by its bounding rectangle** 
147
148 @image html /user_guides/visualization/images/visualization_image009.png
149 @image latex /user_guides/visualization/images/visualization_image009.png
150 Figure 6. Reference to the sensitive primitive, then to the owner 
151
152 @subsubsection occt_1621831385_163370828222 The Sensitive Primitive 
153
154 The sensitive primitive - along with the entity owner - allow you to define what can be made selectable, and in so doing, provide the link between the applicative object and the sensitive zones defined by the 2D bounding boxes. For an object to be dynamically selectable, it has to be represented either as a sensitive primitive or a set of them. These give 2D boxes that will be included in a sorting algorithm. 
155 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. 
156 <h4>Example </h4>
157
158 The sensitive line segment below 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. 
159
160 @image html /user_guides/visualization/images/visualization_image010.png
161 @image latex /user_guides/visualization/images/visualization_image010.png
162 **Figure 7. Example of sensitive primitives **
163
164 When the 2D box associated with the position of the mouse intersects the 2D box of a sensitive primitive, the owner of the sensitive primitive is called and its presentation is highlighted. 
165 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. 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. 
166 @subsubsection occt_1621831385_163370828223 The Principles of Dynamic Selection 
167
168 Dynamic selection causes objects in a view to be automatically highlighted as the mouse cursor moves over them. This allows the user to be certain that the picked object is the correct one. Dynamic Selection is based on the following two concepts: 
169   * a Selectable Object (see *AIS_InteractiveObject*) 
170   * an Interactive Context  
171
172 <h4>Selectable Object </h4>
173 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. 
174
175 *The term, selection mode of a selectable object, can refer to the selection mode of the object itself or to that of one of its parts.* 
176
177 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.) 
178
179 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. 
180
181 <h4>Interactive Context</h4>
182 See chapter 2, AIS: Application Interactive Services, Section 2.4 
183
184 The interactive context is used to manage both selectable objects and selection processes. 
185
186 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. 
187 <h4>Example </h4>
188
189 Let’s consider the 3D selectable shape object, which corresponds to a topological shape. 
190
191 For this class, seven selection modes can be defined: 
192
193 mode 0 - selection of the shape itself 
194 mode 1 - selection of vertices 
195 mode 2 - selection of edges 
196 mode 3 - selection of wires 
197 mode 4 - selection of faces 
198 mode 5 - selection of shells 
199 mode 6 - selection of solids 
200 mode 7 - selection of compounds 
201
202 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. 
203
204 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. 
205
206 To deactivate selection mode 3 remove all those 2D areas. 
207
208
209 *Selection Packages  * 
210 The selection packages are the following: *SelectBasics*, *SelectMgr*, *Select2D*, *Select3D*, *StdSelect*. 
211
212 *SelectBasics  * 
213 The *SelectBasics* package contains the basic classes of the selection: 
214   *  the main definition of a sensitive primitive: *SensitiveEntity  * 
215   *  the definition of a sensitive primitive owner: *EntityOwner  * 
216   *  the algorithm used for sorting sensitive boxes: *SortAlgo  * 
217
218 *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*. 
219
220 *SelectMgr  * 
221 The *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. 
222 There are also implementations of *ViewerSelector* interface for 2D and 3D selection: *ViewerSelector2d* and *ViewerSelector3d*, respectively. 
223
224 *Select2D  * 
225 The *Select2D* package contains the basic classes of 2D sensitive primitives such as Points, Segments, and Circles, which inherit from *SensitiveEntity* from *SelectBasics* and used to represent 2D selectable objects from a dynamic selection viewpoint. 
226
227 *Select3D  * 
228 The *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. 
229
230 *StdSelect  * 
231 The *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). 
232
233 @subsubsection occt_1621831385_163370828224 Methodology 
234
235 Several operations must be performed prior to using dynamic selection: 
236 **1.   **Implement specific sensitive primitives if those defined in Select2D and 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. 
237 **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. 
238 **3.   **Install the process, which provides the user with the identity of the owner of the detected entities in the selection loop. 
239
240 When all these steps have been carried out, follow the procedure below: 
241 **1.   **Create an interactive context. 
242 **2.   **Create the selectable objects and calculate their various possible selections. 
243 **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. 
244 **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. 
245
246 At this stage, the selection of selectable entities in the selectors is available. 
247 The selection loop informs constantly the selectors with the position of the mouse and questions them about the detected entities. 
248
249
250 @subsubsection occt_1621831385_163370828225 Example of Use 
251
252 Let’s suppose you are creating 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. 
253 You define a selectable object called *House* and propose four possible selection modes for this object: 
254 **1 -** selection of the house itself 
255 **2 -** selection of the rooms 
256 **3 -** selection of the walls 
257 **4 - **selection of the doors. 
258
259 You have to write the method, which calculates the four selections above, i.e. the sensitive primitives which are activated when the mode is. 
260 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*.  
261 For example, let’s consider a house with the following representation: 
262 @image html /user_guides/visualization/images/visualization_image011.png
263 @image latex /user_guides/visualization/images/visualization_image011.png
264 **Figure 8. Selection of the rooms of a house** 
265
266 To build the selection, which corresponds to the mode *selection of the rooms* (selection 2 in the list of selection modes) use the following procedure: 
267 <h4>Example </h4>
268
269 Void House::ComputeSelection 
270 (Const Handle(SelectMgr_Selection)&amp; Sel, 
271  const Standard_Integer mode { 
272  switch(mode){  case 0: //Selection of the rooms  {  for(Standard_Integer i = 1; i = myNbRooms; i++)  { //for every room, create an instance of the owner   
273    //along with the given room and its name. Handle(RoomOwner) aRoomOwner = new RoomOwner (Room(i), NameRoom(i)); //Room() returns a room and NameRoom() returns its name. 
274 Handle(Select3d_SensitiveBox) aSensitiveBox; 
275 aSensitiveBox = new Select3d_SensitiveBox 
276 (aRoomOwner, Xmin, Ymin, Zmin, Xmax, Ymax, Zmax); 
277  Sel - Add(aSensitiveBox);  }  break;  Case 1: ... //Selection of the doors  } //Switch   
278 ) // ComputeSelection 
279
280
281 @image html /user_guides/visualization/images/visualization_image012.png
282 @image latex /user_guides/visualization/images/visualization_image012.png
283 **Figure 9. Activated sensitive boxes corresponding to selection mode 0 (selection of the rooms)** 
284
285 @image html /user_guides/visualization/images/visualization_image013.png
286 @image latex /user_guides/visualization/images/visualization_image013.png
287
288 @image html /user_guides/visualization/images/visualization_image014.png
289 @image latex /user_guides/visualization/images/visualization_image014.png
290 **Figure 11. Activated sensitive polygons corresponding to selection mode 1.** 
291
292 **(selection of the doors)** 
293 @image html /user_guides/visualization/images/visualization_image015.png
294 @image latex /user_guides/visualization/images/visualization_image015.png
295
296 **Figure 12. Sensitive rectangles in the selector during dynamic selection in view 2** 
297 @section occt_1621831385_810308609  AIS: Application Interactive Services 
298 Application Interactive Services (**AIS**) offers a set of general services beyond those offered by basic Selection and Presentation packages such as **PrsMgr**, **SelectMgr** and **StdSelect**. These allow you to manage presentations and dynamic selection in a viewer simply and transparently. To use these services optimally, you should know various rules and conventions. Section I provides an overview of the important classes which you need to manipulate AIS well. Sections 2 and 3 explain in detail how to use them and how to implement them, as well as the rules and conventions to respect. The annexes offer various standard Interactive Objects in AIS, an example of an implementation of AIS and a reminder of how to manage presentation and selection. 
299
300 @subsection occt_1621831385_8103086091 Overview 
301
302 @subsubsection occt_1621831385_81030860911 Interactive Context/Local Context 
303 <h4>AIS_InteractiveContext </h4>
304 The central entity, which pilots visualizations and selections, is the Interactive Context. It is linked to a main viewer (and if need be, a trash bin viewer.) It has two operating modes: the Neutral Point and the local visualization and selection context. The neutral point, which is the default mode, allows you to easily visualize and select interactive objects, which have been loaded into the context. Opening Local Contexts allows you to prepare and use a temporary selection environment without disturbing the neutral point. A set of functions allows you 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. When the operation is finished, you close the current local context and return to the state in which you were before opening it (neutral point or previous local context). 
305
306 @subsubsection occt_1621831385_81030860912 The Interactive Object 
307
308 <h4>AIS_InteractiveObject</h4>
309 Entities, which are visualized and selected, are Interactive Objects. 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. 
310
311 @subsubsection occt_1621831385_81030860913 Graphic Attributes Manager or *Drawer* 
312
313 @image html /user_guides/visualization/images/visualization_image016.png
314 @image latex /user_guides/visualization/images/visualization_image016.png
315 An Interactive Object can have a certain number of graphic attributes specific to it (such as visualization mode, color and material) By the same token, the Interactive Context has a drawer which is valid by default for the objects it controls. When an interactive object is visualized, the required graphic attributes are first taken from its own Drawer if it has the ones required, or from the context drawer if it does not have them. 
316
317 @subsubsection occt_1621831385_81030860914 Selection Filters 
318
319 @image html /user_guides/visualization/images/visualization_image017.png
320 @image latex /user_guides/visualization/images/visualization_image017.png
321
322 An important need in selection is the filtering of entities, which you want to select. Consequently there are FILTER entities, which allow you to refine the dynamic detection context, which you want to put into effect. Some of these filters can be used at the Neutral Point, others only in an open local context. A user will be able to program his own filters and load them into the interactive context. 
323
324 @subsection occt_1621831385_8103086092 Rules and Conventions Governing Interactive Objects
325  An interactive object is a *virtual* entity, which can be presented and selected. It can also have its own visualization aspects such as color, material, and mode of visualization. In order to create and manipulate the interactive objects with ease, you must know the rules and conventions, which have been established. Several *virtual* functions must be implemented for these objects to have the behavior expected of them. A certain number of standard interactive objects, which respect the rules and conventions described below, have been implemented in AIS. The current list of them can be found in ANNEX I. The services that concern manipulation of presentations, selection and graphic attributes will be treated separately. 
326
327
328 @subsubsection occt_1621831385_81030860921 Presentations: 
329
330 @image html /user_guides/visualization/images/visualization_image018.png
331 @image latex /user_guides/visualization/images/visualization_image018.png
332 *Conventions  * 
333   * Either in 2D or in 3D, an interactive object can have as many presentations as its creator wants to give it. 
334   * 3D presentations are managed by PresentationManager3D; 2D presentations by PresentationManager2D. As this is transparent in AIS, the user does not have to worry about it. 
335   * A presentation is identified by an index and by the reference to the Presentation Manager which it depends on. 
336   * By convention, the default mode of representation for the Interactive Object has index 0. 
337
338 *Virtual functions  * 
339
340 Calculation of different presentations of an interactive object is done in the *Compute *functions inheriting from *PrsMgr_ PresentableObject::Compute *functions. They are automatically called by *PresentationManager* at a visualization or an update request. 
341
342 If you are creating your own type of interactive object, you must implement the Compute function in one of the following ways: 
343
344   * **For 2D: **
345 <h4>Example </h4>
346
347 void PackageName_ClassName::Compute 
348 (const Handle(PrsMgr_PresentationManager2d)&amp; 
349 aPresentationManager, 
350  const Handle(Graphic2d_GraphicObject)&amp; aGraphicObject, 
351  const Standard_Integer aMode = 0); 
352   * **For 3D: **
353 <h4>Example </h4>
354
355 void PackageName_ClassName::Compute 
356 (const Handle(PrsMgr_PresentationManager3d)&amp; 
357 aPresentationManager,  
358  const Handle(Prs3d_Presentation)&amp; aPresentation, 
359  const Standard_Integer aMode = 0); 
360
361   * **For hidden line removal (HLR) mode in 3D (*): **
362 <h4>Example </h4>
363
364 void PackageName_ClassName::Compute 
365 (const Handle(Prs3d_Projector)&amp; aProjector, 
366  const Handle(Prs3d_Presentation)&amp; aPresentation); 
367
368
369 *WARNING (*)  * 
370 As its call is automatically ordered by a view, this function requires explanation; the view has two states: degenerate mode (normal mode) and non-degenerate mode (Hidden line mode). When the latter is active, the view looks for all presentations displayed in normal mode, which have been signaled as accepting hidden line mode. An internal mechanism allows us to call the interactive object’s own *Compute*, that is, projector, function. How do you declare that such and such a presentation will accept an *equivalent* in hidden line mode?  By convention, it is the Interactive Object, which accepts or rejects the representation of hidden-line mode. You can make this declaration in one of two ways, either initially by using one of the values of the enumeration PrsMgr_TypeOfPresentation: 
371   * PrsMgr_TOP_AllView,
372   * PrsMgr_TOP_ProjectorDependant
373
374 or later on, by using the function: 
375   *   *  PrsMgr_PresentableObject::SetTypeOfPresentation 
376
377 @subsubsection occt_1621831385_81030860922 Important Specifics of AIS: 
378
379 There are four types of interactive object in AIS: 
380   * the *construction element* or Datum, 
381   * the Relation (dimensions and constraints) 
382   * the Object 
383   * the None type (when the object is of an unknown type). 
384
385 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: 
386
387   *  AIS_InteractiveObject::Type 
388   *  AIS_InteractiveObject::Signature. 
389    
390
391 <h4>WARNING </h4>
392 Some signatures have already been used by *standard* objects delivered in AIS. (see the list of standard objects, Annex I.) 
393
394 As will be seen below, 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. Consequently, a virtual function allowing you to get information about this class must be implemented: 
395   *  AIS_InteractiveObject::AcceptDisplayMode. 
396
397 <h5>Services You Should Know </h5>
398 Display Mode: An object can have its own display mode, which is different from that proposed by the interactive context. The functions to use are: 
399   *  AIS_InteractiveContext::SetDisplayMode 
400   *  AIS_InteractiveContext::UnsetDisplayMode. 
401
402 Hilight Mode: At dynamic detection, the presentation echoed by the Interactive Context, is by default the presentation already on the screen. You can always specify the display mode used for highlighting purposes (so called highlight mode), which is valid no matter what the active representation of the object. It makes no difference whether this choice is temporary or definitive. To do this, you use the following functions: 
403   *  AIS_InteractiveObject::SetHilightMode 
404   *  AIS_InteractiveObject::UnSetHilightMode 
405
406 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). 
407
408 An example: For a shape - whether it is visualized in wireframe presentation or with shading - you want to systematically highlight the wireframe presentation. Consequently, you set the highlight mode to *0 *in the constructor of the interactive object. You mustn’t forget to effect the implementation of this representation mode in the *Compute* functions. 
409
410 Infinite Status: 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 in the same way. 
411   *  AIS_InteractiveObject::SetInfiniteState 
412   *  AIS_InteractiveObject::IsInfinite 
413 <h4>Example </h4>
414
415 Let’s take the case of a class called IShape, representing an interactive object 
416 myPk_IShape::myPK_IShape 
417 (const TopoDS_Shape&amp; SH, PrsMgr_TypeOfPresentation aType): 
418
419 AIS_InteractiveObject(aType),   myShape(SH),   myDrwr(new AIS_Drawer()) {     
420 SetHilightMode(0); 
421 }  
422 void myPk_IShape::Compute 
423 (const Handle(PrsMgr_PresentationManager3d) &amp; PM,  const Handle(Prs3d_Presentation)&amp; P,  const Standard_Integer TheMode) 
424
425 switch (TheMode){ 
426
427 case 0: 
428 StdPrs_WFDeflectionShape::Add (P,myShape,myDrwr); 
429 //algo for calculation of wireframe presentation break; 
430
431 case 1: 
432 StdPrs_ShadedShape::Add (P,myShape,myDrwr);  //algo for calculation of shading presentation. break; 
433
434
435 void myPk_IsShape::Compute 
436 (const Handle(Prs3d_Projector)&amp; Prj, 
437 const Handle(Prs3d_Presentation) P) 
438
439 StdPrs_HLRPolyShape::Add(P,myShape,myDrwr); 
440 //Cas-cade hidden line mode calculation algorithm 
441
442
443
444
445 @subsection occt_1621831385_8103086093 Selections 
446 @subsubsection occt_1621831385_81030860931 Conventions 
447
448 An interactive object can have an indefinite number of modes of selection, each representing a *decomposition* into sensitive primitives; each primitive has an Owner (*SelectMgr_EntityOwner*) which allows us to identify the exact entity which has been detected (see ANNEX II). 
449
450 The set of sensitive primitives, which correspond to a given mode, is stocked in a SELECTION (*SelectMgr_Selection*). 
451
452 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*. 
453
454 @subsubsection occt_1621831385_81030860932 Virtual functions 
455
456 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 following function: 
457
458   *  AIS_ConnectedInteractive::ComputeSelection 
459
460 A detailed explanation of the mechanism and the manner of implementing this function has been given in ANNEX II. 
461
462 Moreover, just as the most frequently manipulated entity is TopoDS_Shape, the most used Interactive Object is AIS_Shape. You will see below that 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: 
463
464   *  AIS_ConnectedInteractive::AcceptShapeDecomposition. 
465
466
467
468 @subsubsection occt_1621831385_81030860933 Other Services 
469 You can change the default selection mode index of an Interactive Object. For instance, you can: 
470   * check to see if there is a selection mode 
471   * check the current selection mode 
472   * set a selection mode 
473   * unset a selection mode.
474  The following functions are concerned: 
475
476   *  AIS_InteractiveObject::HasSelectionMode 
477   *  AIS_InteractiveObject::SelectionMode 
478   *  AIS_InteractiveContext::SetSelectionMode 
479   *  AIS_InteractiveContext::UnsetSelectionMode 
480
481 These functions are only of interest if you decide that the *0* mode adopted by convention will not do. In the same way, you can temporarily change the priority of certain interactive objects for selection of 0 mode. You could do this to make it easier to detect them graphically. You can: 
482   * check to see if there is a selection priority setting for the owner 
483   * check the current priority 
484   * set a priority 
485   * unset the priority.
486
487 To do this, you use the following functions: 
488   * AIS_InteractiveObject::HasSelectionPriority 
489   * AIS_InteractiveObject::SelectionPriority 
490   * AIS_InteractiveObject::SetSelectionPriority 
491   * AIS_InteractiveObject::UnsetSelectionPriority 
492
493
494
495 @subsection occt_1621831385_8103086094 Graphic attributes of an interactive object 
496
497 Keep in mind the following points concerning graphic attributes: 
498   * Each interactive object can have its own visualization attributes.
499   * 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 
500   * 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.) 
501   * In the *AIS_InteractiveObject* abstract class, several standard attributes have been privileged. These include: color, thickness of line, material, and transparency. Consequently, a certain number of virtual functions, which allow us to act on these attributes, have been proposed. Each new class of interactive object can redefine these functions in order to bring about the changes it should produce in the behavior of the class. 
502
503
504 @image html /user_guides/visualization/images/visualization_image019.png
505 @image latex /user_guides/visualization/images/visualization_image019.png
506 **Figure 13. Redefinition of virtual functions for changes in AIS_Point ** 
507
508 @image html /user_guides/visualization/images/visualization_image020.png
509 @image latex /user_guides/visualization/images/visualization_image020.png
510 **Figure 14. **Redefinition** of virtual functions for changes in AIS_Shape.**
511
512 The virtual functions concerned here allow you to provide settings for: 
513   * color 
514   * width 
515   * material 
516   * transparency
517
518 The functions concerned are the following: 
519
520   * AIS_InteractiveObject::UnsetColor 
521   * AIS_InteractiveObject::SetWidth 
522   * AIS_InteractiveObject::UnsetWidth 
523   * AIS_InteractiveObject::SetMaterial  (const Graphic3d_NameOfPhysicalMaterial &amp; aName) 
524   * AIS_InteractiveObject::SetMaterial  (const Graphic3d_MaterialAspect &amp; aMat) 
525   * AIS_InteractiveObject::UnsetMaterial 
526   * AIS_InteractiveObject::SetTransparency 
527   * AIS_InteractiveObject::UnsetTransparency 
528
529 For other types of attribute, it is appropriate to change the Drawer of the object directly using: 
530
531   * AIS_InteractiveObject::SetAttributes
532   * AIS_InteractiveObject::UnsetAttributes
533
534
535 @subsubsection occt_1621831385_81030860941 Manipulation of Attributes 
536
537 Some of these functions may imply the recalculation of presentations of the object. It is important to know which ones. If an interactive object’s presentation mode is to be updated, a flag from *PrsMgr_PresentableObject* indicates this. The mode should be updated using the functions *Display* and *Redisplay* in *AIS_InteractiveContext*. 
538
539 @subsection occt_1621831385_8103086095 Complementary Services - Precautions
540
541 @subsubsection occt_1621831385_81030860951 Changing an interactive object’s location 
542
543 When using complementary services for interactive objects, pay special attention to the following cases: 
544 Functions allowing us to temporarily *move* the representation and selection of Interactive Objects in a view without recalculation. 
545   * AIS_InteractiveContext::SetLocation 
546   * AIS_InteractiveContext::ResetLocation 
547   * AIS_InteractiveContext::HasLocation 
548   * AIS_InteractiveContext::Location 
549
550 How you link applicative entities to interactive objects. 
551
552
553 @subsubsection occt_1621831385_810308609552 Connecting an interactive object to an applicative entity
554
555 Each Interactive Object has functions that allow us to attribute it an Owner in the form of a Transient. 
556   * AIS_InteractiveObject::SetOwner 
557   * AIS_InteractiveObject::HasOwner 
558   * AIS_InteractiveObject::Owner 
559
560 An interactive object can therefore be associated with an applicative entity or not, without this affecting its behavior. 
561
562 @subsubsection occt_1621831385_810308609553 Resolving coincident topology
563
564 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. 
565
566 To avoid such kind of a problem when the elements of two or more InteractiveObjects 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. 
567
568 The following method allows you to set up the polygon offsets: 
569   * void AIS_InteractiveObject::SetPolygonOffsets
570 (const Standard_Integer aMode, 
571  const Standard_Real aFactor, 
572  const Standard_Real aUnits) 
573 The parameter aMode can contain various combinations of Aspect_PolygonOffsetMode enumeration elements. The enumeration has the following elements: 
574   * Aspect_POM_None
575   * Aspect_POM_Off
576   * Aspect_POM_Fill
577   * Aspect_POM_Line
578   * Aspect_POM_Point
579   * Aspect_POM_All
580
581 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 the Aspect_POM_Off.  Passing Aspect_POM_None allows you to change 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: 
582  offset = aFactor  * m + aUnits  * r, 
583  where m – maximum depth slope for the polygons currently being displayed, r – minimum depth resolution (implementation-specific) 
584
585 Negative offset values move polygons closer to the viewer while positive values shift polygons away. 
586
587 **WARNING** 
588 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. 
589
590 You can use the following functions to obtain the current settings for polygon offsets: 
591   * void AIS_InteractiveObject::PolygonOffsets
592 (Standard_Integer &amp;aMode, 
593  Standard_Real &amp;aFactor, 
594  Standard_Real &amp;aUnits) 
595   * Standard_Boolean 
596 AIS_InteractiveObject::HasPolygonOffsets() 
597
598 The same operation could be performed for the interactive object known by the AIS_InteractiveContext with the following methods: 
599   * void AIS_InteractiveContext::SetPolygonOffsets
600 (const Handle(AIS_InteractiveObject) &amp;anObj, 
601  const Standard_Integer aMode, 
602  const Standard_Real aFactor, 
603  const Standard_Real aUnits) 
604   * void AIS_InteractiveContext::PolygonOffsets
605 (const Handle(AIS_InteractiveObject) &amp;anObj, 
606  Standard_Integer &amp;aMode, 
607  Standard_Real &amp;aFactor, 
608  Standard_Real &amp;aUnits) 
609   * Standard_Boolean AIS_InteractiveContext::HasPolygonOffsets
610 (const Handle(AIS_InteractiveObject) &amp;anObj) 
611
612 @subsection occt_1621831385_8103086096 The Interactive Context 
613
614 @subsubsection occt_1621831385_810308609661 Preliminary Rules 
615
616 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. 
617
618 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. 
619
620 <h4>Example </h4>
621
622 Handle (AIS_Shape) TheAISShape = new AIS_Shape (ashape); myIntContext-Display(TheAISShape); 
623 myIntContext-SetDisplayMode(TheAISShape ,1); 
624 myIntContext-SetColor(TheAISShape,Quantity_NOC_RED); 
625
626 //but you can write 
627
628 Handle (AIS_Shape) TheAISShape = new AIS_Shape (ashape); TheAISShape-SetColor(Quantity_NOC_RED); 
629 TheAISShape-SetDisplayMode(1); 
630 myIntContext-Display(TheAISShape); 
631
632
633 @subsubsection occt_1621831385_810308609662 Groups of functions 
634
635 You must distinguish two states in the Interactive Context: 
636 * No Open Local Context; which will be referred to as Neutral Point. 
637 * One or several open local contexts, each representing a temporary state of selection and presentation. 
638
639 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. 
640
641 The Interactive Context is composed of a great many functions, which can be conveniently grouped according to theme: 
642   * management proper to the context 
643   * management in the local context 
644   * presentations and selection in open/closed context 
645   * selection strictly speaking 
646
647
648 @subsubsection occt_1621831385_810308609663 Management proper to the Interactive Context 
649
650 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: 
651   * Default Drawer, containing all the color and line attributes which can be used by interactive objects, which do not have their own attributes. 
652   * Default Visualization Mode for interactive objects 
653 Default: mode 0 
654   * Highlight color of entities detected by mouse movement 
655 Default: Quantity_NOC_CYAN1 
656   * Preselection color 
657 Default: Quantity_NOC_GREEN 
658   * Selection color (when you click on a detected object) 
659 Default: Quantity_NOC_GRAY80 
660   * Sub-Intensity color 
661 Default: Quantity_NOC_GRAY40 
662
663 All of these settings can be modified by functions proper to the Context. 
664
665 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. 
666 <h4>Example </h4>
667
668 //obj1, obj2: 2 interactive objects. 
669
670 TheCtx-Display(obj1,Standard_False); // False = no update 
671 of viewer. 
672 TheCtx-Display(obj2,Standard_True); // True = Update of 
673 Viewer 
674 TheCtx-SetDisplayMode(obj1,3,Standard_False); 
675 TheCtx-SetDisplayMode(2); 
676 // obj2 is visualised in mode 2 (if it accepts this mode) 
677 // obj1 stays visualised in its mode 3. 
678
679 To the main Viewer, are associated a *PresentationManager3D* and a *Selector3D *which manage the presentation and selection of present interactive objects. The same is true of the optional Collector. As we shall see, this management is completely transparent for the user. 
680
681
682 @subsection occt_1621831385_8103086097 Management of Local Context 
683
684 @subsubsection occt_1621831385_810308609771 Rules and Conventions 
685
686   * Opening a local context allows you to prepare an environment for temporary presentations and selections, which will disappear once the local context is closed. 
687   * It is possible to open several local contexts, but only the last one will be active. 
688   * When you close a local context, the one before, which is still on the stack, reactivates. If none is left, you return to Neutral Point. 
689   * Each local context has an index created when the context opens. You should close the local context, which you have opened. 
690
691 @subsubsection occt_1621831385_810308609772 Important functionality 
692
693 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*.  
694   * 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. 
695   * The state of a temporary interactive object in a local context can only be modified while another local context is open (except for one special case - see III.4.2) 
696
697 <h4>WARNING </h4>
698 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. Under no circumstances are they decomposed in standard mode etc. 
699
700 @subsubsection occt_1621831385_810308609773 Use 
701 Opening and closing a local context are easy to put into operation: 
702
703   *  AIS_InteractiveContext::OpenLocalContext 
704
705 The options available allow you to control what you want to do: 
706   * *UseDisplayedObjects*: allows you to load or not load the interactive objects visualized at Neutral Point in the local context, which you open. If* FALSE*, the local context is empty after being opened. If *TRUE*, the objects at Neutral Point are modified by their default selection mode. 
707   * *AllowShapeDecomposition*: AIS_Shape allows or prevents decomposition in standard shape location mode of objects at Neutral Point, which are type-*privileged* (see selection chapter). This Flag is only taken into account when *UseDisplayedObjects* is *TRUE*. 
708   * *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. 
709
710 This function returns the index of the created local context. It should be kept and used when the context is closed. 
711
712 To load objects visualized at Neutral Point into a local context or remove them from one: 
713   *  AIS_InteractiveContext::UseDisplayedObjects 
714   *  AIS_InteractiveContext::NotUseDisplayedObjects 
715
716 Closing Local Contexts is done by: 
717   *  AIS_InteractiveContext::CloseLocalContext 
718   *  AIS_InteractiveContext::CloseAllContexts 
719
720 *WARNING  * 
721
722 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. 
723
724 To get the index of the current context, use the following function: 
725
726   *  AIS_InteractiveContext::IndexOfCurrentLocal 
727
728 The second function allows you to close all open local contexts at one go. In this case, you find yourself directly at Neutral Point. 
729
730 When you close a local context, all temporary interactive objects are erased (deleted), all selection modes concerning the context are cancelled, and all content filters are emptied. 
731
732
733
734 @subsubsection occt_1621831385_810308609774 Management of Presentations and Selections 
735
736 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: 
737
738 @subsubsection occt_1621831385_810308609775 Presentation in Neutral Point 
739
740 Neutral Point should be used to visualize the interactive objects, which represent and select an applicative entity. Visualization and Erasing orders are straightforward: 
741
742   *  AIS_InteractiveContext::Display 
743 (const Handle(AIS_InteractiveObject)&amp; anIobj, 
744  const Standard_Boolean updateviewer=Standard_True); 
745
746   *  AIS_InteractiveContext::Display 
747 (const Handle(AIS_InteractiveObject)&amp; anIobj, 
748  const Standard_Integer amode, 
749  const Standard_Integer aSelectionMode, 
750  const Standard_Boolean 
751 updateviewer = Standard_True, 
752  const Standard_Boolean 
753 allowdecomposition = Standard_True); 
754
755   *  AIS_InteractiveContext::Erase 
756   *  AIS_InteractiveContext::EraseMode 
757   *  AIS_InteractiveContext::ClearPrs 
758   *  AIS_InteractiveContext::Redisplay 
759   *  AIS_InteractiveContext::Remove 
760   *  AIS_InteractiveContext::EraseAll 
761   *  AIS_InteractiveContext::Hilight 
762   *  AIS_InteractiveContext::HilightWithColor 
763
764 @subsubsection occt_1621831385_810308609776 Important Remarks: 
765
766 Bear in mind the following points: 
767   * It is recommended to display and erase interactive objects when no local context is opened, and open a local context for local selection only.
768   * 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). 
769   * 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.
770   * 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 the value of -1. This function is especially interesting in open local context, as we will see below. 
771   * In Neutral Point, it is unadvisable 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. 
772   * 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. 
773   * **Erase**() with *putInCollector* = Standard_True** might be slow as it re-computes the objects presentation in the Collector. Set putInCollector to Standard_False if you simply want to hide the object’s presentation temporarily.
774   * Modifications of visualization attributes and graphic behavior is effected through a set of functions similar to those which are available for the interactive object (color, thickness of line, material, transparency, locations etc.) The context then manages immediate and deferred updates. 
775   * 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 that results in memory leaks. In general, if some interactive object’s presentation can be computed quickly, it is recommended to **Remove**() it instead of **Erase**()-ing.
776
777 @subsubsection occt_1621831385_810308609777 Presentation in Local Context 
778
779 In open local context, the Display functions presented above apply as well. 
780
781 <h4>WARNING </h4>
782 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 second function: 
783
784 AIS_InteractiveContext::Display. 
785
786 You can activate or deactivate specific selection modes in local open context in several different ways: 
787 Use the Display functions with the appropriate modes  
788 Activate standard mode: 
789
790   *  AIS_InteractiveContext::ActivateStandardMode 
791 only if a local Context is opened 
792
793   *  AIS_InteractiveContext::DeactivateStandardMode 
794
795   *  AIS_InteractiveContext::ActivatedStandardModes 
796
797   *  AIS_InteractiveContext::SetShapeDecomposition 
798
799 This has the effect of activating 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 answers these decomposition criteria is automatically activated according to these modes. 
800
801 <h4>WARNING </h4>
802 If you have opened a local context by loading an object with the default options (AllowShapeDecomposition = Standard_True), all objects of the *Shape* type are also activated with the same modes. You can act on the state of these *Standard* objects by using SetShapeDecomposition(Status). 
803
804 Load an interactive object by the following function: 
805
806   *  AIS_InteractiveContext::Load. 
807
808 This function allows you to load an Interactive Object whether it is visualized or not with a given selection mode, and/or with the desired 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. 
809
810 Directly activate/deactivate selection modes on an object: 
811
812   *  AIS_InteractiveContext::Activate 
813   *  AIS_InteractiveContext::Deactivate. 
814     
815
816
817
818
819
820
821
822 @subsubsection occt_1621831385_810308609778 Use of Filters 
823
824 When Interactive objects have been *prepared* in 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 (*SelectMgr_EntityOwner*) detected in mouse position by the Local context selector answer *OK*. If so, it is kept; if not, it is rejected. 
825
826 You can therefore create your own class of filter objects by implementing the deferred function *IsOk()*: 
827 <h4>Example </h4>
828
829 class MyFilter : public SelectMgr_Filter { 
830 }; 
831 virtual Standard_Boolean MyFilter::IsOk 
832 (const Handle(SelectMgr_EntityOwner)&amp; anObj) const = 0; 
833
834
835 In *SelectMgr*, there are also Composition filters (AND Filters, OR Filters), which allow you to combine 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*). 
836
837 There are Standard filters, which have already been implemented in several packages: 
838
839   *  StdSelect_EdgeFilter 
840 Filters acting on edges such as lines and circles 
841   *  StdSelect_FaceFilter 
842 Filters acting on faces such as planes, cylinders and spheres 
843   *  StdSelect_ShapeTypeFilter 
844 Filters shape types such as compounds, solids, shells and wires 
845   *  AIS_TypeFilter 
846 Acts on types of interactive objects 
847   *  AIS_SignatureFilter 
848 Acts on types and signatures of interactive objects 
849   *  AIS_AttributeFilter 
850 Acts on attributes of Interactive Objects such as color and width 
851
852 Because there are specific behaviors on shapes, each new Filter class must, if necessary, redefine a function, which allows a Local Context to know if it acts on specific types of sub-shapes: 
853
854   *  AIS_LocalContext::ActsOn. 
855
856 By default, this function answers *FALSE*. 
857
858 *WARNING  * 
859 Only type filters are activated in Neutral Point. This is 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. 
860
861 There are several functions to manipulate filters: 
862
863   *  AIS_InteractiveContext::AddFilter 
864
865 to add a filter passed as an argument. 
866   
867   *  AIS_InteractiveContext::RemoveFilter 
868
869 to remove a filter passed as an argument. 
870
871   *  AIS_InteractiveContext::RemoveFilters 
872
873 to remove all filters present. 
874
875   *  AIS_InteractiveContext::Filters 
876
877 to get the list of filters active in a local context. 
878 <h4>Example </h4>
879
880 myContext-OpenLocalContext(Standard_False); 
881 // no object in neutral point is loaded 
882
883 myContext-ActivateStandardMode(TopAbs_Face); 
884 //activates decomposition of shapes into faces. 
885 Handle (AIS_Shape) myAIShape = new AIS_Shape ( ATopoShape); 
886
887 myContext-Display(myAIShape,1,-1,Standard_True,Standard_True); //shading visualization mode, no specific mode, authorization for //decomposition into sub-shapes. At this Stage, myAIShape is decomposed into faces... 
888
889 Handle(StdSelect_FaceFilter) Fil1= new 
890 StdSelect_FaceFilter(StdSelect_Revol);  
891 Handle(StdSelect_FaceFilter) Fil2= new 
892   StdSelect_FaceFilter(StdSelect_Plane); 
893
894 myContext-AddFilter(Fil1);  myContext-AddFilter(Fil2); //only faces of revolution or planar faces will be selected 
895   *   
896 myContext-MoveTo( xpix,ypix,Vue); 
897 // detects of mouse position 
898
899
900 @subsubsection occt_1621831385_810308609779 Selection Strictly Speaking. 
901 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: 
902
903   *  AIS_InteractiveContext::MoveTo 
904 passes mouse position to Interactive Context selectors 
905   *  AIS_InteractiveContext::Select 
906 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 
907   *  AIS_InteractiveContext::ShiftSelect 
908 if the object detected at the last move was not already selected , it is added to the list of those selected. If not, it is withdrawn. Nothing happens if you click on an empty area. 
909   *  AIS_InteractiveContext::Select 
910 selects everything found in the surrounding area 
911   *  AIS_InteractiveContext::ShiftSelect 
912 selects what was not previously in the list of selected, deselects those already present.  
913
914 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: 
915
916   *  AIS_InteractiveContext::SetAutomaticHilight 
917   *  AIS_InteractiveContext::AutomaticHilight 
918
919
920 If there is no open local context, the objects selected are called CURRENT OBJECTS; SELECTED OBJECTS if there is one. Iterators allow entities to be recovered in either case. A set of functions allows you to manipulate the objects, which have been placed in these different lists. 
921
922 *WARNING  * 
923 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. You can question the Interactive context by moving the mouse. The following functions will allow you to: 
924   * tell whether something has been detected 
925   * tell whether it is a shape 
926   * get the shape if the detected entity is one 
927   * get the interactive object if the detected entity is one. 
928
929 The following functions are concerned: 
930   *  AIS_InteractiveContext::HasDetected 
931   *  AIS_InteractiveContext::HasDetectedShape 
932   *  AIS_InteractiveContext::DetectedShape 
933   *  AIS_InteractiveContext::DetectedInteractive 
934
935 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. You can: 
936   * initiate a scan of this list 
937   * extend the scan 
938   * resume the scan 
939   * get the name of the current object detected in the scan. 
940
941 The following functions are concerned: 
942   *  AIS_InteractiveContext::InitCurrent 
943   *  AIS_InteractiveContext::MoreCurrent 
944   *  AIS_InteractiveContext::NextCurrent 
945   *  AIS_InteractiveContext::Current 
946
947 You can: 
948   * get the first current interactive object 
949   * highlight current objects 
950   * remove highlight from current objects 
951   * empty the list of current objects in order to update it 
952   * find the current object. 
953
954 The following functions are concerned: 
955   *  AIS_InteractiveContext::FirstCurrentObject 
956   *  AIS_InteractiveContext::HilightCurrents 
957   *  AIS_InteractiveContext::UnhilightCurrents 
958   *  AIS_InteractiveContext::ClearCurrents 
959   *  AIS_InteractiveContext::IsCurrent. 
960
961 In Local Context, you can explore the list of selected objects available. You can: 
962   * initiate, 
963   * extend, 
964   * resume a scan, and then 
965   * get the name of the selected object. 
966
967 The following functions are concerned: 
968
969   *  AIS_InteractiveContext::InitSelected 
970   *  AIS_InteractiveContext::MoreSelected 
971   *  AIS_InteractiveContext::NextSelected 
972   *  AIS_InteractiveContext::SelectedShape. 
973
974 You can: 
975   * check to see if you have a selected shape, and if not, 
976   * get the picked interactive object, 
977   * check to see if the applicative object has an owner from Interactive attributed to it 
978   * get the owner of the detected applicative entity 
979   * get the name of the selected object. 
980
981 The following functions are concerned: 
982
983   *  AIS_InteractiveContext::HasSelectedShape 
984   *  AIS_InteractiveContext::Interactive 
985   *  AIS_InteractiveContext::HasApplicative 
986   *  AIS_InteractiveContext::Applicative 
987   *  AIS_InteractiveContext::IsSelected. 
988
989 <h4>Example </h4>
990
991
992 myAISCtx-InitSelected(); 
993 while (myAISCtx-MoreSelected()) 
994
995 if (myAISCtx-HasSelectedShape) 
996
997 TopoDS_Shape ashape = myAISCtx-SelectedShape(); 
998 // to be able to use the picked shape 
999     } 
1000 else 
1001
1002 Handle_AIS_InteractiveObject aniobj = myAISCtx-Interactive(); 
1003 // to be able to use the picked interactive object 
1004
1005 myAISCtx-NextSelected(); }   
1006
1007
1008 @subsubsection occt_1621831385_8103086097710 Remarks: 
1009
1010 In Local Context and in the iteration loop, which allows you to recover selected entities, you have to ask whether you have selected a shape or an interactive object before you can recover the entity. 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: 
1011   * erase selected objects 
1012   * display them, 
1013   * put them in the list of selections 
1014
1015 The following functions are concerned: 
1016
1017   *  AIS_InteractiveContext::EraseSelected 
1018   *  AIS_InteractiveContext::DisplaySelected 
1019   *  AIS_InteractiveContext::SetSelected 
1020
1021
1022 You can also: 
1023
1024   * take the list of selected objects from a local context and put it into the list of current objects in Neutral Point, 
1025   * add or remove an object from the list of selected entities, 
1026   * highlight and 
1027   * remove highlighting from a selected object 
1028   * empty the list of selected objects. 
1029
1030 The following functions are concerned: 
1031
1032   *  AIS_InteractiveContext::SetSelectedCurrent 
1033   *  AIS_InteractiveContext::AddOrRemoveSelected 
1034   *  AIS_InteractiveContext::HilightSelected 
1035   *  AIS_InteractiveContext::UnhilightSelected 
1036   *  AIS_InteractiveContext::ClearSelected 
1037
1038 You can highlight and remove highlighting from a current object, and empty the list of current objects. 
1039
1040   *      AIS_InteractiveContext::HilightCurrents 
1041   *      AIS_InteractiveContext::UnhilightCurrents 
1042   *      AIS_InteractiveContext::ClearCurrents 
1043
1044 When you are in open Local Context, you may be lead to keep *temporary* interactive objects. This is possible using the following functions: 
1045
1046   *  AIS_InteractiveContext::KeepTemporary 
1047   *  AIS_InteractiveContext::SetSelectedCurrent 
1048
1049 The first function 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. The second allows the selected object to become the current object when you close the local context. 
1050 You can also want to modify in a general way the state of the local context before continuing a selection (emptying objects, removing filters, standard activation modes). To do that, you must use the following function: 
1051
1052   *  AIS_InteractiveContext::ClearLocalContext 
1053
1054 @subsubsection occt_1621831385_8103086097711 Advice on Using Local Contexts 
1055
1056 The possiblities of use for local contexts are numerous depending on the type of operation that you want to perform: 
1057   * working on all visualized interactive objects, 
1058   * working on only a few objects, 
1059   * working on a single object. 
1060
1061 1. 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: 
1062
1063 AIS_InteractiveContext::DisplayedObjects 
1064 (AIS_ListOfInteractive&amp; aListOfIO) const; 
1065
1066 AIS_InteractiveContext::DisplayedObjects 
1067 (const AIS_KindOfInteractive WhichKind, 
1068  const Standard_Integer WhichSignature, 
1069 AIS_ListOfInteractive&amp; aListOfIO) const; 
1070
1071 At this stage, you only have to load the functions Load, Activate, and so on. 
1072
1073 2. When you open a Local Context with default options, you must keep the following points in mind: 
1074
1075 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. 
1076
1077 The Shape Type Interactive Objects are automatically decomposed into sub-shapes when standard activation modes are launched. 
1078
1079 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. 
1080
1081 The stages could be the following: 
1082 1. Open a Local Context with the right options; 
1083 2. Load/Visualize the required complementary objects with the desired activation modes. 
1084 3. Activate Standard modes if necessary 
1085 4. Create its filters and add them to the Local Context 
1086 5. Detect/Select/recover the desired entities 
1087 6. Close the Local Context with the adequate index. 
1088
1089 It is useful to create an INTERACTIVE EDITOR, to which you pass the Interactive Context. This will take care of setting up the different contexts of selection/presentation according to the operation, which you want to perform. 
1090 <h4>Example </h4>
1091
1092
1093 You have visualized several types of interactive objects: *AIS_Points*, *AIS_Axes*, *AIS_Trihedrons*, and *AIS_Shapes*. 
1094
1095 For your applicative function, you need an axis to create a revolved object. You could obtain this axis by identifying: 
1096   * an axis which is already visualized,
1097   * 2 points,
1098   * a rectilinear edge on the shapes which are present,
1099   * a cylindrical face on the shapes (You will take the axis of this face) 
1100
1101 myIHMEditor::myIHMEditor 
1102 (const Handle(AIS_InteractiveContext)&amp; Ctx, 
1103  ....) : 
1104  myCtx(Ctx), 
1105 ... 
1106
1107
1108
1109
1110 myIHMEditor::PrepareContext() 
1111
1112 myIndex =myCtx-OpenLocalContext(); 
1113
1114 //the filters 
1115
1116 Handle(AIS_SignatureFilter) F1 = new 
1117  AIS_SignatureFilter(AIS_KOI_Datum,AIS_SD_Point);  
1118 //filter on the points 
1119
1120 Handle(AIS_SignatureFilter) F2 = new 
1121 AIS_SignatureFilter(AIS_KOI_Datum,AIS_SD_Axis);  
1122 //filters on the axes. 
1123
1124 Handle(StdSelect_FaceFilter) F3 = new 
1125  StdSelect_FaceFilter(AIS_Cylinder);  
1126 //cylindrical face filters 
1127
1128 //... 
1129
1130 // activation of standard modes on the shapes.. 
1131 myCtx-ActivateStandardMode(TopAbs_FACE); 
1132 myCtx-ActivateStandardMode(TopAbs_VERTEX); 
1133 myCTX-Add(F1); 
1134 myCTX-Add(F2); 
1135 myCTX-Add(F3); 
1136
1137 // at this point, you can call the selection/detection function 
1138
1139
1140 void myIHMEditor::MoveTo(xpix,ypix,Vue) 
1141
1142 { myCTX-MoveTo(xpix,ypix,vue); // the highlight of what is detected is automatic. }   
1143 Standard_Boolean myIHMEditor::Select() {  // returns true if you should continue the selection   
1144 myCTX-Select();  myCTX-InitSelected(); if(myCTX-MoreSelected()) 
1145  {  if(myCTX-HasSelectedShape())   
1146 { const TopoDS_Shape&amp; sh = myCTX-SelectedShape(); 
1147 if( vertex){ 
1148 if(myFirstV...)  
1149
1150 //if it’s the first vertex, you stock it, then you deactivate the faces and only keep the filter on the points: 
1151 mypoint1 = ....; 
1152 myCtx-RemoveFilters(); 
1153 myCTX-DeactivateStandardMode(TopAbs_FACE);  
1154 myCtx-Add(F1);  
1155 // the filter on the AIS_Points 
1156 myFirstV = Standard_False; 
1157 return Standard_True; 
1158  } else  { 
1159   mypoint2 =...; 
1160 // construction of the axis return Standard_False; 
1161
1162  } 
1163  else 
1164   { 
1165 //it is a cylindrical face : you recover the axis; visualize it; and stock it. 
1166 return Standard_False; 
1167
1168   } 
1169 // it is not a shape but is no doubt a point. 
1170 else 
1171
1172 Handle(AIS_InteractiveObject)  
1173 SelObj = myCTX-SelectedInteractive(); 
1174 if(SelObj-Type()==AIS_KOI_Datum)  
1175
1176 if(SelObj-Signature()==1)  
1177
1178 if (firstPoint) 
1179
1180 mypoint1 =... 
1181 return Standard_True; 
1182
1183 else 
1184
1185 mypoint2 = ...; 
1186 //construction of the axis, visualization, stocking 
1187 return Standard_False; 
1188
1189
1190
1191 else 
1192
1193 // you have selected an axis; stock the axis 
1194 return Standard_False; 
1195
1196
1197
1198
1199
1200 @subsection occt_1621831385_810308609111 ANNEX I: Standard Interactive Object Classes in AIS DATUMS: 
1201
1202 AIS_Point AIS_Axis AIS_Line AIS_Circle AIS_Plane AIS_Trihedron : 4 selection modes 
1203   * mode 0 : selection of a trihedron 
1204   * mode 1 : selection of the origin of the trihedron 
1205   * mode 2 : selection of the axes 
1206   * mode 3 : selection of the planes XOY, YOZ, XOZ 
1207
1208 when you activate one of modes 1 2 3 4 , you pick AIS objects of type: 
1209   * AIS_Point 
1210   * AIS_Axis (and information on the type of axis) 
1211   * AIS_Plane (and information on the type of plane). 
1212
1213 AIS_PlaneTrihedron offers 3 selection modes: 
1214   * mode 0 : selection of the whole trihedron 
1215   * mode 1 : selection of the origin of the trihedron 
1216   * mode 2 : selection of the axes - same remarks as for the Trihedron. 
1217
1218 <h4>Warning </h4>
1219 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 inside it, take the Aspects in which the values for length are stocked (PlaneAspect for the plane, FirstAxisAspect for trihedra), and change these values inside these Aspects. Finally, recalculate the presentation. 
1220
1221 @subsubsection occt_1621831385_8103086092222 OBJECTS 
1222
1223 AIS_Shape : 3 visualization modes : 
1224
1225   * mode 0 : Line (default mode) 
1226   * mode 1 : Shading (depending on the type of shape) 
1227   * mode 2 : Bounding Box 
1228
1229 Seven maximum selection modes, depending on the complexity of the shape: 
1230   * mode 0 : selection of the AIS_Shape 
1231   * mode 1 : selection of the vertices 
1232   * mode 2 : selection of the edges 
1233   * mode 3 : selection of the wires 
1234   * mode 4 : selection of the faces 
1235   * mode 5 : selection of the shells 
1236   * mode 6 : selection of the constituent solids. 
1237
1238 AIS_Triangulation: Simple interactive object for displaying triangular mesh contained in Poly_Triangulation container. 
1239
1240 AIS_ConnectedInteractive: 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. 
1241
1242 AIS_ConnectedShape: 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. 
1243
1244 AIS_MultipleConnectedInteractive: Object connected to a list of interactive objects (which can also be Connected objects. It does not require memory hungry calculations of presentation) 
1245
1246 AIS_MultipleConnectedShape: Interactive Object connected to a list of interactive objects having a Shape (AIS_Shape, AIS_ConnectedShape, AIS_MultipleConnectedShape). The presentation of hidden parts is calculated automatically. 
1247
1248 AIS_TexturedShape: 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. 
1249
1250 MeshVS_Mesh: 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. 
1251
1252 @subsubsection occt_1621831385_8103086093333 RELATIONS 
1253 The list is not exhaustive. 
1254 AIS_ConcentricRelation 
1255 AIS_FixRelation 
1256 AIS_IdenticRelation 
1257 AIS_ParallelRelation 
1258 AIS_PerpendicularRelation 
1259 AIS_Relation 
1260 AIS_SymmetricRelation 
1261 AIS_TangentRelation 
1262
1263 @subsubsection occt_1621831385_810308609444 DIMENSIONS 
1264 AIS_AngleDimension 
1265 AIS_Chamf2dDimension 
1266 AIS_Chamf3dDimension 
1267 AIS_DiameterDimension 
1268 AIS_DimensionOwner 
1269 AIS_LengthDimension 
1270 AIS_OffsetDimension 
1271 AIS_RadiusDimension 
1272
1273 @subsubsection occt_1621831385_810308609555 MeshVS_Mesh
1274 MeshVS_Mesh is an Interactive Object that represents meshes. 
1275 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. 
1276 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. 
1277 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. 
1278 You can add/remove builders using the following methods: 
1279   *  MeshVS_Mesh::AddBuilder 
1280  (const Handle (MeshVS_PrsBuilder) &amp;Builder, 
1281   Standard_Boolean TreatAsHilighter) 
1282   *  MeshVS_Mesh::RemoveBuilder (const Standard_Integer Index) 
1283   *  MeshVS_Mesh::RemoveBuilderById 
1284  (const Standard_Integer Id) 
1285
1286 There is a set of reserved display and highlighting mode flags for MeshVS_Mesh. Mode value is a number of bits that allows you to select additional display parameters and combine the following mode flags: 
1287   * MeshVS_DMF_WireFrame
1288   * MeshVS_DMF_Shading
1289   * MeshVS_DMF_Shrink
1290 base modes: display mesh in wireframe, shading, shrink modes. 
1291
1292   * MeshVS_DMF_VectorDataPrs 
1293   * MeshVS_DMF_NodalColorDataPrs
1294   * MeshVS_DMF_ElementalColorDataPrs
1295   * MeshVS_DMF_TextDataPrs
1296   * MeshVS_DMF_EntitiesWithData
1297 represent different kinds of data 
1298
1299   * MeshVS_DMF_DeformedPrsWireFrame
1300   * MeshVS_DMF_DeformedPrsShading 
1301   * MeshVS_DMF_DeformedPrsShrink
1302 display deformed mesh in wireframe, shading or shrink modes 
1303
1304   * MeshVS_DMF_SelectionPrs
1305   * MeshVS_DMF_HilightPrs
1306 selection and hilighting 
1307
1308   * MeshVS_DMF_User
1309 user-defined mode 
1310
1311 These values will be used by the presentation builder. 
1312 There is also a set of selection modes flags that can be grouped in a combination of bits: 
1313   * MeshVS_SMF_0D
1314   * MeshVS_SMF_Link
1315   * MeshVS_SMF_Face
1316   * MeshVS_SMF_Volume
1317   * MeshVS_SMF_Element
1318 Element: 0D, Link, Face and Volume grouped as a bit mask 
1319
1320   * MeshVS_SMF_Node
1321   * MeshVS_SMF_All
1322 All: Element and Node grouped as a bit mask 
1323
1324   * MeshVS_SMF_Mesh
1325   * MeshVS_SMF_Group
1326
1327 Such an object, for example, can be used for displaying the object, stored in the STL file format: 
1328 <h4>Example </h4>
1329
1330 **// read the data and create a data source** 
1331 Handle (StlMesh_Mesh) aSTLMesh = RWStl::ReadFile (aFileName); 
1332 Handle (XSDRAWSTLVRML_DataSource) aDataSource = 
1333  new XSDRAWSTLVRML_DataSource (aSTLMesh); 
1334
1335 **// create mesh** 
1336 Handle (MeshVS_Mesh) aMesh = new MeshVS(); 
1337 aMesh-SetDataSource (aDataSource); 
1338
1339 **// use default presentation builder** 
1340 Handle (MeshVS_MeshPrsBuilder) aBuilder = 
1341     new MeshVS_MeshPrsBuilder (aMesh); 
1342 aMesh-AddBuilder (aBuilder, Standard_True); 
1343
1344 MeshVS_NodalColorPrsBuilder allows you to represent a mesh with a color scaled texture mapped on it. To do this you should define a color map for the color scale, pass this map to the presentation builder, and define an appropriate value in the range of 0.0 – 1.0 for every node. 
1345 The following example demonstrates how you can do this (**please check,** if the view has been set up to display textures): 
1346 <h4>Example </h4>
1347
1348 **// assign nodal builder to the mesh** 
1349 Handle (MeshVS_NodalColorPrsBuilder) aBuilder = 
1350   new MeshVS_NodalColorPrsBuilder 
1351     (aMesh,MeshVS_DMF_NodalColorDataPrs | MeshVS_DMF_OCCMask); 
1352 aBuilder-UseTexture (Standard_True); 
1353
1354 **// prepare color map** 
1355 Aspect_SequenceOfColor aColorMap; 
1356 aColorMap.Append ((Quantity_NameOfColor) Quantity_NOC_RED); 
1357 aColorMap.Append ((Quantity_NameOfColor) Quantity_NOC_BLUE1); 
1358
1359 **// assign color scale map values (0..1) to nodes** 
1360 TColStd_DataMapOfIntegerReal aScaleMap; 
1361 **…** 
1362 **   // iterate through the nodes and add an node id and an appropriate ** 
1363 **   // value to the map** 
1364  aScaleMap.Bind (anId, aValue); 
1365   
1366 **// pass color map and color scale values to the builder** 
1367 aBuilder-SetColorMap (aColorMap); 
1368 aBuilder-SetInvalidColor (Quantity_NOC_BLACK); 
1369 aBuilder-SetTextureCoords (aScaleMap); 
1370 aMesh-AddBuilder (aBuilder, Standard_True); 
1371
1372 @subsection occt_1621831385_810308609666 ANNEX II : Principles of Dynamic Selection     
1373
1374
1375 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. 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. 
1376
1377
1378 @subsubsection occt_1621831385_81030860912222 How to go from the objects to 2D boxes 
1379
1380
1381 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. 
1382
1383 The sensitive primitive is capable of: 
1384   * giving a 2D bounding box to the selector. 
1385   * answering the rejection criteria positively or negatively by a *Matches* function. 
1386   * being projected from 3D in the 2D space of the view if need be. 
1387   * returning the owner which it will represent in terms of selection. 
1388
1389 A set of standard sensitive primitives exists in Select3D packages for 3D primitives, and Select2D for 2D primitives. 
1390
1391 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 modulate, so as to make one entity more selectable than another. 
1392 @image html /user_guides/visualization/images/visualization_image021.png
1393 @image latex /user_guides/visualization/images/visualization_image021.png
1394
1395 @subsubsection occt_1621831385_81030860912341 Implementation in an interactive/selectable object 
1396   
1397 1. Define the number of selection modes possible, i.e. what you want to identify by activating each of the selection modes. Example: for an interactive object representing a topological shape, 
1398 mode 0: selection of the interactive object itself 
1399 mode 1: selection of the vertices 
1400 mode 2: selection of the edges 
1401 mode 3: selection of the wires 
1402 mode 4: selection of the faces detectable 
1403
1404 2. For each selection mode of an interactive object, *model* the set of entities, which you want to locate by these primitives and these owners. 
1405
1406 3. There exists an *owner* root class, *SelectMgr_EntityOwne*r, 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. 
1407
1408 4. The set of sensitive primitives which has been calculated for a given mode is stocked in *SelectMgr_Selection*. 
1409
1410 5. For an Interactive object, the modeling is done in the *ComputeSelection *virtual function. 
1411
1412 <h4>Example </h4>
1413
1414 Let an interactive object represent a box. 
1415 We are interested in having 2 location modes: 
1416   *  mode 0: location of the whole box. 
1417   *  mode 1: location of the edges on the box. 
1418
1419  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*. 
1420
1421 The *ComputeSelection* function for the interactive box can have the following form: 
1422
1423 void InteractiveBox::ComputeSelection 
1424 (const Handle(SelectMgr_Selection)&amp; Sel, 
1425  const Standard_Integer Mode) 
1426
1427 switch(Mode) 
1428 { case 0:  //locating the whole box by making its faces sensitive... 
1429
1430 Handle(SelectMgr_EntityOwner) Ownr = new 
1431  SelectMgr_EntityOwner(this,5);  
1432 for(Standard_Integer I=1;I=Nbfaces;I++) 
1433
1434 //Array is a TColgp_Array1OfPnt: which represents the array of vertices. Sensitivity is 
1435 Select3D_TypeOfSensitivity value 
1436 Sel-Add(new 
1437 Select3D_SensitiveFace(Ownr,Array,Sensitivity)); 
1438
1439 break; 
1440    } 
1441   case 1: 
1442 // locates the edges {   for(Standard_Integer i=1;i=12;i++) 
1443
1444 // 1 owner per edge... 
1445 Handle(mypk_EdgeOwner) Ownr = 
1446 new mypk_EdgeOwner(this,i,6); 
1447 //6-priority 
1448 Sel-Add(new Select3D_SensitiveSegment 
1449     (Ownr,firstpt(i),lastpt(i))); 
1450
1451 break; 
1452
1453
1454
1455
1456
1457 @subsubsection occt_1621831385_81030860912432 How It Works Concretely 
1458
1459 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. NOTE: This procedure is completely hidden if you use the interactive contexts of AIS (see section 3.3, Contexts) 
1460
1461 <h4>Example </h4>
1462
1463 //We have several  * interactive boxes  * box1, box2, box3; 
1464
1465 Handle(SelectMgr_SelectionManager) SM = new SelectMgr_SelectionManager(); 
1466 Handle(StdSelect_ViewerSelector3d) VS = new StdSelect_ViewerSelector3d(); 
1467
1468 SM-Add(VS); 
1469 SM-Load(box1);SM-Load(box2);SM-Load(box3); 
1470 // box load. 
1471 SM-Activate(box1,0,VS); 
1472 // activates mode 0 of box 1 in the selector VS 
1473 SM-Activate(box1,1,VS);  
1474 M-Activate(box3,1,VS);  
1475
1476 VS-Pick(xpix,ypix,vue3d) 
1477 // detection of primitives by mouse position. 
1478
1479 Handle(EntityOwner) POwnr = VS-OnePicked(); 
1480 // picking of the *best* owner detected 
1481
1482 for(VS-Init();VS-More();VS-Next())  
1483
1484 VS-Picked();  
1485 // picking of all owners detected 
1486   } 
1487 SM-Deactivate(box1);  
1488 // deactivate all active modes of box1 
1489
1490 @image html /user_guides/visualization/images/visualization_image022.png
1491 @image latex /user_guides/visualization/images/visualization_image022.png
1492 1st activation of the box’s mode 1: calculation of sensitive primitives + 3D/2D projection + sorting 
1493
1494 deactivation of mode: only updated by sorting 
1495
1496 rotation of the view: only projection + sorting of active primitives 
1497
1498 modification of the box - Recalculation of the active selection, recalculation flag on the inactive ones  + 3D/2D projection + sorting 
1499
1500 @section occt_1621831385_1539918866 3D Presentations
1501
1502 @subsection occt_1621831385_15399188661 Glossary of 3D terms 
1503
1504 @subsubsection occt_1621831385_153991886611 From Graphic3d 
1505
1506
1507
1508 @subsubsection occt_1621831385_153991886612 From V3d 
1509
1510
1511 **    **  
1512
1513
1514 @subsection occt_1621831385_15399188662 Creating a 3D scene 
1515
1516 To create 3D graphic objects and display them on the screen, follow the procedure below: 
1517 **1. **Create attributes. 
1518 **2. **Create a 3D viewer.. 
1519 **3. **Create a view. 
1520 **4. **Create an interactive context. 
1521 **5. **Create interactive objects. 
1522 **6. **Create primitives in the interactive object 
1523 **7. **Display the interactive object. 
1524
1525 @subsubsection occt_1621831385_153991886621 Create attributes 
1526
1527 Create colors. 
1528 <h4>Example </h4>
1529
1530 Quantity_Color Black (Quantity_NOC_BLACK); 
1531 Quantity_Color Blue (Quantity_NOC_MATRABLUE); 
1532 Quantity_Color Brown (Quantity_NOC_BROWN4); 
1533 Quantity_Color Firebrick (Quantity_NOC_FIREBRICK); 
1534 Quantity_Color Forest (Quantity_NOC_FORESTGREEN); 
1535 Quantity_Color Gray (Quantity_NOC_GRAY70); 
1536 Quantity_Color 
1537 MyColor (0.99, 0.65, 0.31, Quantity_TOC_RGB); 
1538 Quantity_Color Beet (Quantity_NOC_BEET); 
1539 Quantity_Color White (Quantity_NOC_WHITE); 
1540
1541
1542
1543 Create line attributes. 
1544
1545 <h4>Example </h4>
1546
1547 Handle(Graphic3d_AspectLine3d) CTXLBROWN = 
1548 new Graphic3d_AspectLine3d (); 
1549 Handle(Graphic3d_AspectLine3d) CTXLBLUE = 
1550 new Graphic3d_AspectLine3d (); 
1551 Handle(Graphic3d_AspectLine3d) CTXLWHITE = 
1552 new Graphic3d_AspectLine3d(); 
1553 CTXLBROWN-SetColor (Brown); 
1554 CTXLBLUE-SetColor (Blue); 
1555 CTXLWHITE-SetColor (White); 
1556
1557
1558 Create marker attributes. 
1559 <h4>Example </h4>
1560
1561 Handle(Graphic3d_AspectMarker3d) CTXMFIREBRICK = 
1562 new Graphic3d_AspectMarker3d();  
1563 CTXMFIREBRICK-SetColor (Firebrick); 
1564 CTXMFIREBRICK-SetScale (1.0); 
1565 CTXMFIREBRICK-SetType (Aspect_TOM_BALL); 
1566
1567
1568 Create facet attributes. 
1569 <h4>Example </h4>
1570
1571 Handle(Graphic3d_AspectFillArea3d) CTXF = 
1572 new Graphic3d_AspectFillArea3d (); 
1573 Graphic3d_MaterialAspect BrassMaterial 
1574 (Graphic3d_NOM_BRASS); 
1575 Graphic3d_MaterialAspect GoldMaterial 
1576 (Graphic3d_NOM_GOLD); 
1577 CTXF-SetInteriorStyle (Aspect_IS_SOLID); 
1578 CTXF-SetInteriorColor (MyColor); 
1579 CTXF-SetDistinguishOn (); 
1580 CTXF-SetFrontMaterial (GoldMaterial); 
1581 CTXF-SetBackMaterial (BrassMaterial); 
1582 CTXF-SetEdgeOn (); 
1583
1584
1585 Create text attributes. 
1586 <h4>Example </h4>
1587
1588 Handle(Graphic3d_AspectText3d) CTXT = 
1589 new Graphic3d_AspectText3d 
1590 (Forest, Graphic3d_NOF_ASCII_MONO, 1., 0.); 
1591
1592 @subsubsection occt_1621831385_153991886622 Create a 3D Viewer (a Windows example) 
1593 <h4>Example </h4>
1594
1595 Handle(Graphic3d_WNTGraphicDevice) TheGraphicDevice = ...; 
1596 TCollection_ExtendedString aName(*3DV*); 
1597 myViewer = 
1598 new V3d_Viewer (TheGraphicDevice,aName.ToExtString (), **); 
1599 myViewer - SetDefaultLights (); 
1600 myViewer - SetLightOn (); 
1601 @subsubsection occt_1621831385_153991886623 Create a 3D view (a Windows example) 
1602
1603 It is assumed that a valid Windows window may already be accessed via the method GetSafeHwnd().   
1604 <h4>Example </h4>
1605
1606
1607
1608 @subsubsection occt_1621831385_153991886624 Create an interactive context 
1609 <h4>Example </h4>
1610
1611 myAISContext = new AIS_InteractiveContext (myViewer); 
1612
1613
1614 You are now able to display interactive objects such as an AIS_Shape. 
1615 <h4>Example </h4>
1616
1617 TopoDS_Shape aShape = BRepAPI_MakeBox(10,20,30)_Solid(); 
1618 Handle (AIS_Shape) aAISShape = new AIS_Shape(aShape); 
1619 myAISContext - Display (aAISShape); 
1620
1621 @subsubsection occt_1621831385_153991886625 Create your own interactive object 
1622
1623 Follow the procedure below to compute the presentable object: 
1624
1625 **1. **Build a presentable object inheriting from AIS_InteractiveObject (refer to the Chapter on Presentable Objects). 
1626
1627 **2. **Reuse the Prs3d_Presentation provided as an argument of the compute methods. 
1628
1629 *NOTE* 
1630 *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.* 
1631 <h4>Example of the compute methods</h4>
1632
1633 Void 
1634 myPresentableObject::Compute 
1635 (const Handle(PrsMgr_PresentationManager3d)&amp; 
1636 aPresentationManager,  
1637 const Handle(Prs3d_Presentation)&amp; aPrs, 
1638 const Standard_Integer aMode) 
1639
1640 //... 
1641
1642
1643
1644
1645 void 
1646 myPresentableObject::Compute 
1647 (const Handle(Prs3d_Projector)&amp;, 
1648 const Handle(Prs3d_Presentation)&amp; aPrs) 
1649
1650 //... 
1651
1652
1653
1654 @subsubsection occt_1621831385_153991886626 Create primitives in the interactive object 
1655
1656 Get the group used in Prs3d_Presentation. 
1657 <h4>Example </h4>
1658
1659 Handle(Graphic3d_Group) TheGroup = Prs3d_Root::CurrentGroup(aPrs); 
1660
1661
1662 Update the group attributes. 
1663
1664 <h4>Example </h4>
1665
1666 TheGroup - SetPrimitivesAspect(CTXLBLUE); 
1667
1668
1669 Create two triangles in group TheGroup. 
1670 <h4>Example </h4>
1671
1672 Standard_Integer aNbTria = 2; 
1673 Handle(Graphic3d_ArrayOfTriangles) aTriangles = new Graphic3d_ArrayOfTriangles(3  * aNbTria, 0, Standard_True); 
1674 Standard_Integer anIndex; 
1675 for (anIndex = 1; anIndex = aNbTria; nt++) 
1676
1677   aTriangles-AddVertex(anIndex  * 5., 0., 0., 1., 1., 1.); 
1678   aTriangles-AddVertex(anIndex  * 5 + 5, 0., 0., 1., 1., 1.); 
1679   aTriangles-AddVertex(anIndex  * 5 + 2.5, 5., 0., 1., 1., 1.); 
1680
1681 TheGroup-BeginPrimitives (); 
1682 mygroup-AddPrimitiveArray(aTriangles); 
1683 TheGroup-EndPrimitives (); 
1684
1685
1686 The BeginPrimitives () and EndPrimitives () methods are used when creating a set of various primitives in the same group. 
1687 Use the polyline function to create a boundary box for the Struct structure in group TheGroup. 
1688 <h4>Example </h4>
1689
1690 Standard_Real Xm, Ym, Zm, XM, YM, ZM; 
1691 Struct-MinMaxValues (Xm, Ym, Zm, XM, YM, ZM);  
1692
1693 Handle(Graphic3d_ArrayOfPolylines) aPolylines = new Graphic3d_ArrayOfPolylines(16, 4); 
1694 aPolylines-AddBound (4); 
1695 aPolylines-AddVertex (Xm, Ym, Zm); 
1696 aPolylines-AddVertex (Xm, Ym, ZM); 
1697 aPolylines-AddVertex (Xm, YM, ZM); 
1698 aPolylines-AddVertex (Xm, YM, Zm); 
1699 aPolylines-AddBound (4); 
1700 aPolylines-AddVertex (Xm, Ym, Zm); 
1701 aPolylines-AddVertex (XM, Ym, Zm); 
1702 aPolylines-AddVertex (XM, Ym, ZM); 
1703 aPolylines-AddVertex (XM, YM, ZM); 
1704 aPolylines-AddBound (4); 
1705 aPolylines-AddVertex (XM, YM, Zm); 
1706 aPolylines-AddVertex (XM, Ym, Zm); 
1707 aPolylines-AddVertex (XM, YM, Zm); 
1708 aPolylines-AddVertex (Xm, YM, Zm); 
1709 aPolylines-AddBound (4); 
1710 aPolylines-AddVertex (Xm, YM, ZM); 
1711 aPolylines-AddVertex (XM, YM, ZM); 
1712 aPolylines-AddVertex (XM, Ym, ZM); 
1713 aPolylines-AddVertex (Xm, Ym, ZM); 
1714
1715 TheGroup-BeginPrimitives (); 
1716 TheGroup-AddPrimitiveArray(aPolylines); 
1717 TheGroup-EndPrimitives (); 
1718
1719
1720 Create text and markers in group TheGroup. 
1721 <h4>Example </h4>
1722
1723 static char *texte[3] = {  *Application title*, 
1724 *My company*, 
1725 *My company address.* }; 
1726 Graphic3d_Array1OfVertex Tpts8 (0, 1); 
1727 Tpts8(0).SetCoord (-40.0, -40.0, -40.0); 
1728 Tpts8(1).SetCoord (40.0, 40.0, 40.0); 
1729 TheGroup-MarkerSet (Tpts8); 
1730 Graphic3d_Vertex Marker (0.0, 0.0, 0.0); 
1731
1732 for (i=0; i=2; i++) { 
1733   Marker.SetCoord (-(Standard_Real)i*4 + 30, 
1734     (Standard_Real)i*4, 
1735    -(Standard_Real)i*4); 
1736   TheGroup-Text (texte[i], Marker, 20.); 
1737
1738
1739 @section occt_1621831385_1435012457 3D Resources
1740
1741 The 3D resources include the Graphic3d and V3d packages. 
1742
1743 @subsection occt_1621831385_14350124571 Graphic3D 
1744
1745 @subsubsection occt_1621831385_143501245711 Overview 
1746
1747 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. 
1748
1749 @subsubsection occt_1621831385_143501245712 Provided services 
1750
1751 Graphic structures can be: 
1752   * Displayed, 
1753   * Highlighted, 
1754   * Erased, 
1755   * Transformed, 
1756   * Connected to form a tree.
1757  There are classes for: 
1758   * Visual attributes for lines, faces, markers, text, materials, 
1759   * Vectors and vertices, 
1760   * Defining an Advanced Graphic Device, 
1761   * Graphic objects, groups, and structures. 
1762
1763 @subsubsection occt_1621831385_143501245713 About the primitives 
1764 ** ** 
1765 ** **Markers** ** 
1766   * Have one or more vertices, 
1767   * Have a type, a scale factor, and a color, 
1768   * Have a size, shape, and orientation independent of transformations. 
1769 *Polygons  * 
1770   * Have one closed boundary, 
1771   * Have at least three vertices, 
1772   * Are planar and have a normal, 
1773   * Have interior attributes - style, color, front and back material, texture and reflection ratio, 
1774   * Have a boundary with the following attributes - type, width scale factor, color. The boundary is only drawn when the interior style is hollow. 
1775
1776 *Polygons with holes  * 
1777   * Have multiple closed boundaries, each one with at least three vertices, 
1778   * Are planar and have a normal, 
1779   * Have interior attributes - style, color, front and back material, 
1780   * Have a boundary with the following attributes - type, width scale factor, color. The boundary is only drawn when the interior style is hollow. 
1781
1782 *Polylines  * 
1783   * Have two or more vertices, 
1784   * Have the following attributes - type, width scale factor, color. 
1785
1786 *Text  * 
1787   * Has geometric and non-geometric attributes, 
1788   * Geometric attributes - character height, character up vector, text path, horizontal and vertical alignment, orientation, three-dimensional position, zoomable flag
1789   * Non-geometric attributes - text font, character spacing, character expansion factor, color. 
1790
1791 @subsubsection occt_1621831385_143501245714 Primitive arrays
1792
1793 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. 
1794
1795 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. 
1796
1797 The Vertex Buffer Objects can be disabled at the application level. You can use the following method to enable/disable VBOs: 
1798   * void Graphic3d_GraphicDriver::EnableVBO 
1799  (const Standard_Boolean status) 
1800
1801 The following example shows how to disable the VBO support: 
1802 <h4>Example </h4>
1803
1804 **// get the graphic driver** 
1805 Handle (Aspect_GraphicDriver) aDriver = 
1806   myAISContext-CurrentViewer()-Device()-GraphicDriver(); 
1807
1808 **// disable VBO support** 
1809 Handle (Graphic3d_GraphicDriver):: 
1810     DownCast (aDriver)-EnableVBO (Standard_False); 
1811
1812 **Please 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. 
1813
1814 The different types of primitives could be presented with the following primitive arrays: 
1815   * Graphic3d_ArrayOfPoints,
1816   * Graphic3d_ArrayOfPolygons,
1817   * Graphic3d_ArrayOfPolylines,
1818   * Graphic3d_ArrayOfQuadrangles,
1819   * Graphic3d_ArrayOfQuadrangleStrips,
1820   * Graphic3d_ArrayOfSegments,
1821   * Graphic3d_ArrayOfTriangleFans,
1822   * Graphic3d_ArrayOfTriangles,
1823   * Graphic3d_ArrayOfTriangleStrips.
1824
1825 The Graphic3d_ArrayOfPrimitives is a base class for these primitive arrays. 
1826
1827 There is a set of similar methods to add vertices to the primitive array: 
1828   * Standard_Integer Graphic3d_ArrayOfPrimitives::AddVertex
1829
1830 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. 
1831
1832 You can also modify the values assigned to the vertex or query these values by the vertex index: 
1833   * void Graphic3d_ArrayOfPrimitives::SetVertice
1834   * void Graphic3d_ArrayOfPrimitives::SetVertexColor
1835   * void Graphic3d_ArrayOfPrimitives::SetVertexNormal
1836   * void Graphic3d_ArrayOfPrimitives::SetVertexTexel
1837   * gp_Pnt Graphic3d_ArrayOfPrimitives::Verticie
1838   * gp_Dir  Graphic3d_ArrayOfPrimitives::VertexNormal
1839   * gp_Pnt2d Graphic3d_ArrayOfPrimitives::VertexTexel
1840   * Quantity_Color Graphic3d_ArrayOfPrimitives::VertexColor
1841   * void Graphic3d_ArrayOfPrimitives::Verticie
1842   * void Graphic3d_ArrayOfPrimitives::VertexNormal
1843   * void Graphic3d_ArrayOfPrimitives::VertexTexel
1844   * void Graphic3d_ArrayOfPrimitives::VertexColor
1845
1846 The following example shows how to define an array of points: 
1847 <h4>Example </h4>
1848
1849 **// create an array** 
1850 Handle (Graphic3d_ArrayOfPoints) anArray = 
1851   new Graphic3d_ArrayOfPoints (aVerticiesMaxCount); 
1852
1853 **// add vertices to the array** 
1854 anArray-AddVertex (10.0, 10.0, 10.0); 
1855 anArray-AddVertex (0.0, 10.0, 10.0); 
1856
1857 **// add the array to the structure ** 
1858 Handle (Graphic3d_Group) aGroup = 
1859  Prs3d_Root::CurrentGroup (aPrs); 
1860 aGroup-BeginPrimitives (); 
1861 aGroup-AddPrimitiveArray (anArray); 
1862 aGroup-EndPrimitives (); 
1863
1864 If the primitives share the same vertices (polygons, triangles, etc) then you can define them as indices of the vertices array. The following method allows you to define the primitives by the indices: 
1865   *  Standard_Integer Graphic3d_ArrayOfPrimitives::AddEdge
1866
1867 This method adds an *edge* in the range [1, VertexNumber() ] in the array. 
1868 It is also possible to query the vertex defined by an edge: 
1869   * Standard_Integer Graphic3d_ArrayOfPrimitives::Edge
1870
1871 The following example shows how to define an array of triangles: 
1872 <h4>Example </h4>
1873
1874 **// create an array** 
1875 Standard_Boolean IsNormals = Standard_False; 
1876 Standard_Boolean IsColors  = Standard_False; 
1877 Standard_Boolean IsTextureCrds = Standard_False; 
1878 Handle (Graphic3d_ArrayOfTriangles) anArray = 
1879   new Graphic3d_ArrayOfTriangles (aVerticesMaxCount, 
1880   aEdgesMaxCount, 
1881   IsNormals, 
1882   IsColors, 
1883   IsTextureCrds); 
1884 **// add vertices to the array** 
1885 anArray-AddVertex (-1.0, 0.0, 0.0);   **// vertex 1** 
1886 anArray-AddVertex ( 1.0, 0.0, 0.0);   **// vertex 2** 
1887 anArray-AddVertex ( 0.0, 1.0, 0.0);   **// vertex 3** 
1888 anArray-AddVertex ( 0.0,-1.0, 0.0);   **// vertex 4** 
1889
1890 **// add edges to the array** 
1891 anArray-AddEdge (1);  **// first triangle** 
1892 anArray-AddEdge (2); 
1893 anArray-AddEdge (3); 
1894 anArray-AddEdge (1);  **// second triangle** 
1895 anArray-AddEdge (2); 
1896 anArray-AddEdge (4); 
1897
1898 **// add the array to the structure** 
1899 Handle (Graphic3d_Group) aGroup = 
1900   Prs3d_Root::CurrentGroup (aPrs); 
1901 aGroup-BeginPrimitives (); 
1902 aGroup-AddPrimitiveArray (anArray); 
1903 aGroup-EndPrimitives (); 
1904
1905 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 following method to define the bounds and the color for each bound: 
1906   * Standard_Integer Graphic3d_ArrayOfPrimitives::AddBound
1907
1908 This method returns the actual number of bounds. 
1909 It is also possible to set the color and query the number of edges in the bound and bound color: 
1910   * Standard_Integer Graphic3d_ArrayOfPrimitives::Bound
1911   * Quantity_Color Graphic3d_ArrayOfPrimitives::BoundColor
1912   * void Graphic3d_ArrayOfPrimitives::BoundColor
1913
1914 The following example shows how to define an array of polygons: 
1915 <h4>Example </h4>
1916
1917 **// create an array** 
1918 Standard_Boolean IsNormals  = Standard_False; 
1919 Standard_Boolean IsVertexColors = Standard_False; 
1920 Standard_Boolean IsFaceColors   = Standard_False; 
1921 Standard_Boolean IsTextureCrds  = Standard_False; 
1922 Handle (Graphic3d_ArrayOfPolygons) anArray = 
1923   new Graphic3d_ArrayOfPolygons (aVerticesMaxCount, 
1924  aBoundsMaxCount, 
1925  aEdgesMaxCount, 
1926  IsNormals, 
1927      IsVertexColors, 
1928  IsFaceColors, 
1929  IsTextureCrds); 
1930
1931 **// add bounds to the array, first polygon** 
1932 anArray-AddBound (3); 
1933 anArray-AddVertex (-1.0, 0.0, 0.0);   
1934 anArray-AddVertex ( 1.0, 0.0, 0.0);   
1935 anArray-AddVertex ( 0.0, 1.0, 0.0);   
1936
1937 **// add bounds to the array, second polygon** 
1938 anArray-AddBound (4); 
1939 anArray-AddVertex (-1.0, 0.0, 0.0);   
1940 anArray-AddVertex ( 1.0, 0.0, 0.0);   
1941 anArray-AddVertex ( 1.0,-1.0, 0.0);   
1942 anArray-AddVertex (-1.0,-1.0, 0.0);   
1943
1944 **// add the array to the structure ** 
1945 Handle (Graphic3d_Group) aGroup = 
1946   Prs3d_Root::CurrentGroup (aPrs); 
1947 aGroup-BeginPrimitives (); 
1948 aGroup-AddPrimitiveArray (anArray); 
1949 aGroup-EndPrimitives (); 
1950
1951 There are also several helper methods. You can get the type of the primitive array: 
1952   * Graphic3d_TypeOfPrimitiveArray    Graphic3d_ArrayOfPrimitives::Type
1953   * Standard_CString Graphic3d_ArrayOfPrimitives::StringType
1954
1955 and check if the primitive array provides normals, vertex colors, vertex texels (texture coordinates): 
1956   * Standard_Boolean    Graphic3d_ArrayOfPrimitives::HasVertexNormals
1957   * Standard_Boolean     Graphic3d_ArrayOfPrimitives::HasVertexColors
1958   * Standard_Boolean     Graphic3d_ArrayOfPrimitives::HasVertexTexels
1959
1960 or get the number of vertices, edges and bounds: 
1961   * Standard_Integer     Graphic3d_ArrayOfPrimitives::VertexNumber
1962   * Standard_Integer    Graphic3d_ArrayOfPrimitives::EdgeNumber
1963   * Standard_Integer     Graphic3d_ArrayOfPrimitives::BoundNumber
1964
1965 @subsubsection occt_1621831385_143501245715 About materials 
1966
1967 A **material** is defined by coefficients of: 
1968   * Transparency, 
1969   * Diffuse reflection, 
1970   * Ambient reflection, 
1971   * Specular reflection.
1972
1973 Two properties define a given material: 
1974   * Transparency 
1975   * Reflection properties - its absorption and reflection of light. 
1976
1977 **Diffuse reflection** is seen as a component of the color of the object. 
1978
1979 **Specular reflection** is seen as a component of the color of the light source. 
1980
1981 The following items are required to determine the three colors of reflection: 
1982   * Color, 
1983   * Coefficient of diffuse reflection, 
1984   * Coefficient of ambient reflection, 
1985   * Coefficient of specular reflection. 
1986
1987
1988
1989 @subsubsection occt_1621831385_143501245716 About textures 
1990
1991 A **texture **is defined by a name. 
1992 Three types of texture are available: 
1993   * 1D, 
1994   * 2D, 
1995   * Environment mapping. 
1996
1997 @subsubsection occt_1621831385_143501245717 Graphic3d text 
1998
1999 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. 
2000 Graphic3d text primitives have the following features: 
2001   * fixed size (non-zoomable) or zoomable, 
2002   * can be rotated to any angle in the view plane,
2003   * support unicode charset.
2004
2005 The text attributes for the group could be defined with the Graphic3d_AspectText3d attributes group. 
2006 To add any text to the graphic structure you can use the following methods: 
2007   *  void Graphic3d_Group::Text
2008 (const Standard_CString AText, 
2009  const Graphic3d_Vertex&amp; APoint, 
2010  const Standard_Real AHeight, 
2011  const Quantity_PlaneAngle AAngle, 
2012  const Graphic3d_TextPath ATp, 
2013  const Graphic3d_HorizontalTextAlignment AHta, 
2014  const Graphic3d_VerticalTextAlignment AVta, 
2015  const Standard_Boolean EvalMinMax), 
2016 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). 
2017 ATp parameter defines the text path, AHta is the horizontal alignment of the text, AVta is the vertical alignment of the text. 
2018 You can pass Standard_False as EvalMinMax if you don’t want the graphic3d structure boundaries to be affected by the text position. 
2019 **Please note** that the text orientation angle can be defined by Graphic3d_AspectText3d attributes. 
2020
2021   * void Graphic3d_Group::Text
2022 (const Standard_CString AText, 
2023  const Graphic3d_Vertex&amp; APoint, 
2024  const Standard_Real AHeight, 
2025  const Standard_Boolean EvalMinMax) 
2026   * void Graphic3d_Group::Text
2027 (const TCcollection_ExtendedString &amp;AText, 
2028 const Graphic3d_Vertex&amp; APoint, 
2029  const Standard_Real AHeight, 
2030  const Quantity_PlaneAngle AAngle, 
2031  const Graphic3d_TextPath ATp, 
2032  const Graphic3d_HorizontalTextAlignment AHta, 
2033  const Graphic3d_VerticalTextAlignment AVta, 
2034  const Standard_Boolean EvalMinMax) 
2035   * void Graphic3d_Group::Text
2036 (const TCcollection_ExtendedString &amp;AText, 
2037  const Graphic3d_Vertex&amp; APoint, 
2038  const Standard_Real AHeight, 
2039  const Standard_Boolean EvalMinMax) 
2040
2041 <h4>Example </h4>
2042
2043 **// get the group** 
2044 Handle (Graphic3d_Group) aGroup = 
2045  Prs3d_Root::CurrentGroup (aPrs); 
2046
2047 **// change the text aspect** 
2048 Handle(Graphic3d_AspectText3d) aTextAspect = 
2049    new Graphic3d_AspectText3d (); 
2050 aTextAspect-SetTextZoomable (Standard_True); 
2051 aTextAspect-SetTextAngle (45.0); 
2052 aGroup-SetPrimitivesAspect (aTextAspect);  
2053
2054 **// add a text primitive to the structure** 
2055 Graphic3d_Vertex aPoint (1, 1, 1); 
2056 aGroup-Text (Standard_CString (*Text*), aPoint, 16.0); 
2057
2058
2059 @subsubsection occt_1621831385_143501245718 Display priorities 
2060
2061 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. CAS.CADE supports eleven structure display priorities. 
2062
2063 @subsubsection occt_1621831385_143501245719 About structure hierarchies 
2064
2065 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. 
2066
2067 @subsection occt_1621831385_14350124572 V3d 
2068 @subsubsection occt_1621831385_143501245721 Overview 
2069 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. 
2070 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. 
2071
2072 @subsubsection occt_1621831385_143501245722 Provided services 
2073 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: 
2074   * Default parameters of the viewer, 
2075   * Views (orthographic, perspective), 
2076   * Lighting (positional, directional, ambient, spot, headlight), 
2077   * Clipping planes (note that only Z-clipping planes can work with the Phigs interface), 
2078   * Instantiated sequences of views, planes, light sources, graphic structures, and picks, 
2079   * Various package methods. 
2080
2081 @subsubsection occt_1621831385_143501245723 A programming example 
2082 <h4>Example </h4>
2083
2084 This sample TEST program for the V3d Package uses primary packages Xw and Graphic3d and secondary packages Visual3d, Aspect, Quantity, Phigs, math. 
2085
2086 **//Create a Graphic Device from the default DISPLAY ** 
2087 Handle(Graphic3d_GraphicDevice) GD = 
2088 new Graphic3d_GraphicDevice(**) ; 
2089
2090 **// Create a Viewer to this Device ** 
2091 Handle(V3d_Viewer) VM = new V3d_Viewer(GD, 400., 
2092 // Space size 
2093 V3d_Xpos,// Default projection Quantity_NOC_DARKVIOLET, 
2094 // Default background 
2095 V3d_ZBUFFER, 
2096 // Type of visualization 
2097 V3d_GOURAUD, 
2098 // Shading model 
2099 V3d_WAIT); 
2100 // Update mode  
2101 **// Create a structure in this Viewer ** 
2102 Handle(Graphic3d_Structure) S = 
2103 new Graphic3d_Structure(VM-Viewer()) ; 
2104
2105 **// Type of structure ** 
2106 S-SetVisual (Graphic3d_TOS_SHADING); 
2107
2108 **// Create a group of primitives in this structure** 
2109 Handle(Graphic3d_Group) G = new Graphic3d_Group(S) ; 
2110
2111 **// Fill this group with one polygon of size 100** 
2112 Graphic3d_Array1OfVertex Points(0,3) ; 
2113 Points(0).SetCoord(-100./2.,-100./2.,-100./2.) ; 
2114 Points(1).SetCoord(-100./2., 100./2.,-100./2.) ; 
2115 Points(2).SetCoord( 100./2., 100./2.,-100./2.) ; 
2116 Points(3).SetCoord( 100./2.,-100./2.,-100./2.) ; Normal.SetCoord(0.,0.,1.) ; 
2117 G-Polygon(Points,Normal) ; 
2118
2119 **// Create Ambient and Infinite Lights in this Viewer** 
2120 Handle(V3d_AmbientLight) L1 = new V3d_AmbientLight 
2121 (VM,Quantity_NOC_GRAY50) ; 
2122 Handle(V3d_DirectionalLight) L2 = new V3d_DirectionalLight 
2123 (VM,V3d_XnegYnegZneg,Quantity_NOC_WHITE) ; 
2124
2125 **// Create a 3D quality Window from the same GraphicDevice** 
2126 Handle(Xw_Window) W = 
2127 new Xw_Window(GD,*Test V3d*,0.5,0.5,0.5,0.5) ; 
2128
2129 **// Map this Window to this screen** 
2130  W-Map() ; 
2131
2132 **// Create a Perspective View in this Viewer** 
2133 Handle(V3d_PerspectiveView) V = 
2134 new V3d_PerspectiveView(VM); 
2135
2136 **// Set the Eye position** 
2137 V-SetEye(100.,100.,100.) ; 
2138
2139 **// Associate this View with the Window ** 
2140 V-SetWindow(W) ; 
2141
2142 **// Activate ALL defined Lights in this View ** 
2143 V-SetLightOn() ; 
2144
2145 **// Display ALL structures in this View ** 
2146 (VM-Viewer())-Display() ; 
2147
2148 **// Finally update the Visualization in this View ** 
2149 V-Update() ; 
2150
2151 @subsubsection occt_1621831385_143501245724 Glossary of view transformations 
2152 The following terms are used to define view orientation, i.e. transformation from World Coordinates (WC) to the View Reference Coordinates system (VRC) 
2153
2154 The following terms are used to define view mapping, i.e. transformation from View Reference Coordinates (VRC) to the Normalized Projection Coordinates (NPC) 
2155
2156 The V3d_View API uses the following terms to define view orientation and mapping 
2157
2158
2159 @subsubsection occt_1621831385_143501245725 Management of perspective projection 
2160 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: 
2161
2162 @image html /user_guides/visualization/images/visualization_image023.png
2163 @image latex /user_guides/visualization/images/visualization_image023.png
2164
2165 @image html /user_guides/visualization/images/visualization_image024.png
2166 @image latex /user_guides/visualization/images/visualization_image024.png
2167 Figure 1 View Reference Coordinate System, perspective viewing volume and view mapping parameters 
2168
2169 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. 
2170
2171 The perspective projection is defined by two parameters: 
2172   * **Depth** value defines distance between Projection Reference Point and the nearest (front) clipping plane. 
2173   * **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.
2174 **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. 
2175
2176 However, very small Depth values might lead to inaccuracy of *fit all* operation and to non-realistic perspective distortion. 
2177 <h4>Example </h4>
2178
2179 **// Create a Perspective View in Viewer VM** 
2180 Handle(V3d_PerspectiveView) V = 
2181 new V3d_PerspectiveView(VM); 
2182
2183 **// Set the ZSize ** 
2184 V-SetZSize(2000.) ; 
2185
2186 **// Set the Depth value** 
2187 V-SetDepth(20.) ; 
2188
2189 **// Set the current mapping as default** 
2190 **// to be used by Reset() operation** 
2191 V-SetViewMappingDefault() ; 
2192
2193 As an alternative to manual setting of perspective parameters the *V3d_View::DepthFitAll* function can be used. 
2194 <h4>Example </h4>
2195
2196 **// Display  shape in Viewer VM** 
2197 Handle(AIS_InteractiveContext) aContext = 
2198 new AIS_InteractiveContext(VM);  
2199 aContext-Display(shape); 
2200
2201 **// Create a Perspective View in Viewer VM** 
2202 Handle(V3d_PerspectiveView) V = 
2203 new V3d_PerspectiveView(VM); 
2204
2205 **// Set automatically the perspective parameters** 
2206 V-DepthFitAll() ; 
2207
2208 **// Fit view to object size ** 
2209 V-FitAll(); 
2210
2211 **// Set the current mapping as default** 
2212 **// to be used by Reset() operation** 
2213 V-SetViewMappingDefault() ; 
2214
2215
2216 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. 
2217 Make sure the Eye point never gets between the Front and Back clipping planes. 
2218 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. 
2219 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. 
2220
2221 @subsubsection occt_1621831385_143501245726 Underlay and overlay layers management
2222 In addition to interactive 3d graphics displayed in the view you can display an underlying and overlying graphics: text, color scales, drawings. 
2223
2224 All of the v3d view’s 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. 
2225
2226 You can assign your own layer manager to the v3d view using the following method: 
2227   * void V3d_View::SetLayerMgr
2228 (const Handle (V3d_LayerMgr)&amp; aMgr) 
2229
2230 There are three virtual methods to prepare graphics in the manager for further drawing (set up layer dimensions, draw static graphics). These methods could be redefined: 
2231   * void V3d_LayerMgr::Begin ()
2232   * void V3d_LayerMgr::Redraw ()
2233   * void V3d_LayerMgr::End ()
2234
2235 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. 
2236
2237 The layer entity is presented by the *Visual3d_Layer* class. This entity provides drawing services in the layer, for example: 
2238   * void Visual3d_Layer::DrawText
2239   * void Visual3d_Layer::DrawRectangle
2240   * void Visual3d_Layer::SetColor
2241   * void Visual3d_Layer::SetViewport
2242
2243 The following example demonstrates how to draw overlay graphics by the V3d_LayerMgr: 
2244 <h4>Example </h4>
2245
2246 **// redefined method of V3d_LayerMgr** 
2247 void MyLayerMgr::Redraw () 
2248
2249   Quantity_Color aRed (Quantity_NOC_RED); 
2250   myOverlayLayer-SetColor (aRed); 
2251   myOverlayLayer-DrawRectangle (0, 0, 100, 100); 
2252
2253
2254 The layer contains layer items that will be displayed on view redraw. Such items are the Visual3d_LayerItem entities. To manipulate Visual3d_LayerItem entities assigned to the layer’s internal list you can use the following methods: 
2255   * void Visual3d_Layer::AddLayerItem 
2256 (const Handle (Visual3d_LayerItem)&amp; Item) 
2257   * void Visual3d_Layer::RemoveLayerItem
2258 (const Handle (Visual3d_LayerItem)&amp; Item)  
2259   * void Visual3d_Layer::RemoveAllLayerItems ()
2260   * const Visual3d_NListOfLayerItem&amp;
2261 Visual3d_Layer::GetLayerItemList ()   
2262
2263 The layer’s items are rendered when the following method is called by the graphical driver: 
2264   * void Visual3d_Layer::RenderLayerItems () 
2265
2266 The *Visual3d_LayerItem* has virtual methods that are used to render the item: 
2267   * void Visual3d_LayerItem::RedrawLayerPrs () 
2268   * void Visual3d_LayerItem::ComputeLayerPrs () 
2269
2270 The item’s 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: 
2271   * void Visual3d_LayerItem::SetNeedToRecompute
2272 (const Standard_Boolean NeedToRecompute) 
2273   * Standard_Boolean Visual3d_LayerItem::IsNeedToRecompute 
2274
2275 An example of Visual3d_LayerItem is *V3d_ColorScaleLayerItem* that represents the color scale entity as the layer’s item. 
2276 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: 
2277 <h4>Example </h4>
2278
2279 **// tell V3d_ColorScale to draw itself** 
2280 void V3d_ColorScaleLayerItem::RedrawLayerPrs () 
2281
2282   Visual3d_LayerItem::RedrawLayerPrs () 
2283   if (!MyColorScale.IsNull ()) 
2284     MyColorScale-DrawScale (); 
2285
2286
2287 **// V3d_ColorScale has a reference to a LayerMgr** 
2288 void V3d_ColorScale::DrawScale () 
2289
2290     **// calls *V3d_ColorScale::PaintRect, V3d_ColorScale::PaintText*, etc …** 
2291
2292
2293 **// PaintRect method uses overlay layer of LayerMgr to draw a rectangle ** 
2294 void V3d_ColorScale::PaintRect 
2295    (const Standard_Integer X, const Standard_Integer Y, 
2296     const Standard_Integer W, const Standard_Integer H, 
2297     const Quantity_Color aColor, 
2298     const Standard_Boolean aFilled) 
2299
2300   const Handle (Visual3d_Layer)&amp; theLayer = 
2301  myLayerMgr-Overlay (); 
2302 ** …** 
2303
2304 **  **theLayer-SetColor (aColor); 
2305   theLayer-DrawRectangle (X, Y, W, H); 
2306 ** …** 
2307
2308
2309
2310 @subsubsection occt_1621831385_143501245727 View background styles 
2311 There are three types of background styles available for V3d_view: solid color, gradient color and image. 
2312
2313 To set solid color for the background you can use the following methods: 
2314   * void V3d_View::SetBackgroundColor
2315 (const Quantity_TypeOfColor Type, 
2316  const Quantity_Parameter V1, 
2317  const Quantity_Parameter V2, 
2318  const Quantity_Parameter V3) 
2319 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. **Note** that the color value parameters V1,V2,V3 should be in the range between 0.0-1.0. 
2320
2321   * void V3d_View::SetBackgroundColor
2322 (const Quantity_Color &amp;Color) 
2323   * void V3d_View::SetBackgroundColor
2324 (const Quantity_NameOfColor Name) 
2325
2326 The gradient background style could be set up with the following methods: 
2327   * void V3d_View::SetBgGradientColors
2328 (const Quantity_Color&amp; Color1, 
2329  const Quantity_Color&amp; Color2, 
2330  const Aspect_GradientFillMethod FillStyle, 
2331  const Standard_Boolean update) 
2332   * void V3d_View::SetBgGradientColors
2333 (const Quantity_NameOfColor Color1, 
2334  const Quantity_NameOfColor Color2, 
2335  const Aspect_GradientFillMethod FillStyle, 
2336  const Standard_Boolean update) 
2337 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. 
2338
2339 The fill style can be also set with the following method: 
2340   * void V3d_View::SetBgGradientStyle
2341 (const Aspect_GradientFillMethod AMethod, 
2342 const Standard_Boolean update) 
2343
2344 To get the current background color you can use the following methods: 
2345   * void V3d_View::BackgroundColor
2346 (const Quantity_TypeOfColor Type, 
2347  Quantity_Parameter &amp;V1, 
2348  Quantity_Parameter &amp;V2, 
2349  Quantity_Parameter &amp;V3) 
2350   * Quantity_Color V3d_View::BackgroundColor()
2351   * void V3d_View::GradientBackgroundColors
2352 (Quantity_Color&amp; Color1, 
2353  Quantity_Color&amp; Color2) 
2354   * Aspect_GradientBackground GradientBackground()
2355
2356 To set the image as a background and change the background image style you can use the following methods: 
2357   * void V3d_View::SetBackgroundImage
2358 (const Standard_CString FileName, 
2359  const Aspect_FillMethod FillStyle, 
2360  const Standard_Boolean update) 
2361   * void V3d_View::SetBgImageStyle
2362 (const Aspect_FillMethod FillStyle, 
2363  const Standard_Boolean update) 
2364
2365 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: 
2366   * Aspect_FM_NONE:  draw the image in the default position
2367   * Aspect_FM_CENTERED: draw the image at the center of the view
2368   * Aspect_FM_TILED: tile the view with the image
2369   * Aspect_FM_STRETCH: stretch the image over the view
2370
2371 @subsubsection occt_1621831385_143501245728 User-defined clipping planes
2372 The ability to define custom clipping planes could be very useful for some tasks. The v3d view provides such an opportunity. 
2373
2374 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: 
2375   * void V3d_Plane::SetPlane
2376 (const Quantity_Parameter A, 
2377  const Quantity_Parameter B, 
2378  const Quantity_Parameter C, 
2379  const Quantity_Parameter D) 
2380   * void V3d_Plane::Plane
2381 (Quantity_Parameter&amp; A, 
2382  Quantity_Parameter&amp; B, 
2383  Quantity_Parameter&amp; C, 
2384  Quantity_Parameter&amp; D) 
2385
2386  V3d_Plane also provides display services: 
2387   * void V3d_Plane::Display
2388 (const Handle(V3d_View)&amp; aView, 
2389  const Quantity_Color&amp; aColor) 
2390   * void V3d_Plane::Erase ()
2391   * Standard_Boolean V3d_Plane::IsDisplayed ()
2392 The Display method could be redefined to provide custom representation of the clipping plane. 
2393
2394 The clipping planes could be activated with the following methods: 
2395   * void V3d_View::SetPlaneOn 
2396 (const Handle(V3d_Plane)&amp; MyPlane) 
2397   * void V3d_View::SetPlaneOn ()
2398 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. 
2399
2400 The clipping planes could be deactivated with the similar methods: 
2401   * void V3d_View::SetPlaneOff
2402 (const Handle(V3d_Plane)&amp; MyPlane) 
2403   * void V3d_View::SetPlaneOff ()
2404
2405 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. 
2406
2407 You can iterate through the active planes using the following methods: 
2408   * void V3d_View::InitActivePlanes ()
2409 sets the iterator to the beginning of the internal list of clipping planes 
2410   * Standard_Boolean V3d_View::MoreActivePlanes ()
2411 returns Standard_True if there are more active planes to return 
2412   * void V3d_View::NextActivePlanes ()
2413 sets the iterator to the next active plane in the list 
2414   * Handle(V3d_Plane) V3d_View::ActivePlane ()
2415 returns the active plane 
2416
2417 or check if a certain clipping plane has been activated: 
2418   * Standard_Boolean V3d_View::IsActivePlane 
2419 (const Handle (V3d_Plane)&amp; aPlane)The number of clipping planes is limited. The following method allows you to check if it is possible to activate at least one more plane in the view or the limit has been reached: 
2420   * Standard_Boolean V3d_View::IfMorePlanes ()
2421 <h4>Example </h4>
2422
2423 **// try to use an existing clipping plane or create a new one** 
2424 Handle(V3d_Plane) aCustomPlane; 
2425 myView-InitActivePlanes (); 
2426 if (myView-MoreActivePlanes ()) 
2427   aCustomPlane = myView-ActivePlane (); 
2428 else 
2429   aCustomPlane = new V3d_Plane (); 
2430
2431 **// calculate new coefficients** 
2432 Standard_Real a, b, c, d; 
2433 Standard_Real x = 0.0, y = 0.0, z = 10.0; 
2434 Standard_Real dx = 0.0, dy = 0.0, dz = 1.0; 
2435 gp_Pln aPln (gp_Pnt (x, y, z), gp_Dir (dx, dy, dz)); 
2436 aPln.Coefficients (a, b, c, d); 
2437
2438 **// update plane** 
2439 aCustomPlane-SetPlane (a, b, c, d); 
2440 myView-SetPlaneOn (aCustomPlane); 
2441
2442 @subsubsection occt_1621831385_143501245729 Dumping a 3D scene into an image file
2443 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). 
2444
2445 The V3d_View has the following methods for dumping the 3D scene: 
2446   * Standard_Boolean V3d_View::Dump
2447 (const Standard_CString theFile, 
2448  const Image_TypeOfImage theBufferType) 
2449   * Standard_Boolean V3d_View::Dump
2450 (const Standard_CString theFile, 
2451  const Aspect_FormatOfSheetPaper theFormat, 
2452  const Image_TypeOfImage theBufferType) 
2453 These methods dump the 3D scene into an image file passed by its name and path as theFile. 
2454 The raster image data handling algorithm is based on the Image_PixMap class. The supported extensions are *.png*, *.bmp*, *.png*, *.png*. 
2455 The first method dumps the scene into an image file with the view dimensions. The second method allows you to make the dimensions of the output image compatible to a certain format of printing paper passed by theFormat argument. 
2456 The value passed as theBufferType argument defines the type of the buffer for an output image (RGB, RGBA, floating-point, RGBF, RGBAF). Both methods return Standard_True if the scene has been successfully dumped. 
2457 **Please 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. 
2458
2459   * Handle_Image_PixMap V3d_View::ToPixMap
2460 (const Standard_Integer theWidth, 
2461  const Standard_Integer theHeight, 
2462  const Image_TypeOfImage theBufferType, 
2463  const Standard_Boolean theForceCentered) 
2464 This method allows you to dump the displayed 3d scene into a pixmap with a width and height passed as theWidth and theHeight arguments. 
2465 The value passed as theBufferType argument defines the type of the buffer for a pixmap (RGB, RGBA, floating-point, RGBF, RGBAF). 
2466 The last parameter allows you to center the 3D scene on dumping. 
2467
2468 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: 
2469 1) Create a graphic device; 
2470 2) Create a window; 
2471 3) Set up the window as virtual, Aspect_Window::SetVirtual (); 
2472 4) Create a view and an interactive context; 
2473 5) Assign the virtual window to the view; 
2474 6) Display a 3D scene; 
2475 7) Use one of the functions described above to dump the 3D scene. 
2476
2477 The following example demonstrates this procedure for the WNT_Window: 
2478 <h4>Example </h4>
2479
2480 **// create a graphic device** 
2481 Handle (WNT_GraphicDevice) aDevice = 
2482    new Graphic3d_WNTGraphicDevice (); 
2483
2484 **// create a window** 
2485
2486 ~~~~~{c++}
2487 Standard_Integer aDefWidth  = 800; 
2488 Standard_Integer aDefHeight = 600; 
2489 Handle (WNT_WClass) aWClass = 
2490      new WNT_WClass (*Virtual Class*,DefWindowProc, 
2491  CS_VREDRAW | CS_HREDRAW, 0, 0, 
2492  ::LoadCursor (NULL, IDC_ARROW)); 
2493 Handle (WNT_Window) aWindow = 
2494  new WNT_Window (aDevice, *VirtualWnd*,  aWClass, 
2495  WS_OVERLAPPEDWINDOW, 0, 0, 
2496  aDefWidth, aDefHeight); 
2497 ~~~~~
2498
2499 **// set up the window as virtual** 
2500 aWindow-SetVirtual (Standard_True); 
2501
2502 **// create a view and an interactive context** 
2503 Handle (V3d_Viewer) aViewer = 
2504  new V3d_Viewer (aDevice, 
2505  Standard_ExtString (*Virtual*)); 
2506 Handle (AIS_InteractiveContext) aContext = 
2507  new AIS_InteractiveContext (aViewer); 
2508 Handle (V3d_View) aView = aViewer-CreateView (); 
2509
2510 **// assign the virtual window to the view** 
2511 aView-SetWindow (aWindow); 
2512
2513 **// display a 3D scene** 
2514 Handle (AIS_Shape) aBox = 
2515  new AIS_Shape (BRepPrimAPI_MakeBox (5, 5, 5)); 
2516 aContext-Display (aBox); 
2517 aView-FitAll(); 
2518
2519 **// dump the 3D scene into an image file** 
2520 aView-Dump (*3dscene.png*); 
2521
2522 @subsubsection occt_1621831385_1435012457210 Printing a 3D scene
2523 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. 
2524
2525 The following method prints the view contents: 
2526   * void V3d_View::Print
2527 (const Aspect_Handle hPrnDC, 
2528  const Standard_Boolean showDialog, 
2529  const Standard_Boolean showBackground, 
2530  const Standard_CString  filename, 
2531  const Aspect_PrintAlgo   printAlgorithm) 
2532 The 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. 
2533 You can define the filename for the printer driver if you want to print out the result into a file. 
2534 If you do not want to print the background, you can pass *Standard_False* as the showBackground argument. 
2535 The printAlgorithm argument allows you to choose 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. You can pass the following values as the printAlgorithm argument: 
2536   * Aspect_PA_STRETCH,
2537   * Aspect_PA_TILE
2538
2539 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. 
2540
2541 **Please note** that at the moment printing is implemented only for Windows. 
2542
2543 @subsubsection occt_1621831385_1435012457211 Vector image export
2544 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). 
2545
2546 The following method of Visual3d_View class allows you to export your 3D scene: 
2547   * void Visual3d_View::Export
2548 (const Standard_CString FileName, 
2549  const Graphic3d_ExportFormat Format, 
2550  const Graphic3d_SortType aSortType, 
2551  const Standard_Real Precision, 
2552  const Standard_Address ProgressBarFunc, 
2553  const Standard_Address ProgressObject) 
2554
2555 The FileName defines the output image file name and the Format argument defines the output file format: 
2556   * Graphic3d_EF_PostScript (PS),
2557   * Graphic3d_EF_EhnPostScript (EPS),
2558   * Graphic3d_EF_TEX (TEX), 
2559   * Graphic3d_EF_PDF (PDF),
2560   * Graphic3d_EF_SVG (SVG),
2561   * Graphic3d_EF_PGF (PGF)
2562
2563 The aSortType parameter defines the GL2PS sorting algorithm for the primitives. The Precision, ProgressBarFunc and ProgressObject parameters are implemented for future uses and at the moment have no effect. 
2564
2565 The Export method supports only basic 3d graphics and has several limitations: 
2566   * Rendering large scenes could be slow and can lead to large output files;
2567   * Transparency is only supported for PDF and SVG output;
2568   * Textures and some effects are not supported by the GL2PS library.
2569
2570 @section occt_1621831385_1090976821 2D Presentations
2571 @subsection occt_1621831385_10909768211 Glossary of 2D terms 
2572
2573 @subsubsection occt_1621831385_10909768212 Creating a 2D scene 
2574
2575 To create 2D graphic objects and display them on the screen, follow the procedure below: 
2576 **1. **Create the marker map. 
2577 **2. **Create the attribute maps. 
2578 **3. **Define the connection to a graphic device.  
2579 **4. **Create a window. 
2580 **5. **Create a window driver. 
2581 **6. **Install the maps. 
2582 **7. **Create a view. 
2583 **8. **Create a view mapping. 
2584 **9. **Create one or more graphic objects associated with a view. 
2585 **10. **Create primitives and associate them with a graphic object. 
2586 **11. **Get the workspace of the driver. 
2587 **12. **Update the view in the driver. 
2588
2589 @subsubsection occt_1621831385_109097682121 Creating the marker map 
2590
2591 The marker map defines a set of markers available to the application. Markers may be predefined, Aspect_Tom_X for example, or user-defined. 
2592
2593 @image html /user_guides/visualization/images/visualization_image025.png
2594 @image latex /user_guides/visualization/images/visualization_image025.png
2595 Figure 15. Markers. 
2596
2597 The markers are manipulated by an index. 
2598 A marker map is defined as follows: 
2599 <h4>Example </h4>
2600
2601 Handle(Aspect_MarkMap) mkrmap = new Aspect_MarkMap; 
2602 Aspect_MarkMapEntry mkrmapentry1 (1, Aspect_TOM_X) 
2603 Aspect_MarkMapEntry mkrmapentry2 (2, Aspect_TOM_PLUS) 
2604 Aspect_MarkMapEntry mkrmapentry3 (3, Aspect_O_PLUS) 
2605
2606 mkrmap-AddEntry (mkrmapentry1); 
2607 mkrmap-AddEntry (mkrmapentry2); 
2608 mkrmap-AddEntry (mkrmapentry3); 
2609
2610
2611 @subsubsection occt_1621831385_109097682122 Creating the attribute maps
2612
2613 Maps are created for color, line type, line width, and text font. A map is used to reference a given attribute by an integer value. 
2614
2615
2616 @image html /user_guides/visualization/images/visualization_image026.png
2617 @image latex /user_guides/visualization/images/visualization_image026.png
2618 Figure 16. Attributes 
2619
2620 The color map 
2621 The hardware system will certainly have default colors available but to make the application portable and durable, it must be insulated from external factors by defining the set of colors to be used. 
2622
2623 A color map is defined as follows: 
2624
2625 <h4>Example </h4>
2626
2627 Handle(Aspect_GenericColorMap) colmap = 
2628 new Aspect_GenericColorMap; 
2629 Aspect_ColorMapEntry colmapentry; 
2630 Quantity_Color YELLOW (Quantity_NOC_YELLOW); colmapentry.SetValue (1, YELLOW); 
2631 colmap-AddEntry (colmapentry); 
2632 Quantity_Color RED (Quantity_NOC_RED); 
2633 colmapentry.SetValue (2, RED);  
2634 colmap-AddEntry (colmapentry); 
2635 Quantity_Color GREEN (Quantity_NOC_GREEN); colmapentry.SetValue (3, GREEN); 
2636 colmap-AddEntry (colmapentry); 
2637
2638 You can include as many colors in your color map as you like, though there are some restrictions related to the hardware. 
2639
2640 <h4>The type map </h4>
2641 Lines can be solid, dotted, dashed, dot-dashed, or user defined. For a user-defined type the pattern of solid and blank sections is listed. 
2642
2643 A type map is defined as follows: 
2644
2645 <h4>Example </h4>
2646
2647 Handle(Aspect_TypeMap) typmap = new Aspect_TypeMap; 
2648 {TColQuantity_Array1OfLength myLineStyle(1,2); myLineStyle.SetValue(1, 2); // the solid part is 2 mm myLineStyle.SetValue(2, 3); // the blank part is 3 mm Aspect_LineStyle linestyle1 (Aspect_TOL_SOLID); Aspect_LineStyle linestyle2 (Aspect_TOL_DASH); Aspect_LineStyle linestyle3 (myLineStyle); 
2649 Aspect_LineStyle linestyle4 (Aspect_TOL_DOTDASH); Aspect_TypeMapEntry typmapentry1 (1, linestyle1); Aspect_TypeMapEntry typmapentry2 (2, linestyle2); Aspect_TypeMapEntry typmapentry3 (3, linestyle3); Aspect_TypeMapEntry typmapentry4 (4, linestyle4);  
2650 typmap-AddEntry (typmapentry1); 
2651 typmap-AddEntry (typmapentry2); 
2652 typmap-AddEntry (typmapentry3); 
2653 typmap-AddEntry (typmapentry4); 
2654
2655
2656 *NOTE* 
2657 *The line type enumeration and all the other enumerations are available from the Aspect package.* 
2658
2659 <h4>The width map </h4>
2660 The width map defines a set of levels of line thickness available to your application. Widths and all other distances are specified in mms or as members of an enumeration. 
2661
2662 A width map is defined as follows: 
2663 <h4>Example </h4>
2664
2665 Handle(Aspect_WidthMap) widmap = new Aspect_WidthMap; Aspect_WidthMapEntry widmapentry1 (1,Aspect_WOL_THIN); Aspect_WidthMapEntry widmapentry2 (2,Aspect_WOL_MEDIUM); Aspect_WidthMapEntry widmapentry3 (3, 3); Aspect_WidthMapEntry widmapentry4 (4, 40); widmap-AddEntry (widmapentry1); widmap-AddEntry (widmapentry2); widmap-AddEntry (widmapentry3); widmap-AddEntry (widmapentry4);   
2666
2667 The font map 
2668 The font map defines a set of text fonts available to your application. Default fonts enumerated in Aspect may be used with addition of any other font known to the X driver, specifying the size and slant angle desired. 
2669
2670 A font map is defined as follows: 
2671
2672 <h4>Example </h4>
2673
2674 Handle(Aspect_FontMap) fntmap = new Aspect_FontMap; Aspect_FontStyle fontstyle1 (*Courier-Bold*, 3, 0.0); Aspect_FontStyle fontstyle2 (*Helvetica-Bold*, 3, 0.0); Aspect_FontStyle fontstyle3 (Aspect_TOF_DEFAULT); Aspect_FontMapEntry fntmapentry1 (1, fontstyle1); Aspect_FontMapEntry fntmapentry2 (2, fontstyle2); Aspect_FontMapEntry fntmapentry3 (3, fontstyle3); fntmap-AddEntry (fntmapentry1); fntmap-AddEntry (fntmapentry2); fntmap-AddEntry (fntmapentry3);   
2675
2676
2677 @subsubsection occt_1621831385_109097682123 Creating a 2D driver (a Windows example) 
2678
2679 <h4>Example </h4>
2680
2681 Handle(WNT_GraphicDevice) TheGraphicDevice = ...; TCollection_ExtendedString aName(*2DV*); 
2682 my2DViewer = new V2d_Viewer(TheGraphicDevice, 
2683 aName.ToExtString());  
2684 @subsubsection occt_1621831385_109097682124 Installing the maps 
2685
2686 When the 2D viewer has been created, you may install the maps created earlier. 
2687 <h4>Example </h4>
2688
2689 my2DViewer-SetColorMap(colormap); 
2690 my2DViewer-SetTypeMap(typmap); 
2691 my2DViewer-SetWidthMap(widthmap); 
2692 my2DViewer-SetFontMap(fntmap); 
2693
2694
2695 @subsubsection occt_1621831385_109097682125 Creating a view (a Windows example) 
2696
2697 It is assumed that a valid Windows window may be accessed via the method GetSafeHwnd(). 
2698 <h4>Example </h4>
2699
2700 Handle(WNT_Window) aWNTWindow; 
2701 aWNTWindow = new 
2702 WNT_Window(TheGraphicDevice, GetSafeHwnd()); 
2703 aWNTWindow-SetBackground(Quantity_NOC_MATRAGRAY); Handle(WNT_WDriver) aDriver = new 
2704 WNT_WDriver(aWNT_Window); 
2705 myV2dView = new V2d_View(aDriver, my2dViewer, 0,0,50); 
2706 // 0,0: view center and 50: view size 
2707
2708
2709 @subsubsection occt_1621831385_109097682126 Creating the presentable object 
2710
2711 Follow the procedure below to compute the presentable object. 
2712 **1.   **Build a presentable object inheriting from AIS_InteractiveObject (refer to Chapter 1 Fundamental Concepts, Section Presentable objects) 
2713 **2.   **Re-use the graphic object provided as an argument of the Compute method for your presentable object. 
2714 <h4>Example </h4>
2715
2716 void 
2717 myPresentableObject::Compute ( 
2718 const Handle(Prs_Mgr_PresentationManager2D)&amp; 
2719 aPresentationManager,  
2720 const Handle(Graphic2d_GraphicObject)&amp; aGrObj, 
2721 const Standard_Integer aMode) 
2722
2723 ... 
2724
2725
2726
2727 @subsubsection occt_1621831385_109097682127 Creating a primitive 
2728
2729 Primitives may be created using the resources of the Graphic2d package. Here for example an array is instantiated and filled with a set of three circles with different radii, line widths, and colors, centered on given origin coordinates (4.0, 1.0) and passed to the specified graphic object (go). 
2730 <h4>Example </h4>
2731
2732 Handle(Graphic2d_Circle) tcircle[4]; Quantity_Length radius; for (i=1; i=4; i++) { radius = Quantity_Length (i); tcircle[i-1] = new Graphic2d_Circle (aGrObj, 4.0, 1.0, radius); 
2733 tcircle[i-1]-SetColorIndex (i); 
2734 tcircle[i-1]-SetWidthIndex (1); } 
2735
2736 Add a filled rectangle to your graphic object. It will be put outside of your view mapping. 
2737 <h4>Example </h4>
2738
2739 TColStd_Array1OfReal aListX (1, 5); 
2740 TColStd_Array1OfReal aListY (1, 5); 
2741 aListX (1) = -7.0; aListY (1) = -1.0; 
2742 aListX (2) = -7.0; aListY (2) = 1.0; 
2743 aListX (3) = -5.0; aListY (3) = 1.0; 
2744 aListX (4) = -5.0; aListY (4) = -1.0; 
2745 aListX (5) = -7.0; aListY (5) = -1.0; 
2746 Handle(Graphic2d_Polyline) rectangle = 
2747 new Graphic2d_Polyline (go, 0., 0., aListX, aListY); rectangle-SetColorIndex (6); 
2748 rectangle-SetWidthIndex (1); 
2749 rectangle-SetTypeOfPolygonFilling(Graphic2d_TOPF_FILLED); rectangle-SetDrawEdge(Standard_True); 
2750 *A given primitive can only be assigned to a single graphic object.* 
2751
2752 @image html /user_guides/visualization/images/visualization_image027.png
2753 @image latex /user_guides/visualization/images/visualization_image027.png
2754 Figure 17. Graphic object and view mapping in the space model. 
2755
2756 @subsection occt_1621831385_10909768213 Dealing with images 
2757
2758 @subsubsection occt_1621831385_109097682131 General case 
2759
2760 Images are primitives too. The graphic resources can currently accept all image types described in the *AlienImage* package. In the following example only **.xwd **formats are accepted. 
2761
2762 Define the primitive Image in the GraphicObject. 
2763 <h4>Example </h4>
2764
2765 Handle(Image_Image) anImage; if (XwdImage || RgbImage) { anImage = AlienUser-ToImage (); Handle(Graphic2d_Image) gImage = new Graphic2d_Image 
2766 (aGrObj, anImage, 0., 0., 0., 0., Aspect_CP_CENTER); } 
2767
2768
2769 <h4>NOTE</h4>
2770 *The above constructor for image takes as arguments the graphic object which will contain the image, the image itself, XY coordinates for the center, XY offsets in the device space, and a cardinal point value to give a direction of display.  * 
2771
2772 Now update the view in the driver. In other words, draw the image. 
2773
2774 <h4>Example </h4>
2775
2776 Standard_Boolean clear = Standard_True 
2777 view-Update (driver, viewmapping, W/2., H/2., scale, clear); 
2778
2779
2780 @subsubsection occt_1621831385_109097682132 Specific case: xwd format 
2781
2782 When the manipulated image is stored with the xwd format, a special class Graphic2d_ImageFile may be used to increase performance. 
2783 <h4>Example </h4>
2784
2785 OSD_Path aPath (*C:/test.xwd*); 
2786 OSD_File aFile (aPath); 
2787 Handle(Graphic2d_ImageFile)gImageFile = 
2788 new Graphic2d_ImageFile (aGrObj, 
2789 aFile, 
2790 0.,0., 
2791 0.,0., 
2792 Aspect_CP_Center, 1); 
2793 gImageFile-SetZoomable(Standard_True); 
2794
2795
2796 The graphic contains now an image, which is manipulated as a primitive. 
2797
2798
2799 @subsection occt_1621831385_10909768214 Dealing with text 
2800
2801 The constructor for the Graphic2d_Text takes a reference point in the space model and an angle (in radians) as its arguments, as well as the graphic object to which it is assigned. Note that the angle is ignored unless the Xdps driver, which allows angled text, is in use. 
2802 <h4>Example </h4>
2803
2804 TCollection_ExtendedString str1 (*yellow Courier-bold*); TCollection_ExtendedString str2 (*red Helevetica-bold*); TCollection_ExtendedString str3 (*green  Aspect_TOF_DEFAULT*); Handle(Graphic2d_Text) t1 = new Graphic2d_Text 
2805 (aGrObj, str1, 0.3, 0.3, 0.0); 
2806 Handle(Graphic2d_Text) t2 = new Graphic2d_Text 
2807 (aGrObj, str2, 0.0, 0.0, 0.0); 
2808 Handle(Graphic2d_Text) t3 = new Graphic2d_Text 
2809 (aGrObj, str3, -0.3, -0.3, 0.0);  
2810 t1-SetFontIndex (1); t1-SetColorIndex (1); 
2811 t2-SetFontIndex (2); t2-SetColorIndex (2); 
2812 t3-SetFontIndex (3); t3-SetColorIndex (3); 
2813
2814
2815 @subsection occt_1621831385_10909768215 Dealing with markers 
2816
2817 A marker is a primitive that retains its original size when the view is zoomed. Markers can be used, for example, as references to dimensions. 
2818
2819 @subsubsection occt_1621831385_109097682151 Vectorial markers 
2820 Every marker takes an XY point as its reference point. The constructor also takes another pair of XY values as an offset from this reference point. For CircleMarker and EllipsMarker this offset point is its center. For PolylineMarker this offset point is its origin i.e. the first point in its list. 
2821 In the example below, a rectangle is created using Graphic2d_Polyline. 
2822 <h4>Example </h4>
2823
2824 TColStd_Array1OfReal rListX (1, 5); 
2825 TColStd_Array1OfReal rListY (1, 5); 
2826 rListX (1) = -0.3; rListY (1) = -0.3; 
2827 rListX (2) = -0.3; rListY (2) = 0.3; 
2828 rListX (3) = 0.3; rListY (3) = 0.3; 
2829 rListX (4) = 0.3; rListY (4) = -0.3; 
2830 rListX (5) = -0.3; rListY (5) = -0.3; 
2831 Handle(Graphic2d_Polyline) rp = 
2832 new Graphic2d_Polyline (aGrObj, rListX, rListY); 
2833
2834
2835 Two Graphic2d_CircleMarkers are created. The first one has no offset from its center. The second is constrained to be a given offset from a reference point. 
2836 <h4>Example </h4>
2837
2838 Handle(Graphic2d_CircleMarker) rc1 = new 
2839 Graphic2d_CircleMarker 
2840 (aGrObj, 0.04, 0.03, 0.0, 0.0, 0.01); Handle(Graphic2d_CircleMarker) rc2 = new 
2841 Graphic2d_CircleMarker 
2842 (aGrObj, 0.03, -0.03, 0.01, 0.0, 0.01); 
2843 window-Clear (); 
2844
2845 @image html /user_guides/visualization/images/visualization_image028.png
2846 @image latex /user_guides/visualization/images/visualization_image028.png
2847 Figure 18. Figure of zoom and attachment point of a marker. 
2848
2849
2850 @subsubsection occt_1621831385_109097682152 Indexed markers 
2851
2852 Once the marker map has been created, indexed markers may be added to a graphic object. 
2853 <h4>Example </h4>
2854
2855 Handle (Graphic2d_Marker) xmkr = new Graphic2d_Marker 
2856 (aGrObj, 1, 0.04, 0.03, 0.0, 0.0, 0.0); 
2857 Handle (Graphic2d_Marker) plusmkr = new Graphic2d_Marker 
2858 (aGrObj, 2, 0.04, 0.0, 0.0, 0.0, 0.0); 
2859 Handle (Graphic2d_Marker) oplusmkr = new Graphic2d_Marker 
2860 (aGrObj, 3, 0.04, -0.03, 0.0, 0.0, 0.0); 
2861
2862 @subsection occt_1621831385_10909768216 Dragging with Buffers 
2863
2864 A **buffer** is used to draw very quickly a partial area of the scene without deleting the background context. 
2865  A buffer contains a set of graphic objects or primitives which are to be moved, rotated or scaled above the scene in the front planes of the view (in this case, double-buffering is not active). For example: 
2866
2867 **1.   **Draw a very complex scene in the view. 
2868 **2.   **Create a buffer of primitives with the primitive color index 10 and the font index 4: 
2869 buffer = new Graphic2d_Buffer (view, 0., 0., 10, 4); 
2870
2871 **3.   **Add graphic objects or primitives: 
2872 buffer-Add (go); 
2873 buffer-Add (tcircle[1]); 
2874 buffer-Add (t1); 
2875
2876 **4.   **Post the buffer in the view: 
2877 buffer-Post (); 
2878
2879 **5.   **Move, rotate or scale the buffer above the view:     
2880 buffer-Move (x,y); buffer-Rotate (alpha); 
2881 buffer-Scale (zoom_factor); 
2882
2883 **6.   **Unpost the buffer from the view: 
2884 buffer-Unpost (); 
2885 @section occt_1621831385_86393950 2D Resources
2886
2887
2888 The 2D resources include the Graphic2d, Image, AlienImage, and V2d packages.     
2889
2890
2891 @subsection occt_1621831385_863939501 Graphic2d 
2892
2893
2894 @subsubsection occt_1621831385_8639395011 Overview 
2895
2896 The **Graphic2d** package is used to create a 2D graphic object. Each object, called a GraphicObject, is composed of primitives. Each primitive is a class and contains attributes. Each primitive has its own Draw method. 
2897
2898 A Graphic2d_Image is created from an Image from the Image package. 
2899
2900
2901 @subsubsection occt_1621831385_8639395012 The services provided 
2902
2903 The **Graphic2d** packages provides classes for creating the following primitives: 
2904   * Circle 
2905   * Curve 
2906   * Ellips 
2907   * InfiniteLine 
2908   * Polyline 
2909   * Segment 
2910   * SetOfSegments 
2911   * Text 
2912   * Marker 
2913   * SetOfMarkers 
2914   * VectorialMarker 
2915   * CircleMarker 
2916
2917 **2D Resources ** 
2918   * PolylineMarker 
2919   * EllipsMarker 
2920   * Image 
2921   * ImageFile 
2922   * SetOfCurves 
2923
2924
2925
2926 @subsection occt_1621831385_863939502 Image 
2927
2928 @subsubsection occt_1621831385_8639395021 Overview 
2929
2930 The **Image** package provides the resources to produce and manage bitmap images. It has two purposes: 
2931   * To define what is an image on the CAS.CADE platform. 
2932   * To define operations which can be carried out on an image. 
2933
2934 The package allows the user to manipulate images without knowing their type. For various functionalities such as zoom, pan, and rotation, an application does not need to know the type nor the format of the image. Consequently, the image could be stored as an integer, real, or object of the Color type. 
2935
2936 Another important asset of the package is to make the handling of images independent of the type of pixel. Thus a new image based on a different pixel type can be created without rewriting any of the algorithms. 
2937
2938 @subsubsection occt_1621831385_8639395022 The services provided 
2939
2940 The classes **ColorImage** and **PseudoColorImage** define the two types of image, which can be handled by the Image toolkit. These classes support different types of operations, such as zoom and rotate. The **PixMap** class defines system-independent bitmaps. It stores raster image data and provides special services, such as saving the image data into an image file. The PixMaps are powered by the FreeImage library. 
2941
2942 **ColorImage** is used to create 24-bit TrueColor images:  
2943   * Create a ColorImage object with a given background color. 
2944   * Request the type of the image. 
2945   * Request or set the color of a given pixel. 
2946   * Zoom, rotating, translating, simple and refining transformations. 
2947   * Set position and size. 
2948   * Transpose, shift, clip, shift, clear. 
2949   * Draw line and rectangle. 
2950
2951 **PseudoColorImage** is used to create 32-bit images: 
2952   * Create a PseudoColorImage object with a given background color associated with a given ColorMap (Generic, ColorCube, ColorRamp) 
2953   * Ask or set the color of a given pixel, row, or column. 
2954   * Find the maximum &amp; minimum pixel values of an image. 
2955   * Change the pixel values by scaling. 
2956   * Change the pixel values below a threshold value. 
2957   * Zoom, rotating, translating, simple and refining transformations. 
2958   * Set position and size. 
2959   * Transpose, shift, clip, shift, clear. 
2960   *   *     Draw line and rectangle. 
2961
2962 **PixMap **provides support for system-independent bitmaps: 
2963   * Supports different kinds of raster images, such as 24-bit, 32-bit, 96-bit, 128-bit, or RGB, RGBA, floating-point RGB and RGBA.
2964   * Provides direct access to the pixel buffer.
2965   * Provides image dump services. The use of FreeImage library enhances these services with the capability of saving raster images into different image file formats. **Note** that without FreeImage library support, the raster images could be dumped into the PPM format only.
2966   * PixMaps could be used for handling system bitmaps and dumping window contents.
2967   
2968 **Convertor** is used to: 
2969   * Change an image from a ColorImage to a PseudoColorImage. Select between two dithering algorithms for the change. 
2970   * Change an image from a PseudoColorImage to a ColorImage. 
2971   * Change a PseudoColorImage into one with a different ColorMap. 
2972
2973 **LookupTable** is used to: 
2974   * Transform the pixels of a PseudoColorImage. 
2975
2976 Various **PixelInterpolation** classes are available for dealing with pixel values at non-integer coordinates. 
2977
2978 The package also includes a number of **package methods** for zooming, rotation, translation, as well as simple and refining transformations. 
2979
2980 @subsection occt_1621831385_863939503 AlienImage 
2981
2982 @subsubsection occt_1621831385_8639395031 Overview 
2983
2984 The **AlienImage** package is used to import 2D images from some other format into the CAS.CADE format. 
2985
2986 @subsubsection occt_1621831385_8639395032 Available Services 
2987   * Reads the content of an AlienImage object from a file. 
2988   * Writes the content of an AlienImage object to a file. 
2989   * Converts an AlienImage object to an Image object. 
2990   * Converts an Image object to an AlienImage object. 
2991
2992 @subsection occt_1621831385_863939504 V2d 
2993
2994 @subsubsection occt_1621831385_8639395041 Overview 
2995
2996 This package is used to build a 2D mono-view viewer in a windowing system. It contains the commands available within the viewer (zoom, pan, pick, etc). 
2997
2998 @subsubsection occt_1621831385_8639395042 The services provided 
2999
3000 The **V2d** package contains the **View** class. **View** is used to: 
3001   * Create a view in an window. 
3002   * Handle the view: 
3003   * zoom 
3004   * fit all 
3005   * pan 
3006   * translate 
3007   * erase 
3008   * pick 
3009   * highlight 
3010   * set drawing precision 
3011   * Postscript output 
3012
3013 @section occt_1621831385_1676618855 Graphic Attributes
3014 @subsection occt_1621831385_16766188551 Aspect 
3015
3016 @subsubsection occt_1621831385_167661885511 Overview 
3017
3018 The **Aspect** package provides classes for the graphic elements, which are common to all 2D and 3D viewers - screen background, windows, edges, groups of graphic attributes that can be used in describing 2D and 3D objects. 
3019
3020 @subsubsection occt_1621831385_167661885512 The services provided 
3021
3022 The **Aspect** package provides classes to implement: 
3023   * Color maps, 
3024   * Pixels, 
3025   * Groups of graphic attributes, 
3026   * Edges, lines, background, 
3027   * Font classes, 
3028   * Width map classes, 
3029   * Marker map classes, 
3030   * Type of Line map classes, 
3031   * Window, 
3032   * Driver, PlotterDriver (inherited by PS_Driver), WindowDriver, 
3033   * Graphic device (inherited by Xw_GraphicDevice, Graphic3d_GraphicDevice), 
3034   * Enumerations for many of the above, 
3035   * Array instantiations for edges, 
3036   * Array instantiations for map entries for color, type, font, width, and marker.