1Modeling: Bottle Tutorial {#occt__tutorial} 2======= 3 4@tableofcontents 5 6@section sec1 Overview 7 8 9This tutorial will teach you how to use Open CASCADE Technology services to model a 3D object. The purpose of this tutorial is not to describe all Open CASCADE Technology classes but to help you start thinking in terms of Open CASCADE Technology as a tool. 10 11 12@subsection OCCT_TUTORIAL_SUB1_1 Prerequisites 13 14This tutorial assumes that you have experience in using and setting up C++. 15From a programming standpoint, Open CASCADE Technology is designed to enhance your C++ tools with 3D modeling classes, methods and functions. The combination of all these resources will allow you to create substantial applications. 16 17@subsection OCCT_TUTORIAL_SUB1_2 The Model 18 19To illustrate the use of classes provided in the 3D geometric modeling toolkits, you will create a bottle as shown: 20 21@figure{/tutorial/images/tutorial_image001.png,"",240} height=350px 22 23In the tutorial we will create, step-by-step, a function that will model a bottle as shown above. You will find the complete source code of this tutorial, including the very function *MakeBottle* in the distribution of Open CASCADE Technology. The function body is provided in the file samples/qt/Tutorial/src/MakeBottle.cxx. 24 25@subsection OCCT_TUTORIAL_SUB1_3 Model Specifications 26 27We first define the bottle specifications as follows: 28 29| Object Parameter | Parameter Name | Parameter Value | 30| :--------------: | :------------: | :-------------: | 31| Bottle height | MyHeight | 70mm | 32| Bottle width | MyWidth | 50mm | 33| Bottle thickness | MyThickness | 30mm | 34 35In addition, we decide that the bottle's profile (base) will be centered on the origin of the global Cartesian coordinate system. 36 37@figure{/tutorial/images/tutorial_image002.png,"",240} height=350px 38 39This modeling requires four steps: 40 41 * build the bottle's Profile 42 * build the bottle's Body 43 * build the Threading on the bottle's neck 44 * build the result compound 45 46 47@section sec2 Building the Profile 48 49@subsection OCCT_TUTORIAL_SUB2_1 Defining Support Points 50 51To create the bottle's profile, you first create characteristic points with their coordinates as shown below in the (XOY) plane. These points will be the supports that define the geometry of the profile. 52 53@figure{tutorial/images/tutorial_image003.svg,"",466} 54 55There are two classes to describe a 3D Cartesian point from its X, Y and Z coordinates in Open CASCADE Technology: 56 57 * the primitive geometric *gp_Pnt* class 58 * the transient *Geom_CartesianPoint* class manipulated by handle 59 60A handle is a type of smart pointer that provides automatic memory management. 61To choose the best class for this application, consider the following: 62 63 * *gp_Pnt* is manipulated by value. Like all objects of its kind, it will have a limited lifetime. 64 * *Geom_CartesianPoint* is manipulated by handle and may have multiple references and a long lifetime. 65 66Since all the points you will define are only used to create the profile's curves, an object with a limited lifetime will do. Choose the *gp_Pnt* class. 67To instantiate a *gp_Pnt* object, just specify the X, Y, and Z coordinates of the points in the global Cartesian coordinate system: 68 69~~~~{.cpp} 70 gp_Pnt aPnt1(-myWidth / 2., 0, 0); 71 gp_Pnt aPnt2(-myWidth / 2., -myThickness / 4., 0); 72 gp_Pnt aPnt3(0, -myThickness / 2., 0); 73 gp_Pnt aPnt4(myWidth / 2., -myThickness / 4., 0); 74 gp_Pnt aPnt5(myWidth / 2., 0, 0); 75~~~~ 76 77Once your objects are instantiated, you can use methods provided by the class to access and modify its data. For example, to get the X coordinate of a point: 78 79~~~~{.cpp} 80Standard_Real xValue1 = aPnt1.X(); 81~~~~ 82 83@subsection OCCT_TUTORIAL_SUB2_2 Profile: Defining the Geometry 84With the help of the previously defined points, you can compute a part of the bottle's profile geometry. As shown in the figure below, it will consist of two segments and one arc. 85 86@figure{/tutorial/images/tutorial_image004.png,"",240} 87 88To create such entities, you need a specific data structure, which implements 3D geometric objects. This can be found in the Geom package of Open CASCADE Technology. 89In Open CASCADE Technology a package is a group of classes providing related functionality. The classes have names that start with the name of a package they belong to. For example, *Geom_Line* and *Geom_Circle* classes belong to the *Geom* package. The *Geom* package implements 3D geometric objects: elementary curves and surfaces are provided as well as more complex ones (such as *Bezier* and *BSpline*). 90However, the *Geom* package provides only the data structure of geometric entities. You can directly instantiate classes belonging to *Geom*, but it is easier to compute elementary curves and surfaces by using the *GC* package. 91This is because the *GC* provides two algorithm classes which are exactly what is required for our profile: 92 93 * Class *GC_MakeSegment* to create a segment. One of its constructors allows you to define a segment by two end points P1 and P2 94 * Class *GC_MakeArcOfCircle* to create an arc of a circle. A useful constructor creates an arc from two end points P1 and P3 and going through P2. 95 96Both of these classes return a *Geom_TrimmedCurve* manipulated by handle. This entity represents a base curve (line or circle, in our case), limited between two of its parameter values. For example, circle C is parameterized between 0 and 2PI. If you need to create a quarter of a circle, you create a *Geom_TrimmedCurve* on C limited between 0 and M_PI/2. 97 98~~~~{.cpp} 99 Handle(Geom_TrimmedCurve) aArcOfCircle = GC_MakeArcOfCircle(aPnt2,aPnt3,aPnt4); 100 Handle(Geom_TrimmedCurve) aSegment1 = GC_MakeSegment(aPnt1, aPnt2); 101 Handle(Geom_TrimmedCurve) aSegment2 = GC_MakeSegment(aPnt4, aPnt5); 102~~~~ 103 104All *GC* classes provide a casting method to obtain a result automatically with a function-like call. Note that this method will raise an exception if construction has failed. To handle possible errors more explicitly, you may use the *IsDone* and *Value* methods. For example: 105 106~~~~{.cpp} 107 GC_MakeSegment mkSeg (aPnt1, aPnt2); 108 Handle(Geom_TrimmedCurve) aSegment1; 109 if(mkSegment.IsDone()){ 110 aSegment1 = mkSeg.Value(); 111 } 112 else { 113 // handle error 114 } 115~~~~ 116 117 118@subsection OCCT_TUTORIAL_SUB2_3 Profile: Defining the Topology 119 120 121You have created the support geometry of one part of the profile but these curves are independent with no relations between each other. 122To simplify the modeling, it would be right to manipulate these three curves as a single entity. 123This can be done by using the topological data structure of Open CASCADE Technology defined in the *TopoDS* package: it defines relationships between geometric entities which can be linked together to represent complex shapes. 124Each object of the *TopoDS* package, inheriting from the *TopoDS_Shape* class, describes a topological shape as described below: 125 126| Shape | Open CASCADE Technology Class | Description | 127| :-------- | :---------------------------- | :------------------------------------------------------------ | 128| Vertex | TopoDS_Vertex | Zero dimensional shape corresponding to a point in geometry. | 129| Edge | TopoDS_Edge | One-dimensional shape corresponding to a curve and bounded by a vertex at each extremity.| 130| Wire | TopoDS_Wire | Sequence of edges connected by vertices. | 131| Face | TopoDS_Face | Part of a surface bounded by a closed wire(s). | 132| Shell | TopoDS_Shell | Set of faces connected by edges. | 133| Solid | TopoDS_Solid | Part of 3D space bounded by Shells. | 134| CompSolid | TopoDS_CompSolid | Set of solids connected by their faces. | 135| Compound | TopoDS_Compound | Set of any other shapes described above. | 136 137Referring to the previous table, to build the profile, you will create: 138 139 * Three edges out of the previously computed curves. 140 * One wire with these edges. 141 142@figure{/tutorial/images/tutorial_image005.png,"",240} 143 144However, the *TopoDS* package provides only the data structure of the topological entities. Algorithm classes available to compute standard topological objects can be found in the *BRepBuilderAPI* package. 145To create an edge, you use the BRepBuilderAPI_MakeEdge class with the previously computed curves: 146 147~~~~{.cpp} 148 TopoDS_Edge anEdge1 = BRepBuilderAPI_MakeEdge(aSegment1); 149 TopoDS_Edge anEdge2 = BRepBuilderAPI_MakeEdge(aArcOfCircle); 150 TopoDS_Edge anEdge3 = BRepBuilderAPI_MakeEdge(aSegment2); 151~~~~ 152 153In Open CASCADE Technology, you can create edges in several ways. One possibility is to create an edge directly from two points, in which case the underlying geometry of this edge is a line, bounded by two vertices being automatically computed from the two input points. For example, anEdge1 and anEdge3 could have been computed in a simpler way: 154 155~~~~{.cpp} 156 TopoDS_Edge anEdge1 = BRepBuilderAPI_MakeEdge(aPnt1, aPnt3); 157 TopoDS_Edge anEdge2 = BRepBuilderAPI_MakeEdge(aPnt4, aPnt5); 158~~~~ 159 160To connect the edges, you need to create a wire with the *BRepBuilderAPI_MakeWire* class. There are two ways of building a wire with this class: 161 162 * directly from one to four edges 163 * by adding other wire(s) or edge(s) to an existing wire (this is explained later in this tutorial) 164 165When building a wire from less than four edges, as in the present case, you can use the constructor directly as follows: 166 167~~~~{.cpp} 168 TopoDS_Wire aWire = BRepBuilderAPI_MakeWire(anEdge1, anEdge2, anEdge3); 169~~~~ 170 171 172@subsection OCCT_TUTORIAL_SUB2_4 Profile: Completing the Profile 173 174 175Once the first part of your wire is created you need to compute the complete profile. A simple way to do this is to: 176 177 * compute a new wire by reflecting the existing one. 178 * add the reflected wire to the initial one. 179 180@figure{/tutorial/images/tutorial_image006.png,"",377} 181 182To apply a transformation on shapes (including wires), you first need to define the properties of a 3D geometric transformation by using the gp_Trsf class. This transformation can be a translation, a rotation, a scale, a reflection, or a combination of these. 183In our case, we need to define a reflection with respect to the X axis of the global coordinate system. An axis, defined with the gp_Ax1 class, is built out of a point and has a direction (3D unitary vector). There are two ways to define this axis. 184The first way is to define it from scratch, using its geometric definition: 185 186 * X axis is located at (0, 0, 0) - use the *gp_Pnt* class. 187 * X axis direction is (1, 0, 0) - use the *gp_Dir* class. A *gp_Dir* instance is created out of its X, Y and Z coordinates. 188 189~~~~{.cpp} 190 gp_Pnt aOrigin(0, 0, 0); 191 gp_Dir xDir(1, 0, 0); 192 gp_Ax1 xAxis(aOrigin, xDir); 193~~~~ 194 195The second and simplest way is to use the geometric constants defined in the gp package (origin, main directions and axis of the global coordinate system). To get the X axis, just call the *gp::OX* method: 196 197~~~~{.cpp} 198 gp_Ax1 xAxis = gp::OX(); 199~~~~ 200 201As previously explained, the 3D geometric transformation is defined with the *gp_Trsf* class. There are two different ways to use this class: 202 203 * by defining a transformation matrix by all its values 204 * by using the appropriate methods corresponding to the required transformation (SetTranslation for a translation, SetMirror for a reflection, etc.): the matrix is automatically computed. 205 206Since the simplest approach is always the best one, you should use the SetMirror method with the axis as the center of symmetry. 207 208~~~~{.cpp} 209 gp_Trsf aTrsf; 210 aTrsf.SetMirror(xAxis); 211~~~~ 212 213You now have all necessary data to apply the transformation with the BRepBuilderAPI_Transform class by specifying: 214 215 * the shape on which the transformation must be applied. 216 * the geometric transformation 217 218~~~~{.cpp} 219 BRepBuilderAPI_Transform aBRepTrsf(aWire, aTrsf); 220~~~~ 221 222*BRepBuilderAPI_Transform* does not modify the nature of the shape: the result of the reflected wire remains a wire. But the function-like call or the *BRepBuilderAPI_Transform::Shape* method returns a *TopoDS_Shape* object: 223 224~~~~{.cpp} 225 TopoDS_Shape aMirroredShape = aBRepTrsf.Shape(); 226~~~~ 227 228What you need is a method to consider the resulting reflected shape as a wire. The *TopoDS* global functions provide this kind of service by casting a shape into its real type. To cast the transformed wire, use the *TopoDS::Wire* method. 229 230~~~~{.cpp} 231 TopoDS_Wire aMirroredWire = TopoDS::Wire(aMirroredShape); 232~~~~ 233 234The bottle's profile is almost finished. You have created two wires: *aWire* and *aMirroredWire*. You need to concatenate them to compute a single shape. To do this, you use the *BRepBuilderAPI_MakeWire* class as follows: 235 236 * create an instance of *BRepBuilderAPI_MakeWire*. 237 * add all edges of the two wires by using the *Add* method on this object. 238 239~~~~{.cpp} 240 BRepBuilderAPI_MakeWire mkWire; 241 mkWire.Add(aWire); 242 mkWire.Add(aMirroredWire); 243 TopoDS_Wire myWireProfile = mkWire.Wire(); 244~~~~ 245 246 247@section sec3 Building the Body 248 249 250@subsection OCCT_TUTORIAL_SUB3_1 Prism the Profile 251 252 253To compute the main body of the bottle, you need to create a solid shape. The simplest way is to use the previously created profile and sweep it along a direction. The *Prism* functionality of Open CASCADE Technology is the most appropriate for that task. It accepts a shape and a direction as input and generates a new shape according to the following rules: 254 255| Shape | Generates | 256| :----- | :----------------- | 257| Vertex | Edge | 258| Edge | Face | 259| Wire | Shell | 260| Face | Solid | 261| Shell | Compound of Solids | 262 263@figure{/tutorial/images/tutorial_image007.png,"",240} height=350px 264 265Your current profile is a wire. Referring to the Shape/Generates table, you need to compute a face out of its wire to generate a solid. 266To create a face, use the *BRepBuilderAPI_MakeFace* class. As previously explained, a face is a part of a surface bounded by a closed wire. Generally, *BRepBuilderAPI_MakeFace* computes a face out of a surface and one or more wires. 267When the wire lies on a plane, the surface is automatically computed. 268 269~~~~{.cpp} 270 TopoDS_Face myFaceProfile = BRepBuilderAPI_MakeFace(myWireProfile); 271~~~~ 272 273The *BRepPrimAPI* package provides all the classes to create topological primitive constructions: boxes, cones, cylinders, spheres, etc. Among them is the *BRepPrimAPI_MakePrism* class. As specified above, the prism is defined by: 274 275 * the basis shape to sweep; 276 * a vector for a finite prism or a direction for finite and infinite prisms. 277 278You want the solid to be finite, swept along the Z axis and to be myHeight height. The vector, defined with the *gp_Vec* class on its X, Y and Z coordinates, is: 279 280~~~~{.cpp} 281 gp_Vec aPrismVec(0, 0, myHeight); 282~~~~ 283 284All the necessary data to create the main body of your bottle is now available. Just apply the *BRepPrimAPI_MakePrism* class to compute the solid: 285 286~~~~{.cpp} 287 TopoDS_Shape myBody = BRepPrimAPI_MakePrism(myFaceProfile, aPrismVec); 288~~~~ 289 290 291@subsection OCCT_TUTORIAL_SUB3_2 Applying Fillets 292 293 294The edges of the bottle's body are very sharp. To replace them by rounded faces, you use the *Fillet* functionality of Open CASCADE Technology. 295For our purposes, we will specify that fillets must be: 296 297 * applied on all edges of the shape 298 * have a radius of *myThickness* / 12 299 300@figure{/tutorial/images/tutorial_image008.png,"",240} height=350px 301 302To apply fillets on the edges of a shape, you use the *BRepFilletAPI_MakeFillet* class. This class is normally used as follows: 303 304 * Specify the shape to be filleted in the *BRepFilletAPI_MakeFillet* constructor. 305 * Add the fillet descriptions (an edge and a radius) using the *Add* method (you can add as many edges as you need). 306 * Ask for the resulting filleted shape with the *Shape* method. 307 308~~~~{.cpp} 309BRepFilletAPI_MakeFillet mkFillet(myBody); 310~~~~ 311 312To add the fillet description, you need to know the edges belonging to your shape. The best solution is to explore your solid to retrieve its edges. This kind of functionality is provided with the *TopExp_Explorer* class, which explores the data structure described in a *TopoDS_Shape* and extracts the sub-shapes you specifically need. 313Generally, this explorer is created by providing the following information: 314 315 * the shape to explore 316 * the type of sub-shapes to be found. This information is given with the *TopAbs_ShapeEnum* enumeration. 317 318~~~~{.cpp} 319TopExp_Explorer anEdgeExplorer(myBody, TopAbs_EDGE); 320~~~~ 321 322An explorer is usually applied in a loop by using its three main methods: 323 324 * *More()* to know if there are more sub-shapes to explore. 325 * *Current()* to know which is the currently explored sub-shape (used only if the *More()* method returns true). 326 * *Next()* to move onto the next sub-shape to explore. 327 328 329~~~~{.cpp} 330 while(anEdgeExplorer.More()){ 331 TopoDS_Edge anEdge = TopoDS::Edge(anEdgeExplorer.Current()); 332 //Add edge to fillet algorithm 333 ... 334 anEdgeExplorer.Next(); 335 } 336~~~~ 337 338In the explorer loop, you have found all the edges of the bottle shape. Each one must then be added in the *BRepFilletAPI_MakeFillet* instance with the *Add()* method. Do not forget to specify the radius of the fillet along with it. 339 340~~~~{.cpp} 341 mkFillet.Add(myThickness / 12., anEdge); 342~~~~ 343 344Once this is done, you perform the last step of the procedure by asking for the filleted shape. 345 346~~~~{.cpp} 347 myBody = mkFillet.Shape(); 348~~~~ 349 350 351@subsection OCCT_TUTORIAL_SUB3_3 Adding the Neck 352 353 354To add a neck to the bottle, you will create a cylinder and fuse it to the body. The cylinder is to be positioned on the top face of the body with a radius of *myThickness* / 4. and a height of *myHeight* / 10. 355 356@figure{/tutorial/images/tutorial_image009.png,"",240} height=350px 357 358To position the cylinder, you need to define a coordinate system with the *gp_Ax2* class defining a right-handed coordinate system from a point and two directions - the main (Z) axis direction and the X direction (the Y direction is computed from these two). 359To align the neck with the center of the top face, being in the global coordinate system (0, 0, *myHeight*), with its normal on the global Z axis, your local coordinate system can be defined as follows: 360 361~~~~{.cpp} 362 gp_Pnt neckLocation(0, 0, myHeight); 363 gp_Dir neckAxis = gp::DZ(); 364 gp_Ax2 neckAx2(neckLocation, neckAxis); 365~~~~ 366 367To create a cylinder, use another class from the primitives construction package: the *BRepPrimAPI_MakeCylinder* class. The information you must provide is: 368 369 * the coordinate system where the cylinder will be located; 370 * the radius and height. 371 372~~~~{.cpp} 373 Standard_Real myNeckRadius = myThickness / 4.; 374 Standard_Real myNeckHeight = myHeight / 10; 375 BRepPrimAPI_MakeCylinder MKCylinder(neckAx2, myNeckRadius, myNeckHeight); 376 TopoDS_Shape myNeck = MKCylinder.Shape(); 377~~~~ 378 379You now have two separate parts: a main body and a neck that you need to fuse together. 380The *BRepAlgoAPI* package provides services to perform Boolean operations between shapes, and especially: *common* (Boolean intersection), *cut* (Boolean subtraction) and *fuse* (Boolean union). 381Use *BRepAlgoAPI_Fuse* to fuse the two shapes: 382 383~~~~{.cpp} 384 myBody = BRepAlgoAPI_Fuse(myBody, myNeck); 385~~~~ 386 387 388@subsection OCCT_TUTORIAL_SUB3_4 Creating a Hollowed Solid 389 390 391Since a real bottle is used to contain liquid material, you should now create a hollowed solid from the bottle's top face. 392In Open CASCADE Technology, a hollowed solid is called a *Thick* *Solid* and is internally computed as follows: 393 394 * Remove one or more faces from the initial solid to obtain the first wall W1 of the hollowed solid. 395 * Create a parallel wall W2 from W1 at a distance D. If D is positive, W2 will be outside the initial solid, otherwise it will be inside. 396 * Compute a solid from the two walls W1 and W2. 397 398@figure{/tutorial/images/tutorial_image010.png,"",240} height=350px 399 400To compute a thick solid, you create an instance of the *BRepOffsetAPI_MakeThickSolid* class by giving the following information: 401 402 * The shape, which must be hollowed. 403 * The tolerance used for the computation (tolerance criterion for coincidence in generated shapes). 404 * The thickness between the two walls W1 and W2 (distance D). 405 * The face(s) to be removed from the original solid to compute the first wall W1. 406 407The challenging part in this procedure is to find the face to remove from your shape - the top face of the neck, which: 408 409 * has a plane (planar surface) as underlying geometry; 410 * is the highest face (in Z coordinates) of the bottle. 411 412To find the face with such characteristics, you will once again use an explorer to iterate on all the bottle's faces to find the appropriate one. 413 414~~~~{.cpp} 415 for(TopExp_Explorer aFaceExplorer(myBody, TopAbs_FACE) ; aFaceExplorer.More() ; aFaceExplorer.Next()){ 416 TopoDS_Face aFace = TopoDS::Face(aFaceExplorer.Current()); 417 } 418~~~~ 419 420For each detected face, you need to access the geometric properties of the shape: use the *BRep_Tool* class for that. The most commonly used methods of this class are: 421 422 * *Surface* to access the surface of a face; 423 * *Curve* to access the 3D curve of an edge; 424 * *Point* to access the 3D point of a vertex. 425 426~~~~{.cpp} 427Handle(Geom_Surface) aSurface = BRep_Tool::Surface(aFace); 428~~~~ 429 430As you can see, the *BRep_Tool::Surface* method returns an instance of the *Geom_Surface* class manipulated by handle. However, the *Geom_Surface* class does not provide information about the real type of the object *aSurface*, which could be an instance of *Geom_Plane*, *Geom_CylindricalSurface*, etc. 431All objects manipulated by handle, like *Geom_Surface*, inherit from the *Standard_Transient* class which provides two very useful methods concerning types: 432 433 * *DynamicType* to know the real type of the object 434 * *IsKind* to know if the object inherits from one particular type 435 436DynamicType returns the real type of the object, but you need to compare it with the existing known types to determine whether *aSurface* is a plane, a cylindrical surface or some other type. 437To compare a given type with the type you seek, use the *STANDARD_TYPE* macro, which returns the type of a class: 438 439~~~~{.cpp} 440 if(aSurface->DynamicType() == STANDARD_TYPE(Geom_Plane)){ 441 } 442~~~~ 443 444If this comparison is true, you know that the *aSurface* real type is *Geom_Plane*. You can then convert it from *Geom_Surface* to *Geom_Plane* by using the *DownCast()* method provided by each class inheriting *Standard_Transient*. As its name implies, this static method is used to downcast objects to a given type with the following syntax: 445 446~~~~{.cpp} 447 Handle(Geom_Plane) aPlane = Handle(Geom_Plane)::DownCast(aSurface); 448~~~~ 449 450Remember that the goal of all these conversions is to find the highest face of the bottle lying on a plane. Suppose that you have these two global variables: 451 452~~~~{.cpp} 453 TopoDS_Face faceToRemove; 454 Standard_Real zMax = -1; 455~~~~ 456 457You can easily find the plane whose origin is the biggest in Z knowing that the location of the plane is given with the *Geom_Plane::Location* method. For example: 458 459~~~~{.cpp} 460 gp_Pnt aPnt = aPlane->Location(); 461 Standard_Real aZ = aPnt.Z(); 462 if(aZ > zMax){ 463 zMax = aZ; 464 faceToRemove = aFace; 465 } 466~~~~ 467 468You have now found the top face of the neck. Your final step before creating the hollowed solid is to put this face in a list. Since more than one face can be removed from the initial solid, the *BRepOffsetAPI_MakeThickSolid* constructor takes a list of faces as arguments. 469Open CASCADE Technology provides many collections for different kinds of objects: see *TColGeom* package for collections of objects from *Geom* package, *TColgp* package for collections of objects from gp package, etc. 470The collection for shapes can be found in the *TopTools* package. As *BRepOffsetAPI_MakeThickSolid* requires a list, use the *TopTools_ListOfShape* class. 471 472~~~~{.cpp} 473 TopTools_ListOfShape facesToRemove; 474 facesToRemove.Append(faceToRemove); 475~~~~ 476 477All the necessary data are now available so you can create your hollowed solid by calling the *BRepOffsetAPI_MakeThickSolid* MakeThickSolidByJoin method: 478 479~~~~{.cpp} 480 BRepOffsetAPI_MakeThickSolid aSolidMaker; 481 aSolidMaker.MakeThickSolidByJoin(myBody, facesToRemove, -myThickness / 50, 1.e-3); 482 myBody = aSolidMaker.Shape(); 483~~~~ 484 485 486@section sec4 Building the Threading 487 488 489@subsection OCCT_TUTORIAL_SUB4_1 Creating Surfaces 490 491 492Up to now, you have learned how to create edges out of 3D curves. 493You will now learn how to create an edge out of a 2D curve and a surface. 494To learn this aspect of Open CASCADE Technology, you will build helicoidal profiles out of 2D curves on cylindrical surfaces. The theory is more complex than in previous steps, but applying it is very simple. 495As a first step, you compute these cylindrical surfaces. You are already familiar with the curves of the *Geom* package. Now you can create a cylindrical surface (*Geom_CylindricalSurface*) using: 496 497 * a coordinate system; 498 * a radius. 499 500Using the same coordinate system *neckAx2* used to position the neck, you create two cylindrical surfaces *Geom_CylindricalSurface* with the following radii: 501 502@figure{/tutorial/images/tutorial_image011.png,"",300} 503 504Notice that one of the cylindrical surfaces is smaller than the neck. There is a good reason for this: after the thread creation, you will fuse it with the neck. So, we must make sure that the two shapes remain in contact. 505 506~~~~{.cpp} 507 Handle(Geom_CylindricalSurface) aCyl1 = new Geom_CylindricalSurface(neckAx2, myNeckRadius * 0.99); 508 509 Handle(Geom_CylindricalSurface) aCyl2 = new Geom_CylindricalSurface(neckAx2, myNeckRadius * 1.05); 510~~~~ 511 512 513@subsection OCCT_TUTORIAL_SUB4_2 Defining 2D Curves 514 515 516To create the neck of the bottle, you made a solid cylinder based on a cylindrical surface. You will create the profile of threading by creating 2D curves on such a surface. 517All geometries defined in the *Geom* package are parameterized. This means that each curve or surface from Geom is computed with a parametric equation. 518A *Geom_CylindricalSurface* surface is defined with the following parametric equation: 519 520P(U, V) = O + R * (cos(U) * xDir + sin(U) * yDir) + V * zDir, where : 521 522 * P is the point defined by parameters (U, V). 523 * O, *Dir, yDir and zDir are respectively the origin, the X direction, Y direction and Z direction of the cylindrical surface local coordinate system. 524 * R is the radius of the cylindrical surface. 525 * U range is [0, 2PI] and V is infinite. 526 527@figure{/tutorial/images/tutorial_image012.png,"",400} 528 529The advantage of having such parameterized geometries is that you can compute, for any (U, V) parameters of the surface: 530 531 * the 3D point; 532 * the derivative vectors of order 1, 2 to N at this point. 533 534There is another advantage of these parametric equations: you can consider a surface as a 2D parametric space defined with a (U, V) coordinate system. For example, consider the parametric ranges of the neck's surface: 535 536@figure{/tutorial/images/tutorial_image013.png,"",320} 537 538Suppose that you create a 2D line on this parametric (U, V) space and compute its 3D parametric curve. Depending on the line definition, results are as follows: 539 540| Case | Parametric Equation | Parametric Curve | 541| :------------ | :----------------------------------------------------------- | :---------------------------------------------------------------------------- | 542| U = 0 | P(V) = O + V * zDir | Line parallel to the Z direction | 543| V = 0 | P(U) = O + R * (cos(U) * xDir + sin(U) * yDir) | Circle parallel to the (O, X, Y) plane | 544| U != 0 V != 0 | P(U, V) = O + R * (cos(U) * xDir + sin(U) * yDir) + V * zDir | Helicoidal curve describing the evolution of height and angle on the cylinder | 545 546The helicoidal curve type is exactly what you need. On the neck's surface, the evolution laws of this curve will be: 547 548 * In V parameter: between 0 and myHeighNeck for the height description 549 * In U parameter: between 0 and 2PI for the angle description. But, since a cylindrical surface is U periodic, you can decide to extend this angle evolution to 4PI as shown in the following drawing: 550 551@figure{/tutorial/images/tutorial_image014.png,"",440} 552 553In this (U, V) parametric space, you will create a local (X, Y) coordinate system to position the curves to be created. This coordinate system will be defined with: 554 555 * A center located in the middle of the neck's cylinder parametric space at (2*PI, myNeckHeight / 2) in U, V coordinates. 556 * A X direction defined with the (2*PI, myNeckHeight/4) vector in U, V coordinates, so that the curves occupy half of the neck's surfaces. 557 558@figure{/tutorial/images/tutorial_image015.png,"",440} 559 560To use 2D primitive geometry types of Open CASCADE Technology for defining a point and a coordinate system, you will once again instantiate classes from gp: 561 562 * To define a 2D point from its X and Y coordinates, use the *gp_Pnt2d* class. 563 * To define a 2D direction (unit vector) from its X and Y coordinates, use the gp_Dir2d class. The coordinates will automatically be normalized. 564 * To define a 2D right-handed coordinate system, use the *gp_Ax2d* class, which is computed from a point (origin of the coordinate system) and a direction - the X direction of the coordinate system. The Y direction will be automatically computed. 565 566~~~~{.cpp} 567 gp_Pnt2d aPnt(2. * M_PI, myNeckHeight / 2.); 568 gp_Dir2d aDir(2. * M_PI, myNeckHeight / 4.); 569 gp_Ax2d anAx2d(aPnt, aDir); 570~~~~ 571 572You will now define the curves. As previously mentioned, these thread profiles are computed on two cylindrical surfaces. In the following figure, curves on the left define the base (on *aCyl1* surface) and the curves on the right define the top of the thread's shape (on *aCyl2* surface). 573 574@figure{/tutorial/images/tutorial_image016.png,"",440} 575 576You have already used the *Geom* package to define 3D geometric entities. For 2D, you will use the *Geom2d* package. As for *Geom*, all geometries are parameterized. For example, a *Geom2d_Ellipse* ellipse is defined from: 577 578 * a coordinate system whose origin is the ellipse center; 579 * a major radius on the major axis defined by the X direction of the coordinate system; 580 * a minor radius on the minor axis defined by the Y direction of the coordinate system. 581 582Supposing that: 583 584 * Both ellipses have the same major radius of 2*PI, 585 * Minor radius of the first ellipse is myNeckHeight / 10, 586 * And the minor radius value of the second ellipse is a fourth of the first one, 587 588Your ellipses are defined as follows: 589 590~~~~{.cpp} 591 Standard_Real aMajor = 2. * M_PI; 592 Standard_Real aMinor = myNeckHeight / 10; 593 Handle(Geom2d_Ellipse) anEllipse1 = new Geom2d_Ellipse(anAx2d, aMajor, aMinor); 594 Handle(Geom2d_Ellipse) anEllipse2 = new Geom2d_Ellipse(anAx2d, aMajor, aMinor / 4); 595~~~~ 596 597To describe portions of curves for the arcs drawn above, you define *Geom2d_TrimmedCurve* trimmed curves out of the created ellipses and two parameters to limit them. 598As the parametric equation of an ellipse is P(U) = O + (MajorRadius * cos(U) * XDirection) + (MinorRadius * sin(U) * YDirection), the ellipses need to be limited between 0 and M_PI. 599 600~~~~{.cpp} 601 Handle(Geom2d_TrimmedCurve) anArc1 = new Geom2d_TrimmedCurve(anEllipse1, 0, M_PI); 602 Handle(Geom2d_TrimmedCurve) anArc2 = new Geom2d_TrimmedCurve(anEllipse2, 0, M_PI); 603~~~~ 604 605The last step consists in defining the segment, which is the same for the two profiles: a line limited by the first and the last point of one of the arcs. 606To access the point corresponding to the parameter of a curve or a surface, you use the Value or D0 method (meaning 0th derivative), D1 method is for the first derivative, D2 for the second one. 607 608~~~~{.cpp} 609 gp_Pnt2d anEllipsePnt1 = anEllipse1->Value(0); 610 gp_Pnt2d anEllipsePnt2; 611 anEllipse1->D0(M_PI, anEllipsePnt2); 612~~~~ 613 614When creating the bottle's profile, you used classes from the *GC* package, providing algorithms to create elementary geometries. 615In 2D geometry, this kind of algorithms is found in the *GCE2d* package. Class names and behaviors are similar to those in *GC*. For example, to create a 2D segment out of two points: 616 617~~~~{.cpp} 618 Handle(Geom2d_TrimmedCurve) aSegment = GCE2d_MakeSegment(anEllipsePnt1, anEllipsePnt2); 619~~~~ 620 621 622@subsection OCCT_TUTORIAL_SUB4_3 Building Edges and Wires 623 624 625As you did when creating the base profile of the bottle, you can now: 626 627 * compute the edges of the neck's threading. 628 * compute two wires out of these edges. 629 630@figure{/tutorial/images/tutorial_image017.png,"",440} 631 632Previously, you have built: 633 634 * two cylindrical surfaces of the threading 635 * three 2D curves defining the base geometry of the threading 636 637To compute the edges out of these curves, once again use the *BRepBuilderAPI_MakeEdge* class. One of its constructors allows you to build an edge out of a curve described in the 2D parametric space of a surface. 638 639~~~~{.cpp} 640 TopoDS_Edge anEdge1OnSurf1 = BRepBuilderAPI_MakeEdge(anArc1, aCyl1); 641 TopoDS_Edge anEdge2OnSurf1 = BRepBuilderAPI_MakeEdge(aSegment, aCyl1); 642 TopoDS_Edge anEdge1OnSurf2 = BRepBuilderAPI_MakeEdge(anArc2, aCyl2); 643 TopoDS_Edge anEdge2OnSurf2 = BRepBuilderAPI_MakeEdge(aSegment, aCyl2); 644~~~~ 645 646Now, you can create the two profiles of the threading, lying on each surface. 647 648~~~~{.cpp} 649 TopoDS_Wire threadingWire1 = BRepBuilderAPI_MakeWire(anEdge1OnSurf1, anEdge2OnSurf1); 650 TopoDS_Wire threadingWire2 = BRepBuilderAPI_MakeWire(anEdge1OnSurf2, anEdge2OnSurf2); 651~~~~ 652 653Remember that these wires were built out of a surface and 2D curves. 654One important data item is missing as far as these wires are concerned: there is no information on the 3D curves. Fortunately, you do not need to compute this yourself, which can be a difficult task since the mathematics can be quite complex. 655When a shape contains all the necessary information except 3D curves, Open CASCADE Technology provides a tool to build them automatically. In the BRepLib tool package, you can use the *BuildCurves3d* method to compute 3D curves for all the edges of a shape. 656 657~~~~{.cpp} 658 BRepLib::BuildCurves3d(threadingWire1); 659 BRepLib::BuildCurves3d(threadingWire2); 660~~~~ 661 662 663@subsection OCCT_TUTORIAL_SUB4_4 Creating Threading 664 665 666You have computed the wires of the threading. The threading will be a solid shape, so you must now compute the faces of the wires, the faces allowing you to join the wires, the shell out of these faces and then the solid itself. This can be a lengthy operation. 667There are always faster ways to build a solid when the base topology is defined. You would like to create a solid out of two wires. Open CASCADE Technology provides a quick way to do this by building a loft: a shell or a solid passing through a set of wires in a given sequence. 668The loft function is implemented in the *BRepOffsetAPI_ThruSections* class, which you use as follows: 669 670@figure{/tutorial/images/tutorial_image018.png,"",285} 671 672 * Initialize the algorithm by creating an instance of the class. The first parameter of this constructor must be specified if you want to create a solid. By default, *BRepOffsetAPI_ThruSections* builds a shell. 673 * Add the successive wires using the AddWire method. 674 * Use the *CheckCompatibility* method to activate (or deactivate) the option that checks whether the wires have the same number of edges. In this case, wires have two edges each, so you can deactivate this option. 675 * Ask for the resulting loft shape with the Shape method. 676 677~~~~{.cpp} 678 BRepOffsetAPI_ThruSections aTool(Standard_True); 679 aTool.AddWire(threadingWire1); aTool.AddWire(threadingWire2); 680 aTool.CheckCompatibility(Standard_False); 681 TopoDS_Shape myThreading = aTool.Shape(); 682~~~~ 683 684 685@section sec5 Building the Resulting Compound 686 687 688You are almost done building the bottle. Use the *TopoDS_Compound* and *BRep_Builder* classes to build single shape from *myBody* and *myThreading*: 689 690~~~~{.cpp} 691 TopoDS_Compound aRes; 692 BRep_Builder aBuilder; 693 aBuilder.MakeCompound (aRes); 694 aBuilder.Add (aRes, myBody); 695 aBuilder.Add (aRes, myThreading); 696~~~~ 697 698Congratulations! Your bottle is complete. Here is the result snapshot of the Tutorial application: 699 700@figure{/tutorial/images/tutorial_image019.png,"",320} height=450px 701 702We hope that this tutorial has provided you with a feel for the industrial strength power of Open CASCADE Technology. 703If you want to know more and develop major projects using Open CASCADE Technology, we invite you to study our training, support, and consulting services on our site at https://www.opencascade.com/content/technology-support. Our professional services can maximize the power of your Open CASCADE Technology applications. 704 705 706@section sec6 Appendix 707 708 709Complete definition of MakeBottle function (defined in the file src/MakeBottle.cxx of the Tutorial): 710 711~~~~{.cpp} 712 TopoDS_Shape MakeBottle(const Standard_Real myWidth, const Standard_Real myHeight, 713 const Standard_Real myThickness) 714 { 715 // Profile : Define Support Points 716 gp_Pnt aPnt1(-myWidth / 2., 0, 0); 717 gp_Pnt aPnt2(-myWidth / 2., -myThickness / 4., 0); 718 gp_Pnt aPnt3(0, -myThickness / 2., 0); 719 gp_Pnt aPnt4(myWidth / 2., -myThickness / 4., 0); 720 gp_Pnt aPnt5(myWidth / 2., 0, 0); 721 722 // Profile : Define the Geometry 723 Handle(Geom_TrimmedCurve) anArcOfCircle = GC_MakeArcOfCircle(aPnt2,aPnt3,aPnt4); 724 Handle(Geom_TrimmedCurve) aSegment1 = GC_MakeSegment(aPnt1, aPnt2); 725 Handle(Geom_TrimmedCurve) aSegment2 = GC_MakeSegment(aPnt4, aPnt5); 726 727 // Profile : Define the Topology 728 TopoDS_Edge anEdge1 = BRepBuilderAPI_MakeEdge(aSegment1); 729 TopoDS_Edge anEdge2 = BRepBuilderAPI_MakeEdge(anArcOfCircle); 730 TopoDS_Edge anEdge3 = BRepBuilderAPI_MakeEdge(aSegment2); 731 TopoDS_Wire aWire = BRepBuilderAPI_MakeWire(anEdge1, anEdge2, anEdge3); 732 733 // Complete Profile 734 gp_Ax1 xAxis = gp::OX(); 735 gp_Trsf aTrsf; 736 737 aTrsf.SetMirror(xAxis); 738 BRepBuilderAPI_Transform aBRepTrsf(aWire, aTrsf); 739 TopoDS_Shape aMirroredShape = aBRepTrsf.Shape(); 740 TopoDS_Wire aMirroredWire = TopoDS::Wire(aMirroredShape); 741 742 BRepBuilderAPI_MakeWire mkWire; 743 mkWire.Add(aWire); 744 mkWire.Add(aMirroredWire); 745 TopoDS_Wire myWireProfile = mkWire.Wire(); 746 747 // Body : Prism the Profile 748 TopoDS_Face myFaceProfile = BRepBuilderAPI_MakeFace(myWireProfile); 749 gp_Vec aPrismVec(0, 0, myHeight); 750 TopoDS_Shape myBody = BRepPrimAPI_MakePrism(myFaceProfile, aPrismVec); 751 752 // Body : Apply Fillets 753 BRepFilletAPI_MakeFillet mkFillet(myBody); 754 TopExp_Explorer anEdgeExplorer(myBody, TopAbs_EDGE); 755 while(anEdgeExplorer.More()){ 756 TopoDS_Edge anEdge = TopoDS::Edge(anEdgeExplorer.Current()); 757 //Add edge to fillet algorithm 758 mkFillet.Add(myThickness / 12., anEdge); 759 anEdgeExplorer.Next(); 760 } 761 762 myBody = mkFillet.Shape(); 763 764 // Body : Add the Neck 765 gp_Pnt neckLocation(0, 0, myHeight); 766 gp_Dir neckAxis = gp::DZ(); 767 gp_Ax2 neckAx2(neckLocation, neckAxis); 768 769 Standard_Real myNeckRadius = myThickness / 4.; 770 Standard_Real myNeckHeight = myHeight / 10.; 771 772 BRepPrimAPI_MakeCylinder MKCylinder(neckAx2, myNeckRadius, myNeckHeight); 773 TopoDS_Shape myNeck = MKCylinder.Shape(); 774 775 myBody = BRepAlgoAPI_Fuse(myBody, myNeck); 776 777 // Body : Create a Hollowed Solid 778 TopoDS_Face faceToRemove; 779 Standard_Real zMax = -1; 780 781 for(TopExp_Explorer aFaceExplorer(myBody, TopAbs_FACE); aFaceExplorer.More(); aFaceExplorer.Next()){ 782 TopoDS_Face aFace = TopoDS::Face(aFaceExplorer.Current()); 783 // Check if <aFace> is the top face of the bottle's neck 784 Handle(Geom_Surface) aSurface = BRep_Tool::Surface(aFace); 785 if(aSurface->DynamicType() == STANDARD_TYPE(Geom_Plane)){ 786 Handle(Geom_Plane) aPlane = Handle(Geom_Plane)::DownCast(aSurface); 787 gp_Pnt aPnt = aPlane->Location(); 788 Standard_Real aZ = aPnt.Z(); 789 if(aZ > zMax){ 790 zMax = aZ; 791 faceToRemove = aFace; 792 } 793 } 794 } 795 796 TopTools_ListOfShape facesToRemove; 797 facesToRemove.Append(faceToRemove); 798 BRepOffsetAPI_MakeThickSolid aSolidMaker; 799 aSolidMaker.MakeThickSolidByJoin(myBody, facesToRemove, -myThickness / 50, 1.e-3); 800 myBody = aSolidMaker.Shape(); 801 // Threading : Create Surfaces 802 Handle(Geom_CylindricalSurface) aCyl1 = new Geom_CylindricalSurface(neckAx2, myNeckRadius * 0.99); 803 Handle(Geom_CylindricalSurface) aCyl2 = new Geom_CylindricalSurface(neckAx2, myNeckRadius * 1.05); 804 805 // Threading : Define 2D Curves 806 gp_Pnt2d aPnt(2. * M_PI, myNeckHeight / 2.); 807 gp_Dir2d aDir(2. * M_PI, myNeckHeight / 4.); 808 gp_Ax2d anAx2d(aPnt, aDir); 809 810 Standard_Real aMajor = 2. * M_PI; 811 Standard_Real aMinor = myNeckHeight / 10; 812 813 Handle(Geom2d_Ellipse) anEllipse1 = new Geom2d_Ellipse(anAx2d, aMajor, aMinor); 814 Handle(Geom2d_Ellipse) anEllipse2 = new Geom2d_Ellipse(anAx2d, aMajor, aMinor / 4); 815 Handle(Geom2d_TrimmedCurve) anArc1 = new Geom2d_TrimmedCurve(anEllipse1, 0, M_PI); 816 Handle(Geom2d_TrimmedCurve) anArc2 = new Geom2d_TrimmedCurve(anEllipse2, 0, M_PI); 817 gp_Pnt2d anEllipsePnt1 = anEllipse1->Value(0); 818 gp_Pnt2d anEllipsePnt2 = anEllipse1->Value(M_PI); 819 820 Handle(Geom2d_TrimmedCurve) aSegment = GCE2d_MakeSegment(anEllipsePnt1, anEllipsePnt2); 821 // Threading : Build Edges and Wires 822 TopoDS_Edge anEdge1OnSurf1 = BRepBuilderAPI_MakeEdge(anArc1, aCyl1); 823 TopoDS_Edge anEdge2OnSurf1 = BRepBuilderAPI_MakeEdge(aSegment, aCyl1); 824 TopoDS_Edge anEdge1OnSurf2 = BRepBuilderAPI_MakeEdge(anArc2, aCyl2); 825 TopoDS_Edge anEdge2OnSurf2 = BRepBuilderAPI_MakeEdge(aSegment, aCyl2); 826 TopoDS_Wire threadingWire1 = BRepBuilderAPI_MakeWire(anEdge1OnSurf1, anEdge2OnSurf1); 827 TopoDS_Wire threadingWire2 = BRepBuilderAPI_MakeWire(anEdge1OnSurf2, anEdge2OnSurf2); 828 BRepLib::BuildCurves3d(threadingWire1); 829 BRepLib::BuildCurves3d(threadingWire2); 830 831 // Create Threading 832 BRepOffsetAPI_ThruSections aTool(Standard_True); 833 aTool.AddWire(threadingWire1); 834 aTool.AddWire(threadingWire2); 835 aTool.CheckCompatibility(Standard_False); 836 837 TopoDS_Shape myThreading = aTool.Shape(); 838 839 // Building the Resulting Compound 840 TopoDS_Compound aRes; 841 BRep_Builder aBuilder; 842 aBuilder.MakeCompound (aRes); 843 aBuilder.Add (aRes, myBody); 844 aBuilder.Add (aRes, myThreading); 845 846 return aRes; 847 } 848~~~~ 849 850