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