-Visualization {#user_guides__visualization}
-===================
-
-@section occt_1621831385_591811643 Introduction
+Visualization {#occt_user_guides__visualization}
+========================
+@tableofcontents
+@section occt_visu_1 Introduction
-This manual explains how to use Open CASCADE Technology Visualization. It provides basic documentation on setting up and using Visualization. For advanced information on Visualization and its applications, see our offerings on our web site
-(Training and E-Learning) at <a href="http://www.opencascade.org/support/training/">http://www.opencascade.org/support/training/</a>
+Visualization in Open CASCADE Technology is based on the separation of:
+ * on the one hand -- the data which stores the geometry and topology of the entities you want to display and select, and
+ * 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).
-Visualization in Open CASCADE Technology is based on the separation of:
- * on the one hand - the data which stores the geometry and topology of the entities you want to display and select, and
- * on the other hand - its *presentation* (what you see when an object is displayed in a scene) and *selection* (possibility to choose the whole object or its sub-parts interactively in order to apply some application-defined operations to the selected entities).
+Presentations are managed through the **Presentation** component, and selection through the **Selection** component.
-@subsection occt_1621831385_5918116431 Open CASCADE Technology Visualization and the Organization of this guide
+**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.
-Presentations are managed through the Presentation component, and selection through the Selection component.
+*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.
-To make management of these functionalities in 3D more intuitive and consequently, more transparent, **Application Interactive Services** have been created. **AIS** use the notion of the *interactive object*, a displayable and selectable entity, which represents an element from the application data. As a result, in 3D, you, the user, have no need to be familiar with any functions underlying AIS unless you want to create your own interactive objects or selection filters.
+If, however, you require types of interactive objects and filters other than those provided, you will need to know the mechanics of presentable and selectable objects, specifically how to implement their virtual functions. To do this requires familiarity with such fundamental concepts as the Sensitive Primitive and the Presentable Object.
-If, however, you require types of interactive objects and filters other than those provided, you will need to know the mechanics of presentable and selectable objects, specifically how to implement their virtual functions. To do this requires familiarity with such fundamental concepts as the sensitive primitive and the presentable object.
+The the following packages are used to display 3D objects:
+ * *AIS*;
+ * *StdPrs*;
+ * *Prs3d*;
+ * *PrsMgr*;
+ * *V3d*;
+ * *Graphic3d*.
-The packages used to display 3D objects are the following:
- * AIS
- * StdPrs
- * Prs3d
- * PrsMgr
- * V3d
- * Graphic3d
+The packages used to display 3D objects are also applicable for visualization of 2D objects.
-If you are concerned with 2D visualization, you must familiarize yourself with the fundamental concepts of presentation as outlined in the section on this subject in chapter 1, Fundamental Concepts. In brief, the packages used to display 2D objects are the following:
- * AIS2D
- * Prs2d
- * PrsMgr
- * V2d
- * Graphic2d.
+The figure below presents a schematic overview of the relations between the key concepts and packages in visualization. Naturally, "Geometry & Topology" is just an example of application data that can be handled by *AIS*, and application-specific interactive objects can deal with any kind of data.
-Figure 1 below presents a schematic overview of the relations between the key concepts and packages in visualization. AIS stands for both AIS and AIS2D packages. Naturally, *Geometry & 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.
+@figure{visualization_image003.png,"Key concepts and packages in visualization",400}
-@image html /user_guides/visualization/images/visualization_image003.jpg
-@image latex /user_guides/visualization/images/visualization_image003.jpg
-**Figure 1. Key concepts and packages in visualization**
+To answer different needs of CASCADE users, this User's Guide offers the following three paths in reading it.
-To answer different needs of CASCADE users, this user’s guide offers the following three paths in reading it.
-
- * If the 3D services proposed in AIS meet your requirements, you need only read chapter 3, *AIS: Application Interactive Services*.
+ * If the 3D services proposed in AIS meet your requirements, you need only read chapter 3 @ref occt_visu_3 "AIS: Application Interactive Services".
+ * 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.
- * If the services provided do not satisfy your requirements - if for example, you need a selection filter on another type of entity - you should read chapter 2 *Fundamental Concepts*, chapter 3 *AIS: Application Interactive Services*, and possibly chapters 4 and 5 *3D Presentations *and *3D Resources*. You may want to begin with the chapter presenting AIS.
+For advanced information on visualization algorithms, see our <a href="http://www.opencascade.com/content/tutorial-learning">E-learning & Training</a> offerings.
- * If your display will be in 2D, you should read chapter 1 *Fundamental Concepts*, chapter 6 *2D Presentations* and chapter 7 *2D Resources*.
+@section occt_visu_2 Fundamental Concepts
-
-@section occt_1621831385_1633708282 Fundamental Concepts
+@subsection occt_visu_2_1 Presentation
-@subsection occt_1621831385_16337082821 Presentation
+In Open CASCADE Technology, presentation services are separated from the data, which they represent, which is generated by applicative algorithms. This division allows you to modify a geometric or topological algorithm and its resulting objects without modifying the visualization services.
-In Open CASCADE Technology, presentation services are separated from the data, which they represent, which is generated by applicative algorithms. This division allows you to modify a geometric or topological algorithm and its resulting objects without modifying the visualization services.
+@subsubsection occt_visu_2_1_1 Structure of the Presentation
-@subsubsection occt_1621831385_163370828211 Key difference in implementation of 2D and 3D visualization
-Current implementation of 3D visualization services is based on OpenGL.
-2D visualization packages use native window system API (Win32 GDI API on Windows, Xlib API on Unix and Linux).
-@subsubsection occt_1621831385_163370828212 Structure of the Presentation
+Displaying an object on the screen involves three kinds of entities:
+ * a presentable object, the *AIS_InteractiveObject*
+ * a viewer
+ * an interactive context, the *AIS_InteractiveContext*.
-Displaying an object on the screen involves three kinds of entity:
- * a presentable object, the *AIS_InteractiveObject *
- * a viewer
- * an interactive context, the *AIS_InteractiveContext*.
+#### The presentable object
-<h4>The presentable object </h4>
-The purpose of a presentable object is to provide the graphical representation of an object in the form of Graphic2d or Graphic3d structure. On the first display request, it creates this structure by calling the appropriate algorithm and retaining this framework for further display.
-Standard presentation algorithms are provided in the StdPrs and Prs3d packages. You can, however, write specific presentation algorithms of your own, provided that they create presentations made of structures from the Graphic2d or Graphic3d packages. You can also create several presentations of a single presentable object: one for each visualization mode supported by your application.
-Each object to be presented individually must be presentable or associated with a presentable object.
+The purpose of a presentable object is to provide the graphical representation of an object in the form of *Graphic3d* structure. On the first display request, it creates this structure by calling the appropriate algorithm and retaining this framework for further display.
-<h4>The viewer </h4>
-The viewer allows you to interactively manipulate views of the object. When you zoom, translate or rotate a view, the viewer operates on the graphic structure created by the presentable object and not on the data model of the application. Creating Graphic2d and Graphic3d structures in your presentation algorithms allows you to use the 2D and 3D viewers provided in Open CASCADE Technology.
+Standard presentation algorithms are provided in the *StdPrs* and *Prs3d* packages. You can, however, write specific presentation algorithms of your own, provided that they create presentations made of structures from the *Graphic3d* packages. You can also create several presentations of a single presentable object: one for each visualization mode supported by your application.
-<h4>The Interactive Context </h4>
-(see chapter 2, AIS: Application Interactive Services) The interactive context controls the entire presentation process from a common high-level API. When the application requests the display of an object, the interactive context requests the graphic structure from the presentable object and sends it to the viewer for displaying.
+Each object to be presented individually must be presentable or associated with a presentable object.
-<h4>Presentation packages </h4>
-Presentation involves at least the AIS, AIS2D, PrsMgr, StdPrs, V3d and V2d packages. Additional packages such as Prs3d, Prs2d, Graphic3d and Graphic2d may be used if you need to implement your own presentation algorithms.
+#### The viewer
-<h4>AIS and AIS2D</h4>
-See chapter 2, **AIS: Application Interactive Services **The *AIS* package provides all classes to implement interactive objects (presentable and selectable 2D or 3D entities).
+The viewer allows interactively manipulating views of the object. When you zoom, translate or rotate a view, the viewer operates on the graphic structure created by the presentable object and not on the data model of the application. Creating Graphic3d structures in your presentation algorithms allows you to use the 3D viewers provided in Open CASCADE Technology for 3D visualisation.
-<h4>PrsMgr </h4>
-The *PrsMgr* package provides all the classes needed to implement the presentation process: the *Presentation* and *PresentableObject* abstract classes and the *PresentationManager2d* and *PresentationManager3d* concrete classes.
+#### The Interactive Context
-<h4>StdPrs </h4>
-The *StdPrs* package provides ready-to-use standard presentation algorithms of points, curves and shapes of the geometry and topology toolkits.
+The interactive context controls the entire presentation process from a common high-level API. When the application requests the display of an object, the interactive context requests the graphic structure from the presentable object and sends it to the viewer for displaying.
-<h4>V2d and V3d </h4>
-The *V2d* and *V3d* packages provide the services supported by the 2D and 3D viewers.
+@subsubsection occt_visu_2_1_2 Presentation packages
-<h4>Prs3d and Prs2d</h4>
-The *Prs3d* package provides some generic presentation algorithms such as wireframe, shading and hidden line removal associated with a Drawer class which controls the attributes of the presentation to be created in terms of color, line type, thickness, and so on.
+Presentation involves at least the *AIS, PrsMgr, StdPrs* and *V3d* packages. Additional packages, such as *Prs3d* and *Graphic3d* may be used if you need to implement your own presentation algorithms.
-<h4>Graphic2d and Graphic3d </h4>
-The *Graphic2d* and *Graphic3d* packages provide resources to create 2D and 3D graphic structures (please refer to chapters on 3D Resources and 2D Resources for more information).
+* *AIS* package provides all classes to implement interactive objects (presentable and selectable entities).
+* *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*.
+* *StdPrs* package provides ready-to-use standard presentation algorithms for specific geometries: points, curves and shapes of the geometry and topology toolkits.
+* *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.
+* *V3d* package provides the services supported by the 3D viewer.
+* *Graphic3d* package provides resources to create 3D graphic structures.
+* *Visual3d* package contains classes implementing commands for 3D viewer.
+* *DsgPrs* package provides tools for display of dimensions, relations and XYZ trihedrons.
+@subsubsection occt_visu_2_1_3 A Basic Example: How to display a 3D object
-@subsubsection occt_1621831385_163370828213 A Basic Example: How to display a 3D object
-<h4>Example </h4>
+~~~~~
+Handle(V3d_Viewer) theViewer;
+Handle(AIS_InteractiveContext) aContext = new AIS_InteractiveContext (theViewer);
-Void Standard_Real dx = ...; //Parameters Void Standard_Real dy = ...; //to build a wedge Void Standard_Real dz = ...; Void Standard_Real ltx = ...;
+BRepPrimAPI_MakeWedge aWedgeMaker (theWedgeDX, theWedgeDY, theWedgeDZ, theWedgeLtx);
+TopoDS_Solid aShape = aWedgeMaker.Solid();
+Handle(AIS_Shape) aShapePrs = new AIS_Shape (aShape); // creation of the presentable object
+aContext->Display (aShapePrs); // display the presentable object in the 3d viewer
+~~~~~
-Handle(V3d_Viewer)aViewer = ...; Handle(AIS_InteractiveContext)aContext; aContext = new AIS_InteractiveContext(aViewer);
-BRepPrimAPI_MakeWedge w(dx, dy, dz, ltx); TopoDS_Solid & = w.Solid(); Handle(AIS_Shape) anAis = new AIS_Shape(S); //creation of the presentable object aContext - Display(anAis); //Display the presentable object in the 3d viewer.
+The shape is created using the *BRepPrimAPI_MakeWedge* command. An *AIS_Shape* is then created from the shape. When calling the *Display* command, the interactive context calls the Compute method of the presentable object to calculate the presentation data and transfer it to the viewer. See figure below.
-The shape is created using the *BRepPrimAPI_MakeWedge* command. An AIS_Shape is then created from the shape. When calling the *Display *command, the interactive context calls the Compute method of the presentable object to calculate the presentation data and transfer it to the viewer. See Figure 2 below.
+@figure{visualization_image004.svg,"Processes involved in displaying a presentable shape",400}
-** **
+@subsection occt_visu_2_2 Selection
+Standard OCCT selection algorithm is represented by 2 parts: dynamic and static. Dynamic selection causes objects to be automatically highlighted as the mouse cursor moves over them. Static selection allows to pick particular object (or objects) for further processing.
+There are 3 different selection types:
+ - **Point selection** -- allows picking and highlighting a single object (or its part) located under the mouse cursor;
+ - **Rectangle selection** -- allows picking objects or parts located under the rectangle defined by the start and end mouse cursor positions;
+ - **Polyline selection** -- allows picking objects or parts located under a user-defined non-self-intersecting polyline.
+For OCCT selection algorithm, all selectable objects are represented as a set of sensitive zones, called **sensitive entities**. When the mouse cursor moves in the view, the sensitive entities of each object are analyzed for collision.
+@subsubsection occt_visu_2_2_1 Terms and notions
+This section introduces basic terms and notions used throughout the algorithm description.
+#### Sensitive entity
-@image html /user_guides/visualization/images/visualization_image004.png
-@image latex /user_guides/visualization/images/visualization_image004.png
+Sensitive entities in the same way as entity owners are links between objects and the selection mechanism.
-@image html /user_guides/visualization/images/visualization_image005.png
-@image latex /user_guides/visualization/images/visualization_image005.png
-**Figure 2. Processes involved in displaying a presentable shape**
+The purpose of entities is to define what parts of the object will be selectable in particular. Thus, any object that is meant to be selectable must be split into sensitive entities (one or several). For instance, to apply face selection to an object it is necessary to explode it into faces and use them for creation of a sensitive entity set.
-@subsection occt_1621831385_16337082822 Selection
-This chapter deals with the process used for selecting entities, which are displayed in the 2D space of the selection view.
+@figure{visualization_image005.png,"Example of a shape divided into sensitive entities",400}
-@subsubsection occt_1621831385_163370828221 The Selection Principle
+Depending on the user's needs, sensitive entities may be atomic (point or edge) or complex. Complex entities contain many sub-elements that can be handled by detection mechanism in a similar way (for example, a polyline stored as a set of line segments or a triangulation).
-Objects that may be selected graphically, are displayed as sets of sensitive primitives, which provide sensitive zones in 2D graphic space. These zones are sorted according to their position on the screen when starting the selection process.
-The position of the mouse is also associated with a sensitive zone. When moving within the window where objects are displayed, the areas touched by the zone of the mouse are analyzed. The owners of these areas are then highlighted or signaled by other means such as the name of the object highlighted in a list. That way, you are informed of the identity of the element detected.
+Entities are used as internal units of the selection algorithm and do not contain any topological data, hence they have a link to an upper-level interface that maintains topology-specific methods.
-@image html /user_guides/visualization/images/visualization_image006.jpg
-@image latex /user_guides/visualization/images/visualization_image006.jpg
-**Figure 3. A model **
+#### Entity owner
-@image html /user_guides/visualization/images/visualization_image007.jpg
-@image latex /user_guides/visualization/images/visualization_image007.jpg
-**Figure 4. Modeling faces with sensitive primitives **
+Each sensitive entity stores a reference to its owner, which is a class connecting the entity and the corresponding selectable object. Besides, owners can store any additional information, for example, the topological shape of the sensitive entity, highlight colors and methods, or if the entity is selected or not.
-@image html /user_guides/visualization/images/visualization_image008.jpg
-@image latex /user_guides/visualization/images/visualization_image008.jpg
-**Figure 5. In a dynamic selection, each sensitive polygon is represented by its bounding rectangle**
+#### Selection
-@image html /user_guides/visualization/images/visualization_image009.jpg
-@image latex /user_guides/visualization/images/visualization_image009.jpg
-Figure 6. Reference to the sensitive primitive, then to the owner
+To simplify the handling of different selection modes of an object, sensitive entities linked to their owners are organized into sets, called **selections**.
+Each selection contains entities created for a certain mode along with the sensitivity and update states.
-@subsubsection occt_1621831385_163370828222 The Sensitive Primitive
+#### Selectable object
-The sensitive primitive - along with the entity owner - allow you to define what can be made selectable, and in so doing, provide the link between the applicative object and the sensitive zones defined by the 2D bounding boxes. For an object to be dynamically selectable, it has to be represented either as a sensitive primitive or a set of them. These give 2D boxes that will be included in a sorting algorithm.
-The use of 2D boxes allows a pre-selection of the detected entities. After pre-selection, the algorithm checks which sensitive primitives are actually detected. When detected, the primitives provide their owners’ identity.
-<h4>Example </h4>
+Selectable object stores information about all created selection modes and sensitive entities.
-The sensitive line segment below proposes a bounding box to the selector. During selection, positions 1 and 2 of the mouse detect the box but after sorting, only position 2 retains the line segment as selected by the algorithm.
+All successors of a selectable object must implement the method that splits its presentation into sensitive entities according to the given mode. The computed entities are arranged in one selection and added to the list of all selections of this object. No selection will be removed from the list until the object is deleted permanently.
-@image html /user_guides/visualization/images/visualization_image010.jpg
-@image latex /user_guides/visualization/images/visualization_image010.jpg
-**Figure 7. Example of sensitive primitives **
+For all standard OCCT shapes, zero mode is supposed to select the whole object (but it may be redefined easily in the custom object). For example, the standard OCCT selection mechanism and *AIS_Shape* determine the following modes:
+ - 0 -- selection of entire object (AIS_Shape);
+ - 1 -- selection of the vertices;
+ - 2 -- selection of the edges;
+ - 3 -- selection of the wires;
+ - 4 -- selection of the faces;
+ - 5 -- selection of the shells;
+ - 6 -- selection of the constituent solids.
-When the 2D box associated with the position of the mouse intersects the 2D box of a sensitive primitive, the owner of the sensitive primitive is called and its presentation is highlighted.
-The notion of sensitive primitive is important for the developer when defining his own classes of sensitive primitives for the chosen selection modes. The classes must contain *Areas* and *Matches* functions. The former provides the list of 2D sensitive boxes representing the sensitive primitive at pre-selection and the latter determines if the detection of the primitive by the 2D boxes is valid.
-@subsubsection occt_1621831385_163370828223 The Principles of Dynamic Selection
+@figure{visualization_image006.png,"Hierarchy of references from sensitive entity to selectable object",400}
-Dynamic selection causes objects in a view to be automatically highlighted as the mouse cursor moves over them. This allows the user to be certain that the picked object is the correct one. Dynamic Selection is based on the following two concepts:
- * a Selectable Object (see *AIS_InteractiveObject*)
- * an Interactive Context
+@figure{visualization_image007.png,"The principle of entities organization within the selectable object",400}
-<h4>Selectable Object </h4>
-A selectable object presents a given number of selection modes which can be redefined, and which will be activated or deactivated in the selection manager’s selectors.
+#### Viewer selector
-*The term, selection mode of a selectable object, can refer to the selection mode of the object itself or to that of one of its parts.*
+For each OCCT viewer there is a **Viewer selector** class instance. It provides a high-level API for the whole selection algorithm and encapsulates the processing of objects and sensitive entities for each mouse pick.
+The viewer selector maintains activation and deactivation of selection modes, launches the algorithm, which detects candidate entities to be picked, and stores its results, as well as implements an interface for keeping selection structures up-to-date.
-For each selection mode, a *SelectMgr_Selection* object class is included in the selectable object. (Each selection mode establishes a priority of selection for each class of selectable object defined.)
+#### Selection manager
-The notion of SELECTION is comparable to the notion of DISPLAY. Just as a display contains a set of graphic primitives that allow display of the entity in a specific display mode, a SELECTION contains a set of sensitive primitives, which allow detection of the entities they are associated with.
+Selection manager is a high-level API to manipulate selection of all displayed objects. It handles all viewer selectors, activates and deactivates selection modes for the objects in all or particular selectors, manages computation and update of selections for each object. Moreover, it keeps selection structures updated taking into account applied changes.
-<h4>Interactive Context</h4>
-See chapter 2, AIS: Application Interactive Services, Section 2.4
+@figure{visualization_image008.png,"The relations chain between viewer selector and selection manager",400}
-The interactive context is used to manage both selectable objects and selection processes.
+@subsubsection occt_visu_2_2_2 Algorithm
-Selection modes may be activated or de-activated for given selectable objects. Information is then provided about the status of activated/de-activated selection modes for a given object in a given selector.
-<h4>Example </h4>
+All three types of OCCT selection are implemented as a single concept, based on the search for overlap between frustum and sensitive entity through 3-level BVH tree traversal.
-Let’s consider the 3D selectable shape object, which corresponds to a topological shape.
+#### Selection Frustum
-For this class, seven selection modes can be defined:
+The first step of each run of selection algorithm is to build the selection frustum according to the currently activated selection type.
-mode 0 - selection of the shape itself
-mode 1 - selection of vertices
-mode 2 - selection of edges
-mode 3 - selection of wires
-mode 4 - selection of faces
-mode 5 - selection of shells
-mode 6 - selection of solids
-mode 7 - selection of compounds
+For the point or the rectangular selection the base of the frustum is a rectangle built in conformity with the pixel tolerance or the dimensions of a user-defined area, respectively. For the polyline selection, the polygon defined by the constructed line is triangulated and each triangle is used as the base for its own frustum. Thus, this type of selection uses a set of triangular frustums for overlap detection.
-Selection 2 includes the sensitive primitives that model all the edges of the shape. Each of these primitives contains a reference to the edge it represents.
+The frustum length is limited by near and far view volume planes and each plane is built parallel to the corresponding view volume plane.
-The selections may be calculated before any activation and are graph independent as long as they are not activated in a given selector. Activation of selection mode 3 in a selector associated with a view V leads to the projection of the 3D sensitive primitives contained in the selection; then the 2D areas which represent the 2D bounding boxes of these primitives are provided to the sorting process of the selector containing all the detectable areas.
+@figure{visualization_image009.png,"",400}
-To deactivate selection mode 3 remove all those 2D areas.
+The image above shows the rectangular frustum: a) after mouse move or click, b) after applying the rectangular selection.
+@figure{visualization_image010.png,"",400}
-*Selection Packages *
-The selection packages are the following: *SelectBasics*, *SelectMgr*, *Select2D*, *Select3D*, *StdSelect*.
+In the image above triangular frustum is set: a) by a user-defined polyline, b) by triangulation of the polygon based on the given polyline, c) by a triangular frustum based on one of the triangles.
-*SelectBasics *
-The *SelectBasics* package contains the basic classes of the selection:
- * the main definition of a sensitive primitive: *SensitiveEntity *
- * the definition of a sensitive primitive owner: *EntityOwner *
- * the algorithm used for sorting sensitive boxes: *SortAlgo *
+#### BVH trees
-*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*.
+To maintain selection mechanism at the viewer level, a speedup structure composed of 3 BVH trees is used.
-*SelectMgr *
-The *SelectMgr* package is used to manage the whole dynamic selection process. It contains the *SelectableObject**, Entity Owner containing a link to its SelectableObject,* *Selection*, *SelectionManager*, and *ViewSelector* classes.
-There are also implementations of *ViewerSelector* interface for 2D and 3D selection: *ViewerSelector2d* and *ViewerSelector3d*, respectively.
+The first level tree is constructed of axis-aligned bounding boxes of each selectable object. Hence, the root of this tree contains the combination of all selectable boundaries even if they have no currently activated selections. Objects are added during the display of *AIS_InteractiveObject* and will be removed from this tree only when the object is destroyed. The 1st level BVH tree is build on demand simultaneously with the first run of the selection algorithm.
-*Select2D *
-The *Select2D* package contains the basic classes of 2D sensitive primitives such as Points, Segments, and Circles, which inherit from *SensitiveEntity* from *SelectBasics* and used to represent 2D selectable objects from a dynamic selection viewpoint.
+The second level BVH tree consists of all sensitive entities of one selectable object. The 2nd level trees are built automatically when the default mode is activated and rebuilt whenever a new selection mode is calculated for the first time.
-*Select3D *
-The *Select3D* package contains all 3D standard sensitive primitives such as point, curve and face. All these classes inherit from 3D *SensitiveEntry* from *SelectBasics* with an additional method, which allows recovery of the bounding boxes in the 2D graphic selection space, if required. This package also includes the 3D-2D projector.
+The third level BVH tree is used for complex sensitive entities that contain many elements: for example, triangulations, wires with many segments, point sets, etc. It is built on demand for sensitive entities with under 800K sub-elements.
-*StdSelect *
-The *StdSelect* package provides standard uses of the classes described above and main tools used to prevent the developer from redefining the selection objects. In particular, *StdSelect* includes standard means for selection of topological objects (shapes).
+@figure{visualization_image022.png,"Selection BVH tree hierarchy: from the biggest object-level (first) to the smallest complex entity level (third)",400}
-@subsubsection occt_1621831385_163370828224 Methodology
+#### Stages of the algorithm
-Several operations must be performed prior to using dynamic selection:
-**1. **Implement specific sensitive primitives if those defined in Select2D and Select3D are not sufficient. These primitives must inherit from *SensitiveEntity* from *SelectBasics* or from a suitable Select3D sensitive entity class when a projection from 3D to 2D is necessary.
-**2. **Define all the owner types, which will be used, and the classes of selectable objects, i.e. the number of possible selection modes for these objects and the calculation of the decomposition of the object into sensitive primitives of all the primitives describing this mode. It is possible to define only one default selection mode for a selectable object if this object is to be selectable in a unique way.
-**3. **Install the process, which provides the user with the identity of the owner of the detected entities in the selection loop.
+The algorithm includes pre-processing and three main stages.
-When all these steps have been carried out, follow the procedure below:
-**1. **Create an interactive context.
-**2. **Create the selectable objects and calculate their various possible selections.
-**3. **Load these selectable objects in the interactive context. The objects may be common to all the selectors, i.e. they will be seen by all the selectors in the selection manager, or local to one selector or more.
-**4. **Activate or deactivate the objects’ selection modes in the selector(s). When activating a selection mode in a selector for a given object, the manager sends the order to make the sensitive primitives in this selector selectable. If the primitives are to projected from 3D to 2D, the selector calls the specific method used to carry out this projection.
+##### Pre-processing
-At this stage, the selection of selectable entities in the selectors is available.
-The selection loop informs constantly the selectors with the position of the mouse and questions them about the detected entities.
+Implies calculation of the selection frustum and its main characteristics.
+##### First stage -- traverse of the first level BVH tree
-@subsubsection occt_1621831385_163370828225 Example of Use
+After successful building of the selection frustum, the algorithm starts traversal of the object-level BVH tree. The nodes containing axis-aligned bounding boxes are tested for overlap with the selection frustum following the terms of *separating axis theorem (SAT)*. When the traversal goes down to the leaf node, it means that a candidate object with possibly overlapping sensitive entities has been found. If no such objects have been detected, the algorithm stops and it is assumed that no object needs to be selected. Otherwise it passes to the next stage to process the entities of the found selectable object.
-Let’s suppose you are creating an application that displays houses in a viewer of the V3d package and you want to select houses or parts of these houses (windows, doors, etc.) in the graphic window.
-You define a selectable object called *House* and propose four possible selection modes for this object:
-**1 -** selection of the house itself
-**2 -** selection of the rooms
-**3 -** selection of the walls
-**4 - **selection of the doors.
+##### Second stage -- traversal of the second level BVH tree
-You have to write the method, which calculates the four selections above, i.e. the sensitive primitives which are activated when the mode is.
-You must define the class *Owner* specific to your application. This class will contain the reference to the house element it represents: wall, door or room. It inherits from *EntityOwner* from *SelectMgr*.
-For example, let’s consider a house with the following representation:
-@image html /user_guides/visualization/images/visualization_image011.jpg
-@image latex /user_guides/visualization/images/visualization_image011.jpg
-**Figure 8. Selection of the rooms of a house**
+At this stage it is necessary to determine if there are candidates among all sensitive entities of one object.
-To build the selection, which corresponds to the mode *selection of the rooms* (selection 2 in the list of selection modes) use the following procedure:
-<h4>Example </h4>
+First of all, at this stage the algorithm checks if there is any transformation applied for the current object. If it has its own location, then the correspondingly transformed frustum will be used for further calculations. At the next step the nodes of the second level BVH tree of the given object are visited to search for overlapping leaves. If no such leafs have been found, the algorithm returns to the second stage. Otherwise it starts processing the found entities by performing the following checks:
+ - activation check - the entity may be inactive at the moment as it belongs to deactivated selection;
+ - tolerance check - current selection frustum may be too large for further checks as it is always built with the maximum tolerance among all activated entities. Thus, at this step the frustum may be scaled.
-Void House::ComputeSelection
-(Const Handle(SelectMgr_Selection)& Sel,
- const Standard_Integer mode {
- switch(mode){ case 0: //Selection of the rooms { for(Standard_Integer i = 1; i = myNbRooms; i++) { //for every room, create an instance of the owner
- //along with the given room and its name. Handle(RoomOwner) aRoomOwner = new RoomOwner (Room(i), NameRoom(i)); //Room() returns a room and NameRoom() returns its name.
-Handle(Select3d_SensitiveBox) aSensitiveBox;
-aSensitiveBox = new Select3d_SensitiveBox
-(aRoomOwner, Xmin, Ymin, Zmin, Xmax, Ymax, Zmax);
- Sel - Add(aSensitiveBox); } break; Case 1: ... //Selection of the doors } //Switch
-) // ComputeSelection
+After these checks the algorithm passes to the last stage.
+##### Third stage -- overlap or inclusion test of a particular sensitive entity
-@image html /user_guides/visualization/images/visualization_image012.jpg
-@image latex /user_guides/visualization/images/visualization_image012.jpg
-**Figure 9. Activated sensitive boxes corresponding to selection mode 0 (selection of the rooms)**
+If the entity is atomic, a simple SAT test is performed. In case of a complex entity, the third level BVH tree is traversed. The quantitative characteristics (like depth, distance to the center of geometry) of matched sensitive entities is analyzed and clipping planes are applied (if they have been set). The result of detection is stored and the algorithm returns to the second stage.
-@image html /user_guides/visualization/images/visualization_image013.jpg
-@image latex /user_guides/visualization/images/visualization_image013.jpg
+@subsubsection occt_visu_2_2_3 Packages and classes
-@image html /user_guides/visualization/images/visualization_image014.jpg
-@image latex /user_guides/visualization/images/visualization_image014.jpg
-**Figure 11. Activated sensitive polygons corresponding to selection mode 1.**
+Selection is implemented as a combination of various algorithms divided among several packages -- *SelectBasics*, *Select3D*, *SelectMgr* and *StdSelect*.
-**(selection of the doors)**
-@image html /user_guides/visualization/images/visualization_image015.jpg
-@image latex /user_guides/visualization/images/visualization_image015.jpg
+#### SelectBasics
-**Figure 12. Sensitive rectangles in the selector during dynamic selection in view 2**
-@section occt_1621831385_810308609 AIS: Application Interactive Services
-Application Interactive Services (**AIS**) offers a set of general services beyond those offered by basic Selection and Presentation packages such as **PrsMgr**, **SelectMgr** and **StdSelect**. These allow you to manage presentations and dynamic selection in a viewer simply and transparently. To use these services optimally, you should know various rules and conventions. Section I provides an overview of the important classes which you need to manipulate AIS well. Sections 2 and 3 explain in detail how to use them and how to implement them, as well as the rules and conventions to respect. The annexes offer various standard Interactive Objects in AIS, an example of an implementation of AIS and a reminder of how to manage presentation and selection.
+*SelectBasics* package contains basic classes and interfaces for selection. The most notable are:
+ - *SelectBasics_SensitiveEntity* -- the base definition of a sensitive entity;
+ - *SelectBasics_EntityOwner* -- the base definition of the an entity owner -- the link between the sensitive entity and the object to be selected;
+ - *SelectBasics_PickResult* -- the structure for storing quantitative results of detection procedure, for example, depth and distance to the center of geometry;
+ - *SelectBasics_SelectingVolumeManager* -- the interface for interaction with the current selection frustum.
-@subsection occt_1621831385_8103086091 Overview
+Each custom sensitive entity must inherit at least *SelectBasics_SensitiveEntity*.
-@subsubsection occt_1621831385_81030860911 Interactive Context/Local Context
-<h4>AIS_InteractiveContext </h4>
-The central entity, which pilots visualizations and selections, is the Interactive Context. It is linked to a main viewer (and if need be, a trash bin viewer.) It has two operating modes: the Neutral Point and the local visualization and selection context. The neutral point, which is the default mode, allows you to easily visualize and select interactive objects, which have been loaded into the context. Opening Local Contexts allows you to prepare and use a temporary selection environment without disturbing the neutral point. A set of functions allows you to choose the interactive objects, which you want to act on, the selection modes, which you want to activate, and the temporary visualizations, which you will execute. When the operation is finished, you close the current local context and return to the state in which you were before opening it (neutral point or previous local context).
+#### Select3D
-@subsubsection occt_1621831385_81030860912 The Interactive Object
+*Select3D* package provides a definition of standard sensitive entities, such as:
+ - box;
+ - circle;
+ - curve;
+ - face;
+ - group;
+ - point;
+ - segment;
+ - triangle;
+ - triangulation;
+ - wire.
-<h4>AIS_InteractiveObject</h4>
-Entities, which are visualized and selected, are Interactive Objects. You can use classes of standard interactive objects for which all necessary functions have already been programmed, or you can implement your own classes of interactive objects, by respecting a certain number of rules and conventions described below.
+Each basic sensitive entity inherits *Select3D_SensitiveEntity*, which is a child class of *SelectBasics_SensitiveEntity*.
+The package also contains two auxiliary classes, *Select3D_SensitivePoly* and *Select3D_SensitiveSet*.
-@subsubsection occt_1621831385_81030860913 Graphic Attributes Manager or *Drawer*
+*Select3D_SensitiveSet* -- a base class for all complex sensitive entities that require the third level BVH usage. It implements traverse of the tree and defines an interface for the methods that check sub-entities.
-@image html /user_guides/visualization/images/visualization_image016.jpg
-@image latex /user_guides/visualization/images/visualization_image016.jpg
-An Interactive Object can have a certain number of graphic attributes specific to it (such as visualization mode, color and material) By the same token, the Interactive Context has a drawer which is valid by default for the objects it controls. When an interactive object is visualized, the required graphic attributes are first taken from its own Drawer if it has the ones required, or from the context drawer if it does not have them.
+*Select3D_SensitivePoly* -- describes an arbitrary point set and implements basic functions for selection. It is important to know that this class does not perform any internal data checks. Hence, custom implementations of sensitive entity inherited from *Select3D_SensitivePoly* must satisfy the terms of Separating Axis Theorem to use standard OCCT overlap detection methods.
-@subsubsection occt_1621831385_81030860914 Selection Filters
+#### SelectMgr
-@image html /user_guides/visualization/images/visualization_image017.jpg
-@image latex /user_guides/visualization/images/visualization_image017.jpg
+*SelectMgr* package is used to maintain the whole selection process. For this purpose, the package provides the following services:
+ - activation and deactivation of selection modes for all selectable objects;
+ - interfaces to compute selection mode of the object;
+ - definition of selection filter classes;
+ - keeping selection BVH data up-to-date.
-An important need in selection is the filtering of entities, which you want to select. Consequently there are FILTER entities, which allow you to refine the dynamic detection context, which you want to put into effect. Some of these filters can be used at the Neutral Point, others only in an open local context. A user will be able to program his own filters and load them into the interactive context.
+A brief description of the main classes:
+ - *SelectMgr_FrustumBase*, *SelectMgr_Frustum*, *SelectMgr_RectangularFrustum*, *SelectMgr_TriangluarFrustum* and *SelectMgr_TriangularFrustumSet* -- interfaces and implementations of selecting frustums, these classes implement different SAT tests for overlap and inclusion detection. They also contain methods to measure characteristics of detected entities (depth, distance to center of geometry);
+ - *SelectMgr_SensitiveEntity*, *SelectMgr_Selection* and *SelectMgr_SensitiveEntitySet* -- store and handle sensitive entities; *SelectMgr_SensitiveEntitySet* implements a primitive set for the second level BVH tree;
+ - *SelectMgr_SelectableObject* and *SelectMgr_SelectableObjectSet* -- describe selectable objects. They also manage storage, calculation and removal of selections. *SelectMgr_SelectableObjectSet* implements a primitive set for the first level BVH tree;
+ - *SelectMgr_ViewerSelector* -- encapsulates all logics of the selection algorithm and implements the third level BVH tree traverse;
+ - *SelectMgr_SelectionManager* -- manages activation/deactivation, calculation and update of selections of every selectable object, and keeps BVH data up-to-date.
-@subsection occt_1621831385_8103086092 Rules and Conventions Governing Interactive Objects
- An interactive object is a *virtual* entity, which can be presented and selected. It can also have its own visualization aspects such as color, material, and mode of visualization. In order to create and manipulate the interactive objects with ease, you must know the rules and conventions, which have been established. Several *virtual* functions must be implemented for these objects to have the behavior expected of them. A certain number of standard interactive objects, which respect the rules and conventions described below, have been implemented in AIS. The current list of them can be found in ANNEX I. The services that concern manipulation of presentations, selection and graphic attributes will be treated separately.
+#### StdSelect
+*StdSelect* package contains the implementation of some *SelectMgr* classes and tools for creation of selection structures. For example,
+ - *StdSelect_BRepOwner* -- defines an entity owner with a link to its topological shape and methods for highlighting;
+ - *StdSelect_BRepSelectionTool* -- contains algorithms for splitting standard AIS shapes into sensitive primitives;
+ - *StdSelect_ViewerSelector3d* -- an example of *SelectMgr_ViewerSelecor* implementation, which is used in a default OCCT selection mechanism;
+ - *StdSelect_FaceFilter*, *StdSelect_EdgeFilter* -- implementation of selection filters.
-@subsubsection occt_1621831385_81030860921 Presentations:
+@subsubsection occt_visu_2_2_4 Examples of usage
-@image html /user_guides/visualization/images/visualization_image018.jpg
-@image latex /user_guides/visualization/images/visualization_image018.jpg
-*Conventions *
- * Either in 2D or in 3D, an interactive object can have as many presentations as its creator wants to give it.
- * 3D presentations are managed by PresentationManager3D; 2D presentations by PresentationManager2D. As this is transparent in AIS, the user does not have to worry about it.
- * A presentation is identified by an index and by the reference to the Presentation Manager which it depends on.
- * By convention, the default mode of representation for the Interactive Object has index 0.
+The first code snippet illustrates the implementation of *SelectMgr_SelectableObject::ComputeSelection()* method in a custom interactive object. The method is used for computation of user-defined selection modes.
+Let us assume it is required to make a box selectable in two modes -- the whole shape (mode 0) and each of its edges (mode 1).
+To select the whole box, the application can create a sensitive primitive for each face of the interactive object. In this case, all primitives share the same owner -- the box itself.
+To select box's edge, the application must create one sensitive primitive per edge. Here all sensitive entities cannot share the owner since different geometric primitives must be highlighted as the result of selection procedure.
+
+~~~~
+void InteractiveBox::ComputeSelection (const Handle(SelectMgr_Selection)& theSel,
+ const Standard_Integer theMode)
+{
+ switch (theMode)
+ {
+ case 0: // creation of face sensitives for selection of the whole box
+ {
+ Handle(SelectMgr_EntityOwner) anOwner = new SelectMgr_EntityOwner (this, 5);
+ for (Standard_Integer aFaceIter = 1; aFaceIter <= myNbFaces; ++aFaceIter)
+ {
+ Select3D_TypeOfSensitivity aSensType = myIsInterior;
+ theSel->Add (new Select3D_SensitiveFace (anOwner, myFaces[aFaceIter]->PointArray(), aSensType));
+ }
+ break;
+ }
+ case 1: // creation of edge sensitives for selection of box edges only
+ {
+ for (Standard_Integer anEdgeIter = 1; anEdgeIter <= 12; ++anEdgeIter)
+ {
+ // 1 owner per edge, where 6 is a priority of the sensitive
+ Handle(MySelection_EdgeOwner) anOwner = new MySelection_EdgeOwner (this, anEdgeIter, 6);
+ theSel->Add (new Select3D_SensitiveSegment (anOwner, myFirstPnt[anEdgeIter]), myLastPnt[anEdgeIter]));
+ }
+ break;
+ }
+ }
+}
+~~~~
+
+The algorithms for creating selection structures store sensitive primitives in *SelectMgr_Selection* instance. Each *SelectMgr_Selection* sequence in the list of selections of the object must correspond to a particular selection mode.
+To describe the decomposition of the object into selectable primitives, a set of ready-made sensitive entities is supplied in *Select3D* package. Custom sensitive primitives can be defined through inheritance from *SelectBasics_SensitiveEntity*.
+To make custom interactive objects selectable or customize selection modes of existing objects, the entity owners must be defined. They must inherit *SelectMgr_EntityOwner* interface.
+
+Selection structures for any interactive object are created in *SelectMgr_SelectableObject::ComputeSelection()* method.
+The example below shows how computation of different selection modes of the topological shape can be done using standard OCCT mechanisms, implemented in *StdSelect_BRepSelectionTool*.
+
+~~~~
+ void MyInteractiveObject::ComputeSelection (const Handle(SelectMgr_Selection)& theSelection,
+ const Standard_Integer theMode)
+ {
+ switch (theMode)
+ {
+ case 0: StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_SHAPE); break;
+ case 1: StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_VERTEX); break;
+ case 2: StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_EDGE); break;
+ case 3: StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_WIRE); break;
+ case 4: StdSelect_BRepSelectionTool::Load (theSelection, this, myShape, TopAbs_FACE); break;
+ }
+ }
+~~~~
+
+The *StdSelect_BRepSelectionTool* class provides a high level API for computing sensitive entities of the given type (for example, face, vertex, edge, wire and others) using topological data from the given *TopoDS_Shape*.
+
+The 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:
+
+ - each entity owner has to maintain its own *Prs3d_Presentation* object, that results in a considerable memory overhead;
+ - drawing selected owners one by one is not efficient from the visualization point of view.
+
+Therefore, to overcome these limitations, OCCT has an alternative way to implement the highlighting of a selected presentation. Using this approach, the interactive object itself will be responsible for the highlighting, not the entity owner.
+
+On the basis of *SelectMgr_EntityOwner::IsAutoHilight()* return value, *AIS_InteractiveContext* object either uses the traditional way of highlighting (in case if *IsAutoHilight()* returns TRUE) or groups such owners according to their selectable objects and finally calls *SelectMgr_SelectableObject::HilightSelected()* or *SelectMgr_SelectableObject::ClearSelected()*, passing a group of owners as an argument.
+
+Hence, an application can derive its own interactive object and redefine virtual methods *HilightSelected()*, *ClearSelected()* and *HilightOwnerWithColor()* from *SelectMgr_SelectableObject*. *SelectMgr_SelectableObject::GetHilightPresentation* and *SelectMgr_SelectableObject::GetSelectPresentation* methods can be used to optimize filling of selection and highlight presentations according to the user's needs.
+The *AIS_InteractiveContext::HighlightSelected()* method can be used for efficient redrawing of the selection presentation for a given interactive object from an application code.
+
+After all the necessary sensitive entities are computed and packed in *SelectMgr_Selection* instance with the corresponding owners in a redefinition of *SelectMgr_SelectableObject::ComputeSelection()* method, it is necessary to register the prepared selection in *SelectMgr_SelectionManager* through the following steps:
+ - if there was no *AIS_InteractiveContext* opened, create an interactive context and display the selectable object in it;
+ - load the selectable object to the selection manager of the interactive context using *AIS_InteractiveContext::Load()* method. If the selection mode passed as a parameter to this method is not equal to -1, *ComputeSelection()* for this selection mode will be called;
+ - activate or deactivate the defined selection mode using *AIS_InteractiveContext::Activate()* or *AIS_InteractiveContext::Deactivate()* methods.
+
+After these steps, the selection manager of the created interactive context will contain the given object and its selection entities, and they will be involved in the detection procedure.
+
+The code snippet below illustrates the above steps. It also contains the code to start the detection procedure and parse the results of selection.
+
+~~~~~
+// Suppose there is an instance of class InteractiveBox from the previous sample.
+// It contains an implementation of method InteractiveBox::ComputeSelection() for selection
+// modes 0 (whole box must be selected) and 1 (edge of the box must be selectable)
+Handle(InteractiveBox) theBox;
+Handle(AIS_InteractiveContext) theContext;
+// To prevent automatic activation of the default selection mode
+theContext->SetAutoActivateSelection (false);
+theContext->Display (theBox, false);
+
+// Load a box to the selection manager without computation of any selection mode
+theContext->Load (theBox, -1, true);
+// Activate edge selection
+theContext->Activate (theBox, 1);
+
+// Run the detection mechanism for activated entities in the current mouse coordinates and in the current view.
+// Detected owners will be highlighted with context highlight color
+theContext->MoveTo (aXMousePos, aYMousePos, myView);
+// Select the detected owners
+theContext->Select();
+// Iterate through the selected owners
+for (theContext->InitSelected(); theContext->MoreSelected() && !aHasSelected; theContext->NextSelected())
+{
+ Handle(AIS_InteractiveObject) anIO = theContext->SelectedInteractive();
+}
+
+// deactivate all selection modes for aBox1
+theContext->Deactivate (aBox1);
+~~~~~
+
+It is also important to know, that there are 2 types of detection implemented for rectangular selection in OCCT:
+ - <b>inclusive</b> detection. In this case the sensitive primitive is considered detected only when all its points are included in the area defined by the selection rectangle;
+ - <b>overlap</b> detection. In this case the sensitive primitive is considered detected when it is partially overlapped by the selection rectangle.
-*Virtual functions *
+The standard OCCT selection mechanism uses inclusion detection by default. To change this, use the following code:
-Calculation of different presentations of an interactive object is done in the *Compute *functions inheriting from *PrsMgr_ PresentableObject::Compute *functions. They are automatically called by *PresentationManager* at a visualization or an update request.
+~~~~~
+// Assume there is a created interactive context
+const Handle(AIS_InteractiveContext) theContext;
+// Retrieve the current viewer selector
+const Handle(StdSelect_ViewerSelector3d)& aMainSelector = theContext->MainSelector();
+// Set the flag to allow overlap detection
+aMainSelector->AllowOverlapDetection (true);
+~~~~~
-If you are creating your own type of interactive object, you must implement the Compute function in one of the following ways:
+@section occt_visu_3 Application Interactive Services
+@subsection occt_visu_3_1 Introduction
- * **For 2D: **
-<h4>Example </h4>
+Application Interactive Services allow managing presentations and dynamic selection in a viewer in a simple and transparent manner.
+The central entity for management of visualization and selections is the **Interactive Context**. It is connected to the main viewer.
-void PackageName_ClassName::Compute
-(const Handle(PrsMgr_PresentationManager2d)&
-aPresentationManager,
- const Handle(Graphic2d_GraphicObject)& aGraphicObject,
- const Standard_Integer aMode = 0);
- * **For 3D: **
-<h4>Example </h4>
+Interactive context by default starts at **Neutral Point** with each selectable object picked as a whole, but the user might activate **Local Selection** for specific objects to make selectable parts of the objects.
+Local/global selection is managed by a list of selection modes activated for each displayed object with 0 (default selection mode) usually meaning Global (entire object) selection.
-void PackageName_ClassName::Compute
-(const Handle(PrsMgr_PresentationManager3d)&
-aPresentationManager,
- const Handle(Prs3d_Presentation)& aPresentation,
- const Standard_Integer aMode = 0);
+**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.
- * **For hidden line removal (HLR) mode in 3D (*): **
-<h4>Example </h4>
+An Interactive Object is a "virtual" entity, which can be presented and selected. An Interactive Object can have a certain number of specific graphic attributes, such as visualization mode, color and material.
+When an Interactive Object is visualized, the required graphic attributes are taken from its own **Drawer** (*Prs3d_Drawer*) if it has the required custom attributes or otherwise from the context drawer.
-void PackageName_ClassName::Compute
-(const Handle(Prs3d_Projector)& aProjector,
- const Handle(Prs3d_Presentation)& aPresentation);
+@figure{visualization_image017.png,"",360}
+It can be necessary to filter the entities to be selected. Consequently there are **Filter** entities, which allow refining the dynamic detection context. Some of these filters can be used only within at the Neutral Point, others only within Local Selection. It is possible to program custom filters and load them into the interactive context.
-*WARNING (*) *
-As its call is automatically ordered by a view, this function requires explanation; the view has two states: degenerate mode (normal mode) and non-degenerate mode (Hidden line mode). When the latter is active, the view looks for all presentations displayed in normal mode, which have been signaled as accepting hidden line mode. An internal mechanism allows us to call the interactive object’s own *Compute*, that is, projector, function. How do you declare that such and such a presentation will accept an *equivalent* in hidden line mode? By convention, it is the Interactive Object, which accepts or rejects the representation of hidden-line mode. You can make this declaration in one of two ways, either initially by using one of the values of the enumeration PrsMgr_TypeOfPresentation:
- * PrsMgr_TOP_AllView,
- * PrsMgr_TOP_ProjectorDependant
+@subsection occt_visu_3_2 Interactive objects
-or later on, by using the function:
- * * PrsMgr_PresentableObject::SetTypeOfPresentation
+Entities 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.
-@subsubsection occt_1621831385_81030860922 Important Specifics of AIS:
+@subsubsection occt_visu_3_2_1 Presentations
-There are four types of interactive object in AIS:
- * the *construction element* or Datum,
- * the Relation (dimensions and constraints)
- * the Object
- * the None type (when the object is of an unknown type).
+An interactive object can have as many presentations as its creator wants to give it.
+3D presentations are managed by **Presentation Manager** (*PrsMgr_PresentationManager*). As this is transparent in AIS, the user does not have to worry about it.
-Inside these categories, additional characterization is available by means of a signature (an index.) By default, the interactive object has a NONE type and a signature of 0 (equivalent to NONE.) If you want to give a particular type and signature to your interactive object, you must redefine two virtual functions:
+A presentation is identified by an index (*Display Mode*) and by the reference to the Presentation Manager, which it depends on.
+By convention, the default mode of representation for the Interactive Object has index 0.
- * AIS_InteractiveObject::Type
- * AIS_InteractiveObject::Signature.
-
+@figure{visualization_image018.png,"",360}
-<h4>WARNING </h4>
-Some signatures have already been used by *standard* objects delivered in AIS. (see the list of standard objects, Annex I.)
+Calculation of different presentations of an interactive object is done by the *Compute* functions inheriting from *PrsMgr_PresentableObject::Compute* functions. They are automatically called by *PresentationManager* at a visualization or an update request.
-As will be seen below, the interactive context can have a default mode of representation for the set of interactive objects. This mode may not be accepted by a given class of objects. Consequently, a virtual function allowing you to get information about this class must be implemented:
- * AIS_InteractiveObject::AcceptDisplayMode.
+If you are creating your own type of interactive object, you must implement the Compute function in one of the following ways:
-<h5>Services You Should Know </h5>
-Display Mode: An object can have its own display mode, which is different from that proposed by the interactive context. The functions to use are:
- * AIS_InteractiveContext::SetDisplayMode
- * AIS_InteractiveContext::UnsetDisplayMode.
+#### For 3D:
-Hilight Mode: At dynamic detection, the presentation echoed by the Interactive Context, is by default the presentation already on the screen. You can always specify the display mode used for highlighting purposes (so called highlight mode), which is valid no matter what the active representation of the object. It makes no difference whether this choice is temporary or definitive. To do this, you use the following functions:
- * AIS_InteractiveObject::SetHilightMode
- * AIS_InteractiveObject::UnSetHilightMode
+~~~~~
+void PackageName_ClassName::Compute (const Handle(PrsMgr_PresentationManager3d)& thePresentationManager,
+ const Handle(Prs3d_Presentation)& thePresentation,
+ const Standard_Integer theMode);
+~~~~~
-Note that the same presentation (and consequently the same highlight mode) is used for highlighting *detected* objects and for highlighting *selected* objects, the latter being drawn with a special *selection color *(refer to the section related to *Interactive Context* services).
+#### For hidden line removal (HLR) mode in 3D:
+~~~~~
+void PackageName_ClassName::Compute (const Handle(Prs3d_Projector)& theProjector,
+ const Handle(Prs3d_Presentation)& thePresentation);
+~~~~~
-An example: For a shape - whether it is visualized in wireframe presentation or with shading - you want to systematically highlight the wireframe presentation. Consequently, you set the highlight mode to *0 *in the constructor of the interactive object. You mustn’t forget to effect the implementation of this representation mode in the *Compute* functions.
+@subsubsection occt_visu_3_2_2 Hidden Line Removal
-Infinite Status: If you don’t want an object to be affected by a FitAll view, you must declare it infinite; you can cancel its *infinite* status in the same way.
- * AIS_InteractiveObject::SetInfiniteState
- * AIS_InteractiveObject::IsInfinite
-<h4>Example </h4>
+The view can have two states: the normal mode or the computed mode (Hidden Line Removal mode). When the latter is active, the view looks for all presentations displayed in the normal mode, which have been signalled as accepting HLR mode. An internal mechanism allows calling the interactive object's own *Compute*, that is projector function.
-Let’s take the case of a class called IShape, representing an interactive object
-myPk_IShape::myPK_IShape
-(const TopoDS_Shape& SH, PrsMgr_TypeOfPresentation aType):
+By convention, the Interactive Object accepts or rejects the representation of HLR mode. It is possible to make this declaration in one of two ways:
-AIS_InteractiveObject(aType), myShape(SH), myDrwr(new AIS_Drawer()) {
-SetHilightMode(0);
-}
-void myPk_IShape::Compute
-(const Handle(PrsMgr_PresentationManager3d) & PM, const Handle(Prs3d_Presentation)& P, const Standard_Integer TheMode)
-{
-switch (TheMode){
-
-case 0:
-StdPrs_WFDeflectionShape::Add (P,myShape,myDrwr);
-//algo for calculation of wireframe presentation break;
-
-case 1:
-StdPrs_ShadedShape::Add (P,myShape,myDrwr); //algo for calculation of shading presentation. break;
-}
-}
-void myPk_IsShape::Compute
-(const Handle(Prs3d_Projector)& Prj,
-const Handle(Prs3d_Presentation) P)
-{
-StdPrs_HLRPolyShape::Add(P,myShape,myDrwr);
-//Cas-cade hidden line mode calculation algorithm
-}
-
-
-
-@subsection occt_1621831385_8103086093 Selections
-@subsubsection occt_1621831385_81030860931 Conventions
-
-An interactive object can have an indefinite number of modes of selection, each representing a *decomposition* into sensitive primitives; each primitive has an Owner (*SelectMgr_EntityOwner*) which allows us to identify the exact entity which has been detected (see ANNEX II).
-
-The set of sensitive primitives, which correspond to a given mode, is stocked in a SELECTION (*SelectMgr_Selection*).
-
-Each Selection mode is identified by an index. By Convention, the default selection mode that allows us to grasp the Interactive object in its entirety is mode *0*.
-
-@subsubsection occt_1621831385_81030860932 Virtual functions
-
-The calculation of Selection primitives (or sensitive primitives) is done by the intermediary of a virtual function, *ComputeSelection*. This should be implemented for each type of interactive object on which you want to make different type selections using the following function:
-
- * AIS_ConnectedInteractive::ComputeSelection
-
-A detailed explanation of the mechanism and the manner of implementing this function has been given in ANNEX II.
-
-Moreover, just as the most frequently manipulated entity is TopoDS_Shape, the most used Interactive Object is AIS_Shape. You will see below that activation functions for standard selection modes are proposed in the Interactive context (selection by vertex, by edges etc.). To create new classes of interactive object with the same behavior as AIS_Shape - such as vertices and edges - you must redefine the virtual function:
-
- * AIS_ConnectedInteractive::AcceptShapeDecomposition.
-
-
-
-@subsubsection occt_1621831385_81030860933 Other Services
-You can change the default selection mode index of an Interactive Object. For instance, you can:
- * check to see if there is a selection mode
- * check the current selection mode
- * set a selection mode
- * unset a selection mode.
- The following functions are concerned:
-
- * AIS_InteractiveObject::HasSelectionMode
- * AIS_InteractiveObject::SelectionMode
- * AIS_InteractiveContext::SetSelectionMode
- * AIS_InteractiveContext::UnsetSelectionMode
-
-These functions are only of interest if you decide that the *0* mode adopted by convention will not do. In the same way, you can temporarily change the priority of certain interactive objects for selection of 0 mode. You could do this to make it easier to detect them graphically. You can:
- * check to see if there is a selection priority setting for the owner
- * check the current priority
- * set a priority
- * unset the priority.
-
-To do this, you use the following functions:
- * AIS_InteractiveObject::HasSelectionPriority
- * AIS_InteractiveObject::SelectionPriority
- * AIS_InteractiveObject::SetSelectionPriority
- * AIS_InteractiveObject::UnsetSelectionPriority
-
-
-
-@subsection occt_1621831385_8103086094 Graphic attributes of an interactive object
-
-Keep in mind the following points concerning graphic attributes:
- * Each interactive object can have its own visualization attributes.
- * 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
- * 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.)
- * In the *AIS_InteractiveObject* abstract class, several standard attributes have been privileged. These include: color, thickness of line, material, and transparency. Consequently, a certain number of virtual functions, which allow us to act on these attributes, have been proposed. Each new class of interactive object can redefine these functions in order to bring about the changes it should produce in the behavior of the class.
-
-
-@image html /user_guides/visualization/images/visualization_image019.jpg
-@image latex /user_guides/visualization/images/visualization_image019.jpg
-**Figure 13. Redefinition of virtual functions for changes in AIS_Point **
-
-@image html /user_guides/visualization/images/visualization_image020.jpg
-@image latex /user_guides/visualization/images/visualization_image020.jpg
-**Figure 14. **Redefinition** of virtual functions for changes in AIS_Shape.**
-
-The virtual functions concerned here allow you to provide settings for:
- * color
- * width
- * material
- * transparency
-
-The functions concerned are the following:
-
- * AIS_InteractiveObject::UnsetColor
- * AIS_InteractiveObject::SetWidth
- * AIS_InteractiveObject::UnsetWidth
- * AIS_InteractiveObject::SetMaterial (const Graphic3d_NameOfPhysicalMaterial & aName)
- * AIS_InteractiveObject::SetMaterial (const Graphic3d_MaterialAspect & aMat)
- * AIS_InteractiveObject::UnsetMaterial
- * AIS_InteractiveObject::SetTransparency
- * AIS_InteractiveObject::UnsetTransparency
-
-For other types of attribute, it is appropriate to change the Drawer of the object directly using:
-
- * AIS_InteractiveObject::SetAttributes
- * AIS_InteractiveObject::UnsetAttributes
-
-
-@subsubsection occt_1621831385_81030860941 Manipulation of Attributes
-
-Some of these functions may imply the recalculation of presentations of the object. It is important to know which ones. If an interactive object’s presentation mode is to be updated, a flag from *PrsMgr_PresentableObject* indicates this. The mode should be updated using the functions *Display* and *Redisplay* in *AIS_InteractiveContext*.
-
-@subsection occt_1621831385_8103086095 Complementary Services - Precautions
-
-@subsubsection occt_1621831385_81030860951 Changing an interactive object’s location
-
-When using complementary services for interactive objects, pay special attention to the following cases:
-Functions allowing us to temporarily *move* the representation and selection of Interactive Objects in a view without recalculation.
- * AIS_InteractiveContext::SetLocation
- * AIS_InteractiveContext::ResetLocation
- * AIS_InteractiveContext::HasLocation
- * AIS_InteractiveContext::Location
-
-How you link applicative entities to interactive objects.
-
-
-@subsubsection occt_1621831385_810308609552 Connecting an interactive object to an applicative entity
-
-Each Interactive Object has functions that allow us to attribute it an Owner in the form of a Transient.
- * AIS_InteractiveObject::SetOwner
- * AIS_InteractiveObject::HasOwner
- * AIS_InteractiveObject::Owner
-
-An interactive object can therefore be associated with an applicative entity or not, without this affecting its behavior.
-
-@subsubsection occt_1621831385_810308609553 Resolving coincident topology
-
-Due to the fact that the accuracy of three-dimensional graphics coordinates has a finite resolution the elements of topological objects can coincide producing the effect of *popping* some elements one over another.
-
-To avoid such kind of a problem when the elements of two or more InteractiveObjects are coincident you can apply the polygon offset. It is a sort of graphics computational offset, or depth buffer offset, that allows you to arrange elements (by modifying their depth value) without changing their coordinates. The graphical elements that accept this kind of offsets are solid polygons or displayed as boundary lines and points. The polygons could be displayed as lines or points by setting the appropriate interior style.
-
-The following method allows you to set up the polygon offsets:
- * void AIS_InteractiveObject::SetPolygonOffsets
-(const Standard_Integer aMode,
- const Standard_Real aFactor,
- const Standard_Real aUnits)
-The parameter aMode can contain various combinations of Aspect_PolygonOffsetMode enumeration elements. The enumeration has the following elements:
- * Aspect_POM_None
- * Aspect_POM_Off
- * Aspect_POM_Fill
- * Aspect_POM_Line
- * Aspect_POM_Point
- * Aspect_POM_All
-
-The combination of these elements defines the polygon display modes that will use the given offsets. You can switch off the polygon offsets by passing the Aspect_POM_Off. Passing Aspect_POM_None allows you to change the aFactor and aUnits values without changing the mode. If aMode is different from Aspect_POM_Off, the aFactor and aUnits arguments are used by the graphics renderer to calculate the depth offset value:
- offset = aFactor * m + aUnits * r,
- where m – maximum depth slope for the polygons currently being displayed, r – minimum depth resolution (implementation-specific)
-
-Negative offset values move polygons closer to the viewer while positive values shift polygons away.
-
-**WARNING**
-This method has a side effect – it creates its own shading aspect if not yet created, so it is better to set up the object shading aspect first.
-
-You can use the following functions to obtain the current settings for polygon offsets:
- * void AIS_InteractiveObject::PolygonOffsets
-(Standard_Integer &aMode,
- Standard_Real &aFactor,
- Standard_Real &aUnits)
- * Standard_Boolean
-AIS_InteractiveObject::HasPolygonOffsets()
-
-The same operation could be performed for the interactive object known by the AIS_InteractiveContext with the following methods:
- * void AIS_InteractiveContext::SetPolygonOffsets
-(const Handle(AIS_InteractiveObject) &anObj,
- const Standard_Integer aMode,
- const Standard_Real aFactor,
- const Standard_Real aUnits)
- * void AIS_InteractiveContext::PolygonOffsets
-(const Handle(AIS_InteractiveObject) &anObj,
- Standard_Integer &aMode,
- Standard_Real &aFactor,
- Standard_Real &aUnits)
- * Standard_Boolean AIS_InteractiveContext::HasPolygonOffsets
-(const Handle(AIS_InteractiveObject) &anObj)
-
-@subsection occt_1621831385_8103086096 The Interactive Context
-
-@subsubsection occt_1621831385_810308609661 Preliminary Rules
-
-The Interactive Context allows us to manage in a transparent way, the graphic and *selectable* behavior of interactive objects in one or more viewers. Most functions which allow us to modify the attributes of interactive objects, and which were presented in the preceding chapter, will be looked at again here.
-
-There is one essential rule to follow: the modification of an interactive object, which is already known by the Context, must be done using Context functions. You can only directly call the functions available for an interactive object if it has not been loaded into an Interactive Context.
-
-<h4>Example </h4>
-
-Handle (AIS_Shape) TheAISShape = new AIS_Shape (ashape); myIntContext-Display(TheAISShape);
-myIntContext-SetDisplayMode(TheAISShape ,1);
-myIntContext-SetColor(TheAISShape,Quantity_NOC_RED);
-
-//but you can write
-
-Handle (AIS_Shape) TheAISShape = new AIS_Shape (ashape); TheAISShape-SetColor(Quantity_NOC_RED);
-TheAISShape-SetDisplayMode(1);
-myIntContext-Display(TheAISShape);
-
-
-@subsubsection occt_1621831385_810308609662 Groups of functions
-
-You must distinguish two states in the Interactive Context:
-* No Open Local Context; which will be referred to as Neutral Point.
-* One or several open local contexts, each representing a temporary state of selection and presentation.
-
-Some functions can only be used in open Local Context; others in closed local context; others do not have the same behavior in one state as in the other.
-
-The Interactive Context is composed of a great many functions, which can be conveniently grouped according to theme:
- * management proper to the context
- * management in the local context
- * presentations and selection in open/closed context
- * selection strictly speaking
-
-
-@subsubsection occt_1621831385_810308609663 Management proper to the Interactive Context
-
-The Interactive Context is made up of a Principal Viewer and, optionally, a trash bin or *Collector* Viewer. It also has a group of adjustable settings allowing you to personalize the behavior of presentations and selections:
- * Default Drawer, containing all the color and line attributes which can be used by interactive objects, which do not have their own attributes.
- * Default Visualization Mode for interactive objects
-Default: mode 0
- * Highlight color of entities detected by mouse movement
-Default: Quantity_NOC_CYAN1
- * Preselection color
-Default: Quantity_NOC_GREEN
- * Selection color (when you click on a detected object)
-Default: Quantity_NOC_GRAY80
- * Sub-Intensity color
-Default: Quantity_NOC_GRAY40
-
-All of these settings can be modified by functions proper to the Context.
-
-When you change a graphic attribute pertaining to the Context (visualization mode, for example), all interactive objects, which do not have the corresponding appropriate attribute, are updated.
-<h4>Example </h4>
-
-//obj1, obj2: 2 interactive objects.
+* Initially by using one of the values of the enumeration *PrsMgr_TypeOfPresentation*:
+ * *PrsMgr_TOP_AllView*,
+ * *PrsMgr_TOP_ProjectorDependant*
-TheCtx-Display(obj1,Standard_False); // False = no update
-of viewer.
-TheCtx-Display(obj2,Standard_True); // True = Update of
-Viewer
-TheCtx-SetDisplayMode(obj1,3,Standard_False);
-TheCtx-SetDisplayMode(2);
-// obj2 is visualised in mode 2 (if it accepts this mode)
-// obj1 stays visualised in its mode 3.
+* Later by using the function *PrsMgr_PresentableObject::SetTypeOfPresentation*
-To the main Viewer, are associated a *PresentationManager3D* and a *Selector3D *which manage the presentation and selection of present interactive objects. The same is true of the optional Collector. As we shall see, this management is completely transparent for the user.
+*AIS_Shape* class is an example of an interactive object that supports HLR representation.
+The type of the HLR algorithm is stored in *Prs3d_Drawer* of the shape. It is a value of the *Prs3d_TypeOfHLR* enumeration and can be set to:
+ * *Prs3d_TOH_PolyAlgo* for a polygonal algorithm based on the shape's triangulation;
+ * *Prs3d_TOH_Algo* for an exact algorithm that works with the shape's real geometry;
+ * *Prs3d_TOH_NotSet* if the type of algorithm is not set for the given interactive object instance.
+The type of the HLR algorithm used for *AIS_Shape* can be changed by calling the *AIS_Shape::SetTypeOfHLR()* method.
+The current HLR algorithm type can be obtained using *AIS_Shape::TypeOfHLR()* method is to be used.
-@subsection occt_1621831385_8103086097 Management of Local Context
+These methods get the value from the drawer of *AIS_Shape*. If the HLR algorithm type in the *AIS_Drawer* is set to *Prs3d_TOH_NotSet*, the *AIS_Drawer* gets the value from the default drawer of *AIS_InteractiveContext*.
+So it is possible to change the default HLR algorithm used by all newly displayed interactive objects. The value of the HLR algorithm type stored in the context drawer can be *Prs3d_TOH_Algo* or *Prs3d_TOH_PolyAlgo*. The polygonal algorithm is the default one.
-@subsubsection occt_1621831385_810308609771 Rules and Conventions
+@subsubsection occt_visu_3_2_3 Presentation modes
- * Opening a local context allows you to prepare an environment for temporary presentations and selections, which will disappear once the local context is closed.
- * It is possible to open several local contexts, but only the last one will be active.
- * When you close a local context, the one before, which is still on the stack, reactivates. If none is left, you return to Neutral Point.
- * Each local context has an index created when the context opens. You should close the local context, which you have opened.
+There are four types of interactive objects in AIS:
+ * the "construction element" or Datum,
+ * the Relation (dimensions and constraints)
+ * the Object
+ * the None type (when the object is of an unknown type).
-@subsubsection occt_1621831385_810308609772 Important functionality
+Inside these categories, additional characterization is available by means of a signature (an index.) By default, the interactive object has a NONE type and a signature of 0 (equivalent to NONE). If you want to give a particular type and signature to your interactive object, you must redefine two virtual functions:
+ * *AIS_InteractiveObject::Type*
+ * *AIS_InteractiveObject::Signature*.
-The interactive object, which is used the most by applications, is *AIS_Shape*. Consequently, standard functions are available which allow you to easily prepare selection operations on the constituent elements of shapes (selection of vertices, edges, faces etc) in an open local context. The selection modes specific to *Shape* type objects are called **Standard Activation Mode**. These modes are only taken into account in open local context and only act on interactive objects which have redefined the virtual function *AcceptShapeDecomposition() *so that it returns *TRUE*.
- * 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.
- * The state of a temporary interactive object in a local context can only be modified while another local context is open (except for one special case - see III.4.2)
+**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").
-<h4>WARNING </h4>
-The specific modes of selection only concern the interactive objects, which are present in the Main Viewer. In the Collector, you can only locate interactive objects, which answer positively to the positioned filters when a local context is open. Under no circumstances are they decomposed in standard mode etc.
+The interactive context can have a default mode of representation for the set of interactive objects. This mode may not be accepted by a given class of objects.
+Consequently, to get information about this class it is necessary to use virtual function *AIS_InteractiveObject::AcceptDisplayMode*.
-@subsubsection occt_1621831385_810308609773 Use
-Opening and closing a local context are easy to put into operation:
+#### Display Mode
- * AIS_InteractiveContext::OpenLocalContext
+The functions *AIS_InteractiveContext::SetDisplayMode* and *AIS_InteractiveContext::UnsetDisplayMode* allow setting a custom display mode for an objects, which can be different from that proposed by the interactive context.
-The options available allow you to control what you want to do:
- * *UseDisplayedObjects*: allows you to load or not load the interactive objects visualized at Neutral Point in the local context, which you open. If* FALSE*, the local context is empty after being opened. If *TRUE*, the objects at Neutral Point are modified by their default selection mode.
- * *AllowShapeDecomposition*: AIS_Shape allows or prevents decomposition in standard shape location mode of objects at Neutral Point, which are type-*privileged* (see selection chapter). This Flag is only taken into account when *UseDisplayedObjects* is *TRUE*.
- * *AcceptEraseOfObjects*: authorises other local contexts to erase the interactive objects present in this context. This option is rarely used. The last option has no current use.
+#### Highlight Mode
-This function returns the index of the created local context. It should be kept and used when the context is closed.
+At dynamic detection, the presentation echoed by the Interactive Context, is by default the presentation already on the screen.
-To load objects visualized at Neutral Point into a local context or remove them from one:
- * AIS_InteractiveContext::UseDisplayedObjects
- * AIS_InteractiveContext::NotUseDisplayedObjects
+The functions *AIS_InteractiveObject::SetHilightMode* and *AIS_InteractiveObject::UnSetHilightMode* allow specifying the display mode used for highlighting (so called highlight mode), which is valid independently from the active representation of the object. It makes no difference whether this choice is temporary or definitive.
-Closing Local Contexts is done by:
- * AIS_InteractiveContext::CloseLocalContext
- * AIS_InteractiveContext::CloseAllContexts
+Note that the same presentation (and consequently the same highlight mode) is used for highlighting *detected* objects and for highlighting *selected* objects, the latter being drawn with a special *selection color* (refer to the section related to *Interactive Context* services).
-*WARNING *
+For example, you want to systematically highlight the wireframe presentation of a shape - non regarding if it is visualized in wireframe presentation or with shading. Thus, you set the highlight mode to *0* in the constructor of the interactive object. Do not forget to implement this representation mode in the *Compute* functions.
-When the index isn’t specified in the first function, the current Context is closed. This option can be dangerous, as other Interactive Functions can open local contexts without necessarily warning the user. For greater security, you have to close the context with the index given on opening.
+#### Infinite Status
-To get the index of the current context, use the following function:
+If 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.
- * AIS_InteractiveContext::IndexOfCurrentLocal
+Let us take for example the class called *IShape* representing an interactive object:
-The second function allows you to close all open local contexts at one go. In this case, you find yourself directly at Neutral Point.
+~~~~~
+myPk_IShape::myPK_IShape (const TopoDS_Shape& theShape, PrsMgr_TypeOfPresentation theType)
+: AIS_InteractiveObject (theType), myShape (theShape) { SetHilightMode (0); }
-When you close a local context, all temporary interactive objects are erased (deleted), all selection modes concerning the context are cancelled, and all content filters are emptied.
+void myPk_IShape::Compute (const Handle(PrsMgr_PresentationManager3d)& thePrsMgr,
+ const Handle(Prs3d_Presentation)& thePrs,
+ const Standard_Integer theMode)
+{
+ switch (theMode)
+ {
+ // algo for calculation of wireframe presentation
+ case 0: StdPrs_WFDeflectionShape::Add (thePrs, myShape, myDrawer); return;
+ // algo for calculation of shading presentation
+ case 1: StdPrs_ShadedShape::Add (thePrs, myShape, myDrawer); return;
+ }
+}
+void myPk_IShape::Compute (const Handle(Prs3d_Projector)& theProjector,
+ const Handle(Prs3d_Presentation)& thePrs)
+{
+ // Hidden line mode calculation algorithm
+ StdPrs_HLRPolyShape::Add (thePrs, myShape, myDrawer, theProjector);
+}
+~~~~~
+@subsubsection occt_visu_3_2_4 Selection
-@subsubsection occt_1621831385_810308609774 Management of Presentations and Selections
-
-You must distinguish between the Neutral Point and the Open Local Context states. Although the majority of visualization functions can be used in both situations, their behavior is different:
-
-@subsubsection occt_1621831385_810308609775 Presentation in Neutral Point
-
-Neutral Point should be used to visualize the interactive objects, which represent and select an applicative entity. Visualization and Erasing orders are straightforward:
-
- * AIS_InteractiveContext::Display
-(const Handle(AIS_InteractiveObject)& anIobj,
- const Standard_Boolean updateviewer=Standard_True);
-
- * AIS_InteractiveContext::Display
-(const Handle(AIS_InteractiveObject)& anIobj,
- const Standard_Integer amode,
- const Standard_Integer aSelectionMode,
- const Standard_Boolean
-updateviewer = Standard_True,
- const Standard_Boolean
-allowdecomposition = Standard_True);
-
- * AIS_InteractiveContext::Erase
- * AIS_InteractiveContext::EraseMode
- * AIS_InteractiveContext::ClearPrs
- * AIS_InteractiveContext::Redisplay
- * AIS_InteractiveContext::Remove
- * AIS_InteractiveContext::EraseAll
- * AIS_InteractiveContext::Hilight
- * AIS_InteractiveContext::HilightWithColor
-
-@subsubsection occt_1621831385_810308609776 Important Remarks:
-
-Bear in mind the following points:
- * It is recommended to display and erase interactive objects when no local context is opened, and open a local context for local selection only.
- * 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).
- * 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.
- * The second **Display** function should only be used in Neutral Point to visualize a supplementary mode for the object, which you can erase by EraseMode (...). You activate the selection mode. This is passed as an argument. By convention, if you do not want to activate a selection mode, you must set the *SelectionMode *argument to the value of -1. This function is especially interesting in open local context, as we will see below.
- * In Neutral Point, it is unadvisable to activate other selection modes than the default selection one. It is preferable to open a local context in order to activate particular selection modes.
- * 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.
- * **Erase**() with *putInCollector* = Standard_True** might be slow as it re-computes the objects presentation in the Collector. Set putInCollector to Standard_False if you simply want to hide the object’s presentation temporarily.
- * Modifications of visualization attributes and graphic behavior is effected through a set of functions similar to those which are available for the interactive object (color, thickness of line, material, transparency, locations etc.) The context then manages immediate and deferred updates.
- * Call **Remove**() method of *InteractiveContext* as soon as the interactive object is no longer needed and you want to destroy it.. Otherwise, references to *InteractiveObject* are kept by *InteractiveContext*, and the *Object* is not destroyed that results in memory leaks. In general, if some interactive object’s presentation can be computed quickly, it is recommended to **Remove**() it instead of **Erase**()-ing.
-
-@subsubsection occt_1621831385_810308609777 Presentation in Local Context
-
-In open local context, the Display functions presented above apply as well.
-
-<h4>WARNING </h4>
-The function, AIS_InteractiveObject::Display, automatically activates the object’s default selection mode. When you only want to visualize an Interactive Object in open Context, you must call the second function:
-
-AIS_InteractiveContext::Display.
-
-You can activate or deactivate specific selection modes in local open context in several different ways:
-Use the Display functions with the appropriate modes
-Activate standard mode:
-
- * AIS_InteractiveContext::ActivateStandardMode
-only if a local Context is opened
-
- * AIS_InteractiveContext::DeactivateStandardMode
-
- * AIS_InteractiveContext::ActivatedStandardModes
-
- * AIS_InteractiveContext::SetShapeDecomposition
-
-This has the effect of activating the corresponding selection mode for all objects in Local Context, which accept decomposition into sub-shapes. Every new Object which has been loaded into the interactive context and which answers these decomposition criteria is automatically activated according to these modes.
-
-<h4>WARNING </h4>
-If you have opened a local context by loading an object with the default options (AllowShapeDecomposition = Standard_True), all objects of the *Shape* type are also activated with the same modes. You can act on the state of these *Standard* objects by using SetShapeDecomposition(Status).
-
-Load an interactive object by the following function:
+An interactive object can have an indefinite number of selection modes, each representing a "decomposition" into sensitive primitives. Each primitive has an **Owner** (*SelectMgr_EntityOwner*) which allows identifying the exact interactive object or shape which has been detected (see @ref occt_visu_2_2 "Selection" chapter).
- * AIS_InteractiveContext::Load.
+The set of sensitive primitives, which correspond to a given mode, is stocked in a **Selection** (*SelectMgr_Selection*).
-This function allows you to load an Interactive Object whether it is visualized or not with a given selection mode, and/or with the desired decomposition option. If *AllowDecomp=TRUE* and obviously, if the interactive object is of the *Shape* type, these *standard* selection modes will be automatically activated as a function of the modes present in the Local Context.
+Each selection mode is identified by an index. By convention, the default selection mode that allows us to grasp the interactive object in its entirety is mode *0*. However, it can be modified in the custom interactive objects using method *SelectMgr_SelectableObject::setGlobalSelMode()*.
-Directly activate/deactivate selection modes on an object:
+The calculation of selection primitives (or sensitive entities) is done in a virtual function *ComputeSelection*. It should be implemented for each type of interactive object that is assumed to have different selection modes using the function *AIS_InteractiveObject::ComputeSelection*.
+A detailed explanation of the mechanism and the manner of implementing this function has been given in @ref occt_visu_2_2 "Selection" chapter.
- * AIS_InteractiveContext::Activate
- * AIS_InteractiveContext::Deactivate.
+There are some examples of selection mode calculation for the most widely used interactive object in OCCT -- *AIS_Shape* (selection by vertex, by edges, etc). To create new classes of interactive objects with the same selection behavior as *AIS_Shape* -- such as vertices and edges -- you must redefine the virtual function *AIS_InteractiveObject::AcceptShapeDecomposition*.
+@subsubsection occt_visu_3_2_5 Graphic attributes
+Graphic attributes manager, or *Prs3d_Drawer*, stores graphic attributes for specific interactive objects and for interactive objects controlled by interactive context.
+Initially, all drawer attributes are filled out with the predefined values which will define the default 3D object appearance.
+When 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.
+Keep in mind the following points concerning graphic attributes:
+ * Each interactive object can have its own visualization attributes.
+ * 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.)
+ * 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.
+@figure{visualization_image020.svg,"Redefinition of virtual functions for changes in AIS_Shape and AIS_TextLabel.",360}
+The following virtual functions provide settings for color, width, material and transparency:
+ * *AIS_InteractiveObject::UnsetColor*
+ * *AIS_InteractiveObject::SetWidth*
+ * *AIS_InteractiveObject::UnsetWidth*
+ * *AIS_InteractiveObject::SetMaterial*
+ * *AIS_InteractiveObject::UnsetMaterial*
+ * *AIS_InteractiveObject::SetTransparency*
+ * *AIS_InteractiveObject::UnsetTransparency*
+These methods can be used as a shortcut assigning properties in common way, but result might be not available.
+Some interactive objects might not implement these methods at all or implement only a sub-set of them.
+Direct modification of *Prs3d_Drawer* properties returned by *AIS_InteractiveObject::Attributes* can be used for more precise and predictable configuration.
-@subsubsection occt_1621831385_810308609778 Use of Filters
-
-When Interactive objects have been *prepared* in local context, you can add rejection filters. The root class of objects is *SelectMgr_Filter*. The principle behind it is straightforward: a filter tests to see whether the owners (*SelectMgr_EntityOwner*) detected in mouse position by the Local context selector answer *OK*. If so, it is kept; if not, it is rejected.
-
-You can therefore create your own class of filter objects by implementing the deferred function *IsOk()*:
-<h4>Example </h4>
-
-class MyFilter : public SelectMgr_Filter {
-};
-virtual Standard_Boolean MyFilter::IsOk
-(const Handle(SelectMgr_EntityOwner)& anObj) const = 0;
-
-
-In *SelectMgr*, there are also Composition filters (AND Filters, OR Filters), which allow you to combine several filters. In InteractiveContext , all filters that you add are stocked in an OR filter (which answers *OK* if at least one filter answers *OK*).
-
-There are Standard filters, which have already been implemented in several packages:
-
- * StdSelect_EdgeFilter
-Filters acting on edges such as lines and circles
- * StdSelect_FaceFilter
-Filters acting on faces such as planes, cylinders and spheres
- * StdSelect_ShapeTypeFilter
-Filters shape types such as compounds, solids, shells and wires
- * AIS_TypeFilter
-Acts on types of interactive objects
- * AIS_SignatureFilter
-Acts on types and signatures of interactive objects
- * AIS_AttributeFilter
-Acts on attributes of Interactive Objects such as color and width
-
-Because there are specific behaviors on shapes, each new Filter class must, if necessary, redefine a function, which allows a Local Context to know if it acts on specific types of sub-shapes:
-
- * AIS_LocalContext::ActsOn.
-
-By default, this function answers *FALSE*.
-
-*WARNING *
-Only type filters are activated in Neutral Point. This is to make it possible to identify a specific type of visualized object. For filters to come into play, one or more object selection modes must be activated.
-
-There are several functions to manipulate filters:
-
- * AIS_InteractiveContext::AddFilter
-
-to add a filter passed as an argument.
-
- * AIS_InteractiveContext::RemoveFilter
-
-to remove a filter passed as an argument.
-
- * AIS_InteractiveContext::RemoveFilters
-
-to remove all filters present.
-
- * AIS_InteractiveContext::Filters
-
-to get the list of filters active in a local context.
-<h4>Example </h4>
-
-myContext-OpenLocalContext(Standard_False);
-// no object in neutral point is loaded
-
-myContext-ActivateStandardMode(TopAbs_Face);
-//activates decomposition of shapes into faces.
-Handle (AIS_Shape) myAIShape = new AIS_Shape ( ATopoShape);
-
-myContext-Display(myAIShape,1,-1,Standard_True,Standard_True); //shading visualization mode, no specific mode, authorization for //decomposition into sub-shapes. At this Stage, myAIShape is decomposed into faces...
-
-Handle(StdSelect_FaceFilter) Fil1= new
-StdSelect_FaceFilter(StdSelect_Revol);
-Handle(StdSelect_FaceFilter) Fil2= new
- StdSelect_FaceFilter(StdSelect_Plane);
-
-myContext-AddFilter(Fil1); myContext-AddFilter(Fil2); //only faces of revolution or planar faces will be selected
- *
-myContext-MoveTo( xpix,ypix,Vue);
-// detects of mouse position
-
-
-@subsubsection occt_1621831385_810308609779 Selection Strictly Speaking.
-Dynamic detection and selection are put into effect in a straightforward way. There are only a few conventions and functions to be familiar with. The functions are the same in neutral point and in open local context:
-
- * AIS_InteractiveContext::MoveTo
-passes mouse position to Interactive Context selectors
- * 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
- * AIS_InteractiveContext::ShiftSelect
-if the object detected at the last move was not already selected , it is added to the list of those selected. If not, it is withdrawn. Nothing happens if you click on an empty area.
- * AIS_InteractiveContext::Select
-selects everything found in the surrounding area
- * AIS_InteractiveContext::ShiftSelect
-selects what was not previously in the list of selected, deselects those already present.
-
-Highlighting of detected and selected entities is automatically managed by the Interactive Context, whether you are in neutral point or Local Context. The Highlight colors are those dealt with above. You can nonetheless disconnect this automatic mode if you want to manage this part yourself:
-
- * AIS_InteractiveContext::SetAutomaticHilight
- * AIS_InteractiveContext::AutomaticHilight
-
-
-If there is no open local context, the objects selected are called CURRENT OBJECTS; SELECTED OBJECTS if there is one. Iterators allow entities to be recovered in either case. A set of functions allows you to manipulate the objects, which have been placed in these different lists.
-
-*WARNING *
-When a Local Context is open, you can select entities other than interactive objects (vertices, edges etc.) from decompositions in standard modes, or from activation in specific modes on specific interactive objects. Only interactive objects are stocked in the list of selected objects. You can question the Interactive context by moving the mouse. The following functions will allow you to:
- * tell whether something has been detected
- * tell whether it is a shape
- * get the shape if the detected entity is one
- * get the interactive object if the detected entity is one.
-
-The following functions are concerned:
- * AIS_InteractiveContext::HasDetected
- * AIS_InteractiveContext::HasDetectedShape
- * AIS_InteractiveContext::DetectedShape
- * AIS_InteractiveContext::DetectedInteractive
-
-After using the Select and ShiftSelect functions in Neutral Point, you can explore the list of selections, referred to as current objects in this context. You can:
- * initiate a scan of this list
- * extend the scan
- * resume the scan
- * get the name of the current object detected in the scan.
-
-The following functions are concerned:
- * AIS_InteractiveContext::InitCurrent
- * AIS_InteractiveContext::MoreCurrent
- * AIS_InteractiveContext::NextCurrent
- * AIS_InteractiveContext::Current
-
-You can:
- * get the first current interactive object
- * highlight current objects
- * remove highlight from current objects
- * empty the list of current objects in order to update it
- * find the current object.
-
-The following functions are concerned:
- * AIS_InteractiveContext::FirstCurrentObject
- * AIS_InteractiveContext::HilightCurrents
- * AIS_InteractiveContext::UnhilightCurrents
- * AIS_InteractiveContext::ClearCurrents
- * AIS_InteractiveContext::IsCurrent.
-
-In Local Context, you can explore the list of selected objects available. You can:
- * initiate,
- * extend,
- * resume a scan, and then
- * get the name of the selected object.
-
-The following functions are concerned:
-
- * AIS_InteractiveContext::InitSelected
- * AIS_InteractiveContext::MoreSelected
- * AIS_InteractiveContext::NextSelected
- * AIS_InteractiveContext::SelectedShape.
-
-You can:
- * check to see if you have a selected shape, and if not,
- * get the picked interactive object,
- * check to see if the applicative object has an owner from Interactive attributed to it
- * get the owner of the detected applicative entity
- * get the name of the selected object.
-
-The following functions are concerned:
-
- * AIS_InteractiveContext::HasSelectedShape
- * AIS_InteractiveContext::Interactive
- * AIS_InteractiveContext::HasApplicative
- * AIS_InteractiveContext::Applicative
- * AIS_InteractiveContext::IsSelected.
-
-<h4>Example </h4>
-
-
-myAISCtx-InitSelected();
-while (myAISCtx-MoreSelected())
-{
-if (myAISCtx-HasSelectedShape)
-{
-TopoDS_Shape ashape = myAISCtx-SelectedShape();
-// to be able to use the picked shape
- }
-else
-{
-Handle_AIS_InteractiveObject aniobj = myAISCtx-Interactive();
-// to be able to use the picked interactive object
-}
-myAISCtx-NextSelected(); }
-
-
-@subsubsection occt_1621831385_8103086097710 Remarks:
-
-In Local Context and in the iteration loop, which allows you to recover selected entities, you have to ask whether you have selected a shape or an interactive object before you can recover the entity. If you have selected a Shape from TopoDS on decomposition in standard mode, the *Interactive ()* function returns the interactive object, which provided the selected shape. Other functions allow you to manipulate the content of Selected or Current Objects:
- * erase selected objects
- * display them,
- * put them in the list of selections
-
-The following functions are concerned:
-
- * AIS_InteractiveContext::EraseSelected
- * AIS_InteractiveContext::DisplaySelected
- * AIS_InteractiveContext::SetSelected
-
-
-You can also:
-
- * take the list of selected objects from a local context and put it into the list of current objects in Neutral Point,
- * add or remove an object from the list of selected entities,
- * highlight and
- * remove highlighting from a selected object
- * empty the list of selected objects.
-
-The following functions are concerned:
-
- * AIS_InteractiveContext::SetSelectedCurrent
- * AIS_InteractiveContext::AddOrRemoveSelected
- * AIS_InteractiveContext::HilightSelected
- * AIS_InteractiveContext::UnhilightSelected
- * AIS_InteractiveContext::ClearSelected
-
-You can highlight and remove highlighting from a current object, and empty the list of current objects.
-
- * AIS_InteractiveContext::HilightCurrents
- * AIS_InteractiveContext::UnhilightCurrents
- * AIS_InteractiveContext::ClearCurrents
-
-When you are in open Local Context, you may be lead to keep *temporary* interactive objects. This is possible using the following functions:
-
- * AIS_InteractiveContext::KeepTemporary
- * AIS_InteractiveContext::SetSelectedCurrent
-
-The first function transfers the characteristics of the interactive object seen in its local context (visualization mode etc.) to the neutral point. When the local context is closed, the object does not disappear. The second allows the selected object to become the current object when you close the local context.
-You can also want to modify in a general way the state of the local context before continuing a selection (emptying objects, removing filters, standard activation modes). To do that, you must use the following function:
-
- * AIS_InteractiveContext::ClearLocalContext
-
-@subsubsection occt_1621831385_8103086097711 Advice on Using Local Contexts
-
-The possiblities of use for local contexts are numerous depending on the type of operation that you want to perform:
- * working on all visualized interactive objects,
- * working on only a few objects,
- * working on a single object.
-
-1. When you want to work on one type of entity, you should open a local context with the option UseDisplayedObjects set to FALSE. Some functions which allow you to recover the visualized interactive objects, which have a given Type, and Signature from the *Neutral Point* are:
-
-AIS_InteractiveContext::DisplayedObjects
-(AIS_ListOfInteractive& aListOfIO) const;
-
-AIS_InteractiveContext::DisplayedObjects
-(const AIS_KindOfInteractive WhichKind,
- const Standard_Integer WhichSignature,
-AIS_ListOfInteractive& aListOfIO) const;
-
-At this stage, you only have to load the functions Load, Activate, and so on.
-
-2. When you open a Local Context with default options, you must keep the following points in mind:
-
-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.
-
-The Shape Type Interactive Objects are automatically decomposed into sub-shapes when standard activation modes are launched.
-
-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.
-
-The stages could be the following:
-1. Open a Local Context with the right options;
-2. Load/Visualize the required complementary objects with the desired activation modes.
-3. Activate Standard modes if necessary
-4. Create its filters and add them to the Local Context
-5. Detect/Select/recover the desired entities
-6. Close the Local Context with the adequate index.
-
-It is useful to create an INTERACTIVE EDITOR, to which you pass the Interactive Context. This will take care of setting up the different contexts of selection/presentation according to the operation, which you want to perform.
-<h4>Example </h4>
-
-
-You have visualized several types of interactive objects: *AIS_Points*, *AIS_Axes*, *AIS_Trihedrons*, and *AIS_Shapes*.
-
-For your applicative function, you need an axis to create a revolved object. You could obtain this axis by identifying:
- * an axis which is already visualized,
- * 2 points,
- * a rectilinear edge on the shapes which are present,
- * a cylindrical face on the shapes (You will take the axis of this face)
-
-myIHMEditor::myIHMEditor
-(const Handle(AIS_InteractiveContext)& Ctx,
- ....) :
- myCtx(Ctx),
-...
-
-{
-}
-
-myIHMEditor::PrepareContext()
-{
-myIndex =myCtx-OpenLocalContext();
-
-//the filters
-
-Handle(AIS_SignatureFilter) F1 = new
- AIS_SignatureFilter(AIS_KOI_Datum,AIS_SD_Point);
-//filter on the points
-
-Handle(AIS_SignatureFilter) F2 = new
-AIS_SignatureFilter(AIS_KOI_Datum,AIS_SD_Axis);
-//filters on the axes.
-
-Handle(StdSelect_FaceFilter) F3 = new
- StdSelect_FaceFilter(AIS_Cylinder);
-//cylindrical face filters
-
-//...
-
-// activation of standard modes on the shapes..
-myCtx-ActivateStandardMode(TopAbs_FACE);
-myCtx-ActivateStandardMode(TopAbs_VERTEX);
-myCTX-Add(F1);
-myCTX-Add(F2);
-myCTX-Add(F3);
-
-// at this point, you can call the selection/detection function
-}
-
-void myIHMEditor::MoveTo(xpix,ypix,Vue)
-
-{ myCTX-MoveTo(xpix,ypix,vue); // the highlight of what is detected is automatic. }
-Standard_Boolean myIHMEditor::Select() { // returns true if you should continue the selection
-myCTX-Select(); myCTX-InitSelected(); if(myCTX-MoreSelected())
- { if(myCTX-HasSelectedShape())
-{ const TopoDS_Shape& sh = myCTX-SelectedShape();
-if( vertex){
-if(myFirstV...)
-{
-//if it’s the first vertex, you stock it, then you deactivate the faces and only keep the filter on the points:
-mypoint1 = ....;
-myCtx-RemoveFilters();
-myCTX-DeactivateStandardMode(TopAbs_FACE);
-myCtx-Add(F1);
-// the filter on the AIS_Points
-myFirstV = Standard_False;
-return Standard_True;
- } else {
- mypoint2 =...;
-// construction of the axis return Standard_False;
-}
- }
- else
- {
-//it is a cylindrical face : you recover the axis; visualize it; and stock it.
-return Standard_False;
-}
- }
-// it is not a shape but is no doubt a point.
-else
-{
-Handle(AIS_InteractiveObject)
-SelObj = myCTX-SelectedInteractive();
-if(SelObj-Type()==AIS_KOI_Datum)
-{
-if(SelObj-Signature()==1)
-{
-if (firstPoint)
-{
-mypoint1 =...
-return Standard_True;
-}
-else
-{
-mypoint2 = ...;
-//construction of the axis, visualization, stocking
-return Standard_False;
-}
-}
-
-else
-{
-// you have selected an axis; stock the axis
-return Standard_False;
-}
-}
-}
-}
-}
-@subsection occt_1621831385_810308609111 ANNEX I: Standard Interactive Object Classes in AIS DATUMS:
-
-AIS_Point AIS_Axis AIS_Line AIS_Circle AIS_Plane AIS_Trihedron : 4 selection modes
- * mode 0 : selection of a trihedron
- * mode 1 : selection of the origin of the trihedron
- * mode 2 : selection of the axes
- * mode 3 : selection of the planes XOY, YOZ, XOZ
-
-when you activate one of modes 1 2 3 4 , you pick AIS objects of type:
- * AIS_Point
- * AIS_Axis (and information on the type of axis)
- * AIS_Plane (and information on the type of plane).
-
-AIS_PlaneTrihedron offers 3 selection modes:
- * mode 0 : selection of the whole trihedron
- * mode 1 : selection of the origin of the trihedron
- * mode 2 : selection of the axes - same remarks as for the Trihedron.
-
-<h4>Warning </h4>
-For the presentation of planes and trihedra, the default unit of length is millimeter, and the default value for the representation of axes is 100. If you modify these dimensions, you must temporarily recover the object DRAWER. From inside it, take the Aspects in which the values for length are stocked (PlaneAspect for the plane, FirstAxisAspect for trihedra), and change these values inside these Aspects. Finally, recalculate the presentation.
-
-@subsubsection occt_1621831385_8103086092222 OBJECTS
-AIS_Shape : 3 visualization modes :
- * mode 0 : Line (default mode)
- * mode 1 : Shading (depending on the type of shape)
- * mode 2 : Bounding Box
-
-7 maximum selection modes, depending on the complexity of the shape :
- * * mode 0 : selection of the AIS_Shape
- * * mode 1 : selection of the vertices
- * * mode 2 : selection of the edges
- * * mode 3 : selection of the wires
- * * mode 4 : selection of the faces
- * * mode 5 : selection of the shells
- * * mode 6 : selection of the constituent solids.
-
-AIS_Triangulation: Simple interactive object for displaying triangular mesh contained in Poly_Triangulation container.
-
-AIS_ConnectedInteractive: Interactive Object connecting to another interactive object reference, and located elsewhere in the viewer makes it possible not to calculate presentation and selection, but to deduce them from your object reference.
-
-AIS_ConnectedShape: Object connected to interactive objects having a shape; this class has the same decompositions as AIS_Shape. What’s more, it allows a presentation of hidden parts, which are calculated automatically from the shape of its reference.
-
-AIS_MultipleConnectedInteractive: Object connected to a list of interactive objects (which can also be Connected objects. It does not require memory hungry calculations of presentation)
-
-AIS_MultipleConnectedShape: Interactive Object connected to a list of interactive objects having a Shape (AIS_Shape, AIS_ConnectedShape, AIS_MultipleConnectedShape). The presentation of hidden parts is calculated automatically.
-
-AIS_TexturedShape: Interactive Object that supports texture mapping. It is constructed as a usual AIS_Shape, but has additional methods that allow to map a texture on it.
-
-MeshVS_Mesh: Interactive Object that represents meshes, it has a data source that provides geometrical information (nodes, elements) and can be built up from the source data with a custom presentation builder.
-
-@subsubsection occt_1621831385_8103086093333 RELATIONS
-The list is not exhaustive.
-AIS_ConcentricRelation
-AIS_FixRelation
-AIS_IdenticRelation
-AIS_ParallelRelation
-AIS_PerpendicularRelation
-AIS_Relation
-AIS_SymmetricRelation
-AIS_TangentRelation
-
-@subsubsection occt_1621831385_810308609444 DIMENSIONS
-AIS_AngleDimension
-AIS_Chamf2dDimension
-AIS_Chamf3dDimension
-AIS_DiameterDimension
-AIS_DimensionOwner
-AIS_LengthDimension
-AIS_OffsetDimension
-AIS_RadiusDimension
-
-@subsubsection occt_1621831385_810308609555 MeshVS_Mesh
-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.
-However, the *DataSource* does not provide any information on attributes, for example nodal colors, but you can apply them in a special way – by choosing the appropriate presentation builder.
-The presentations of MeshVS_Mesh are built with the presentation builders (*MeshVS_PrsBuilder*). You can choose between the builders to represent the object in a different way. Moreover, you can redefine the base builder class and provide your own presentation builder.
-You can add/remove builders using the following methods:
- * MeshVS_Mesh::AddBuilder
- (const Handle (MeshVS_PrsBuilder) &Builder,
- Standard_Boolean TreatAsHilighter)
- * MeshVS_Mesh::RemoveBuilder (const Standard_Integer Index)
- * MeshVS_Mesh::RemoveBuilderById
- (const Standard_Integer Id)
-
-There is a set of reserved display and highlighting mode flags for MeshVS_Mesh. Mode value is a number of bits that allows you to select additional display parameters and combine the following mode flags:
- * MeshVS_DMF_WireFrame
- * MeshVS_DMF_Shading
- * MeshVS_DMF_Shrink
-base modes: display mesh in wireframe, shading, shrink modes.
-
- * MeshVS_DMF_VectorDataPrs
- * MeshVS_DMF_NodalColorDataPrs
- * MeshVS_DMF_ElementalColorDataPrs
- * MeshVS_DMF_TextDataPrs
- * MeshVS_DMF_EntitiesWithData
-represent different kinds of data
-
- * MeshVS_DMF_DeformedPrsWireFrame
- * MeshVS_DMF_DeformedPrsShading
- * MeshVS_DMF_DeformedPrsShrink
-display deformed mesh in wireframe, shading or shrink modes
-
- * MeshVS_DMF_SelectionPrs
- * MeshVS_DMF_HilightPrs
-selection and hilighting
-
- * MeshVS_DMF_User
-user-defined mode
-
-These values will be used by the presentation builder.
-There is also a set of selection modes flags that can be grouped in a combination of bits:
- * MeshVS_SMF_0D
- * MeshVS_SMF_Link
- * MeshVS_SMF_Face
- * MeshVS_SMF_Volume
- * MeshVS_SMF_Element
-Element: 0D, Link, Face and Volume grouped as a bit mask
-
- * MeshVS_SMF_Node
- * MeshVS_SMF_All
-All: Element and Node grouped as a bit mask
-
- * MeshVS_SMF_Mesh
- * MeshVS_SMF_Group
-
-Such an object, for example, can be used for displaying the object, stored in the STL file format:
-<h4>Example </h4>
-
-**// read the data and create a data source**
-Handle (StlMesh_Mesh) aSTLMesh = RWStl::ReadFile (aFileName);
-Handle (XSDRAWSTLVRML_DataSource) aDataSource =
- new XSDRAWSTLVRML_DataSource (aSTLMesh);
-
-**// create mesh**
-Handle (MeshVS_Mesh) aMesh = new MeshVS();
-aMesh-SetDataSource (aDataSource);
-
-**// use default presentation builder**
-Handle (MeshVS_MeshPrsBuilder) aBuilder =
- new MeshVS_MeshPrsBuilder (aMesh);
-aMesh-AddBuilder (aBuilder, Standard_True);
-
-MeshVS_NodalColorPrsBuilder allows you to represent a mesh with a color scaled texture mapped on it. To do this you should define a color map for the color scale, pass this map to the presentation builder, and define an appropriate value in the range of 0.0 – 1.0 for every node.
-The following example demonstrates how you can do this (**please check,** if the view has been set up to display textures):
-<h4>Example </h4>
-
-**// assign nodal builder to the mesh**
-Handle (MeshVS_NodalColorPrsBuilder) aBuilder =
- new MeshVS_NodalColorPrsBuilder
- (aMesh,MeshVS_DMF_NodalColorDataPrs | MeshVS_DMF_OCCMask);
-aBuilder-UseTexture (Standard_True);
-
-**// prepare color map**
-Aspect_SequenceOfColor aColorMap;
-aColorMap.Append ((Quantity_NameOfColor) Quantity_NOC_RED);
-aColorMap.Append ((Quantity_NameOfColor) Quantity_NOC_BLUE1);
-
-**// assign color scale map values (0..1) to nodes**
-TColStd_DataMapOfIntegerReal aScaleMap;
-**…**
-** // iterate through the nodes and add an node id and an appropriate **
-** // value to the map**
- aScaleMap.Bind (anId, aValue);
-
-**// pass color map and color scale values to the builder**
-aBuilder-SetColorMap (aColorMap);
-aBuilder-SetInvalidColor (Quantity_NOC_BLACK);
-aBuilder-SetTextureCoords (aScaleMap);
-aMesh-AddBuilder (aBuilder, Standard_True);
-
-@subsection occt_1621831385_810308609666 ANNEX II : Principles of Dynamic Selection
-
-
-The idea of dynamic selection is to represent the entities, which you want to select by a bounding box in the actual 2D space of the selection view. The set of these zones is ordered by a powerful sorting algorithm. To then find the applicative entities actually detected at this position, all you have to do is read which rectangles are touched at mouse position (X,Y) of the view, and judiciously reject some of the entities which have provided these rectangles.
-
-
-@subsubsection occt_1621831385_81030860912222 How to go from the objects to 2D boxes
-
-
-An intermediary stage consists in representing what you can make selectable by means of sensitive primitives and owners, entities of a high enough level to be known by the selector mechanisms.
-
-The sensitive primitive is capable of:
- * giving a 2D bounding box to the selector.
- * answering the rejection criteria positively or negatively by a *Matches* function.
- * being projected from 3D in the 2D space of the view if need be.
- * returning the owner which it will represent in terms of selection.
-
-A set of standard sensitive primitives exists in Select3D packages for 3D primitives, and Select2D for 2D primitives.
-
-The owner is the entity, which makes it possible to link the sensitive primitives and the objects that you really wanted to detect. It stocks the diverse information, which makes it possible to find objects. An owner has a priority (*5* by default), which you can modulate, so as to make one entity more selectable than another.
-@image html /user_guides/visualization/images/visualization_image021.jpg
-@image latex /user_guides/visualization/images/visualization_image021.jpg
-
-@subsubsection occt_1621831385_81030860912341 Implementation in an interactive/selectable object
-
-1. Define the number of selection modes possible, i.e. what you want to identify by activating each of the selection modes. Example: for an interactive object representing a topological shape,
-mode 0: selection of the interactive object itself
-mode 1: selection of the vertices
-mode 2: selection of the edges
-mode 3: selection of the wires
-mode 4: selection of the faces detectable
-
-2. For each selection mode of an interactive object, *model* the set of entities, which you want to locate by these primitives and these owners.
-
-3. There exists an *owner* root class, *SelectMgr_EntityOwne*r, containing a reference to a selectable object, which has created it. If you want to stock its information, you have to create classes derived from this root class. Example: for shapes, there is the *StdSelect_BRepOwner *class, which can save a TopoDS shape as a field as well as the Interactive Object.
-
-4. The set of sensitive primitives which has been calculated for a given mode is stocked in *SelectMgr_Selection*.
-
-5. For an Interactive object, the modeling is done in the *ComputeSelection *virtual function.
-
-<h4>Example </h4>
-
-Let an interactive object represent a box.
-We are interested in having 2 location modes:
- * mode 0: location of the whole box.
- * mode 1: location of the edges on the box.
-
- For the first mode, all sensitive primitives will have the same owner, which will represent the interactive object. In the second case, we have to create an owner for each edge, and this owner will have to contain the index for the edge, which it represents. You will create a class of owner, which derives from *SelectMgr_EntityOwner*.
-
-The *ComputeSelection* function for the interactive box can have the following form:
-
-void InteractiveBox::ComputeSelection
-(const Handle(SelectMgr_Selection)& Sel,
- const Standard_Integer Mode)
-{
-switch(Mode)
-{ case 0: //locating the whole box by making its faces sensitive...
-{
-Handle(SelectMgr_EntityOwner) Ownr = new
- SelectMgr_EntityOwner(this,5);
-for(Standard_Integer I=1;I=Nbfaces;I++)
-{
-//Array is a TColgp_Array1OfPnt: which represents the array of vertices. Sensitivity is
-Select3D_TypeOfSensitivity value
-Sel-Add(new
-Select3D_SensitiveFace(Ownr,Array,Sensitivity));
-}
-break;
- }
- case 1:
-// locates the edges { for(Standard_Integer i=1;i=12;i++)
-{
-// 1 owner per edge...
-Handle(mypk_EdgeOwner) Ownr =
-new mypk_EdgeOwner(this,i,6);
-//6-priority
-Sel-Add(new Select3D_SensitiveSegment
- (Ownr,firstpt(i),lastpt(i)));
-}
-break;
-}
-}
-}
-
+It is important to know which functions may imply the recalculation of presentations of the object.
+If the presentation mode of an interactive object is to be updated, a flag from *PrsMgr_PresentableObject* indicates this.
+The mode can be updated using the functions *Display* and *Redisplay* in *AIS_InteractiveContext*.
-@subsubsection occt_1621831385_81030860912432 How It Works Concretely
+@subsubsection occt_visu_3_2_6 Complementary Services
-Selectable objects are loaded in the selection manager, which has one or more selectors; in general, we suggest assigning one selector per viewer. All you have to do afterwards is to activate or deactivate the different selection modes for selectable objects. The *SelectionManager* looks after the call to the *ComputeSelection* functions for different objects. NOTE: This procedure is completely hidden if you use the interactive contexts of AIS (see section 3.3, Contexts)
+When you use complementary services for interactive objects, pay special attention to the cases mentioned below.
-<h4>Example </h4>
+#### Change the location of an interactive object
-//We have several * interactive boxes * box1, box2, box3;
+The following functions allow "moving" the representation and selection of Interactive Objects in a view without recalculation (and modification of the original shape).
+ * *AIS_InteractiveContext::SetLocation*
+ * *AIS_InteractiveContext::ResetLocation*
+ * *AIS_InteractiveContext::HasLocation*
+ * *AIS_InteractiveContext::Location*
-Handle(SelectMgr_SelectionManager) SM = new SelectMgr_SelectionManager();
-Handle(StdSelect_ViewerSelector3d) VS = new StdSelect_ViewerSelector3d();
+#### Connect an interactive object to an applicative entity
-SM-Add(VS);
-SM-Load(box1);SM-Load(box2);SM-Load(box3);
-// box load.
-SM-Activate(box1,0,VS);
-// activates mode 0 of box 1 in the selector VS
-SM-Activate(box1,1,VS);
-M-Activate(box3,1,VS);
+Each Interactive Object has functions that allow attributing it an *Owner* in form of a *Transient*.
+ * *AIS_InteractiveObject::SetOwner*
+ * *AIS_InteractiveObject::HasOwner*
+ * *AIS_InteractiveObject::Owner*
-VS-Pick(xpix,ypix,vue3d)
-// detection of primitives by mouse position.
+An interactive object can therefore be associated or not with an applicative entity, without affecting its behavior.
-Handle(EntityOwner) POwnr = VS-OnePicked();
-// picking of the *best* owner detected
+**NOTE:** Don't be confused by owners of another kind - *SelectBasics_EntityOwner* used for identifying selectable parts of the object or object itself.
-for(VS-Init();VS-More();VS-Next())
-{
-VS-Picked();
-// picking of all owners detected
- }
-SM-Deactivate(box1);
-// deactivate all active modes of box1
+#### Resolving coincident topology
-@image html /user_guides/visualization/images/visualization_image022.jpg
-@image latex /user_guides/visualization/images/visualization_image022.jpg
-1st activation of the box’s mode 1: calculation of sensitive primitives + 3D/2D projection + sorting
+Due to the fact that the accuracy of three-dimensional graphics coordinates has a finite resolution the elements of topological objects can coincide producing the effect of "popping" some elements one over another.
-deactivation of mode: only updated by sorting
+To the problem when the elements of two or more Interactive Objects are coincident you can apply the polygon offset. It is a sort of graphics computational offset, or depth buffer offset, that allows you to arrange elements (by modifying their depth value) without changing their coordinates. The graphical elements that accept this kind of offsets are solid polygons or displayed as boundary lines and points. The polygons could be displayed as lines or points by setting the appropriate interior style.
-rotation of the view: only projection + sorting of active primitives
+The methods *AIS_InteractiveObject::SetPolygonOffsets* and *AIS_InteractiveContext::SetPolygonOffsets* allow setting up the polygon offsets.
-modification of the box - Recalculation of the active selection, recalculation flag on the inactive ones + 3D/2D projection + sorting
+@subsubsection occt_visu_3_2_7 Object hierarchy
-@section occt_1621831385_1539918866 3D Presentations
+Each *PrsMgr_PresentableObject* has a list of objects called *myChildren*.
+Any transformation of *PrsMgr_PresentableObject* is also applied to its children. This hierarchy does not propagate to *Graphic3d* level and below.
-@subsection occt_1621831385_15399188661 Glossary of 3D terms
+*PrsMgr_PresentableObject* sends its combined (according to the hierarchy) transformation down to *Graphic3d_Structure*.
+The materials of structures are not affected by the hierarchy.
-@subsubsection occt_1621831385_153991886611 From Graphic3d
+Object hierarchy can be controlled by the following API calls:
+* *PrsMgr_PresentableObject::AddChild*;
+* *PrsMgr_PresentableObject::RemoveChild*.
+@subsubsection occt_visu_3_2_8 Instancing
+The conception of instancing operates the object hierarchy as follows:
+* Instances are represented by separated *AIS* objects.
+* Instances do not compute any presentations.
-@subsubsection occt_1621831385_153991886612 From V3d
+Classes *AIS_ConnectedInteractive* and *AIS_MultipleConnectedInteractive* are used to implement this conception.
+*AIS_ConnectedInteractive* is an object instance, which reuses the geometry of the connected object but has its own transformation and visibility flag. This connection is propagated down to *OpenGl* level, namely to *OpenGl_Structure*. *OpenGl_Structure* can be connected only to a single other structure.
-** **
+*AIS_ConnectedInteractive* can be referenced to any *AIS_InteractiveObject* in general. When it is referenced to another *AIS_ConnectedInteractive*, it just copies the reference.
+*AIS_MultipleConnectedInteractive* represents an assembly, which does not have its own presentation. The assemblies are able to participate in the object hierarchy and are intended to handle a grouped set of instanced objects. It behaves as a single object in terms of selection. It applies high level transformation to all sub-elements since it is located above in the hierarchy.
-@subsection occt_1621831385_15399188662 Creating a 3D scene
+All *AIS_MultipleConnectedInteractive* are able to have child assemblies. Deep copy of object instances tree is performed if one assembly is attached to another.
-To create 3D graphic objects and display them on the screen, follow the procedure below:
-**1. **Create attributes.
-**2. **Create a 3D viewer..
-**3. **Create a view.
-**4. **Create an interactive context.
-**5. **Create interactive objects.
-**6. **Create primitives in the interactive object
-**7. **Display the interactive object.
+Note that *AIS_ConnectedInteractive* cannot reference *AIS_MultipleConnectedInteractive*. *AIS_ConnectedInteractive* copies sensitive entities of the origin object for selection, unlike *AIS_MultipleConnectedInteractive* that re-uses the entities of the origin object.
-@subsubsection occt_1621831385_153991886621 Create attributes
+Instances can be controlled by the following DRAW commands:
+* *vconnect* : Creates and displays *AIS_MultipleConnectedInteractive* object from input objects and location.
+* *vconnectto* : Makes an instance of object with the given position.
+* *vdisconnect* : Disconnects all objects from an assembly or disconnects an object by name or number.
+* *vaddconnected* : Adds an object to the assembly.
+* *vlistconnected* : Lists objects in the assembly.
-Create colors.
-<h4>Example </h4>
+Have a look at the examples below:
+~~~~~
+pload ALL
+vinit
+psphere s 1
+vdisplay s
+vconnectto s2 3 0 0 s # make instance
+vfit
+~~~~~
-Quantity_Color Black (Quantity_NOC_BLACK);
-Quantity_Color Blue (Quantity_NOC_MATRABLUE);
-Quantity_Color Brown (Quantity_NOC_BROWN4);
-Quantity_Color Firebrick (Quantity_NOC_FIREBRICK);
-Quantity_Color Forest (Quantity_NOC_FORESTGREEN);
-Quantity_Color Gray (Quantity_NOC_GRAY70);
-Quantity_Color
-MyColor (0.99, 0.65, 0.31, Quantity_TOC_RGB);
-Quantity_Color Beet (Quantity_NOC_BEET);
-Quantity_Color White (Quantity_NOC_WHITE);
+See how proxy *OpenGl_Structure* is used to represent instance:
+@figure{/user_guides/visualization/images/visualization_image029.png,"",240}
+The original object does not have to be displayed in order to make instance. Also selection handles transformations of instances correctly:
-Create line attributes.
+~~~~~
+pload ALL
+vinit
+psphere s 1
+psphere p 0.5
+vdisplay s # p is not displayed
+vsetloc s -2 0 0
+vconnect x 3 0 0 s p # make assembly
+vfit
+~~~~~
-<h4>Example </h4>
+@figure{/user_guides/visualization/images/visualization_image030.png,"",420}
-Handle(Graphic3d_AspectLine3d) CTXLBROWN =
-new Graphic3d_AspectLine3d ();
-Handle(Graphic3d_AspectLine3d) CTXLBLUE =
-new Graphic3d_AspectLine3d ();
-Handle(Graphic3d_AspectLine3d) CTXLWHITE =
-new Graphic3d_AspectLine3d();
-CTXLBROWN-SetColor (Brown);
-CTXLBLUE-SetColor (Blue);
-CTXLWHITE-SetColor (White);
+Here is the example of a more complex hierarchy involving sub-assemblies:
+~~~~~
+pload ALL
+vinit
+box b 1 1 1
+psphere s 0.5
+vdisplay b s
+vsetlocation s 0 2.5 0
+box d 0.5 0.5 3
+box d2 0.5 3 0.5
+vdisplay d d2
-Create marker attributes.
-<h4>Example </h4>
+vconnectto b1 -2 0 0 b
+vconnect z 2 0 0 b s
+vconnect z2 4 0 0 d d2
+vconnect z3 6 0 0 z z2
+vfit
+~~~~~
-Handle(Graphic3d_AspectMarker3d) CTXMFIREBRICK =
-new Graphic3d_AspectMarker3d();
-CTXMFIREBRICK-SetColor (Firebrick);
-CTXMFIREBRICK-SetScale (1.0);
-CTXMFIREBRICK-SetType (Aspect_TOM_BALL);
+@subsection occt_visu_3_3 Interactive Context
+@subsubsection occt_visu_3_3_1 Rules
-Create facet attributes.
-<h4>Example </h4>
+The 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.
-Handle(Graphic3d_AspectFillArea3d) CTXF =
-new Graphic3d_AspectFillArea3d ();
-Graphic3d_MaterialAspect BrassMaterial
-(Graphic3d_NOM_BRASS);
-Graphic3d_MaterialAspect GoldMaterial
-(Graphic3d_NOM_GOLD);
-CTXF-SetInteriorStyle (Aspect_IS_SOLID);
-CTXF-SetInteriorColor (MyColor);
-CTXF-SetDistinguishOn ();
-CTXF-SetFrontMaterial (GoldMaterial);
-CTXF-SetBackMaterial (BrassMaterial);
-CTXF-SetEdgeOn ();
+There is one essential rule to follow: the modification of an interactive object, which is already known by the Context, must be done using Context functions. You can only directly call the functions available for an interactive object if it has not been loaded into an Interactive Context.
+~~~~~
+Handle(AIS_Shape) aShapePrs = new AIS_Shape (theShape);
+myIntContext->Display (aShapePrs, AIS_Shaded, 0, false, aShapePrs->AcceptShapeDecomposition());
+myIntContext->SetColor(aShapePrs, Quantity_NOC_RED);
+~~~~~
-Create text attributes.
-<h4>Example </h4>
+You can also write
-Handle(Graphic3d_AspectText3d) CTXT =
-new Graphic3d_AspectText3d
-(Forest, Graphic3d_NOF_ASCII_MONO, 1., 0.);
+~~~~~
+Handle(AIS_Shape) aShapePrs = new AIS_Shape (theShape);
+aShapePrs->SetColor (Quantity_NOC_RED);
+aShapePrs->SetDisplayMode (AIS_Shaded);
+myIntContext->Display (aShapePrs);
+~~~~~
-@subsubsection occt_1621831385_153991886622 Create a 3D Viewer (a Windows example)
-<h4>Example </h4>
+@subsubsection occt_visu_3_3_2 Groups of functions
-Handle(Graphic3d_WNTGraphicDevice) TheGraphicDevice = ...;
-TCollection_ExtendedString aName(*3DV*);
-myViewer =
-new V3d_Viewer (TheGraphicDevice,aName.ToExtString (), **);
-myViewer - SetDefaultLights ();
-myViewer - SetLightOn ();
-@subsubsection occt_1621831385_153991886623 Create a 3D view (a Windows example)
+**Neutral Point** and **Local Selection** constitute the two operating modes or states of the **Interactive Context**, which is the central entity which pilots visualizations and selections.
+The **Neutral Point**, which is the default mode, allows easily visualizing and selecting interactive objects, which have been loaded into the context.
+Activating **Local Selection** for specific Objects allows selecting of their sub-parts.
-It is assumed that a valid Windows window may already be accessed via the method GetSafeHwnd().
-<h4>Example </h4>
+@subsubsection occt_visu_3_3_3 Management of the Interactive Context
+An 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.
+When an interactive object is visualized, the required graphic attributes are first taken from the object's own *Drawer* if it exists, or from the context drawer if otherwise.
+The following adjustable settings allow personalizing the behavior of presentations and selections:
+ * Default Drawer, containing all the color and line attributes which can be used by interactive objects, which do not have their own attributes.
+ * Default Visualization Mode for interactive objects. By default: *mode 0*;
+ * Highlight color of entities detected by mouse movement. By default: *Quantity_NOC_CYAN1*;
+ * Pre-selection color. By default: *Quantity_NOC_GREEN*;
+ * Selection color (when you click on a detected object). By default: *Quantity_NOC_GRAY80*;
+
+All of these settings can be modified by functions proper to the Context.
+When you change a graphic attribute pertaining to the Context (visualization mode, for example), all interactive objects, which do not have the corresponding appropriate attribute, are updated.
+
+Let us examine the case of two interactive objects: *theObj1* and *theObj2*:
+
+~~~~~
+theCtx->Display (theObj1, false);
+theCtx->Display (theObj2, true); // TRUE for viewer update
+theCtx->SetDisplayMode (theObj1, 3, false);
+theCtx->SetDisplayMode (2, true);
+// theObj2 is visualised in mode 2 (if it accepts this mode)
+// theObj1 stays visualised in its mode 3
+~~~~~
+
+*PresentationManager* and *Selector3D*, which manage the presentation and selection of present interactive objects, are associated to the main Viewer.
+
+@subsection occt_visu_3_4 Local Selection
+
+@subsubsection occt_visu_3_4_1 Selection Modes
+
+The Local Selection is defined by index (Selection Mode). The Selection Modes implemented by a specific interactive object and their meaning should be checked within the documentation of this class.
+See, for example, *MeshVS_SelectionModeFlags* for *MeshVS_Mesh* object.
+
+The interactive object, which is used the most by applications, is *AIS_Shape*. Consequently, there are standard functions, which allow you to easily prepare selection operations on the constituent elements of shapes (selection of vertices, edges, faces, etc.). The Selection Mode for a specific shape type (*TopAbs_ShapeEnum*) is returned by method *AIS_Shape::SelectionMode()*.
+
+The function *AIS_InteractiveObject::Display* (without argument taking Selection Mode) activates the object's default Selection Mode.
+The functions *AIS_InteractiveContext::Activate* and *AIS_InteractiveContext::Deactivate* activate and deactivate specific Selection Mode.
+
+More than one Selection Mode can be activated at the same time (but default 0 mode for selecting entire object is exclusive - it cannot be combined with others).
+The list of active modes can be retrieved using function *AIS_InteractiveContext::ActivatedModes*.
+
+@subsubsection occt_visu_3_4_2 Filters
+
+To define an environment of dynamic detection, you can use standard filter classes or create your own.
+A filter questions the owner of the sensitive primitive to determine if it has the desired qualities. If it answers positively, it is kept. If not, it is rejected.
-@subsubsection occt_1621831385_153991886624 Create an interactive context
-<h4>Example </h4>
+The root class of objects is *SelectMgr_Filter*. The principle behind it is straightforward: a filter tests to see whether the owners (*SelectMgr_EntityOwner*) detected in mouse position by selector answer *OK*. If so, it is kept, otherwise it is rejected.
+You can create a custom class of filter objects by implementing the deferred function *SelectMgr_Filter::IsOk()*.
-myAISContext = new AIS_InteractiveContext (myViewer);
+In *SelectMgr*, there are also Composition filters (AND Filters, OR Filters), which allow combining several filters. In Interactive Context, all filters that you add are stored in an OR filter (which answers *OK* if at least one filter answers *OK*).
+
+There are Standard filters, which have already been implemented in several packages:
+ * *StdSelect_EdgeFilter* -- for edges, such as lines and circles;
+ * *StdSelect_FaceFilter* -- for faces, such as planes, cylinders and spheres;
+ * *StdSelect_ShapeTypeFilter* -- for shape types, such as compounds, solids, shells and wires;
+ * *AIS_TypeFilter* -- for types of interactive objects;
+ * *AIS_SignatureFilter* -- for types and signatures of interactive objects;
+ * *AIS_AttributeFilter* -- for attributes of Interactive Objects, such as color and width.
+There are several functions to manipulate filters:
+* *AIS_InteractiveContext::AddFilter* adds a filter passed as an argument.
+* *AIS_InteractiveContext::RemoveFilter* removes a filter passed as an argument.
+* *AIS_InteractiveContext::RemoveFilters* removes all present filters.
+* *AIS_InteractiveContext::Filters* gets the list of filters active in a context.
-You are now able to display interactive objects such as an AIS_Shape.
-<h4>Example </h4>
+#### Example
-TopoDS_Shape aShape = BRepAPI_MakeBox(10,20,30)_Solid();
-Handle (AIS_Shape) aAISShape = new AIS_Shape(aShape);
-myAISContext - Display (aAISShape);
+~~~~~
+// shading visualization mode, no specific mode, authorization for decomposition into sub-shapes
+const TopoDS_Shape theShape;
+Handle(AIS_Shape) aShapePrs = new AIS_Shape (theShape);
+myContext->Display (aShapePrs, AIS_Shaded, -1, true, true);
-@subsubsection occt_1621831385_153991886625 Create your own interactive object
+// activates decomposition of shapes into faces
+const int aSubShapeSelMode = AIS_Shape::SelectionMode (TopAbs_Face);
+myContext->Activate (aShapePrs, aSubShapeSelMode);
-Follow the procedure below to compute the presentable object:
+Handle(StdSelect_FaceFilter) aFil1 = new StdSelect_FaceFilter (StdSelect_Revol);
+Handle(StdSelect_FaceFilter) aFil2 = new StdSelect_FaceFilter (StdSelect_Plane);
+myContext->AddFilter (aFil1);
+myContext->AddFilter (aFil2);
-**1. **Build a presentable object inheriting from AIS_InteractiveObject (refer to the Chapter on Presentable Objects).
+// only faces of revolution or planar faces will be selected
+myContext->MoveTo (thePixelX, thePixelY, myView);
+~~~~~
-**2. **Reuse the Prs3d_Presentation provided as an argument of the compute methods.
+@subsubsection occt_visu_3_4_6 Selection
-*NOTE*
-*There are two compute methods: one for a ‘standard representation, and the other for a ‘degenerated representation, i.e. in hidden line removal and wireframe modes.*
-<h4>Example of the compute methods</h4>
+Dynamic detection and selection are put into effect in a straightforward way. There are only a few conventions and functions to be familiar with:
+ * *AIS_InteractiveContext::MoveTo* -- passes mouse position to Interactive Context selectors.
+ * *AIS_InteractiveContext::Select* -- stores what has been detected at the last *MoveTo*. Replaces the previously selected object. Empties the stack if nothing has been detected at the last move.
+ * *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.
+ * *AIS_InteractiveContext::Select* -- selects everything found in the surrounding area.
+ * *AIS_InteractiveContext::ShiftSelect* -- selects what was not previously in the list of selected, deselects those already present.
-Void
-myPresentableObject::Compute
-(const Handle(PrsMgr_PresentationManager3d)&
-aPresentationManager,
-const Handle(Prs3d_Presentation)& aPrs,
-const Standard_Integer aMode)
-(
-//...
-)
+Highlighting of detected and selected entities is automatically managed by the Interactive Context. The Highlight colors are those dealt with above. You can nonetheless disconnect this automatic mode if you want to manage this part yourself:
+~~~~~
+ AIS_InteractiveContext::SetAutomaticHilight
+ AIS_InteractiveContext::AutomaticHilight
+~~~~~
+You can question the Interactive context by moving the mouse. The following functions can be used:
+ * *AIS_InteractiveContext::HasDetected* -- checks if there is a detected entity;
+ * *AIS_InteractiveContext::DetectedOwner* -- returns the (currently highlighted) detected entity.
+After using the *Select* and *ShiftSelect* functions, you can explore the list of selections. The following functions can be used:
+ * *AIS_InteractiveContext::InitSelected* -- initializes an iterator;
+ * *AIS_InteractiveContext::MoreSelected* -- checks if the iterator is valid;
+ * *AIS_InteractiveContext::NextSelected* -- moves the iterator to the next position;
+ * *AIS_InteractiveContext::SelectedOwner* -- returns an entity at the current iterator position.
-void
-myPresentableObject::Compute
-(const Handle(Prs3d_Projector)&,
-const Handle(Prs3d_Presentation)& aPrs)
-(
-//...
-)
+The owner object *SelectMgr_EntityOwner* is a key object identifying selectable entitiy in the viewer (returned by methods *AIS_InteractiveContext::DetectedOwner* and *AIS_InteractiveContext::SelectedOwner*).
+The Interactive Object itself can be retrieved by method *SelectMgr_EntityOwner::Selectable*, while identifying sub-part depends on type of Interactive Object.
+In case of *AIS_Shape*, the (sub)shape is returned by method *StdSelect_BRepOwner::Shape*.
+#### Example
+~~~~~
+for (myAISCtx->InitSelected(); myAISCtx->MoreSelected(); myAISCtx->NextSelected())
+{
+ Handle(SelectMgr_EntityOwner) anOwner = myAISCtx->SelectedOwner();
+ Handle(AIS_InteractiveObject) anObj = Handle(AIS_InteractiveObject)::DownCast (anOwner->Selectable());
+ if (Handle(StdSelect_BRepOwner) aBRepOwner = Handle(StdSelect_BRepOwner)::DownCast (anOwner))
+ {
+ // to be able to use the picked shape
+ TopoDS_Shape aShape = aBRepOwner->Shape();
+ }
+}
+~~~~~
-@subsubsection occt_1621831385_153991886626 Create primitives in the interactive object
+@subsection occt_visu_3_5 Standard Interactive Object Classes
-Get the group used in Prs3d_Presentation.
-<h4>Example </h4>
+Interactive Objects are selectable and viewable objects connecting graphic representation and the underlying reference geometry.
-Handle(Graphic3d_Group) TheGroup = Prs3d_Root::CurrentGroup(aPrs);
+They are divided into four types:
+ * the **Datum** -- a construction geometric element;
+ * the **Relation** -- a constraint on the interactive shape and the corresponding reference geometry;
+ * the **Object** -- a topological shape or connection between shapes;
+ * **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.
+Inside 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*).
+If you want to give a particular type and signature to your interactive object, you must redefine the two virtual methods: *Type* and *Signature*.
-Update the group attributes.
+@subsubsection occt_visu_3_5_1 Datum
-<h4>Example </h4>
+The **Datum** groups together the construction elements such as lines, circles, points, trihedrons, plane trihedrons, planes and axes.
-TheGroup - SetPrimitivesAspect(CTXLBLUE);
+*AIS_Point, AIS_Axis, AIS_Line, AIS_Circle, AIS_Plane* and *AIS_Trihedron* have four selection modes:
+ * mode 0 : selection of a trihedron;
+ * mode 1 : selection of the origin of the trihedron;
+ * mode 2 : selection of the axes;
+ * mode 3 : selection of the planes XOY, YOZ, XOZ.
+when you activate one of modes: 1 2 3 4, you pick AIS objects of type:
+ * *AIS_Point*;
+ * *AIS_Axis* (and information on the type of axis);
+ * *AIS_Plane* (and information on the type of plane).
-Create two triangles in group TheGroup.
-<h4>Example </h4>
+*AIS_PlaneTrihedron* offers three selection modes:
+ * mode 0 : selection of the whole trihedron;
+ * mode 1 : selection of the origin of the trihedron;
+ * mode 2 : selection of the axes -- same remarks as for the Trihedron.
-Standard_Integer aNbTria = 2;
-Handle(Graphic3d_ArrayOfTriangles) aTriangles = new Graphic3d_ArrayOfTriangles(3 * aNbTria, 0, Standard_True);
-Standard_Integer anIndex;
-for (anIndex = 1; anIndex = aNbTria; nt++)
-{
- aTriangles-AddVertex(anIndex * 5., 0., 0., 1., 1., 1.);
- aTriangles-AddVertex(anIndex * 5 + 5, 0., 0., 1., 1., 1.);
- aTriangles-AddVertex(anIndex * 5 + 2.5, 5., 0., 1., 1., 1.);
-}
-TheGroup-BeginPrimitives ();
-mygroup-AddPrimitiveArray(aTriangles);
-TheGroup-EndPrimitives ();
+For the presentation of planes and trihedra, the default length unit is millimeter and the default value for the representation of axes is 10. To modify these dimensions, you must temporarily recover the object **Drawer**. From it, take the *DatumAspect()* and change the value *FirstAxisLength*. Finally, recalculate the presentation.
+@subsubsection occt_visu_3_5_2 Object
-The BeginPrimitives () and EndPrimitives () methods are used when creating a set of various primitives in the same group.
-Use the polyline function to create a boundary box for the Struct structure in group TheGroup.
-<h4>Example </h4>
+The **Object** type includes topological shapes, and connections between shapes.
+
+*AIS_Shape* has two visualization modes:
+ * mode 0 : Line (default mode)
+ * mode 1 : Shading (depending on the type of shape)
-Standard_Real Xm, Ym, Zm, XM, YM, ZM;
-Struct-MinMaxValues (Xm, Ym, Zm, XM, YM, ZM);
+*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.
+*AIS_MultipleConnectedInteractive* is an object connected to a list of interactive objects (which can also be Connected objects. It does not require memory-hungry presentation calculations).
+
+*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.
+
+The class *AIS_ColoredShape* allows using custom colors and line widths for *TopoDS_Shape* objects and their sub-shapes.
+
+~~~~~
+ AIS_ColoredShape aColoredShape = new AIS_ColoredShape (theShape);
+
+ // setup color of entire shape
+ aColoredShape->SetColor (Quantity_NOC_RED);
+
+ // setup line width of entire shape
+ aColoredShape->SetWidth (1.0);
+
+ // set transparency value
+ aColoredShape->SetTransparency (0.5);
+
+ // customize color of specified sub-shape
+ aColoredShape->SetCustomColor (theSubShape, Quantity_NOC_BLUE1);
+
+ // customize line width of specified sub-shape
+ aColoredShape->SetCustomWidth (theSubShape, 0.25);
+~~~~~
+
+The 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.
+- The type of point marker used to draw points can be specified as a presentation aspect.
+- The presentation provides selection by a bounding box of the visualized set of points. It supports two display / highlighting modes: points or bounding box.
+
+@figure{point_cloud.png,"A random colored cloud of points",240}
+
+Example:
+~~~~~
+Handle(Graphic3d_ArrayOfPoints) aPoints = new Graphic3d_ArrayOfPoints (2000, Standard_True);
+aPoints->AddVertex (gp_Pnt(-40.0, -40.0, -40.0), Quantity_Color (Quantity_NOC_BLUE1));
+aPoints->AddVertex (gp_Pnt (40.0, 40.0, 40.0), Quantity_Color (Quantity_NOC_BLUE2));
+
+Handle(AIS_PointCloud) aPntCloud = new AIS_PointCloud();
+aPntCloud->SetPoints (aPoints);
+~~~~~
+
+The draw command *vpointcloud* builds a cloud of points from shape triangulation.
+This command can also draw a sphere surface or a volume with a large amount of points (more than one million).
+
+@subsubsection occt_visu_3_5_3 Relations
+
+The **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.
+
+The following relations are provided by *AIS*:
+ * *AIS_ConcentricRelation*
+ * *AIS_FixRelation*
+ * *AIS_IdenticRelation*
+ * *AIS_ParallelRelation*
+ * *AIS_PerpendicularRelation*
+ * *AIS_Relation*
+ * *AIS_SymmetricRelation*
+ * *AIS_TangentRelation*
-Handle(Graphic3d_ArrayOfPolylines) aPolylines = new Graphic3d_ArrayOfPolylines(16, 4);
-aPolylines-AddBound (4);
-aPolylines-AddVertex (Xm, Ym, Zm);
-aPolylines-AddVertex (Xm, Ym, ZM);
-aPolylines-AddVertex (Xm, YM, ZM);
-aPolylines-AddVertex (Xm, YM, Zm);
-aPolylines-AddBound (4);
-aPolylines-AddVertex (Xm, Ym, Zm);
-aPolylines-AddVertex (XM, Ym, Zm);
-aPolylines-AddVertex (XM, Ym, ZM);
-aPolylines-AddVertex (XM, YM, ZM);
-aPolylines-AddBound (4);
-aPolylines-AddVertex (XM, YM, Zm);
-aPolylines-AddVertex (XM, Ym, Zm);
-aPolylines-AddVertex (XM, YM, Zm);
-aPolylines-AddVertex (Xm, YM, Zm);
-aPolylines-AddBound (4);
-aPolylines-AddVertex (Xm, YM, ZM);
-aPolylines-AddVertex (XM, YM, ZM);
-aPolylines-AddVertex (XM, Ym, ZM);
-aPolylines-AddVertex (Xm, Ym, ZM);
+The list of relations is not exhaustive.
+
+@subsubsection occt_visu_3_5_4 Dimensions
+ * *AIS_AngleDimension*
+ * *AIS_Chamf3dDimension*
+ * *AIS_DiameterDimension*
+ * *AIS_DimensionOwner*
+ * *AIS_LengthDimension*
+ * *AIS_OffsetDimension*
+ * *AIS_RadiusDimension*
+
+@subsubsection occt_visu_3_5_5 MeshVS_Mesh
+
+*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.
+
+However, the *DataSource* does not provide any information on attributes, for example nodal colors, but you can apply them in a special way -- by choosing the appropriate presentation builder.
+
+The presentations of *MeshVS_Mesh* are built with the presentation builders *MeshVS_PrsBuilder*. You can choose between the builders to represent the object in a different way. Moreover, you can redefine the base builder class and provide your own presentation builder.
+
+You can add/remove builders using the following methods:
+~~~~~
+ MeshVS_Mesh::AddBuilder (const Handle(MeshVS_PrsBuilder)& theBuilder, Standard_Boolean theToTreatAsHilighter);
+ MeshVS_Mesh::RemoveBuilder (const Standard_Integer theIndex);
+ MeshVS_Mesh::RemoveBuilderById (const Standard_Integer theId);
+~~~~~
-TheGroup-BeginPrimitives ();
-TheGroup-AddPrimitiveArray(aPolylines);
-TheGroup-EndPrimitives ();
-
-
-Create text and markers in group TheGroup.
-<h4>Example </h4>
-
-static char *texte[3] = { *Application title*,
-*My company*,
-*My company address.* };
-Graphic3d_Array1OfVertex Tpts8 (0, 1);
-Tpts8(0).SetCoord (-40.0, -40.0, -40.0);
-Tpts8(1).SetCoord (40.0, 40.0, 40.0);
-TheGroup-MarkerSet (Tpts8);
-Graphic3d_Vertex Marker (0.0, 0.0, 0.0);
-
-for (i=0; i=2; i++) {
- Marker.SetCoord (-(Standard_Real)i*4 + 30,
- (Standard_Real)i*4,
- -(Standard_Real)i*4);
- TheGroup-Text (texte[i], Marker, 20.);
-}
-
-@section occt_1621831385_1435012457 3D Resources
-
-The 3D resources include the Graphic3d and V3d packages.
-
-@subsection occt_1621831385_14350124571 Graphic3D
-
-@subsubsection occt_1621831385_143501245711 Overview
-
-The **Graphic3d** package is used to create 3D graphic objects in a 3D viewer. These objects called **structures** are made up of groups of primitives and attributes. A group is the smallest editable element of a structure. A transformation can be applied to a structure. Structures can be connected to form a tree of structures, composed by transformations. Structures are globally manipulated by the viewer.
-
-@subsubsection occt_1621831385_143501245712 Provided services
-
-Graphic structures can be:
- * Displayed,
- * Highlighted,
- * Erased,
- * Transformed,
- * Connected to form a tree.
- There are classes for:
- * Visual attributes for lines, faces, markers, text, materials,
- * Vectors and vertices,
- * Defining an Advanced Graphic Device,
- * Graphic objects, groups, and structures.
-
-@subsubsection occt_1621831385_143501245713 About the primitives
-** **
-** **Markers** **
- * Have one or more vertices,
- * Have a type, a scale factor, and a color,
- * Have a size, shape, and orientation independent of transformations.
-*Polygons *
- * Have one closed boundary,
- * Have at least three vertices,
- * Are planar and have a normal,
- * Have interior attributes - style, color, front and back material, texture and reflection ratio,
- * Have a boundary with the following attributes - type, width scale factor, color. The boundary is only drawn when the interior style is hollow.
-
-*Polygons with holes *
- * Have multiple closed boundaries, each one with at least three vertices,
- * Are planar and have a normal,
- * Have interior attributes - style, color, front and back material,
- * Have a boundary with the following attributes - type, width scale factor, color. The boundary is only drawn when the interior style is hollow.
-
-*Polylines *
- * Have two or more vertices,
- * Have the following attributes - type, width scale factor, color.
-
-*Text *
- * Has geometric and non-geometric attributes,
- * Geometric attributes - character height, character up vector, text path, horizontal and vertical alignment, orientation, three-dimensional position, zoomable flag
- * Non-geometric attributes - text font, character spacing, character expansion factor, color.
-
-@subsubsection occt_1621831385_143501245714 Primitive arrays
-
-Primitive arrays are a more efficient approach to describe and display the primitives from the aspects of memory usage and graphical performance. The key feature of the primitive arrays is that the primitive data is not duplicated. For example, two polygons could share the same vertices, so it is more efficient to keep the vertices in a single array and specify the polygon vertices with indices of this array. In addition to such kind of memory savings, the OpenGl graphics driver provides the Vertex Buffer Objects (VBO). VBO is a sort of video memory storage that can be allocated to hold the primitive arrays, thus making the display operations more efficient and releasing the RAM memory.
-
-The Vertex Buffer Objects are enabled by default, but VBOs availability depends on the implementation of OpenGl. If the VBOs are unavailable or there is not enough video memory to store the primitive arrays, the RAM memory will be used to store the arrays.
-
-The Vertex Buffer Objects can be disabled at the application level. You can use the following method to enable/disable VBOs:
- * void Graphic3d_GraphicDriver::EnableVBO
- (const Standard_Boolean status)
-
-The following example shows how to disable the VBO support:
-<h4>Example </h4>
-
-**// get the graphic driver**
-Handle (Aspect_GraphicDriver) aDriver =
- myAISContext-CurrentViewer()-Device()-GraphicDriver();
-
-**// disable VBO support**
-Handle (Graphic3d_GraphicDriver)::
- DownCast (aDriver)-EnableVBO (Standard_False);
-
-**Please note** that the use of Vertex Buffer Objects requires the application level primitive data provided by the Graphic3d_ArrayOfPrimitives to be transferred to the video memory. TKOpenGl transfers the data and releases the Graphic3d_ArrayOfPrimitives internal pointers to the primitive data. Thus it might be necessary to pay attention to such kind of behaviour, as the pointers could be modified (nullified) by the TKOpenGl.
-
-The different types of primitives could be presented with the following primitive arrays:
- * Graphic3d_ArrayOfPoints,
- * Graphic3d_ArrayOfPolygons,
- * Graphic3d_ArrayOfPolylines,
- * Graphic3d_ArrayOfQuadrangles,
- * Graphic3d_ArrayOfQuadrangleStrips,
- * Graphic3d_ArrayOfSegments,
- * Graphic3d_ArrayOfTriangleFans,
- * Graphic3d_ArrayOfTriangles,
- * Graphic3d_ArrayOfTriangleStrips.
-
-The Graphic3d_ArrayOfPrimitives is a base class for these primitive arrays.
-
-There is a set of similar methods to add vertices to the primitive array:
- * Standard_Integer Graphic3d_ArrayOfPrimitives::AddVertex
-
-These methods take vertex coordinates as an argument and allow you to define the color, the normal and the texture coordinates assigned to the vertex. The return value is the actual number of vertices in the array.
-
-You can also modify the values assigned to the vertex or query these values by the vertex index:
- * void Graphic3d_ArrayOfPrimitives::SetVertice
- * void Graphic3d_ArrayOfPrimitives::SetVertexColor
- * void Graphic3d_ArrayOfPrimitives::SetVertexNormal
- * void Graphic3d_ArrayOfPrimitives::SetVertexTexel
- * gp_Pnt Graphic3d_ArrayOfPrimitives::Verticie
- * gp_Dir Graphic3d_ArrayOfPrimitives::VertexNormal
- * gp_Pnt2d Graphic3d_ArrayOfPrimitives::VertexTexel
- * Quantity_Color Graphic3d_ArrayOfPrimitives::VertexColor
- * void Graphic3d_ArrayOfPrimitives::Verticie
- * void Graphic3d_ArrayOfPrimitives::VertexNormal
- * void Graphic3d_ArrayOfPrimitives::VertexTexel
- * void Graphic3d_ArrayOfPrimitives::VertexColor
-
-The following example shows how to define an array of points:
-<h4>Example </h4>
-
-**// create an array**
-Handle (Graphic3d_ArrayOfPoints) anArray =
- new Graphic3d_ArrayOfPoints (aVerticiesMaxCount);
-
-**// add vertices to the array**
-anArray-AddVertex (10.0, 10.0, 10.0);
-anArray-AddVertex (0.0, 10.0, 10.0);
-
-**// add the array to the structure **
-Handle (Graphic3d_Group) aGroup =
- Prs3d_Root::CurrentGroup (aPrs);
-aGroup-BeginPrimitives ();
-aGroup-AddPrimitiveArray (anArray);
-aGroup-EndPrimitives ();
-
-If the primitives share the same vertices (polygons, triangles, etc) then you can define them as indices of the vertices array. The following method allows you to define the primitives by the indices:
- * Standard_Integer Graphic3d_ArrayOfPrimitives::AddEdge
-
-This method adds an *edge* in the range [1, VertexNumber() ] in the array.
-It is also possible to query the vertex defined by an edge:
- * Standard_Integer Graphic3d_ArrayOfPrimitives::Edge
-
-The following example shows how to define an array of triangles:
-<h4>Example </h4>
-
-**// create an array**
-Standard_Boolean IsNormals = Standard_False;
-Standard_Boolean IsColors = Standard_False;
-Standard_Boolean IsTextureCrds = Standard_False;
-Handle (Graphic3d_ArrayOfTriangles) anArray =
- new Graphic3d_ArrayOfTriangles (aVerticesMaxCount,
- aEdgesMaxCount,
- IsNormals,
- IsColors,
- IsTextureCrds);
-**// add vertices to the array**
-anArray-AddVertex (-1.0, 0.0, 0.0); **// vertex 1**
-anArray-AddVertex ( 1.0, 0.0, 0.0); **// vertex 2**
-anArray-AddVertex ( 0.0, 1.0, 0.0); **// vertex 3**
-anArray-AddVertex ( 0.0,-1.0, 0.0); **// vertex 4**
-
-**// add edges to the array**
-anArray-AddEdge (1); **// first triangle**
-anArray-AddEdge (2);
-anArray-AddEdge (3);
-anArray-AddEdge (1); **// second triangle**
-anArray-AddEdge (2);
-anArray-AddEdge (4);
-
-**// add the array to the structure**
-Handle (Graphic3d_Group) aGroup =
- Prs3d_Root::CurrentGroup (aPrs);
-aGroup-BeginPrimitives ();
-aGroup-AddPrimitiveArray (anArray);
-aGroup-EndPrimitives ();
-
-If the primitive array presents primitives built from sequential sets of vertices, for example polygons, then you can specify the bounds, or the number of vertices for each primitive. You can use the following method to define the bounds and the color for each bound:
- * Standard_Integer Graphic3d_ArrayOfPrimitives::AddBound
-
-This method returns the actual number of bounds.
-It is also possible to set the color and query the number of edges in the bound and bound color:
- * Standard_Integer Graphic3d_ArrayOfPrimitives::Bound
- * Quantity_Color Graphic3d_ArrayOfPrimitives::BoundColor
- * void Graphic3d_ArrayOfPrimitives::BoundColor
-
-The following example shows how to define an array of polygons:
-<h4>Example </h4>
-
-**// create an array**
-Standard_Boolean IsNormals = Standard_False;
-Standard_Boolean IsVertexColors = Standard_False;
-Standard_Boolean IsFaceColors = Standard_False;
-Standard_Boolean IsTextureCrds = Standard_False;
-Handle (Graphic3d_ArrayOfPolygons) anArray =
- new Graphic3d_ArrayOfPolygons (aVerticesMaxCount,
- aBoundsMaxCount,
- aEdgesMaxCount,
- IsNormals,
- IsVertexColors,
- IsFaceColors,
- IsTextureCrds);
-
-**// add bounds to the array, first polygon**
-anArray-AddBound (3);
-anArray-AddVertex (-1.0, 0.0, 0.0);
-anArray-AddVertex ( 1.0, 0.0, 0.0);
-anArray-AddVertex ( 0.0, 1.0, 0.0);
-
-**// add bounds to the array, second polygon**
-anArray-AddBound (4);
-anArray-AddVertex (-1.0, 0.0, 0.0);
-anArray-AddVertex ( 1.0, 0.0, 0.0);
-anArray-AddVertex ( 1.0,-1.0, 0.0);
-anArray-AddVertex (-1.0,-1.0, 0.0);
-
-**// add the array to the structure **
-Handle (Graphic3d_Group) aGroup =
- Prs3d_Root::CurrentGroup (aPrs);
-aGroup-BeginPrimitives ();
-aGroup-AddPrimitiveArray (anArray);
-aGroup-EndPrimitives ();
-
-There are also several helper methods. You can get the type of the primitive array:
- * Graphic3d_TypeOfPrimitiveArray Graphic3d_ArrayOfPrimitives::Type
- * Standard_CString Graphic3d_ArrayOfPrimitives::StringType
-
-and check if the primitive array provides normals, vertex colors, vertex texels (texture coordinates):
- * Standard_Boolean Graphic3d_ArrayOfPrimitives::HasVertexNormals
- * Standard_Boolean Graphic3d_ArrayOfPrimitives::HasVertexColors
- * Standard_Boolean Graphic3d_ArrayOfPrimitives::HasVertexTexels
-
-or get the number of vertices, edges and bounds:
- * Standard_Integer Graphic3d_ArrayOfPrimitives::VertexNumber
- * Standard_Integer Graphic3d_ArrayOfPrimitives::EdgeNumber
- * Standard_Integer Graphic3d_ArrayOfPrimitives::BoundNumber
-
-@subsubsection occt_1621831385_143501245715 About materials
-
-A **material** is defined by coefficients of:
- * Transparency,
- * Diffuse reflection,
- * Ambient reflection,
- * Specular reflection.
-
-Two properties define a given material:
- * Transparency
- * Reflection properties - its absorption and reflection of light.
-
-**Diffuse reflection** is seen as a component of the color of the object.
-
-**Specular reflection** is seen as a component of the color of the light source.
-
-The following items are required to determine the three colors of reflection:
- * Color,
- * Coefficient of diffuse reflection,
- * Coefficient of ambient reflection,
- * Coefficient of specular reflection.
-
-
-
-@subsubsection occt_1621831385_143501245716 About textures
-
-A **texture **is defined by a name.
-Three types of texture are available:
- * 1D,
- * 2D,
- * Environment mapping.
-
-@subsubsection occt_1621831385_143501245717 Graphic3d text
-
-The OpenGl graphics driver uses advanced text rendering powered by FTGL library. This library provides vector text rendering, as a result the text can be rotated and zoomed without quality loss.
-Graphic3d text primitives have the following features:
- * fixed size (non-zoomable) or zoomable,
+There is a set of reserved display and highlighting mode flags for *MeshVS_Mesh*. Mode value is a number of bits that allows selecting additional display parameters and combining the following mode flags, which allow displaying mesh in wireframe, shading and shrink modes:
+~~~~~
+ MeshVS_DMF_WireFrame
+ MeshVS_DMF_Shading
+ MeshVS_DMF_Shrink
+~~~~~
+
+It is also possible to display deformed mesh in wireframe, shading or shrink modes usung:
+~~~~~
+ MeshVS_DMF_DeformedPrsWireFrame
+ MeshVS_DMF_DeformedPrsShading
+ MeshVS_DMF_DeformedPrsShrink
+~~~~~
+
+The following methods represent different kinds of data:
+~~~~~
+ MeshVS_DMF_VectorDataPrs
+ MeshVS_DMF_NodalColorDataPrs
+ MeshVS_DMF_ElementalColorDataPrs
+ MeshVS_DMF_TextDataPrs
+ MeshVS_DMF_EntitiesWithData
+~~~~~
+
+The following methods provide selection and highlighting:
+~~~~~
+ MeshVS_DMF_SelectionPrs
+ MeshVS_DMF_HilightPrs
+~~~~~
+
+*MeshVS_DMF_User* is a user-defined mode.
+
+These values will be used by the presentation builder.
+There is also a set of selection modes flags that can be grouped in a combination of bits:
+ * *MeshVS_SMF_0D*
+ * *MeshVS_SMF_Link*
+ * *MeshVS_SMF_Face*
+ * *MeshVS_SMF_Volume*
+ * *MeshVS_SMF_Element* -- groups *0D, Link, Face* and *Volume* as a bit mask;
+ * *MeshVS_SMF_Node*
+ * *MeshVS_SMF_All* -- groups *Element* and *Node* as a bit mask;
+ * *MeshVS_SMF_Mesh*
+ * *MeshVS_SMF_Group*
+
+Such an object, for example, can be used for displaying the object and stored in the STL file format:
+
+~~~~~
+// read the data and create a data source
+Handle(Poly_Triangulation) aSTLMesh = RWStl::ReadFile (aFileName);
+Handle(XSDRAWSTLVRML_DataSource) aDataSource = new XSDRAWSTLVRML_DataSource (aSTLMesh);
+
+// create mesh
+Handle(MeshVS_Mesh) aMeshPrs = new MeshVS();
+aMeshPrs->SetDataSource (aDataSource);
+
+// use default presentation builder
+Handle(MeshVS_MeshPrsBuilder) aBuilder = new MeshVS_MeshPrsBuilder (aMeshPrs);
+aMeshPrs->AddBuilder (aBuilder, true);
+~~~~~
+
+*MeshVS_NodalColorPrsBuilder* allows representing a mesh with a color scaled texture mapped on it.
+To do this you should define a color map for the color scale, pass this map to the presentation builder, and define an appropriate value in the range of 0.0 - 1.0 for every node.
+The following example demonstrates how you can do this (check if the view has been set up to display textures):
+
+~~~~~
+// assign nodal builder to the mesh
+Handle(MeshVS_NodalColorPrsBuilder) aBuilder = new MeshVS_NodalColorPrsBuilder (theMeshPrs, MeshVS_DMF_NodalColorDataPrs | MeshVS_DMF_OCCMask);
+aBuilder->UseTexture (true);
+
+// prepare color map
+Aspect_SequenceOfColor aColorMap;
+aColorMap.Append (Quantity_NOC_RED);
+aColorMap.Append (Quantity_NOC_BLUE1);
+
+// assign color scale map values (0..1) to nodes
+TColStd_DataMapOfIntegerReal aScaleMap;
+...
+// iterate through the nodes and add an node id and an appropriate value to the map
+aScaleMap.Bind (anId, aValue);
+
+// pass color map and color scale values to the builder
+aBuilder->SetColorMap (aColorMap);
+aBuilder->SetInvalidColor (Quantity_NOC_BLACK);
+aBuilder->SetTextureCoords (aScaleMap);
+aMesh->AddBuilder (aBuilder, true);
+~~~~~
+
+@subsection occt_visu_3_6 Dynamic Selection
+
+The dynamic selection represents the topological shape, which you want to select, by decomposition of *sensitive primitives* -- the sub-parts of the shape that will be detected and highlighted. The sets of these primitives are handled by the powerful three-level BVH tree selection algorithm.
+
+For more details on the algorithm and examples of usage, please, refer to @ref occt_visu_2_2 "Selection" chapter.
+
+@section occt_visu_4 3D Presentations
+
+@subsection occt_visu_4_1 Glossary of 3D terms
+
+* **Group** -- a set of primitives and attributes on those primitives. Primitives and attributes may be added to a group but cannot be removed from it, unless erased globally. A group can have a pick identity.
+* **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.
+* **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.
+* **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.
+* **View** -- is defined by a view orientation, a view mapping, and a context view.
+* **Viewer** -- manages a set of views.
+* **View orientation** -- defines the manner in which the observer looks at the scene in terms of View Reference Coordinates.
+* **View mapping** -- defines the transformation from View Reference Coordinates to the Normalized Projection Coordinates. This follows the Phigs scheme.
+* **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.
+
+@subsection occt_visu_4_2 Graphic primitives
+
+The *Graphic3d* package is used to create 3D graphic objects in a 3D viewer. These objects called **structures** are made up of groups of primitives and attributes, 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.
+
+Graphic structures can be:
+ * Displayed,
+ * Highlighted,
+ * Erased,
+ * Transformed,
+ * Connected to form a tree hierarchy of structures, created by transformations.
+
+There are classes for:
+ * Visual attributes for lines, faces, markers, text, materials,
+ * Vectors and vertices,
+ * Graphic objects, groups, and structures.
+
+@subsubsection occt_visu_4_2_2 Structure hierarchies
+
+The root is the top of a structure hierarchy or structure network. The attributes of a parent structure are passed to its descendants. The attributes of the descendant structures do not affect the parent. Recursive structure networks are not supported.
+
+@subsubsection occt_visu_4_2_3 Graphic primitives
+* **Markers**
+ * Have one or more vertices,
+ * Have a type, a scale factor, and a color,
+ * Have a size, shape, and orientation independent of transformations.
+* **Triangulation**
+ * Have at least three vertices,
+ * Have nodal normals defined for shading,
+ * Have interior attributes -- style, color, front and back material, texture and reflection ratio,
+* **Polylines** or **Segments**
+ * Have two or more vertices,
+ * Have the following attributes -- type, width scale factor, color.
+* **Text**
+ * Has geometric and non-geometric attributes,
+ * Geometric attributes -- character height, character up vector, text path, horizontal and vertical alignment, orientation, three-dimensional position, zoomable flag
+ * Non-geometric attributes -- text font, character spacing, character expansion factor, color.
+
+@subsubsection occt_visu_4_2_4 Primitive arrays
+
+The different types of primitives could be presented with the following primitive arrays:
+ * *Graphic3d_ArrayOfPoints,*
+ * *Graphic3d_ArrayOfPolylines,*
+ * *Graphic3d_ArrayOfSegments,*
+ * *Graphic3d_ArrayOfTriangleFans,*
+ * *Graphic3d_ArrayOfTriangles,*
+ * *Graphic3d_ArrayOfTriangleStrips.*
+
+The *Graphic3d_ArrayOfPrimitives* is a base class for these primitive arrays.
+Method set *Graphic3d_ArrayOfPrimitives::AddVertex* allows adding vertices to the primitive array with their attributes (color, normal, texture coordinates).
+You can also modify the values assigned to the vertex or query these values by the vertex index.
+
+The following example shows how to define an array of points:
+
+~~~~~
+// create an array
+Handle(Graphic3d_ArrayOfPoints) anArray = new Graphic3d_ArrayOfPoints (theVerticiesMaxCount);
+
+// add vertices to the array
+anArray->AddVertex (10.0, 10.0, 10.0);
+anArray->AddVertex (0.0, 10.0, 10.0);
+
+// add the array to the structure
+Handle(Graphic3d_Group) aGroup = thePrs->NewGroup();
+aGroup->AddPrimitiveArray (anArray);
+aGroup->SetGroupPrimitivesAspect (myDrawer->PointAspect()->Aspect());
+~~~~~
+
+If the primitives share the same vertices (polygons, triangles, etc.) then you can define them as indices of the vertices array.
+The method *Graphic3d_ArrayOfPrimitives::AddEdge* allows defining the primitives by indices. This method adds an "edge" in the range *[1, VertexNumber()]* in the array.
+It is also possible to query the vertex defined by an edge using method *Graphic3d_ArrayOfPrimitives::Edge*.
+
+The following example shows how to define an array of triangles:
+
+~~~~~
+// create an array
+Standard_Boolean hasNormals = false;
+Standard_Boolean hasColors = false;
+Standard_Boolean hasTextureCrds = false;
+Handle(Graphic3d_ArrayOfTriangles) anArray = new Graphic3d_ArrayOfTriangles (theVerticesMaxCount, theEdgesMaxCount, hasNormals, hasColors, hasTextureCrds);
+// add vertices to the array
+anArray->AddVertex (-1.0, 0.0, 0.0); // vertex 1
+anArray->AddVertex ( 1.0, 0.0, 0.0); // vertex 2
+anArray->AddVertex ( 0.0, 1.0, 0.0); // vertex 3
+anArray->AddVertex ( 0.0,-1.0, 0.0); // vertex 4
+
+// add edges to the array
+anArray->AddEdge (1); // first triangle
+anArray->AddEdge (2);
+anArray->AddEdge (3);
+anArray->AddEdge (1); // second triangle
+anArray->AddEdge (2);
+anArray->AddEdge (4);
+
+// add the array to the structure
+Handle(Graphic3d_Group) aGroup = thePrs->NewGroup();
+aGroup->AddPrimitiveArray (anArray);
+aGroup->SetGroupPrimitivesAspect (myDrawer->ShadingAspect()->Aspect());
+~~~~~
+
+@subsubsection occt_visu_4_2_5 Text primitive
+
+TKOpenGL toolkit renders text labels using texture fonts. *Graphic3d* text primitives have the following features:
+ * fixed size (non-zoomable) or zoomable,
* can be rotated to any angle in the view plane,
* support unicode charset.
-The text attributes for the group could be defined with the Graphic3d_AspectText3d attributes group.
-To add any text to the graphic structure you can use the following methods:
- * void Graphic3d_Group::Text
-(const Standard_CString AText,
- const Graphic3d_Vertex& APoint,
- const Standard_Real AHeight,
- const Quantity_PlaneAngle AAngle,
- const Graphic3d_TextPath ATp,
- const Graphic3d_HorizontalTextAlignment AHta,
- const Graphic3d_VerticalTextAlignment AVta,
- const Standard_Boolean EvalMinMax),
-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).
-ATp parameter defines the text path, AHta is the horizontal alignment of the text, AVta is the vertical alignment of the text.
-You can pass Standard_False as EvalMinMax if you don’t want the graphic3d structure boundaries to be affected by the text position.
-**Please note** that the text orientation angle can be defined by Graphic3d_AspectText3d attributes.
-
- * void Graphic3d_Group::Text
-(const Standard_CString AText,
- const Graphic3d_Vertex& APoint,
- const Standard_Real AHeight,
- const Standard_Boolean EvalMinMax)
- * void Graphic3d_Group::Text
-(const TCcollection_ExtendedString &AText,
-const Graphic3d_Vertex& APoint,
- const Standard_Real AHeight,
- const Quantity_PlaneAngle AAngle,
- const Graphic3d_TextPath ATp,
- const Graphic3d_HorizontalTextAlignment AHta,
- const Graphic3d_VerticalTextAlignment AVta,
- const Standard_Boolean EvalMinMax)
- * void Graphic3d_Group::Text
-(const TCcollection_ExtendedString &AText,
- const Graphic3d_Vertex& APoint,
- const Standard_Real AHeight,
- const Standard_Boolean EvalMinMax)
-
-<h4>Example </h4>
-
-**// get the group**
-Handle (Graphic3d_Group) aGroup =
- Prs3d_Root::CurrentGroup (aPrs);
-
-**// change the text aspect**
-Handle(Graphic3d_AspectText3d) aTextAspect =
- new Graphic3d_AspectText3d ();
-aTextAspect-SetTextZoomable (Standard_True);
-aTextAspect-SetTextAngle (45.0);
-aGroup-SetPrimitivesAspect (aTextAspect);
-
-**// add a text primitive to the structure**
-Graphic3d_Vertex aPoint (1, 1, 1);
-aGroup-Text (Standard_CString (*Text*), aPoint, 16.0);
-
-
-@subsubsection occt_1621831385_143501245718 Display priorities
-
-Structure display priorities control the order in which structures are drawn. When you display a structure you specify its priority. The lower the value, the lower the display priority. When the display is regenerated the structures with the lowest priority are drawn first. For structures with the same display priority the order in which they were displayed determines the drawing order. CAS.CADE supports eleven structure display priorities.
-
-@subsubsection occt_1621831385_143501245719 About structure hierarchies
-
-The root is the top of a structure hierarchy or structure network. The attributes of a parent structure are passed to its descendants. The attributes of the descendant structures do not affect the parent. Recursive structure networks are not supported.
-
-@subsection occt_1621831385_14350124572 V3d
-@subsubsection occt_1621831385_143501245721 Overview
-The **V3d** package provides the resources to define a 3D viewer and the views attached to this viewer (orthographic, perspective). This package provides the commands to manipulate the graphic scene of any 3D object visualized in a view on screen.
-A set of high-level commands allows the separate manipulation of parameters and the result of a projection (Rotations, Zoom, Panning, etc.) as well as the visualization attributes (Mode, Lighting, Clipping, Depth-cueing, etc) in any particular view.
-
-@subsubsection occt_1621831385_143501245722 Provided services
-The V3d package is basically a set of tools directed by commands from the viewer front-end. This tool set contains methods for creating and editing classes of the viewer such as:
- * Default parameters of the viewer,
- * Views (orthographic, perspective),
- * Lighting (positional, directional, ambient, spot, headlight),
- * Clipping planes (note that only Z-clipping planes can work with the Phigs interface),
- * Instantiated sequences of views, planes, light sources, graphic structures, and picks,
- * Various package methods.
-
-@subsubsection occt_1621831385_143501245723 A programming example
-<h4>Example </h4>
-
-This sample TEST program for the V3d Package uses primary packages Xw and Graphic3d and secondary packages Visual3d, Aspect, Quantity, Phigs, math.
-
-**//Create a Graphic Device from the default DISPLAY **
-Handle(Graphic3d_GraphicDevice) GD =
-new Graphic3d_GraphicDevice(**) ;
-
-**// Create a Viewer to this Device **
-Handle(V3d_Viewer) VM = new V3d_Viewer(GD, 400.,
-// Space size
-V3d_Xpos,// Default projection Quantity_NOC_DARKVIOLET,
-// Default background
-V3d_ZBUFFER,
-// Type of visualization
-V3d_GOURAUD,
-// Shading model
-V3d_WAIT);
-// Update mode
-**// Create a structure in this Viewer **
-Handle(Graphic3d_Structure) S =
-new Graphic3d_Structure(VM-Viewer()) ;
-
-**// Type of structure **
-S-SetVisual (Graphic3d_TOS_SHADING);
-
-**// Create a group of primitives in this structure**
-Handle(Graphic3d_Group) G = new Graphic3d_Group(S) ;
-
-**// Fill this group with one polygon of size 100**
-Graphic3d_Array1OfVertex Points(0,3) ;
-Points(0).SetCoord(-100./2.,-100./2.,-100./2.) ;
-Points(1).SetCoord(-100./2., 100./2.,-100./2.) ;
-Points(2).SetCoord( 100./2., 100./2.,-100./2.) ;
-Points(3).SetCoord( 100./2.,-100./2.,-100./2.) ; Normal.SetCoord(0.,0.,1.) ;
-G-Polygon(Points,Normal) ;
-
-**// Create Ambient and Infinite Lights in this Viewer**
-Handle(V3d_AmbientLight) L1 = new V3d_AmbientLight
-(VM,Quantity_NOC_GRAY50) ;
-Handle(V3d_DirectionalLight) L2 = new V3d_DirectionalLight
-(VM,V3d_XnegYnegZneg,Quantity_NOC_WHITE) ;
-
-**// Create a 3D quality Window from the same GraphicDevice**
-Handle(Xw_Window) W =
-new Xw_Window(GD,*Test V3d*,0.5,0.5,0.5,0.5) ;
-
-**// Map this Window to this screen**
- W-Map() ;
-
-**// Create a Perspective View in this Viewer**
-Handle(V3d_PerspectiveView) V =
-new V3d_PerspectiveView(VM);
-
-**// Set the Eye position**
-V-SetEye(100.,100.,100.) ;
-
-**// Associate this View with the Window **
-V-SetWindow(W) ;
-
-**// Activate ALL defined Lights in this View **
-V-SetLightOn() ;
-
-**// Display ALL structures in this View **
-(VM-Viewer())-Display() ;
-
-**// Finally update the Visualization in this View **
-V-Update() ;
-
-@subsubsection occt_1621831385_143501245724 Glossary of view transformations
-The following terms are used to define view orientation, i.e. transformation from World Coordinates (WC) to the View Reference Coordinates system (VRC)
-
-The following terms are used to define view mapping, i.e. transformation from View Reference Coordinates (VRC) to the Normalized Projection Coordinates (NPC)
-
-The V3d_View API uses the following terms to define view orientation and mapping
-
-
-@subsubsection occt_1621831385_143501245725 Management of perspective projection
-The perspective projection allows definition of viewing volume as a truncated pyramid (frustum) with apex at the Projection Reference Point. In the View Reference Coordinate system it can be presented by the following picture:
-
-@image html /user_guides/visualization/images/visualization_image023.png
-@image latex /user_guides/visualization/images/visualization_image023.png
-
-@image html /user_guides/visualization/images/visualization_image024.png
-@image latex /user_guides/visualization/images/visualization_image024.png
-Figure 1 View Reference Coordinate System, perspective viewing volume and view mapping parameters
-
-During panning, window limits are changed, as if a sort of *frame* through which the user sees a portion of the view plane was moved over the view. The perspective frustum itself remains unchanged.
-
-The perspective projection is defined by two parameters:
- * **Depth** value defines distance between Projection Reference Point and the nearest (front) clipping plane.
- * **ZSize** defines distance between Front and Back clipping planes. The influence of this parameter is caused by the OCCT specific to center viewing volume around View Reference Point so the front and back plane distances were the same: FPD = BPD = ZSize / 2.
-**Note** that the closer the displayed object to the Projection Reference Point the more visible its perspective distortion. Thus, in order to get a good perspective it is recommended to set ZSize value comparable with the expected model size and small Depth value.
-
-However, very small Depth values might lead to inaccuracy of *fit all* operation and to non-realistic perspective distortion.
-<h4>Example </h4>
-
-**// Create a Perspective View in Viewer VM**
-Handle(V3d_PerspectiveView) V =
-new V3d_PerspectiveView(VM);
-
-**// Set the ZSize **
-V-SetZSize(2000.) ;
-
-**// Set the Depth value**
-V-SetDepth(20.) ;
-
-**// Set the current mapping as default**
-**// to be used by Reset() operation**
-V-SetViewMappingDefault() ;
-
-As an alternative to manual setting of perspective parameters the *V3d_View::DepthFitAll* function can be used.
-<h4>Example </h4>
-
-**// Display shape in Viewer VM**
-Handle(AIS_InteractiveContext) aContext =
-new AIS_InteractiveContext(VM);
-aContext-Display(shape);
-
-**// Create a Perspective View in Viewer VM**
-Handle(V3d_PerspectiveView) V =
-new V3d_PerspectiveView(VM);
-
-**// Set automatically the perspective parameters**
-V-DepthFitAll() ;
-
-**// Fit view to object size **
-V-FitAll();
-
-**// Set the current mapping as default**
-**// to be used by Reset() operation**
-V-SetViewMappingDefault() ;
-
-
-It is necessary to take into account that during rotation Z size of the view might be modified automatically to fit the model into the viewing volume.
-Make sure the Eye point never gets between the Front and Back clipping planes.
-In perspective view, changing Z size results in changed perspective effect. To avoid this, an application should specify the maximum expected Z size using V3d_View::SetZSize() method in advance.
-V3d_View::FitAll() with FitZ = Standard_True and V3d_View::ZFitAll() also change the perspective effect and should therefore be used with precautions similar to those for rotation.
-
-@subsubsection occt_1621831385_143501245726 Underlay and overlay layers management
-In addition to interactive 3d graphics displayed in the view you can display an underlying and overlying graphics: text, color scales, drawings.
-
-All of the v3d view’s graphical objects in the overlay are managed by the default layer manager (*V3d_LayerMgr*). The v3d view has a basic layer manager capable of displaying the color scale, but you can redefine this class to provide your own overlay and underlay graphics.
-
-You can assign your own layer manager to the v3d view using the following method:
- * void V3d_View::SetLayerMgr
-(const Handle (V3d_LayerMgr)& aMgr)
-
-There are three virtual methods to prepare graphics in the manager for further drawing (set up layer dimensions, draw static graphics). These methods could be redefined:
- * void V3d_LayerMgr::Begin ()
- * void V3d_LayerMgr::Redraw ()
- * void V3d_LayerMgr::End ()
-
-The layer manager controls layers* *(*Visual3d_Layer*) and layer items* *(*Visual3d_LayerItem*). Both the overlay and underlay layers can be created by the layer manager.
-
-The layer entity is presented by the *Visual3d_Layer* class. This entity provides drawing services in the layer, for example:
- * void Visual3d_Layer::DrawText
- * void Visual3d_Layer::DrawRectangle
- * void Visual3d_Layer::SetColor
- * void Visual3d_Layer::SetViewport
-
-The following example demonstrates how to draw overlay graphics by the V3d_LayerMgr:
-<h4>Example </h4>
-
-**// redefined method of V3d_LayerMgr**
-void MyLayerMgr::Redraw ()
-{
- Quantity_Color aRed (Quantity_NOC_RED);
- myOverlayLayer-SetColor (aRed);
- myOverlayLayer-DrawRectangle (0, 0, 100, 100);
-}
-
-The layer contains layer items that will be displayed on view redraw. Such items are the Visual3d_LayerItem entities. To manipulate Visual3d_LayerItem entities assigned to the layer’s internal list you can use the following methods:
- * void Visual3d_Layer::AddLayerItem
-(const Handle (Visual3d_LayerItem)& Item)
- * void Visual3d_Layer::RemoveLayerItem
-(const Handle (Visual3d_LayerItem)& Item)
- * void Visual3d_Layer::RemoveAllLayerItems ()
- * const Visual3d_NListOfLayerItem&
-Visual3d_Layer::GetLayerItemList ()
-
-The layer’s items are rendered when the following method is called by the graphical driver:
- * void Visual3d_Layer::RenderLayerItems ()
-
-The *Visual3d_LayerItem* has virtual methods that are used to render the item:
- * void Visual3d_LayerItem::RedrawLayerPrs ()
- * void Visual3d_LayerItem::ComputeLayerPrs ()
-
-The item’s presentation can be computed before drawing by the ComputeLayerPrs method to save time on redraw. It also has an additional flag that is used to tell that the presentation should be recomputed:
- * void Visual3d_LayerItem::SetNeedToRecompute
-(const Standard_Boolean NeedToRecompute)
- * Standard_Boolean Visual3d_LayerItem::IsNeedToRecompute
-
-An example of Visual3d_LayerItem is *V3d_ColorScaleLayerItem* that represents the color scale entity as the layer’s item.
-The *V3d_ColorScaleLayerItem* sends render requests to the color scale entity represented by it. As this entity (*V3d_ColorScale*) is assigned to the *V3d_LayerMgr* it uses its overlay layer’s services for drawing:
-<h4>Example </h4>
-
-**// tell V3d_ColorScale to draw itself**
-void V3d_ColorScaleLayerItem::RedrawLayerPrs ()
-{
- Visual3d_LayerItem::RedrawLayerPrs ()
- if (!MyColorScale.IsNull ())
- MyColorScale-DrawScale ();
-}
-
-**// V3d_ColorScale has a reference to a LayerMgr**
-void V3d_ColorScale::DrawScale ()
-{
- **// calls *V3d_ColorScale::PaintRect, V3d_ColorScale::PaintText*, etc …**
-}
-
-**// PaintRect method uses overlay layer of LayerMgr to draw a rectangle **
-void V3d_ColorScale::PaintRect
- (const Standard_Integer X, const Standard_Integer Y,
- const Standard_Integer W, const Standard_Integer H,
- const Quantity_Color aColor,
- const Standard_Boolean aFilled)
-{
- const Handle (Visual3d_Layer)& theLayer =
- myLayerMgr-Overlay ();
-** …**
-
-** **theLayer-SetColor (aColor);
- theLayer-DrawRectangle (X, Y, W, H);
-** …**
-}
-
-
-@subsubsection occt_1621831385_143501245727 View background styles
-There are three types of background styles available for V3d_view: solid color, gradient color and image.
-
-To set solid color for the background you can use the following methods:
- * void V3d_View::SetBackgroundColor
-(const Quantity_TypeOfColor Type,
- const Quantity_Parameter V1,
- const Quantity_Parameter V2,
- const Quantity_Parameter V3)
-This method allows you to specify the background color in RGB (red, green, blue) or HLS (hue, lightness, saturation) color spaces, so the appropriate values of the Type parameter are Quantity_TOC_RGB and Quantity_TOC_HLS. **Note** that the color value parameters V1,V2,V3 should be in the range between 0.0-1.0.
-
- * void V3d_View::SetBackgroundColor
-(const Quantity_Color &Color)
- * void V3d_View::SetBackgroundColor
-(const Quantity_NameOfColor Name)
-
-The gradient background style could be set up with the following methods:
- * void V3d_View::SetBgGradientColors
-(const Quantity_Color& Color1,
- const Quantity_Color& Color2,
- const Aspect_GradientFillMethod FillStyle,
- const Standard_Boolean update)
- * void V3d_View::SetBgGradientColors
-(const Quantity_NameOfColor Color1,
- const Quantity_NameOfColor Color2,
- const Aspect_GradientFillMethod FillStyle,
- const Standard_Boolean update)
-The Color1 and Color2 parameters define the boundary colors of interpolation, the FillStyle parameter defines the direction of interpolation. You can pass Standard_True as the last parameter to update the view.
-
-The fill style can be also set with the following method:
- * void V3d_View::SetBgGradientStyle
-(const Aspect_GradientFillMethod AMethod,
-const Standard_Boolean update)
-
-To get the current background color you can use the following methods:
- * void V3d_View::BackgroundColor
-(const Quantity_TypeOfColor Type,
- Quantity_Parameter &V1,
- Quantity_Parameter &V2,
- Quantity_Parameter &V3)
- * Quantity_Color V3d_View::BackgroundColor()
- * void V3d_View::GradientBackgroundColors
-(Quantity_Color& Color1,
- Quantity_Color& Color2)
- * Aspect_GradientBackground GradientBackground()
-
-To set the image as a background and change the background image style you can use the following methods:
- * void V3d_View::SetBackgroundImage
-(const Standard_CString FileName,
- const Aspect_FillMethod FillStyle,
- const Standard_Boolean update)
- * void V3d_View::SetBgImageStyle
-(const Aspect_FillMethod FillStyle,
- const Standard_Boolean update)
-
-The FileName parameter defines the image file name and the path to it, the FillStyle parameter defines the method of filling the background with the image. The methods are:
- * Aspect_FM_NONE: draw the image in the default position
- * Aspect_FM_CENTERED: draw the image at the center of the view
- * Aspect_FM_TILED: tile the view with the image
- * Aspect_FM_STRETCH: stretch the image over the view
-
-@subsubsection occt_1621831385_143501245728 User-defined clipping planes
-The ability to define custom clipping planes could be very useful for some tasks. The v3d view provides such an opportunity.
-
-The V3d_Plane class provides the services of clipping planes: it holds the plane equation coefficients and provides its graphical representation. To set and get plane equation coefficients you can use the following methods:
- * void V3d_Plane::SetPlane
-(const Quantity_Parameter A,
- const Quantity_Parameter B,
- const Quantity_Parameter C,
- const Quantity_Parameter D)
- * void V3d_Plane::Plane
-(Quantity_Parameter& A,
- Quantity_Parameter& B,
- Quantity_Parameter& C,
- Quantity_Parameter& D)
-
- V3d_Plane also provides display services:
- * void V3d_Plane::Display
-(const Handle(V3d_View)& aView,
- const Quantity_Color& aColor)
- * void V3d_Plane::Erase ()
- * Standard_Boolean V3d_Plane::IsDisplayed ()
-The Display method could be redefined to provide custom representation of the clipping plane.
-
-The clipping planes could be activated with the following methods:
- * void V3d_View::SetPlaneOn
-(const Handle(V3d_Plane)& MyPlane)
- * void V3d_View::SetPlaneOn ()
-The first method appends the given V3d_Plane to the internal list of user-defined clipping planes of a view and activates it. If the plane is already in the list, it becomes activated. The second method activates all of the planes defined for the view.
-
-The clipping planes could be deactivated with the similar methods:
- * void V3d_View::SetPlaneOff
-(const Handle(V3d_Plane)& MyPlane)
- * void V3d_View::SetPlaneOff ()
-
-The only difference is that these methods remove the user-defined clipping planes from the internal list. Thus, the view retains only active clipping planes.
-
-You can iterate through the active planes using the following methods:
- * void V3d_View::InitActivePlanes ()
-sets the iterator to the beginning of the internal list of clipping planes
- * Standard_Boolean V3d_View::MoreActivePlanes ()
-returns Standard_True if there are more active planes to return
- * void V3d_View::NextActivePlanes ()
-sets the iterator to the next active plane in the list
- * Handle(V3d_Plane) V3d_View::ActivePlane ()
-returns the active plane
-
-or check if a certain clipping plane has been activated:
- * Standard_Boolean V3d_View::IsActivePlane
-(const Handle (V3d_Plane)& aPlane)The number of clipping planes is limited. The following method allows you to check if it is possible to activate at least one more plane in the view or the limit has been reached:
- * Standard_Boolean V3d_View::IfMorePlanes ()
-<h4>Example </h4>
-
-**// try to use an existing clipping plane or create a new one**
-Handle(V3d_Plane) aCustomPlane;
-myView-InitActivePlanes ();
-if (myView-MoreActivePlanes ())
- aCustomPlane = myView-ActivePlane ();
-else
- aCustomPlane = new V3d_Plane ();
-
-**// calculate new coefficients**
-Standard_Real a, b, c, d;
-Standard_Real x = 0.0, y = 0.0, z = 10.0;
-Standard_Real dx = 0.0, dy = 0.0, dz = 1.0;
-gp_Pln aPln (gp_Pnt (x, y, z), gp_Dir (dx, dy, dz));
-aPln.Coefficients (a, b, c, d);
-
-**// update plane**
-aCustomPlane-SetPlane (a, b, c, d);
-myView-SetPlaneOn (aCustomPlane);
-
-@subsubsection occt_1621831385_143501245729 Dumping a 3D scene into an image file
-The 3D scene displayed in the view could be dumped in high resolution into an image file. The high resolution (8192x8192 on some implementations) is achieved using the Frame Buffer Objects (FBO) provided by the graphic driver. Frame Buffer Objects enable off-screen rendering into a virtual view to produce images in the background mode (without displaying any graphics on the screen).
-
-The V3d_View has the following methods for dumping the 3D scene:
- * Standard_Boolean V3d_View::Dump
-(const Standard_CString theFile,
- const Image_TypeOfImage theBufferType)
- * Standard_Boolean V3d_View::Dump
-(const Standard_CString theFile,
- const Aspect_FormatOfSheetPaper theFormat,
- const Image_TypeOfImage theBufferType)
-These methods dump the 3D scene into an image file passed by its name and path as theFile.
-The raster image data handling algorithm is based on the Image_PixMap class. The supported extensions are *.png*, *.bmp*, *.jpg*, *.png*.
-The first method dumps the scene into an image file with the view dimensions. The second method allows you to make the dimensions of the output image compatible to a certain format of printing paper passed by theFormat argument.
-The value passed as theBufferType argument defines the type of the buffer for an output image (RGB, RGBA, floating-point, RGBF, RGBAF). Both methods return Standard_True if the scene has been successfully dumped.
-**Please note** that dumping the image for a paper format with large dimensions is a memory consuming operation, it might be necessary to take care of preparing enough free memory to perform this operation.
-
- * Handle_Image_PixMap V3d_View::ToPixMap
-(const Standard_Integer theWidth,
- const Standard_Integer theHeight,
- const Image_TypeOfImage theBufferType,
- const Standard_Boolean theForceCentered)
-This method allows you to dump the displayed 3d scene into a pixmap with a width and height passed as theWidth and theHeight arguments.
-The value passed as theBufferType argument defines the type of the buffer for a pixmap (RGB, RGBA, floating-point, RGBF, RGBAF).
-The last parameter allows you to center the 3D scene on dumping.
-
-All these methods assume that you have created a view and displayed a 3d scene in it. However, the window used for such a view could be virtual, so you can dump the 3d scene in the background mode without displaying it on the screen. To use such an opportunity you can perform the following steps:
-1) Create a graphic device;
-2) Create a window;
-3) Set up the window as virtual, Aspect_Window::SetVirtual ();
-4) Create a view and an interactive context;
-5) Assign the virtual window to the view;
-6) Display a 3D scene;
-7) Use one of the functions described above to dump the 3D scene.
-
-The following example demonstrates this procedure for the WNT_Window:
-<h4>Example </h4>
-
-**// create a graphic device**
-Handle (WNT_GraphicDevice) aDevice =
- new Graphic3d_WNTGraphicDevice ();
-
-**// create a window**
-Standard_Integer aDefWidth = 800;
-Standard_Integer aDefHeight = 600;
-Handle (WNT_WClass) aWClass =
- new WNT_WClass (*Virtual Class*,DefWindowProc,
- CS_VREDRAW | CS_HREDRAW, 0, 0,
- ::LoadCursor (NULL, IDC_ARROW));
-Handle (WNT_Window) aWindow =
- new WNT_Window (aDevice, *VirtualWnd*, aWClass,
- WS_OVERLAPPEDWINDOW, 0, 0,
- aDefWidth, aDefHeight);
-
-**// set up the window as virtual**
-aWindow-SetVirtual (Standard_True);
-
-**// create a view and an interactive context**
-Handle (V3d_Viewer) aViewer =
- new V3d_Viewer (aDevice,
- Standard_ExtString (*Virtual*));
-Handle (AIS_InteractiveContext) aContext =
- new AIS_InteractiveContext (aViewer);
-Handle (V3d_View) aView = aViewer-CreateView ();
-
-**// assign the virtual window to the view**
-aView-SetWindow (aWindow);
-
-**// display a 3D scene**
-Handle (AIS_Shape) aBox =
- new AIS_Shape (BRepPrimAPI_MakeBox (5, 5, 5));
-aContext-Display (aBox);
-aView-FitAll();
-
-**// dump the 3D scene into an image file**
-aView-Dump (*3dscene.png*);
-
-@subsubsection occt_1621831385_1435012457210 Printing a 3D scene
-The contents of a view can be printed out. Moreover, the OpenGl graphic driver used by the v3d view supports printing in high resolution. The print method uses the OpenGl frame buffer (Frame Buffer Object) for rendering the view contents and advanced print algorithms that allow printing in, theoretically, any resolution.
-
-The following method prints the view contents:
- * void V3d_View::Print
-(const Aspect_Handle hPrnDC,
- const Standard_Boolean showDialog,
- const Standard_Boolean showBackground,
- const Standard_CString filename,
- const Aspect_PrintAlgo printAlgorithm)
-The hPrnDC is the printer device handle. You can pass your own printer handle or *NULL* to select the printer by the default dialog. In that case you can use the default dialog or pass *Standard_False* as the showDialog argument to select the default printer automatically.
-You can define the filename for the printer driver if you want to print out the result into a file.
-If you do not want to print the background, you can pass *Standard_False* as the showBackground argument.
-The printAlgorithm argument allows you to choose between two print algorithms that define how the 3d scene is mapped to the print area when the maximum dimensions of the frame buffer are smaller than the dimensions of the print area. You can pass the following values as the printAlgorithm argument:
- * Aspect_PA_STRETCH,
- * Aspect_PA_TILE
-
-The first value defines the stretch algorithm: the scene is drawn with the maximum possible frame buffer dimensions and then is stretched to the whole printing area. The second value defines TileSplit algorithm: covering the whole printing area by rendering multiple parts of the viewer.
-
-**Please note** that at the moment printing is implemented only for Windows.
-
-@subsubsection occt_1621831385_1435012457211 Vector image export
-The 3D content of a view can be exported to the vector image file format. The vector image export is powered by the GL2PS library. You can export your 3D scenes into a file format supported by the GL2PS library: PostScript (PS), Encapsulated PostScript (EPS), Portable Document Format (PDF), Scalable Vector Graphics (SVG), LaTeX file format and Portable LaTeX Graphics (PGF).
-
-The following method of Visual3d_View class allows you to export your 3D scene:
- * 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)
-The FileName defines the output image file name and the Format argument defines the output file format:
- * Graphic3d_EF_PostScript (PS),
- * Graphic3d_EF_EhnPostScript (EPS),
- * Graphic3d_EF_TEX (TEX),
- * Graphic3d_EF_PDF (PDF),
- * Graphic3d_EF_SVG (SVG),
- * Graphic3d_EF_PGF (PGF)
-
-The aSortType parameter defines the GL2PS sorting algorithm for the primitives. The Precision, ProgressBarFunc and ProgressObject parameters are implemented for future uses and at the moment have no effect.
-
-The Export method supports only basic 3d graphics and has several limitations:
- * Rendering large scenes could be slow and can lead to large output files;
- * Transparency is only supported for PDF and SVG output;
- * Textures and some effects are not supported by the GL2PS library.
-@section occt_1621831385_1090976821 2D Presentations
-@subsection occt_1621831385_10909768211 Glossary of 2D terms
-
-@subsubsection occt_1621831385_10909768212 Creating a 2D scene
-
-To create 2D graphic objects and display them on the screen, follow the procedure below:
-**1. **Create the marker map.
-**2. **Create the attribute maps.
-**3. **Define the connection to a graphic device.
-**4. **Create a window.
-**5. **Create a window driver.
-**6. **Install the maps.
-**7. **Create a view.
-**8. **Create a view mapping.
-**9. **Create one or more graphic objects associated with a view.
-**10. **Create primitives and associate them with a graphic object.
-**11. **Get the workspace of the driver.
-**12. **Update the view in the driver.
-
-@subsubsection occt_1621831385_109097682121 Creating the marker map
-
-The marker map defines a set of markers available to the application. Markers may be predefined, Aspect_Tom_X for example, or user-defined.
-
-@image html /user_guides/visualization/images/visualization_image025.jpg
-@image latex /user_guides/visualization/images/visualization_image025.jpg
-Figure 15. Markers.
-
-The markers are manipulated by an index.
-A marker map is defined as follows:
-<h4>Example </h4>
-
-Handle(Aspect_MarkMap) mkrmap = new Aspect_MarkMap;
-Aspect_MarkMapEntry mkrmapentry1 (1, Aspect_TOM_X)
-Aspect_MarkMapEntry mkrmapentry2 (2, Aspect_TOM_PLUS)
-Aspect_MarkMapEntry mkrmapentry3 (3, Aspect_O_PLUS)
-
-mkrmap-AddEntry (mkrmapentry1);
-mkrmap-AddEntry (mkrmapentry2);
-mkrmap-AddEntry (mkrmapentry3);
-
-
-@subsubsection occt_1621831385_109097682122 Creating the attribute maps
-
-Maps are created for color, line type, line width, and text font. A map is used to reference a given attribute by an integer value.
-
-
-@image html /user_guides/visualization/images/visualization_image026.jpg
-@image latex /user_guides/visualization/images/visualization_image026.jpg
-Figure 16. Attributes
-
-The color map
-The hardware system will certainly have default colors available but to make the application portable and durable, it must be insulated from external factors by defining the set of colors to be used.
-
-A color map is defined as follows:
-
-<h4>Example </h4>
-
-Handle(Aspect_GenericColorMap) colmap =
-new Aspect_GenericColorMap;
-Aspect_ColorMapEntry colmapentry;
-Quantity_Color YELLOW (Quantity_NOC_YELLOW); colmapentry.SetValue (1, YELLOW);
-colmap-AddEntry (colmapentry);
-Quantity_Color RED (Quantity_NOC_RED);
-colmapentry.SetValue (2, RED);
-colmap-AddEntry (colmapentry);
-Quantity_Color GREEN (Quantity_NOC_GREEN); colmapentry.SetValue (3, GREEN);
-colmap-AddEntry (colmapentry);
-
-You can include as many colors in your color map as you like, though there are some restrictions related to the hardware.
-
-<h4>The type map </h4>
-Lines can be solid, dotted, dashed, dot-dashed, or user defined. For a user-defined type the pattern of solid and blank sections is listed.
-
-A type map is defined as follows:
-
-<h4>Example </h4>
-
-Handle(Aspect_TypeMap) typmap = new Aspect_TypeMap;
-{TColQuantity_Array1OfLength myLineStyle(1,2); myLineStyle.SetValue(1, 2); // the solid part is 2 mm myLineStyle.SetValue(2, 3); // the blank part is 3 mm Aspect_LineStyle linestyle1 (Aspect_TOL_SOLID); Aspect_LineStyle linestyle2 (Aspect_TOL_DASH); Aspect_LineStyle linestyle3 (myLineStyle);
-Aspect_LineStyle linestyle4 (Aspect_TOL_DOTDASH); Aspect_TypeMapEntry typmapentry1 (1, linestyle1); Aspect_TypeMapEntry typmapentry2 (2, linestyle2); Aspect_TypeMapEntry typmapentry3 (3, linestyle3); Aspect_TypeMapEntry typmapentry4 (4, linestyle4);
-typmap-AddEntry (typmapentry1);
-typmap-AddEntry (typmapentry2);
-typmap-AddEntry (typmapentry3);
-typmap-AddEntry (typmapentry4);
-
-
-*NOTE*
-*The line type enumeration and all the other enumerations are available from the Aspect package.*
-
-<h4>The width map </h4>
-The width map defines a set of levels of line thickness available to your application. Widths and all other distances are specified in mms or as members of an enumeration.
-
-A width map is defined as follows:
-<h4>Example </h4>
-
-Handle(Aspect_WidthMap) widmap = new Aspect_WidthMap; Aspect_WidthMapEntry widmapentry1 (1,Aspect_WOL_THIN); Aspect_WidthMapEntry widmapentry2 (2,Aspect_WOL_MEDIUM); Aspect_WidthMapEntry widmapentry3 (3, 3); Aspect_WidthMapEntry widmapentry4 (4, 40); widmap-AddEntry (widmapentry1); widmap-AddEntry (widmapentry2); widmap-AddEntry (widmapentry3); widmap-AddEntry (widmapentry4);
-
-The font map
-The font map defines a set of text fonts available to your application. Default fonts enumerated in Aspect may be used with addition of any other font known to the X driver, specifying the size and slant angle desired.
-
-A font map is defined as follows:
-
-<h4>Example </h4>
-
-Handle(Aspect_FontMap) fntmap = new Aspect_FontMap; Aspect_FontStyle fontstyle1 (*Courier-Bold*, 3, 0.0); Aspect_FontStyle fontstyle2 (*Helvetica-Bold*, 3, 0.0); Aspect_FontStyle fontstyle3 (Aspect_TOF_DEFAULT); Aspect_FontMapEntry fntmapentry1 (1, fontstyle1); Aspect_FontMapEntry fntmapentry2 (2, fontstyle2); Aspect_FontMapEntry fntmapentry3 (3, fontstyle3); fntmap-AddEntry (fntmapentry1); fntmap-AddEntry (fntmapentry2); fntmap-AddEntry (fntmapentry3);
-
-
-@subsubsection occt_1621831385_109097682123 Creating a 2D driver (a Windows example)
-
-<h4>Example </h4>
-
-Handle(WNT_GraphicDevice) TheGraphicDevice = ...; TCollection_ExtendedString aName(*2DV*);
-my2DViewer = new V2d_Viewer(TheGraphicDevice,
-aName.ToExtString());
-@subsubsection occt_1621831385_109097682124 Installing the maps
-
-When the 2D viewer has been created, you may install the maps created earlier.
-<h4>Example </h4>
-
-my2DViewer-SetColorMap(colormap);
-my2DViewer-SetTypeMap(typmap);
-my2DViewer-SetWidthMap(widthmap);
-my2DViewer-SetFontMap(fntmap);
-
-
-@subsubsection occt_1621831385_109097682125 Creating a view (a Windows example)
-
-It is assumed that a valid Windows window may be accessed via the method GetSafeHwnd().
-<h4>Example </h4>
-
-Handle(WNT_Window) aWNTWindow;
-aWNTWindow = new
-WNT_Window(TheGraphicDevice, GetSafeHwnd());
-aWNTWindow-SetBackground(Quantity_NOC_MATRAGRAY); Handle(WNT_WDriver) aDriver = new
-WNT_WDriver(aWNT_Window);
-myV2dView = new V2d_View(aDriver, my2dViewer, 0,0,50);
-// 0,0: view center and 50: view size
-
-
-@subsubsection occt_1621831385_109097682126 Creating the presentable object
-
-Follow the procedure below to compute the presentable object.
-**1. **Build a presentable object inheriting from AIS_InteractiveObject (refer to Chapter 1 Fundamental Concepts, Section Presentable objects)
-**2. **Re-use the graphic object provided as an argument of the Compute method for your presentable object.
-<h4>Example </h4>
-
-void
-myPresentableObject::Compute (
-const Handle(Prs_Mgr_PresentationManager2D)&
-aPresentationManager,
-const Handle(Graphic2d_GraphicObject)& aGrObj,
-const Standard_Integer aMode)
-{
-...
-}
-
-
-@subsubsection occt_1621831385_109097682127 Creating a primitive
-
-Primitives may be created using the resources of the Graphic2d package. Here for example an array is instantiated and filled with a set of three circles with different radii, line widths, and colors, centered on given origin coordinates (4.0, 1.0) and passed to the specified graphic object (go).
-<h4>Example </h4>
-
-Handle(Graphic2d_Circle) tcircle[4]; Quantity_Length radius; for (i=1; i=4; i++) { radius = Quantity_Length (i); tcircle[i-1] = new Graphic2d_Circle (aGrObj, 4.0, 1.0, radius);
-tcircle[i-1]-SetColorIndex (i);
-tcircle[i-1]-SetWidthIndex (1); }
-
-Add a filled rectangle to your graphic object. It will be put outside of your view mapping.
-<h4>Example </h4>
-
-TColStd_Array1OfReal aListX (1, 5);
-TColStd_Array1OfReal aListY (1, 5);
-aListX (1) = -7.0; aListY (1) = -1.0;
-aListX (2) = -7.0; aListY (2) = 1.0;
-aListX (3) = -5.0; aListY (3) = 1.0;
-aListX (4) = -5.0; aListY (4) = -1.0;
-aListX (5) = -7.0; aListY (5) = -1.0;
-Handle(Graphic2d_Polyline) rectangle =
-new Graphic2d_Polyline (go, 0., 0., aListX, aListY); rectangle-SetColorIndex (6);
-rectangle-SetWidthIndex (1);
-rectangle-SetTypeOfPolygonFilling(Graphic2d_TOPF_FILLED); rectangle-SetDrawEdge(Standard_True);
-*A given primitive can only be assigned to a single graphic object.*
-
-@image html /user_guides/visualization/images/visualization_image027.jpg
-@image latex/user_guides/visualization/images/visualization_image027.jpg
-Figure 17. Graphic object and view mapping in the space model.
-
-@subsection occt_1621831385_10909768213 Dealing with images
-
-@subsubsection occt_1621831385_109097682131 General case
-
-Images are primitives too. The graphic resources can currently accept all image types described in the *AlienImage* package. In the following example only **.xwd **formats are accepted.
-
-Define the primitive Image in the GraphicObject.
-<h4>Example </h4>
-
-Handle(Image_Image) anImage; if (XwdImage || RgbImage) { anImage = AlienUser-ToImage (); Handle(Graphic2d_Image) gImage = new Graphic2d_Image
-(aGrObj, anImage, 0., 0., 0., 0., Aspect_CP_CENTER); }
-
-
-<h4>NOTE</h4>
-*The above constructor for image takes as arguments the graphic object which will contain the image, the image itself, XY coordinates for the center, XY offsets in the device space, and a cardinal point value to give a direction of display. *
-
-Now update the view in the driver. In other words, draw the image.
-
-<h4>Example </h4>
-
-Standard_Boolean clear = Standard_True
-view-Update (driver, viewmapping, W/2., H/2., scale, clear);
-
-
-@subsubsection occt_1621831385_109097682132 Specific case: xwd format
-
-When the manipulated image is stored with the xwd format, a special class Graphic2d_ImageFile may be used to increase performance.
-<h4>Example </h4>
-
-OSD_Path aPath (*C:/test.xwd*);
-OSD_File aFile (aPath);
-Handle(Graphic2d_ImageFile)gImageFile =
-new Graphic2d_ImageFile (aGrObj,
-aFile,
-0.,0.,
-0.,0.,
-Aspect_CP_Center, 1);
-gImageFile-SetZoomable(Standard_True);
-
-
-The graphic contains now an image, which is manipulated as a primitive.
-
-
-@subsection occt_1621831385_10909768214 Dealing with text
-
-The constructor for the Graphic2d_Text takes a reference point in the space model and an angle (in radians) as its arguments, as well as the graphic object to which it is assigned. Note that the angle is ignored unless the Xdps driver, which allows angled text, is in use.
-<h4>Example </h4>
-
-TCollection_ExtendedString str1 (*yellow Courier-bold*); TCollection_ExtendedString str2 (*red Helevetica-bold*); TCollection_ExtendedString str3 (*green Aspect_TOF_DEFAULT*); Handle(Graphic2d_Text) t1 = new Graphic2d_Text
-(aGrObj, str1, 0.3, 0.3, 0.0);
-Handle(Graphic2d_Text) t2 = new Graphic2d_Text
-(aGrObj, str2, 0.0, 0.0, 0.0);
-Handle(Graphic2d_Text) t3 = new Graphic2d_Text
-(aGrObj, str3, -0.3, -0.3, 0.0);
-t1-SetFontIndex (1); t1-SetColorIndex (1);
-t2-SetFontIndex (2); t2-SetColorIndex (2);
-t3-SetFontIndex (3); t3-SetColorIndex (3);
-
-
-@subsection occt_1621831385_10909768215 Dealing with markers
-
-A marker is a primitive that retains its original size when the view is zoomed. Markers can be used, for example, as references to dimensions.
-
-@subsubsection occt_1621831385_109097682151 Vectorial markers
-Every marker takes an XY point as its reference point. The constructor also takes another pair of XY values as an offset from this reference point. For CircleMarker and EllipsMarker this offset point is its center. For PolylineMarker this offset point is its origin i.e. the first point in its list.
-In the example below, a rectangle is created using Graphic2d_Polyline.
-<h4>Example </h4>
-
-TColStd_Array1OfReal rListX (1, 5);
-TColStd_Array1OfReal rListY (1, 5);
-rListX (1) = -0.3; rListY (1) = -0.3;
-rListX (2) = -0.3; rListY (2) = 0.3;
-rListX (3) = 0.3; rListY (3) = 0.3;
-rListX (4) = 0.3; rListY (4) = -0.3;
-rListX (5) = -0.3; rListY (5) = -0.3;
-Handle(Graphic2d_Polyline) rp =
-new Graphic2d_Polyline (aGrObj, rListX, rListY);
-
-
-Two Graphic2d_CircleMarkers are created. The first one has no offset from its center. The second is constrained to be a given offset from a reference point.
-<h4>Example </h4>
-
-Handle(Graphic2d_CircleMarker) rc1 = new
-Graphic2d_CircleMarker
-(aGrObj, 0.04, 0.03, 0.0, 0.0, 0.01); Handle(Graphic2d_CircleMarker) rc2 = new
-Graphic2d_CircleMarker
-(aGrObj, 0.03, -0.03, 0.01, 0.0, 0.01);
-window-Clear ();
-
-@image html /user_guides/visualization/images/visualization_image028.jpg
-@image latex /user_guides/visualization/images/visualization_image028.jpg
-Figure 18. Figure of zoom and attachment point of a marker.
-
-
-@subsubsection occt_1621831385_109097682152 Indexed markers
-
-Once the marker map has been created, indexed markers may be added to a graphic object.
-<h4>Example </h4>
+The text attributes for the group could be defined with the *Graphic3d_AspectText3d* attributes group.
+To add any text to the graphic structure you can use the following methods:
+~~~~~
+void Graphic3d_Group::Text (const Standard_CString theText,
+ const Graphic3d_Vertex& thePoint,
+ const Standard_Real theHeight,
+ const Quantity_PlaneAngle theAngle,
+ const Graphic3d_TextPath theTp,
+ const Graphic3d_HorizontalTextAlignment theHta,
+ const Graphic3d_VerticalTextAlignment theVta,
+ const Standard_Boolean theToEvalMinMax);
+~~~~~
+*theText* parameter is the text string, *thePoint* is the three-dimensional position of the text, *theHeight* is the text height, *theAngle* 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).
+*theTp* parameter defines the text path, *theHta* is the horizontal alignment of the text, *theVta* is the vertical alignment of the text.
+You can pass FALSE as *theToEvalMinMax* if you do not want the graphic3d structure boundaries to be affected by the text position.
+
+**Note** that the text orientation angle can be defined by *Graphic3d_AspectText3d* attributes.
+~~~~~
+void Graphic3d_Group::Text (const Standard_CString theText,
+ const Graphic3d_Vertex& thePoint,
+ const Standard_Real theHeight,
+ const Standard_Boolean theToEvalMinMax);
+void Graphic3d_Group::Text (const TCcollection_ExtendedString& theText,
+ const Graphic3d_Vertex& thePoint,
+ const Standard_Real theHeight,
+ const Quantity_PlaneAngle theAngle,
+ const Graphic3d_TextPath theTp,
+ const Graphic3d_HorizontalTextAlignment theHta,
+ const Graphic3d_VerticalTextAlignment theVta,
+ const Standard_Boolean theToEvalMinMax);
+void Graphic3d_Group::Text (const TCcollection_ExtendedString& theText,
+ const Graphic3d_Vertex& thePoint,
+ const Standard_Real theHeight,
+ const Standard_Boolean theToEvalMinMax);
+~~~~~
+
+See the example:
+~~~~~
+// get the group
+Handle(Graphic3d_Group) aGroup = thePrs->NewGroup();
+
+// change the text aspect
+Handle(Graphic3d_AspectText3d) aTextAspect = new Graphic3d_AspectText3d();
+aTextAspect->SetTextZoomable (true);
+aTextAspect->SetTextAngle (45.0);
+aGroup->SetPrimitivesAspect (aTextAspect);
+
+// add a text primitive to the structure
+Graphic3d_Vertex aPoint (1, 1, 1);
+aGroup->Text (Standard_CString ("Text"), aPoint, 16.0);
+~~~~~
+
+@subsubsection occt_visu_4_2_6 Materials
+
+A *Graphic3d_MaterialAspect* is defined by:
+ * Transparency;
+ * Diffuse reflection -- a component of the object color;
+ * Ambient reflection;
+ * Specular reflection -- a component of the color of the light source;
+ * Refraction index.
+
+The following items are required to determine the three colors of reflection:
+ * Color;
+ * Coefficient of diffuse reflection;
+ * Coefficient of ambient reflection;
+ * Coefficient of specular reflection.
+
+@subsubsection occt_visu_4_2_7 Textures
+
+A *texture* is defined by a name.
+Three types of texture are available:
+ * 1D;
+ * 2D;
+ * Environment mapping.
+
+@subsubsection occt_visu_4_2_8 Shaders
+
+OCCT visualization core supports GLSL shaders. Shaders can be assigned to a generic presentation by its drawer attributes (Graphic3d aspects). To enable custom shader for a specific AIS_Shape in your application, the following API functions can be used:
+
+~~~~~
+// Create shader program
+Handle(Graphic3d_ShaderProgram) aProgram = new Graphic3d_ShaderProgram();
+
+// Attach vertex shader
+aProgram->AttachShader (Graphic3d_ShaderObject::CreateFromFile (Graphic3d_TOS_VERTEX, "<Path to VS>"));
+
+// Attach fragment shader
+aProgram->AttachShader (Graphic3d_ShaderObject::CreateFromFile (Graphic3d_TOS_FRAGMENT, "<Path to FS>"));
+
+// Set values for custom uniform variables (if they are)
+aProgram->PushVariable ("MyColor", Graphic3d_Vec3 (0.0f, 1.0f, 0.0f));
+
+// Set aspect property for specific AIS_Shape
+theAISShape->Attributes()->ShadingAspect()->Aspect()->SetShaderProgram (aProgram);
+~~~~~
+
+@subsection occt_visu_4_3 Graphic attributes
+
+@subsubsection occt_visu_4_3_1 Aspect package overview
+
+The *Aspect* package provides classes for the graphic elements in the viewer:
+ * Groups of graphic attributes;
+ * Edges, lines, background;
+ * Window;
+ * Driver;
+ * Enumerations for many of the above.
+
+@subsection occt_visu_4_4 3D view facilities
+
+@subsubsection occt_visu_4_4_1 Overview
+
+The *V3d* package provides the resources to define a 3D viewer and the views attached to this viewer (orthographic, perspective). This package provides the commands to manipulate the graphic scene of any 3D object visualized in a view on screen.
-Handle (Graphic2d_Marker) xmkr = new Graphic2d_Marker
-(aGrObj, 1, 0.04, 0.03, 0.0, 0.0, 0.0);
-Handle (Graphic2d_Marker) plusmkr = new Graphic2d_Marker
-(aGrObj, 2, 0.04, 0.0, 0.0, 0.0, 0.0);
-Handle (Graphic2d_Marker) oplusmkr = new Graphic2d_Marker
-(aGrObj, 3, 0.04, -0.03, 0.0, 0.0, 0.0);
+A set of high-level commands allows the separate manipulation of parameters and the result of a projection (Rotations, Zoom, Panning, etc.) as well as the visualization attributes (Mode, Lighting, Clipping, etc.) in any particular view.
-@subsection occt_1621831385_10909768216 Dragging with Buffers
+The *V3d* package is basically a set of tools directed by commands from the viewer front-end. This tool set contains methods for creating and editing classes of the viewer such as:
+ * Default parameters of the viewer,
+ * Views (orthographic, perspective),
+ * Lighting (positional, directional, ambient, spot, headlight),
+ * Clipping planes,
+ * Instantiated sequences of views, planes, light sources, graphic structures, and picks,
+ * Various package methods.
-A **buffer** is used to draw very quickly a partial area of the scene without deleting the background context.
- A buffer contains a set of graphic objects or primitives which are to be moved, rotated or scaled above the scene in the front planes of the view (in this case, double-buffering is not active). For example:
+@subsubsection occt_visu_4_4_2 A programming example
-**1. **Draw a very complex scene in the view.
-**2. **Create a buffer of primitives with the primitive color index 10 and the font index 4:
-buffer = new Graphic2d_Buffer (view, 0., 0., 10, 4);
+This sample TEST program for the *V3d* Package uses primary packages *Xw* and *Graphic3d* and secondary packages *Visual3d, Aspect, Quantity* and *math*.
-**3. **Add graphic objects or primitives:
-buffer-Add (go);
-buffer-Add (tcircle[1]);
-buffer-Add (t1);
+~~~~~
+// create a default display connection
+Handle(Aspect_DisplayConnection) aDispConnection = new Aspect_DisplayConnection();
+// create a Graphic Driver
+Handle(OpenGl_GraphicDriver) aGraphicDriver = new OpenGl_GraphicDriver (aDispConnection);
+// create a Viewer to this Driver
+Handle(V3d_Viewer) VM = new V3d_Viewer (aGraphicDriver);
+VM->SetDefaultBackgroundColor (Quantity_NOC_DARKVIOLET);
+VM->SetDefaultViewProj (V3d_Xpos);
+// Create a structure in this Viewer
+Handle(Graphic3d_Structure) aStruct = new Graphic3d_Structure (VM->Viewer());
-**4. **Post the buffer in the view:
-buffer-Post ();
+// Type of structure
+aStruct->SetVisual (Graphic3d_TOS_SHADING);
-**5. **Move, rotate or scale the buffer above the view:
-buffer-Move (x,y); buffer-Rotate (alpha);
-buffer-Scale (zoom_factor);
+// Create a group of primitives in this structure
+Handle(Graphic3d_Group) aPrsGroup = new Graphic3d_Group (aStruct);
-**6. **Unpost the buffer from the view:
-buffer-Unpost ();
-@section occt_1621831385_86393950 2D Resources
+// Fill this group with one quad of size 100
+Handle(Graphic3d_ArrayOfTriangleStrips) aTriangles = new Graphic3d_ArrayOfTriangleStrips (4);
+aTriangles->AddVertex (-100./2., -100./2., 0.0);
+aTriangles->AddVertex (-100./2., 100./2., 0.0);
+aTriangles->AddVertex ( 100./2., -100./2., 0.0);
+aTriangles->AddVertex ( 100./2., 100./2., 0.0);
+aPrsGroup->AddPrimitiveArray (aTriangles);
+aPrsGroup->SetGroupPrimitivesAspect (new Graphic3d_AspectFillArea3d());
+// Create Ambient and Infinite Lights in this Viewer
+Handle(V3d_AmbientLight) aLight1 = new V3d_AmbientLight (VM, Quantity_NOC_GRAY50);
+Handle(V3d_DirectionalLight) aLight2 = new V3d_DirectionalLight (VM, V3d_XnegYnegZneg, Quantity_NOC_WHITE);
-The 2D resources include the Graphic2d, Image, AlienImage, and V2d packages.
+// Create a 3D quality Window with the same DisplayConnection
+Handle(Xw_Window) aWindow = new Xw_Window (aDispConnection, "Test V3d", 0.5, 0.5, 0.5, 0.5);
+// Map this Window to this screen
+aWindow->Map();
-@subsection occt_1621831385_863939501 Graphic2d
+// Create a Perspective View in this Viewer
+Handle(V3d_View) aView = new V3d_View (VM);
+aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Perspective);
+// Associate this View with the Window
+aView ->SetWindow (aWindow);
+// Display ALL structures in this View
+VM->Viewer()->Display();
+// Finally update the Visualization in this View
+aView->Update();
+// Fit view to object size
+V->FitAll();
+~~~~~
+@subsubsection occt_visu_4_4_3 Define viewing parameters
-@subsubsection occt_1621831385_8639395011 Overview
+View 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:
-The **Graphic2d** package is used to create a 2D graphic object. Each object, called a GraphicObject, is composed of primitives. Each primitive is a class and contains attributes. Each primitive has its own Draw method.
+* **Eye** -- defines the observer (camera) position. Make sure the Eye point never gets between the Front and Back clipping planes.
-A Graphic2d_Image is created from an Image from the Image package.
+* **Center** -- defines the origin of View Reference Coordinates (where camera is aimed at).
+* **Direction** -- defines the direction of camera view (from the Eye to the Center).
-@subsubsection occt_1621831385_8639395012 The services provided
+* **Distance** -- defines the distance between the Eye and the Center.
-The **Graphic2d** packages provides classes for creating the following primitives:
- * Circle
- * Curve
- * Ellips
- * InfiniteLine
- * Polyline
- * Segment
- * SetOfSegments
- * Text
- * Marker
- * SetOfMarkers
- * VectorialMarker
- * CircleMarker
+* **Front** Plane -- defines the position of the front clipping plane in View Reference Coordinates system.
-**2D Resources **
- * PolylineMarker
- * EllipsMarker
- * Image
- * ImageFile
- * SetOfCurves
+* **Back** Plane -- defines the position of the back clipping plane in View Reference Coordinates system.
+* **ZNear** -- defines the distance between the Eye and the Front plane.
+* **ZFar** -- defines the distance between the Eye and the Back plane.
-@subsection occt_1621831385_863939502 Image
+Most 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:
-@subsubsection occt_1621831385_8639395021 Overview
+Example:
+~~~~~
+// rotate camera by X axis on 30.0 degrees
+gp_Trsf aTrsf;
+aTrsf.SetRotation (gp_Ax1 (gp_Pnt (0.0, 0.0, 0.0), gp_Dir (1.0, 0.0, 0.0)), 30.0);
+aView->Camera()->Transform (aTrsf);
+~~~~~
-The **Image** package provides the resources to produce and manage bitmap images. It has two purposes:
- * To define what is an image on the CAS.CADE platform.
- * To define operations which can be carried out on an image.
+@subsubsection occt_visu_4_4_4 Orthographic Projection
-The package allows the user to manipulate images without knowing their type. For various functionalities such as zoom, pan, and rotation, an application does not need to know the type nor the format of the image. Consequently, the image could be stored as an integer, real, or object of the Color type.
+@figure{view_frustum.png,"Perspective and orthographic projection",420}
-Another important asset of the package is to make the handling of images independent of the type of pixel. Thus a new image based on a different pixel type can be created without rewriting any of the algorithms.
+The following code configures the camera for orthographic rendering:
-@subsubsection occt_1621831385_8639395022 The services provided
+~~~~~
+// Create an orthographic View in this Viewer
+Handle(V3d_View) aView = new V3d_View (VM);
+aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Orthographic);
+// update the Visualization in this View
+aView->Update();
+~~~~~
-The classes **ColorImage** and **PseudoColorImage** define the two types of image, which can be handled by the Image toolkit. These classes support different types of operations, such as zoom and rotate. The **PixMap** class defines system-independent bitmaps. It stores raster image data and provides special services, such as saving the image data into an image file. The PixMaps are powered by the FreeImage library.
+@subsubsection occt_visu_4_4_5 Perspective Projection
-**ColorImage** is used to create 24-bit TrueColor images:
- * Create a ColorImage object with a given background color.
- * Request the type of the image.
- * Request or set the color of a given pixel.
- * Zoom, rotating, translating, simple and refining transformations.
- * Set position and size.
- * Transpose, shift, clip, shift, clear.
- * Draw line and rectangle.
+**Field of view (FOVy)** -- defines the field of camera view by y axis in degrees (45° is default).
-**PseudoColorImage** is used to create 32-bit images:
- * Create a PseudoColorImage object with a given background color associated with a given ColorMap (Generic, ColorCube, ColorRamp)
- * Ask or set the color of a given pixel, row, or column.
- * Find the maximum & minimum pixel values of an image.
- * Change the pixel values by scaling.
- * Change the pixel values below a threshold value.
- * Zoom, rotating, translating, simple and refining transformations.
- * Set position and size.
- * Transpose, shift, clip, shift, clear.
- * * Draw line and rectangle.
+@figure{camera_perspective.png,"Perspective frustum",420}
-**PixMap **provides support for system-independent bitmaps:
- * Supports different kinds of raster images, such as 24-bit, 32-bit, 96-bit, 128-bit, or RGB, RGBA, floating-point RGB and RGBA.
- * Provides direct access to the pixel buffer.
- * Provides image dump services. The use of FreeImage library enhances these services with the capability of saving raster images into different image file formats. **Note** that without FreeImage library support, the raster images could be dumped into the PPM format only.
- * PixMaps could be used for handling system bitmaps and dumping window contents.
-
-**Convertor** is used to:
- * Change an image from a ColorImage to a PseudoColorImage. Select between two dithering algorithms for the change.
- * Change an image from a PseudoColorImage to a ColorImage.
- * Change a PseudoColorImage into one with a different ColorMap.
+The following code configures the camera for perspective rendering:
-**LookupTable** is used to:
- * Transform the pixels of a PseudoColorImage.
+~~~~~
+// Create a perspective View in this Viewer
+Handle(V3d_View) aView = new V3d_View(VM);
+aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Perspective);
+aView->Update();
+~~~~~
-Various **PixelInterpolation** classes are available for dealing with pixel values at non-integer coordinates.
-The package also includes a number of **package methods** for zooming, rotation, translation, as well as simple and refining transformations.
+@subsubsection occt_visu_4_4_6 Stereographic Projection
-@subsection occt_1621831385_863939503 AlienImage
+**IOD** -- defines the intraocular distance (in world space units).
-@subsubsection occt_1621831385_8639395031 Overview
+There are two types of IOD:
+* _IODType_Absolute_ : Intraocular distance is defined as an absolute value.
+* _IODType_Relative_ : Intraocular distance is defined relative to the camera focal length (as its coefficient).
-The **AlienImage** package is used to import 2D images from some other format into the CAS.CADE format.
+**Field of view (FOV)** -- defines the field of camera view by y axis in degrees (45° is default).
-@subsubsection occt_1621831385_8639395032 Available Services
- * Reads the content of an AlienImage object from a file.
- * Writes the content of an AlienImage object to a file.
- * Converts an AlienImage object to an Image object.
- * Converts an Image object to an AlienImage object.
+**ZFocus** -- defines the distance to the point of stereographic focus.
-@subsection occt_1621831385_863939504 V2d
+@figure{stereo.png,"Stereographic projection",420}
-@subsubsection occt_1621831385_8639395041 Overview
+To enable stereo projection, your workstation should meet the following requirements:
-This package is used to build a 2D mono-view viewer in a windowing system. It contains the commands available within the viewer (zoom, pan, pick, etc).
+* The graphic card should support quad buffering.
+* You need active 3D glasses (LCD shutter glasses).
+* 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.
-@subsubsection occt_1621831385_8639395042 The services provided
+In 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.
-The **V2d** package contains the **View** class. **View** is used to:
- * Create a view in an window.
- * Handle the view:
- * zoom
- * fit all
- * pan
- * translate
- * erase
- * pick
- * highlight
- * set drawing precision
- * Postscript output
+To enable quad buffering support you should provide the following settings to the graphic driver *opengl_caps*:
-@section occt_1621831385_1676618855 Graphic Attributes
-@subsection occt_1621831385_16766188551 Aspect
+~~~~~
+Handle(OpenGl_GraphicDriver) aDriver = new OpenGl_GraphicDriver();
+OpenGl_Caps& aCaps = aDriver->ChangeOptions();
+aCaps.contextStereo = Standard_True;
+~~~~~
-@subsubsection occt_1621831385_167661885511 Overview
+The following code configures the camera for stereographic rendering:
-The **Aspect** package provides classes for the graphic elements, which are common to all 2D and 3D viewers - screen background, windows, edges, groups of graphic attributes that can be used in describing 2D and 3D objects.
+~~~~~
+// Create a Stereographic View in this Viewer
+Handle(V3d_View) aView = new V3d_View(VM);
+aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Stereo);
+// Change stereo parameters
+aView->Camera()->SetIOD (IODType_Absolute, 5.0);
+// Finally update the Visualization in this View
+aView->Update();
+~~~~~
-@subsubsection occt_1621831385_167661885512 The services provided
+@subsubsection occt_visu_4_4_7 View frustum culling
-The **Aspect** package provides classes to implement:
- * Color maps,
- * Pixels,
- * Groups of graphic attributes,
- * Edges, lines, background,
- * Font classes,
- * Width map classes,
- * Marker map classes,
- * Type of Line map classes,
- * Window,
- * Driver, PlotterDriver (inherited by PS_Driver), WindowDriver,
- * Graphic device (inherited by Xw_GraphicDevice, Graphic3d_GraphicDevice),
- * Enumerations for many of the above,
- * Array instantiations for edges,
- * Array instantiations for map entries for color, type, font, width, and marker.
+The 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:
+* *Graphic3d_Structure::CalculateBoundBox()* is used to calculate axis-aligned bounding box of a presentation considering its transformation.
+* *V3d_View::SetFrustumCulling* enables or disables frustum culling for the specified view.
+* Classes *OpenGl_BVHClipPrimitiveSet* and *OpenGl_BVHTreeSelector* handle the detection of outer objects and usage of acceleration structure for frustum culling.
+* *BVH_BinnedBuilder* class splits several objects with null bounding box.
+@subsubsection occt_visu_4_4_9 View background styles
+There are three types of background styles available for *V3d_View*: solid color, gradient color and image.
+To set solid color for the background you can use the following method:
+~~~~~
+void V3d_View::SetBackgroundColor (const Quantity_Color& theColor);
+~~~~~
+
+The gradient background style could be set up with the following method:
+~~~~~
+void V3d_View::SetBgGradientColors (const Quantity_Color& theColor1,
+ const Quantity_Color& theColor2,
+ const Aspect_GradientFillMethod theFillStyle,
+ const Standard_Boolean theToUpdate = false);
+~~~~~
+
+The *theColor1* and *theColor2* parameters define the boundary colors of interpolation, the *theFillStyle* parameter defines the direction of interpolation.
+
+To set the image as a background and change the background image style you can use the following method:
+~~~~~
+void V3d_View::SetBackgroundImage (const Standard_CString theFileName,
+ const Aspect_FillMethod theFillStyle,
+ const Standard_Boolean theToUpdate = false);
+~~~~~
+
+The *theFileName* parameter defines the image file name and the path to it, the *theFillStyle* parameter defines the method of filling the background with the image. The methods are:
+ * *Aspect_FM_NONE* -- draws the image in the default position;
+ * *Aspect_FM_CENTERED* -- draws the image at the center of the view;
+ * *Aspect_FM_TILED* -- tiles the view with the image;
+ * *Aspect_FM_STRETCH* -- stretches the image over the view.
+
+@subsubsection occt_visu_4_4_10 Dumping a 3D scene into an image file
+
+The 3D scene displayed in the view can be dumped into image file with resolution independent from window size (using offscreen buffer).
+The *V3d_View* has the following methods for dumping the 3D scene:
+~~~~
+Standard_Boolean V3d_View::Dump (const Standard_CString theFile,
+ const Image_TypeOfImage theBufferType);
+~~~~
+Dumps the scene into an image file with the view dimensions.
+The raster image data handling algorithm is based on the *Image_AlienPixMap* class. The supported extensions are ".png", ".bmp", ".jpg" and others supported by **FreeImage** library.
+The value passed as *theBufferType* argument defines the type of the buffer for an output image *(RGB, RGBA, floating-point, RGBF, RGBAF)*. Method returns TRUE if the scene has been successfully dumped.
+
+~~~~
+Standard_Boolean V3d_View::ToPixMap (Image_PixMap& theImage,
+ const V3d_ImageDumpOptions& theParams);
+~~~~
+Dumps the displayed 3d scene into a pixmap with a width and height passed through parameters structure *theParams*.
+
+@subsubsection occt_visu_4_4_13 Ray tracing support
+
+OCCT 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:
+* Hard shadows
+* Refractions
+* Reflection
+* Transparency
+* Texturing
+* Support of non-polygon objects, such as lines, text, highlighting, selection.
+* Performance optimization using 2-level bounding volume hierarchy (BVH).
+
+The 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.
+To make the BVH reusable it has been added into an individual reusable OCCT package *TKMath/BVH*.
+
+There are several ray-tracing options that user can switch on/off:
+* Maximum ray tracing depth
+* Shadows rendering
+* Specular reflections
+* Adaptive anti aliasing
+* Transparency shadow effects
+
+Example:
+~~~~~
+Graphic3d_RenderingParams& aParams = aView->ChangeRenderingParams();
+// specifies rendering mode
+aParams.Method = Graphic3d_RM_RAYTRACING;
+// maximum ray-tracing depth
+aParams.RaytracingDepth = 3;
+// enable shadows rendering
+aParams.IsShadowEnabled = true;
+// enable specular reflections.
+aParams.IsReflectionEnabled = true;
+// enable adaptive anti-aliasing
+aParams.IsAntialiasingEnabled = true;
+// enable light propagation through transparent media.
+aParams.IsTransparentShadowEnabled = true;
+// update the view
+aView->Update();
+~~~~~
+
+@subsubsection occt_visu_4_4_14 Display priorities
+
+Structure 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.
+
+@subsubsection occt_visu_4_4_15 Z-layer support
+
+OCCT 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.
+
+Example:
+
+~~~~~
+// set z-layer to an interactive object
+Handle(AIS_InteractiveContext) theContext;
+Handle(AIS_InteractiveObject) theInterObj;
+Standard_Integer anId = 3;
+aViewer->AddZLayer (anId);
+theContext->SetZLayer (theInterObj, anId);
+~~~~~
+
+For each z-layer, it is allowed to:
+* Enable / disable depth test for layer.
+* Enable / disable depth write for layer.
+* Enable / disable depth buffer clearing.
+* Enable / disable polygon offset.
+
+You can get the options using getter from *V3d_Viewer*. It returns *Graphic3d_ZLayerSettings* for a given *LayerId*.
+
+Example:
+~~~~~
+// change z-layer settings
+Graphic3d_ZLayerSettings aSettings = aViewer->ZLayerSettings (anId);
+aSettings.SetEnableDepthTest (true);
+aSettings.SetEnableDepthWrite(true);
+aSettings.SetClearDepth (true);
+aSettings.SetPolygonOffset (Graphic3d_PolygonOffset());
+aViewer->SetZLayerSettings (anId, aSettings);
+~~~~~
+
+Another application for Z-Layer feature is treating visual precision issues when displaying objects far from the World Center.
+The key problem with such objects is that visualization data is stored and manipulated with single precision floating-point numbers (32-bit).
+Single precision 32-bit floating-point numbers give only 6-9 significant decimal digits precision,
+while double precision 64-bit numbers give 15-17 significant decimal digits precision, which is sufficient enough for most applications.
+
+When moving an Object far from the World Center, float number steadily eats precision.
+The camera Eye position adds leading decimal digits to the overall Object transformation, which discards smaller digits due to floating point number nature.
+For example, the object of size 0.0000123 moved to position 1000 has result transformation 1000.0000123,
+which overflows single precision floating point - considering the most optimistic scenario of 9 significant digits (but it is really not this case), the result number will be 1000.00001.
+
+This imprecision results in visual artifacts of two kinds in the 3D Viewer:
+
+* Overall per-vertex Object distortion.
+ This happens when each vertex position has been defined within World Coordinate system.
+* The object itself is not distorted, but its position in the World is unstable and imprecise - the object jumps during camera manipulations.
+ This happens when vertices have been defined within Local Coordinate system at the distance small enough to keep precision within single precision float,
+ however Local Transformation applied to the Object is corrupted due to single precision float.
+
+The first issue cannot be handled without switching the entire presentation into double precision (for each vertex position).
+However, visualization hardware is much faster using single precision float number rather than double precision - so this is not an option in most cases.
+The second issue, however, can be negated by applying special rendering tricks.
+
+So, to apply this feature in OCCT, the application:
+
+* Defines Local Transformation for each object to fit the presentation data into single precision float without distortion.
+* Spatially splits the world into smaller areas/cells where single precision float will be sufficient.
+ The size of such cell might vary and depends on the precision required by application (e.g. how much user is able to zoom in camera within application).
+* Defines a Z-Layer for each spatial cell containing any object.
+* Defines the Local Origin property of the Z-Layer according to the center of the cell.
+
+~~~~~
+Graphic3d_ZLayerSettings aSettings = aViewer->ZLayerSettings (anId);
+aSettings.SetLocalOrigin (400.0, 0.0, 0.0);
+~~~~~
+* Assigns a presentable object to the nearest Z-Layer.
+
+Note that Local Origin of the Layer is used only for rendering - everything outside will be still defined in the World Coordinate System,
+including Local Transformation of the Object and Detection results.
+E.g., while moving the presentation between Z-layers with different Local Origins, the Object will stay at the same place - only visualization quality will vary.
+
+@subsubsection occt_visu_4_4_16 Clipping planes
+
+The ability to define custom clipping planes could be very useful for some tasks. OCCT provides such an opportunity.
+
+The *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:
+
+~~~~~
+Graphic3d_ClipPlane::Graphic3d_ClipPlane (const gp_Pln& thePlane)
+void Graphic3d_ClipPlane::SetEquation (const gp_Pln& thePlane)
+Graphic3d_ClipPlane::Graphic3d_ClipPlane (const Equation& theEquation)
+void Graphic3d_ClipPlane::SetEquation (const Equation& theEquation)
+gp_Pln Graphic3d_ClipPlane::ToPlane() const
+~~~~~
+
+The clipping planes can be activated with the following method:
+~~~~~
+void Graphic3d_ClipPlane::SetOn (const Standard_Boolean theIsOn)
+~~~~~
+
+The number of clipping planes is limited. You can check the limit value via method *Graphic3d_GraphicDriver::InquireLimit()*;
+
+~~~~~
+// get the limit of clipping planes for the current view
+Standard_Integer aMaxClipPlanes = aView->Viewer()->Driver()->InquireLimit (Graphic3d_TypeOfLimit_MaxNbClipPlanes);
+~~~~~
+
+Let us see for example how to create a new clipping plane with custom parameters and add it to a view or to an object:
+~~~~~
+// create a new clipping plane
+const Handle(Graphic3d_ClipPlane)& aClipPlane = new Graphic3d_ClipPlane();
+// change equation of the clipping plane
+Standard_Real aCoeffA = ...
+Standard_Real aCoeffB = ...
+Standard_Real aCoeffC = ...
+Standard_Real aCoeffD = ...
+aClipPlane->SetEquation (gp_Pln (aCoeffA, aCoeffB, aCoeffC, aCoeffD));
+// set capping
+aClipPlane->SetCapping (aCappingArg == "on");
+// set the material with red color of clipping plane
+Graphic3d_MaterialAspect aMat = aClipPlane->CappingMaterial();
+Quantity_Color aColor (1.0, 0.0, 0.0, Quantity_TOC_RGB);
+aMat.SetAmbientColor (aColor);
+aMat.SetDiffuseColor (aColor);
+aClipPlane->SetCappingMaterial (aMat);
+// set the texture of clipping plane
+Handle(Graphic3d_Texture2Dmanual) aTexture = ...
+aTexture->EnableModulate();
+aTexture->EnableRepeat();
+aClipPlane->SetCappingTexture (aTexture);
+// add the clipping plane to an interactive object
+Handle(AIS_InteractiveObject) aIObj = ...
+aIObj->AddClipPlane (aClipPlane);
+// or to the whole view
+aView->AddClipPlane (aClipPlane);
+// activate the clipping plane
+aClipPlane->SetOn(Standard_True);
+// update the view
+aView->Update();
+~~~~~
+
+
+@subsubsection occt_visu_4_4_17 Automatic back face culling
+
+Back 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()*.
+
+The following features are applied in *StdPrs_ToolShadedShape::IsClosed()*, which is used for definition of back face culling in *ShadingAspect*:
+* disable culling for free closed Shells (not inside the Solid) since reversed orientation of a free Shell is a valid case;
+* enable culling for Solids packed into a compound;
+* ignore Solids with incomplete triangulation.
+
+Back face culling is turned off at TKOpenGl level in the following cases:
+* clipping/capping planes are in effect;
+* for translucent objects;
+* with hatching presentation style.
+
+@subsection occt_visu_4_5 Examples: creating a 3D scene
+
+To create 3D graphic objects and display them in the screen, follow the procedure below:
+1. Create attributes.
+2. Create a 3D viewer.
+3. Create a view.
+4. Create an interactive context.
+5. Create interactive objects.
+6. Create primitives in the interactive object.
+7. Display the interactive object.
+
+@subsubsection occt_visu_4_5_1 Create attributes
+
+Create colors.
+
+~~~~~
+Quantity_Color aBlack (Quantity_NOC_BLACK);
+Quantity_Color aBlue (Quantity_NOC_MATRABLUE);
+Quantity_Color aBrown (Quantity_NOC_BROWN4);
+Quantity_Color aFirebrick (Quantity_NOC_FIREBRICK);
+Quantity_Color aForest (Quantity_NOC_FORESTGREEN);
+Quantity_Color aGray (Quantity_NOC_GRAY70);
+Quantity_Color aMyColor (0.99, 0.65, 0.31, Quantity_TOC_RGB);
+Quantity_Color aBeet (Quantity_NOC_BEET);
+Quantity_Color aWhite (Quantity_NOC_WHITE);
+~~~~~
+
+Create line attributes.
+
+~~~~~
+Handle(Graphic3d_AspectLine3d) anAspectBrown = new Graphic3d_AspectLine3d();
+Handle(Graphic3d_AspectLine3d) anAspectBlue = new Graphic3d_AspectLine3d();
+Handle(Graphic3d_AspectLine3d) anAspectWhite = new Graphic3d_AspectLine3d();
+anAspectBrown->SetColor (aBrown);
+anAspectBlue ->SetColor (aBlue);
+anAspectWhite->SetColor (aWhite);
+~~~~~
+
+Create marker attributes.
+~~~~~
+Handle(Graphic3d_AspectMarker3d aFirebrickMarker = new Graphic3d_AspectMarker3d();
+// marker attributes
+aFirebrickMarker->SetColor (Firebrick);
+aFirebrickMarker->SetScale (1.0);
+aFirebrickMarker->SetType (Aspect_TOM_BALL);
+// or this
+// it is a preferred way (supports full-color images on modern hardware).
+aFirebrickMarker->SetMarkerImage (theImage)
+~~~~~
+
+Create facet attributes.
+~~~~~
+Handle(Graphic3d_AspectFillArea3d) aFaceAspect = new Graphic3d_AspectFillArea3d();
+Graphic3d_MaterialAspect aBrassMaterial (Graphic3d_NOM_BRASS);
+Graphic3d_MaterialAspect aGoldMaterial (Graphic3d_NOM_GOLD);
+aFaceAspect->SetInteriorStyle (Aspect_IS_SOLID);
+aFaceAspect->SetInteriorColor (aMyColor);
+aFaceAspect->SetDistinguishOn ();
+aFaceAspect->SetFrontMaterial (aGoldMaterial);
+aFaceAspect->SetBackMaterial (aBrassMaterial);
+aFaceAspect->SetEdgeOn();
+~~~~~
+
+Create text attributes.
+~~~~~
+Handle(Graphic3d_AspectText3d) aTextAspect = new Graphic3d_AspectText3d (aForest, Graphic3d_NOF_ASCII_MONO, 1.0, 0.0);
+~~~~~
+
+@subsubsection occt_visu_4_5_2 Create a 3D Viewer (a Windows example)
+
+~~~~~
+// create a default connection
+Handle(Aspect_DisplayConnection) aDisplayConnection;
+// create a graphic driver from default connection
+Handle(OpenGl_GraphicDriver) aGraphicDriver = new OpenGl_GraphicDriver (aDisplayConnection);
+// create a viewer
+myViewer = new V3d_Viewer (aGraphicDriver);
+// set parameters for V3d_Viewer
+// defines default lights -
+// positional-light 0.3 0.0 0.0
+// directional-light V3d_XnegYposZpos
+// directional-light V3d_XnegYneg
+// ambient-light
+a3DViewer->SetDefaultLights();
+// activates all the lights defined in this viewer
+a3DViewer->SetLightOn();
+// set background color to black
+a3DViewer->SetDefaultBackgroundColor (Quantity_NOC_BLACK);
+~~~~~
+
+
+@subsubsection occt_visu_4_5_3 Create a 3D view (a Windows example)
+
+It is assumed that a valid Windows window may already be accessed via the method *GetSafeHwnd()* (as in case of MFC sample).
+~~~~~
+Handle(WNT_Window) aWNTWindow = new WNT_Window (GetSafeHwnd());
+myView = myViewer->CreateView();
+myView->SetWindow (aWNTWindow);
+~~~~~
+
+@subsubsection occt_visu_4_5_4 Create an interactive context
+
+~~~~~
+myAISContext = new AIS_InteractiveContext (myViewer);
+~~~~~
+
+You are now able to display interactive objects such as an *AIS_Shape*.
+
+~~~~~
+TopoDS_Shape aShape = BRepAPI_MakeBox (10, 20, 30).Solid();
+Handle(AIS_Shape) anAISShape = new AIS_Shape (aShape);
+myAISContext->Display (anAISShape);
+~~~~~
+
+@subsubsection occt_visu_4_5_5 Create your own interactive object
+
+Follow the procedure below to compute the presentable object:
+
+1. Build a presentable object inheriting from *AIS_InteractiveObject* (refer to the Chapter on @ref occt_visu_2_1 "Presentable Objects").
+2. Reuse the *Prs3d_Presentation* provided as an argument of the compute methods.
+
+**Note** that there are two compute methods: one for a standard representation, and the other for a degenerated representation, i.e. in hidden line removal and wireframe modes.
+
+Let us look at the example of compute methods
+
+~~~~~
+void MyPresentableObject::Compute (const Handle(PrsMgr_PresentationManager3d)& thePrsManager,
+ const Handle(Prs3d_Presentation)& thePrs,
+ const Standard_Integer theMode)
+(
+ //...
+)
+
+void MyPresentableObject::Compute (const Handle(Prs3d_Projector)& theProjector,
+ const Handle(Prs3d_Presentation)& thePrs)
+(
+ //...
+)
+~~~~~
+
+@subsubsection occt_visu_4_5_6 Create primitives in the interactive object
+
+Get the group used in *Prs3d_Presentation*.
+
+~~~~~
+Handle(Graphic3d_Group) aGroup = thePrs->NewGroup();
+~~~~~
+
+Update the group attributes.
+
+~~~~~
+aGroup->SetGroupPrimitivesAspect (anAspectBlue);
+~~~~~
+
+Create two triangles in *aGroup*.
+
+~~~~~
+Standard_Integer aNbTria = 2;
+Handle(Graphic3d_ArrayOfTriangles) aTriangles = new Graphic3d_ArrayOfTriangles (3 * aNbTria, 0, true);
+for (Standard_Integer aTriIter = 1; aTriIter <= aNbTria; ++aTriIter)
+{
+ aTriangles->AddVertex (aTriIter * 5., 0., 0., 1., 1., 1.);
+ aTriangles->AddVertex (aTriIter * 5 + 5, 0., 0., 1., 1., 1.);
+ aTriangles->AddVertex (aTriIter * 5 + 2.5, 5., 0., 1., 1., 1.);
+}
+aGroup->AddPrimitiveArray (aTriangles);
+aGroup->SetGroupPrimitivesAspect (new Graphic3d_AspectFillArea3d());
+~~~~~
+
+Use the polyline function to create a boundary box for the *thePrs* structure in group *aGroup*.
+
+~~~~~
+Standard_Real Xm, Ym, Zm, XM, YM, ZM;
+thePrs->MinMaxValues (Xm, Ym, Zm, XM, YM, ZM);
+
+Handle(Graphic3d_ArrayOfPolylines) aPolylines = new Graphic3d_ArrayOfPolylines (16, 4);
+aPolylines->AddBound (4);
+aPolylines->AddVertex (Xm, Ym, Zm);
+aPolylines->AddVertex (Xm, Ym, ZM);
+aPolylines->AddVertex (Xm, YM, ZM);
+aPolylines->AddVertex (Xm, YM, Zm);
+aPolylines->AddBound (4);
+aPolylines->AddVertex (Xm, Ym, Zm);
+aPolylines->AddVertex (XM, Ym, Zm);
+aPolylines->AddVertex (XM, Ym, ZM);
+aPolylines->AddVertex (XM, YM, ZM);
+aPolylines->AddBound (4);
+aPolylines->AddVertex (XM, YM, Zm);
+aPolylines->AddVertex (XM, Ym, Zm);
+aPolylines->AddVertex (XM, YM, Zm);
+aPolylines->AddVertex (Xm, YM, Zm);
+aPolylines->AddBound (4);
+aPolylines->AddVertex (Xm, YM, ZM);
+aPolylines->AddVertex (XM, YM, ZM);
+aPolylines->AddVertex (XM, Ym, ZM);
+aPolylines->AddVertex (Xm, Ym, ZM);
+
+aGroup->AddPrimitiveArray(aPolylines);
+aGroup->SetGroupPrimitivesAspect (new Graphic3d_AspectLine3d());
+~~~~~
+
+Create text and markers in group *aGroup*.
+
+~~~~~
+static char* texte[3] =
+{
+ "Application title",
+ "My company",
+ "My company address."
+};
+Handle(Graphic3d_ArrayOfPoints) aPtsArr = new Graphic3d_ArrayOfPoints (2, 1);
+aPtsArr->AddVertex (-40.0, -40.0, -40.0);
+aPtsArr->AddVertex (40.0, 40.0, 40.0);
+aGroup->AddPrimitiveArray (aPtsArr);
+aGroup->SetGroupPrimitivesAspect (new Graphic3d_AspectText3d());
+
+Graphic3d_Vertex aMarker (0.0, 0.0, 0.0);
+for (int i = 0; i <= 2; i++)
+{
+ aMarker.SetCoord (-(Standard_Real )i * 4 + 30,
+ (Standard_Real )i * 4,
+ -(Standard_Real )i * 4);
+ aGroup->Text (texte[i], Marker, 20.);
+}
+
+~~~~~
+
+@section occt_visu_5 Mesh Visualization Services
+
+*MeshVS* (Mesh Visualization Service) component extends 3D visualization capabilities of Open CASCADE Technology. It provides flexible means of displaying meshes along with associated pre- and post-processor data.
+
+From a developer's point of view, it is easy to integrate the *MeshVS* component into any mesh-related application with the following guidelines:
+
+* Derive a data source class from the *MeshVS_DataSource* class.
+* Re-implement its virtual methods, so as to give the *MeshVS* component access to the application data model. This is the most important part of the job, since visualization performance is affected by performance of data retrieval methods of your data source class.
+* Create an instance of *MeshVS_Mesh* class.
+* Create an instance of your data source class and pass it to a *MeshVS_Mesh* object through the *SetDataSource()* method.
+* Create one or several objects of *MeshVS_PrsBuilder*-derived classes (standard, included in the *MeshVS* package, or your custom ones).
+* Each *PrsBuilder* is responsible for drawing a *MeshVS_Mesh* presentation in a certain display mode(s) specified as a *PrsBuilder* constructor's argument. Display mode is treated by *MeshVS* classes as a combination of bit flags (two least significant bits are used to encode standard display modes: wireframe, shading and shrink).
+* Pass these objects to the *MeshVS_Mesh::AddBuilder()* method. *MeshVS_Mesh* takes advantage of improved selection highlighting mechanism: it highlights its selected entities itself, with the help of so called "highlighter" object. You can set one of *PrsBuilder* objects to act as a highlighter with the help of a corresponding argument of the *AddBuilder()* method.
+
+Visual attributes of the *MeshVS_Mesh* object (such as shading color, shrink coefficient and so on) are controlled through *MeshVS_Drawer* object. It maintains a map "Attribute ID --> attribute value" and can be easily extended with any number of custom attributes.
+
+In all other respects, *MeshVS_Mesh* is very similar to any other class derived from *AIS_InteractiveObject* and it should be used accordingly (refer to the description of *AIS package* in the documentation).
projects / occt.git / blobdiff