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