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