1 Modeling Algorithms {#occt_user_guides__modeling_algos}
2 =========================
6 @section occt_modalg_1 Introduction
8 This manual explains how to use the Modeling Algorithms. It provides basic documentation on modeling algorithms. For advanced information on Modeling Algorithms, see our <a href="http://www.opencascade.com/content/tutorial-learning">E-learning & Training</a> offerings.
10 The Modeling Algorithms module brings together a wide range of topological algorithms used in modeling. Along with these tools, you will find the geometric algorithms, which they call.
12 @section occt_modalg_2 Geometric Tools
14 Open CASCADE Technology geometric tools provide algorithms to:
15 * Calculate the intersection of two 2D curves, surfaces, or a 3D curve and a surface;
16 * Project points onto 2D and 3D curves, points onto surfaces, and 3D curves onto surfaces;
17 * Construct lines and circles from constraints;
18 * Construct curves and surfaces from constraints;
19 * Construct curves and surfaces by interpolation.
21 @subsection occt_modalg_2_2 Intersections
23 The Intersections component is used to compute intersections between 2D or 3D geometrical objects:
24 * the intersections between two 2D curves;
25 * the self-intersections of a 2D curve;
26 * the intersection between a 3D curve and a surface;
27 * the intersection between two surfaces.
29 The *Geom2dAPI_InterCurveCurve* class allows the evaluation of the intersection points (*gp_Pnt2d*) between two geometric curves (*Geom2d_Curve*) and the evaluation of the points of self-intersection of a curve.
31 @figure{/user_guides/modeling_algos/images/modeling_algos_image003.png,"Intersection and self-intersection of curves",420}
33 In both cases, the algorithm requires a value for the tolerance (Standard_Real) for the confusion between two points. The default tolerance value used in all constructors is *1.0e-6.*
35 @figure{/user_guides/modeling_algos/images/modeling_algos_image004.png,"Intersection and tangent intersection",420}
37 The algorithm returns a point in the case of an intersection and a segment in the case of tangent intersection.
39 @subsubsection occt_modalg_2_2_1 Intersection of two curves
41 *Geom2dAPI_InterCurveCurve* class may be instantiated for intersection of curves *C1* and *C2*.
43 Geom2dAPI_InterCurveCurve Intersector(C1,C2,tolerance);
46 or for self-intersection of curve *C3*.
48 Geom2dAPI_InterCurveCurve Intersector(C3,tolerance);
52 Standard_Integer N = Intersector.NbPoints();
54 Calls the number of intersection points
56 To select the desired intersection point, pass an integer index value in argument.
58 gp_Pnt2d P = Intersector.Point(Index);
61 To call the number of intersection segments, use
63 Standard_Integer M = Intersector.NbSegments();
66 To select the desired intersection segment pass integer index values in argument.
68 Handle(Geom2d_Curve) Seg1, Seg2;
69 Intersector.Segment(Index,Seg1,Seg2);
70 // if intersection of 2 curves
71 Intersector.Segment(Index,Seg1);
72 // if self-intersection of a curve
75 If you need access to a wider range of functionalities the following method will return the algorithmic object for the calculation of intersections:
78 Geom2dInt_GInter& TheIntersector = Intersector.Intersector();
81 @subsubsection occt_modalg_2_2_2 Intersection of Curves and Surfaces
83 The *GeomAPI_IntCS* class is used to compute the intersection points between a curve and a surface.
85 This class is instantiated as follows:
87 GeomAPI_IntCS Intersector(C, S);
90 To call the number of intersection points, use:
92 Standard_Integer nb = Intersector.NbPoints();
97 gp_Pnt& P = Intersector.Point(Index);
100 Where *Index* is an integer between 1 and *nb*, calls the intersection points.
102 @subsubsection occt_modalg_2_2_3 Intersection of two Surfaces
103 The *GeomAPI_IntSS* class is used to compute the intersection of two surfaces from *Geom_Surface* with respect to a given tolerance.
105 This class is instantiated as follows:
107 GeomAPI_IntSS Intersector(S1, S2, Tolerance);
109 Once the *GeomAPI_IntSS* object has been created, it can be interpreted.
112 Standard_Integer nb = Intersector. NbLines();
114 Calls the number of intersection curves.
117 Handle(Geom_Curve) C = Intersector.Line(Index)
119 Where *Index* is an integer between 1 and *nb*, calls the intersection curves.
122 @subsection occt_modalg_2_3 Interpolations
124 The Interpolation Laws component provides definitions of functions: <i> y=f(x) </i>.
126 In particular, it provides definitions of:
128 * an <i> S </i> function, and
129 * an interpolation function for a range of values.
131 Such functions can be used to define, for example, the evolution law of a fillet along the edge of a shape.
133 The validity of the function built is never checked: the Law package does not know for what application or to what end the function will be used. In particular, if the function is used as the evolution law of a fillet, it is important that the function is always positive. The user must check this.
135 @subsubsection occt_modalg_2_3_1 Geom2dAPI_Interpolate
136 This class is used to interpolate a BSplineCurve passing through an array of points. If tangency is not requested at the point of interpolation, continuity will be *C2*. If tangency is requested at the point, continuity will be *C1*. If Periodicity is requested, the curve will be closed and the junction will be the first point given. The curve will then have a continuity of *C1* only.
137 This class may be instantiated as follows:
139 Geom2dAPI_Interpolate
140 (const Handle_TColgp_HArray1OfPnt2d& Points,
141 const Standard_Boolean PeriodicFlag,
142 const Standard_Real Tolerance);
144 Geom2dAPI_Interpolate Interp(Points, Standard_False,
145 Precision::Confusion());
149 It is possible to call the BSpline curve from the object defined above it.
151 Handle(Geom2d_BSplineCurve) C = Interp.Curve();
154 Note that the *Handle(Geom2d_BSplineCurve)* operator has been redefined by the method *Curve()*. Consequently, it is unnecessary to pass via the construction of an intermediate object of the *Geom2dAPI_Interpolate* type and the following syntax is correct.
157 Handle(Geom2d_BSplineCurve) C =
158 Geom2dAPI_Interpolate(Points,
160 Precision::Confusion());
163 @subsubsection occt_modalg_2_3_2 GeomAPI_Interpolate
165 This class may be instantiated as follows:
168 (const Handle_TColgp_HArray1OfPnt& Points,
169 const Standard_Boolean PeriodicFlag,
170 const Standard_Real Tolerance);
172 GeomAPI_Interpolate Interp(Points, Standard_False,
173 Precision::Confusion());
176 It is possible to call the BSpline curve from the object defined above it.
178 Handle(Geom_BSplineCurve) C = Interp.Curve();
180 Note that the *Handle(Geom_BSplineCurve)* operator has been redefined by the method *Curve()*. Thus, it is unnecessary to pass via the construction of an intermediate object of the *GeomAPI_Interpolate* type and the following syntax is correct.
182 Handle(Geom_BSplineCurve) C =
183 GeomAPI_Interpolate(Points,
187 Boundary conditions may be imposed with the method Load.
189 GeomAPI_Interpolate AnInterpolator
190 (Points, Standard_False, 1.0e-5);
191 AnInterpolator.Load (StartingTangent, EndingTangent);
194 @subsection occt_modalg_2_4 Lines and Circles from Constraints
196 @subsubsection occt_modalg_2_4_1 Types of constraints
198 The algorithms for construction of 2D circles or lines can be described with numeric or geometric constraints in relation to other curves.
200 These constraints can impose the following :
201 * the radius of a circle,
202 * the angle that a straight line makes with another straight line,
203 * the tangency of a straight line or circle in relation to a curve,
204 * the passage of a straight line or circle through a point,
205 * the circle with center in a point or curve.
207 For example, these algorithms enable to easily construct a circle of a given radius, centered on a straight line and tangential to another circle.
209 The implemented algorithms are more complex than those provided by the Direct Constructions component for building 2D circles or lines.
211 The expression of a tangency problem generally leads to several results, according to the relative positions of the solution and the circles or straight lines in relation to which the tangency constraints are expressed. For example, consider the following
212 case of a circle of a given radius (a small one) which is tangential to two secant circles C1 and C2:
214 @figure{/user_guides/modeling_algos/images/modeling_algos_image058.png,"Example of a Tangency Constraint",360}
216 This diagram clearly shows that there are 8 possible solutions.
218 In order to limit the number of solutions, we can try to express the relative position
219 of the required solution in relation to the circles to which it is tangential. For
220 example, if we specify that the solution is inside the circle C1 and outside the
221 circle C2, only two solutions referenced 3 and 4 on the diagram respond to the problem
224 These definitions are very easy to interpret on a circle, where it is easy to identify
225 the interior and exterior sides. In fact, for any kind of curve the interior is defined
226 as the left-hand side of the curve in relation to its orientation.
228 This technique of qualification of a solution, in relation to the curves to which
229 it is tangential, can be used in all algorithms for constructing a circle or a straight
230 line by geometric constraints. Four qualifiers are used:
231 * **Enclosing** -- the solution(s) must enclose the argument;
232 * **Enclosed** -- the solution(s) must be enclosed by the argument;
233 * **Outside** -- the solution(s) and the argument must be external to one another;
234 * **Unqualified** -- the relative position is not qualified, i.e. all solutions apply.
236 It is possible to create expressions using the qualifiers, for example:
239 Solver(GccEnt::Outside(C1),
240 GccEnt::Enclosing(C2), Rad, Tolerance);
243 This expression finds all circles of radius *Rad*, which are tangent to both circle *C1* and *C2*, while *C1* is outside and *C2* is inside.
245 @subsubsection occt_modalg_2_4_2 Available types of lines and circles
247 The following analytic algorithms using value-handled entities for creation of 2D lines or circles with geometric constraints are available:
248 * circle tangent to three elements (lines, circles, curves, points),
249 * circle tangent to two elements and having a radius,
250 * circle tangent to two elements and centered on a third element,
251 * circle tangent to two elements and centered on a point,
252 * circle tangent to one element and centered on a second,
253 * bisector of two points,
254 * bisector of two lines,
255 * bisector of two circles,
256 * bisector of a line and a point,
257 * bisector of a circle and a point,
258 * bisector of a line and a circle,
259 * line tangent to two elements (points, circles, curves),
260 * line tangent to one element and parallel to a line,
261 * line tangent to one element and perpendicular to a line,
262 * line tangent to one element and forming angle with a line.
264 #### Exterior/Interior
265 It is not hard to define the interior and exterior of a circle. As is shown in the following diagram, the exterior is indicated by the sense of the binormal, that is to say the right side according to the sense of traversing the circle. The left side is therefore the interior (or "material").
267 @figure{/user_guides/modeling_algos/images/modeling_algos_image006.png,"Exterior/Interior of a Circle",220}
269 By extension, the interior of a line or any open curve is defined as the left side according to the passing direction, as shown in the following diagram:
271 @figure{/user_guides/modeling_algos/images/modeling_algos_image007.png,"Exterior/Interior of a Line and a Curve",220}
273 #### Orientation of a Line
274 It is sometimes necessary to define in advance the sense of travel along a line to be created. This sense will be from first to second argument.
276 The following figure shows a line, which is first tangent to circle C1 which is interior to the line, and then passes through point P1.
278 @figure{/user_guides/modeling_algos/images/modeling_algos_image008.png,"An Oriented Line",220}
281 #### Line tangent to two circles
282 The following four diagrams illustrate four cases of using qualifiers in the creation of a line. The fifth shows the solution if no qualifiers are given.
287 @figure{/user_guides/modeling_algos/images/modeling_algos_image009.png,"Both circles outside",220}
290 Tangent and Exterior to C1.
291 Tangent and Exterior to C2.
297 Solver(GccEnt::Outside(C1),
304 @figure{/user_guides/modeling_algos/images/modeling_algos_image010.png,"Both circles enclosed",220}
307 Tangent and Including C1.
308 Tangent and Including C2.
314 Solver(GccEnt::Enclosing(C1),
315 GccEnt::Enclosing(C2),
321 @figure{/user_guides/modeling_algos/images/modeling_algos_image011.png,"C1 enclosed and C2 outside",220}
324 Tangent and Including C1.
325 Tangent and Exterior to C2.
330 Solver(GccEnt::Enclosing(C1),
337 @figure{/user_guides/modeling_algos/images/modeling_algos_image012.png,"C1 outside and C2 enclosed",220}
339 Tangent and Exterior to C1.
340 Tangent and Including C2.
345 Solver(GccEnt::Outside(C1),
346 GccEnt::Enclosing(C2),
352 @figure{/user_guides/modeling_algos/images/modeling_algos_image013.png,"Without qualifiers",220}
355 Tangent and Undefined with respect to C1.
356 Tangent and Undefined with respect to C2.
361 Solver(GccEnt::Unqualified(C1),
362 GccEnt::Unqualified(C2),
366 #### Circle of given radius tangent to two circles
367 The following four diagrams show the four cases in using qualifiers in the creation of a circle.
370 @figure{/user_guides/modeling_algos/images/modeling_algos_image014.png,"Both solutions outside",220}
373 Tangent and Exterior to C1.
374 Tangent and Exterior to C2.
379 Solver(GccEnt::Outside(C1),
380 GccEnt::Outside(C2), Rad, Tolerance);
385 @figure{/user_guides/modeling_algos/images/modeling_algos_image015.png,"C2 encompasses C1",220}
388 Tangent and Exterior to C1.
389 Tangent and Included by C2.
394 Solver(GccEnt::Outside(C1),
395 GccEnt::Enclosed(C2), Rad, Tolerance);
399 @figure{/user_guides/modeling_algos/images/modeling_algos_image016.png,"Solutions enclose C2",220}
402 Tangent and Exterior to C1.
403 Tangent and Including C2.
408 Solver(GccEnt::Outside(C1),
409 GccEnt::Enclosing(C2), Rad, Tolerance);
413 @figure{/user_guides/modeling_algos/images/modeling_algos_image017.png,"Solutions enclose C1",220}
416 Tangent and Enclosing C1.
417 Tangent and Enclosing C2.
422 Solver(GccEnt::Enclosing(C1),
423 GccEnt::Enclosing(C2), Rad, Tolerance);
428 The following syntax will give all the circles of radius *Rad*, which are tangent to *C1* and *C2* without discrimination of relative position:
431 GccAna_Circ2d2TanRad Solver(GccEnt::Unqualified(C1),
432 GccEnt::Unqualified(C2),
437 @subsubsection occt_modalg_2_4_3 Types of algorithms
439 OCCT implements several categories of algorithms:
441 * **Analytic** algorithms, where solutions are obtained by the resolution of an equation, such algorithms are used when the geometries which are worked on (tangency arguments, position of the center, etc.) are points, lines or circles;
442 * **Geometric** algorithms, where the solution is generally obtained by calculating the intersection of parallel or bisecting curves built from geometric arguments;
443 * **Iterative** algorithms, where the solution is obtained by a process of iteration.
445 For each kind of geometric construction of a constrained line or circle, OCCT provides two types of access:
447 * algorithms from the package <i> Geom2dGcc </i> automatically select the algorithm best suited to the problem, both in the general case and in all types of specific cases; the used arguments are *Geom2d* objects, while the computed solutions are <i> gp </i> objects;
448 * algorithms from the package <i> GccAna</i> resolve the problem analytically, and can only be used when the geometries to be worked on are lines or circles; both the used arguments and the computed solutions are <i> gp </i> objects.
450 The provided algorithms compute all solutions, which correspond to the stated geometric problem, unless the solution is found by an iterative algorithm.
452 Iterative algorithms compute only one solution, closest to an initial position. They can be used in the following cases:
453 * to build a circle, when an argument is more complex than a line or a circle, and where the radius is not known or difficult to determine: this is the case for a circle tangential to three geometric elements, or tangential to two geometric elements and centered on a curve;
454 * to build a line, when a tangency argument is more complex than a line or a circle.
456 Qualified curves (for tangency arguments) are provided either by:
457 * the <i> GccEnt</i> package, for direct use by <i> GccAna</i> algorithms, or
458 * the <i> Geom2dGcc </i> package, for general use by <i> Geom2dGcc </i> algorithms.
460 The <i> GccEnt</i> and <i> Geom2dGcc</i> packages also provide simple functions for building qualified curves in a very efficient way.
462 The <i> GccAna </i>package also provides algorithms for constructing bisecting loci between circles, lines or points. Bisecting loci between two geometric objects are such that each of their points is at the same distance from the two geometric objects. They
463 are typically curves, such as circles, lines or conics for <i> GccAna</i> algorithms.
464 Each elementary solution is given as an elementary bisecting locus object (line, circle, ellipse, hyperbola, parabola), described by the <i>GccInt</i> package.
466 Note: Curves used by <i>GccAna</i> algorithms to define the geometric problem to be solved, are 2D lines or circles from the <i> gp</i> package: they are not explicitly parameterized. However, these lines or circles retain an implicit parameterization, corresponding to that which they induce on equivalent Geom2d objects. This induced parameterization is the one used when returning parameter values on such curves, for instance with the functions <i> Tangency1, Tangency2, Tangency3, Intersection2</i> and <i> CenterOn3</i> provided by construction algorithms from the <i> GccAna </i> or <i> Geom2dGcc</i> packages.
468 @subsection occt_modalg_2_5 Curves and Surfaces from Constraints
470 The Curves and Surfaces from Constraints component groups together high level functions used in 2D and 3D geometry for:
471 * creation of faired and minimal variation 2D curves
472 * construction of ruled surfaces
473 * construction of pipe surfaces
474 * filling of surfaces
475 * construction of plate surfaces
476 * extension of a 3D curve or surface beyond its original bounds.
478 OPEN CASCADE company also provides a product known as <a href="http://www.opencascade.com/content/surfaces-scattered-points">Surfaces from Scattered Points</a>, which allows constructing surfaces from scattered points. This algorithm accepts or constructs an initial B-Spline surface and looks for its deformation (finite elements method) which would satisfy the constraints. Using optimized computation methods, this algorithm is able to construct a surface from more than 500 000 points.
480 SSP product is not supplied with Open CASCADE Technology, but can be purchased separately.
482 @subsubsection occt_modalg_2_5_1 Faired and Minimal Variation 2D Curves
484 Elastic beam curves have their origin in traditional methods of modeling applied
485 in boat-building, where a long thin piece of wood, a lathe, was forced to pass
486 between two sets of nails and in this way, take the form of a curve based on the
487 two points, the directions of the forces applied at those points, and the properties
488 of the wooden lathe itself.
490 Maintaining these constraints requires both longitudinal and transversal forces to
491 be applied to the beam in order to compensate for its internal elasticity. The longitudinal
492 forces can be a push or a pull and the beam may or may not be allowed to slide over
497 The class *FairCurve_Batten* allows producing faired curves defined on the basis of one or more constraints on each of the two reference points. These include point, angle of tangency and curvature settings.
498 The following constraint orders are available:
500 * 0 the curve must pass through a point
501 * 1 the curve must pass through a point and have a given tangent
502 * 2 the curve must pass through a point, have a given tangent and a given curvature.
504 Only 0 and 1 constraint orders are used.
505 The function Curve returns the result as a 2D BSpline curve.
507 #### Minimal Variation Curves
509 The class *FairCurve_MinimalVariation* allows producing curves with minimal variation in curvature at each reference point. The following constraint orders are available:
511 * 0 the curve must pass through a point
512 * 1 the curve must pass through a point and have a given tangent
513 * 2 the curve must pass through a point, have a given tangent and a given curvature.
515 Constraint orders of 0, 1 and 2 can be used. The algorithm minimizes tension, sagging and jerk energy.
517 The function *Curve* returns the result as a 2D BSpline curve.
519 If you want to give a specific length to a batten curve, use:
522 b.SetSlidingFactor(L / b.SlidingOfReference())
524 where *b* is the name of the batten curve object
526 Free sliding is generally more aesthetically pleasing than constrained sliding. However, the computation can fail with values such as angles greater than *p/2* because in this case the length is theoretically infinite.
528 In other cases, when sliding is imposed and the sliding factor is too large, the batten can collapse.
530 The constructor parameters, *Tolerance* and *NbIterations*, control how precise the computation is, and how long it will take.
532 @subsubsection occt_modalg_2_5_2 Ruled Surfaces
534 A ruled surface is built by ruling a line along the length of two curves.
536 #### Creation of Bezier surfaces
538 The class *GeomFill_BezierCurves* allows producing a Bezier surface from contiguous Bezier curves. Note that problems may occur with rational Bezier Curves.
540 #### Creation of BSpline surfaces
542 The class *GeomFill_BSplineCurves* allows producing a BSpline surface from contiguous BSpline curves. Note that problems may occur with rational BSplines.
544 @subsubsection occt_modalg_2_5_3 Pipe Surfaces
546 The class *GeomFill_Pipe* allows producing a pipe by sweeping a curve (the section) along another curve (the path). The result is a BSpline surface.
548 The following types of construction are available:
549 * pipes with a circular section of constant radius,
550 * pipes with a constant section,
551 * pipes with a section evolving between two given curves.
554 @subsubsection occt_modalg_2_5_4 Filling a contour
556 It is often convenient to create a surface from some curves, which will form the boundaries that define the new surface.
557 This is done by the class *GeomFill_ConstrainedFilling*, which allows filling a contour defined by three or four curves as well as by tangency constraints. The resulting surface is a BSpline.
559 A case in point is the intersection of two fillets at a corner. If the radius of the fillet on one edge is different from that of the fillet on another, it becomes impossible to sew together all the edges of the resulting surfaces. This leaves a gap in the overall surface of the object which you are constructing.
561 @figure{/user_guides/modeling_algos/images/modeling_algos_image059.png,"Intersecting filleted edges with differing radiuses",220}
563 These algorithms allow you to fill this gap from two, three or four curves. This can be done with or without constraints, and the resulting surface will be either a Bezier or a BSpline surface in one of a range of filling styles.
565 #### Creation of a Boundary
567 The class *GeomFill_SimpleBound* allows you defining a boundary for the surface to be constructed.
569 #### Creation of a Boundary with an adjoining surface
571 The class *GeomFill_BoundWithSurf* allows defining a boundary for the surface to be constructed. This boundary will already be joined to another surface.
575 The enumerations *FillingStyle* specify the styles used to build the surface. These include:
577 * *Stretch* -- the style with the flattest patches
578 * *Coons* -- a rounded style with less depth than *Curved*
579 * *Curved* -- the style with the most rounded patches.
581 @figure{/user_guides/modeling_algos/images/modeling_algos_image018.png,"Intersecting filleted edges with different radii leave a gap filled by a surface",274}
583 @subsubsection occt_modalg_2_5_5 Plate surfaces
585 In CAD, it is often necessary to generate a surface which has no exact mathematical definition, but which is defined by respective constraints. These can be of a mathematical, a technical or an aesthetic order.
587 Essentially, a plate surface is constructed by deforming a surface so that it conforms to a given number of curve or point constraints. In the figure below, you can see four segments of the outline of the plane, and a point which have been used as the
588 curve constraints and the point constraint respectively. The resulting surface can be converted into a BSpline surface by using the function <i> MakeApprox </i>.
590 The surface is built using a variational spline algorithm. It uses the principle of deformation of a thin plate by localised mechanical forces. If not already given in the input, an initial surface is calculated. This corresponds to the plate prior
591 to deformation. Then, the algorithm is called to calculate the final surface. It looks for a solution satisfying constraints and minimizing energy input.
593 @figure{/user_guides/modeling_algos/images/modeling_algos_image061.png,"Surface generated from two curves and a point",360}
595 The package *GeomPlate* provides the following services for creating surfaces respecting curve and point constraints:
597 #### Definition of a Framework
599 The class *BuildPlateSurface* allows creating a framework to build surfaces according to curve and point constraints as well as tolerance settings. The result is returned with the function *Surface*.
601 Note that you do not have to specify an initial surface at the time of construction. It can be added later or, if none is loaded, a surface will be computed automatically.
603 #### Definition of a Curve Constraint
605 The class *CurveConstraint* allows defining curves as constraints to the surface, which you want to build.
607 #### Definition of a Point Constraint
609 The class *PointConstraint* allows defining points as constraints to the surface, which you want to build.
611 #### Applying Geom_Surface to Plate Surfaces
613 The class *Surface* allows describing the characteristics of plate surface objects returned by **BuildPlateSurface::Surface** using the methods of *Geom_Surface*
615 #### Approximating a Plate surface to a BSpline
617 The class *MakeApprox* allows converting a *GeomPlate* surface into a *Geom_BSplineSurface*.
619 @figure{/user_guides/modeling_algos/images/modeling_algos_image060.png,"Surface generated from four curves and a point",360}
621 Let us create a Plate surface and approximate it from a polyline as a curve constraint and a point constraint
624 Standard_Integer NbCurFront=4,
627 gp_Pnt P2(0.,10.,0.);
628 gp_Pnt P3(0.,10.,10.);
629 gp_Pnt P4(0.,0.,10.);
631 BRepBuilderAPI_MakePolygon W;
637 // Initialize a BuildPlateSurface
638 GeomPlate_BuildPlateSurface BPSurf(3,15,2);
639 // Create the curve constraints
640 BRepTools_WireExplorer anExp;
641 for(anExp.Init(W); anExp.More(); anExp.Next())
643 TopoDS_Edge E = anExp.Current();
644 Handle(BRepAdaptor_HCurve) C = new
645 BRepAdaptor_HCurve();
646 C-ChangeCurve().Initialize(E);
647 Handle(BRepFill_CurveConstraint) Cont= new
648 BRepFill_CurveConstraint(C,0);
652 Handle(GeomPlate_PointConstraint) PCont= new
653 GeomPlate_PointConstraint(P5,0);
655 // Compute the Plate surface
657 // Approximation of the Plate surface
658 Standard_Integer MaxSeg=9;
659 Standard_Integer MaxDegree=8;
660 Standard_Integer CritOrder=0;
661 Standard_Real dmax,Tol;
662 Handle(GeomPlate_Surface) PSurf = BPSurf.Surface();
663 dmax = Max(0.0001,10*BPSurf.G0Error());
666 Mapp(PSurf,Tol,MaxSeg,MaxDegree,dmax,CritOrder);
667 Handle (Geom_Surface) Surf (Mapp.Surface());
668 // create a face corresponding to the approximated Plate
670 Standard_Real Umin, Umax, Vmin, Vmax;
671 PSurf->Bounds( Umin, Umax, Vmin, Vmax);
672 BRepBuilderAPI_MakeFace MF(Surf,Umin, Umax, Vmin, Vmax);
675 @subsection occt_modalg_2_6 Projections
677 Projections provide for computing the following:
678 * the projections of a 2D point onto a 2D curve
679 * the projections of a 3D point onto a 3D curve or surface
680 * the projection of a 3D curve onto a surface.
681 * the planar curve transposition from the 3D to the 2D parametric space of an underlying plane and v. s.
682 * the positioning of a 2D gp object in the 3D geometric space.
684 @subsubsection occt_modalg_2_6_1 Projection of a 2D Point on a Curve
686 *Geom2dAPI_ProjectPointOnCurve* allows calculation of all normals projected from a point (*gp_Pnt2d*) onto a geometric curve (*Geom2d_Curve*). The calculation may be restricted to a given domain.
688 @figure{/user_guides/modeling_algos/images/modeling_algos_image020.png,"Normals from a point to a curve",320}
690 The curve does not have to be a *Geom2d_TrimmedCurve*. The algorithm will function with any class inheriting *Geom2d_Curve*.
692 The class *Geom2dAPI_ProjectPointOnCurve* may be instantiated as in the following example:
696 Handle(Geom2d_BezierCurve) C =
697 new Geom2d_BezierCurve(args);
698 Geom2dAPI_ProjectPointOnCurve Projector (P, C);
701 To restrict the search for normals to a given domain <i>[U1,U2]</i>, use the following constructor:
703 Geom2dAPI_ProjectPointOnCurve Projector (P, C, U1, U2);
705 Having thus created the *Geom2dAPI_ProjectPointOnCurve* object, we can now interrogate it.
707 #### Calling the number of solution points
710 Standard_Integer NumSolutions = Projector.NbPoints();
713 #### Calling the location of a solution point
715 The solutions are indexed in a range from *1* to *Projector.NbPoints()*. The point, which corresponds to a given *Index* may be found:
717 gp_Pnt2d Pn = Projector.Point(Index);
720 #### Calling the parameter of a solution point
722 For a given point corresponding to a given *Index*:
725 Standard_Real U = Projector.Parameter(Index);
728 This can also be programmed as:
732 Projector.Parameter(Index,U);
735 #### Calling the distance between the start and end points
737 We can find the distance between the initial point and a point, which corresponds to the given *Index*:
740 Standard_Real D = Projector.Distance(Index);
743 #### Calling the nearest solution point
746 This class offers a method to return the closest solution point to the starting point. This solution is accessed as follows:
748 gp_Pnt2d P1 = Projector.NearestPoint();
751 #### Calling the parameter of the nearest solution point
754 Standard_Real U = Projector.LowerDistanceParameter();
757 #### Calling the minimum distance from the point to the curve
760 Standard_Real D = Projector.LowerDistance();
763 #### Redefined operators
765 Some operators have been redefined to find the closest solution.
767 *Standard_Real()* returns the minimum distance from the point to the curve.
770 Standard_Real D = Geom2dAPI_ProjectPointOnCurve (P,C);
773 *Standard_Integer()* returns the number of solutions.
777 Geom2dAPI_ProjectPointOnCurve (P,C);
780 *gp_Pnt2d()* returns the nearest solution point.
783 gp_Pnt2d P1 = Geom2dAPI_ProjectPointOnCurve (P,C);
786 Using these operators makes coding easier when you only need the nearest point. Thus:
788 Geom2dAPI_ProjectPointOnCurve Projector (P, C);
789 gp_Pnt2d P1 = Projector.NearestPoint();
791 can be written more concisely as:
793 gp_Pnt2d P1 = Geom2dAPI_ProjectPointOnCurve (P,C);
795 However, note that in this second case no intermediate *Geom2dAPI_ProjectPointOnCurve* object is created, and thus it is impossible to have access to other solution points.
798 #### Access to lower-level functionalities
800 If you want to use the wider range of functionalities available from the *Extrema* package, a call to the *Extrema()* method will return the algorithmic object for calculating extrema. For example:
803 Extrema_ExtPC2d& TheExtrema = Projector.Extrema();
806 @subsubsection occt_modalg_2_6_2 Projection of a 3D Point on a Curve
808 The class *GeomAPI_ProjectPointOnCurve* is instantiated as in the following example:
812 Handle(Geom_BezierCurve) C =
813 new Geom_BezierCurve(args);
814 GeomAPI_ProjectPointOnCurve Projector (P, C);
817 If you wish to restrict the search for normals to the given domain [U1,U2], use the following constructor:
820 GeomAPI_ProjectPointOnCurve Projector (P, C, U1, U2);
822 Having thus created the *GeomAPI_ProjectPointOnCurve* object, you can now interrogate it.
824 #### Calling the number of solution points
827 Standard_Integer NumSolutions = Projector.NbPoints();
830 #### Calling the location of a solution point
832 The solutions are indexed in a range from 1 to *Projector.NbPoints()*. The point, which corresponds to a given index, may be found:
834 gp_Pnt Pn = Projector.Point(Index);
837 #### Calling the parameter of a solution point
839 For a given point corresponding to a given index:
842 Standard_Real U = Projector.Parameter(Index);
845 This can also be programmed as:
848 Projector.Parameter(Index,U);
851 #### Calling the distance between the start and end point
853 The distance between the initial point and a point, which corresponds to a given index, may be found:
855 Standard_Real D = Projector.Distance(Index);
858 #### Calling the nearest solution point
860 This class offers a method to return the closest solution point to the starting point. This solution is accessed as follows:
862 gp_Pnt P1 = Projector.NearestPoint();
865 #### Calling the parameter of the nearest solution point
868 Standard_Real U = Projector.LowerDistanceParameter();
871 #### Calling the minimum distance from the point to the curve
874 Standard_Real D = Projector.LowerDistance();
877 #### Redefined operators
879 Some operators have been redefined to find the nearest solution.
881 *Standard_Real()* returns the minimum distance from the point to the curve.
884 Standard_Real D = GeomAPI_ProjectPointOnCurve (P,C);
887 *Standard_Integer()* returns the number of solutions.
889 Standard_Integer N = GeomAPI_ProjectPointOnCurve (P,C);
892 *gp_Pnt2d()* returns the nearest solution point.
895 gp_Pnt P1 = GeomAPI_ProjectPointOnCurve (P,C);
897 Using these operators makes coding easier when you only need the nearest point. In this way,
900 GeomAPI_ProjectPointOnCurve Projector (P, C);
901 gp_Pnt P1 = Projector.NearestPoint();
904 can be written more concisely as:
906 gp_Pnt P1 = GeomAPI_ProjectPointOnCurve (P,C);
908 In the second case, however, no intermediate *GeomAPI_ProjectPointOnCurve* object is created, and it is impossible to access other solutions points.
910 #### Access to lower-level functionalities
912 If you want to use the wider range of functionalities available from the *Extrema* package, a call to the *Extrema()* method will return the algorithmic object for calculating the extrema. For example:
915 Extrema_ExtPC& TheExtrema = Projector.Extrema();
918 @subsubsection occt_modalg_2_6_3 Projection of a Point on a Surface
920 The class *GeomAPI_ProjectPointOnSurf* allows calculation of all normals projected from a point from *gp_Pnt* onto a geometric surface from *Geom_Surface*.
922 @figure{/user_guides/modeling_algos/images/modeling_algos_image021.png,"Projection of normals from a point to a surface",360}
924 Note that the surface does not have to be of *Geom_RectangularTrimmedSurface* type.
925 The algorithm will function with any class inheriting *Geom_Surface*.
927 *GeomAPI_ProjectPointOnSurf* is instantiated as in the following example:
930 Handle (Geom_Surface) S = new Geom_BezierSurface(args);
931 GeomAPI_ProjectPointOnSurf Proj (P, S);
934 To restrict the search for normals within the given rectangular domain [U1, U2, V1, V2], use the constructor <i>GeomAPI_ProjectPointOnSurf Proj (P, S, U1, U2, V1, V2)</i>
936 The values of *U1, U2, V1* and *V2* lie at or within their maximum and minimum limits, i.e.:
938 Umin <= U1 < U2 <= Umax
939 Vmin <= V1 < V2 <= Vmax
941 Having thus created the *GeomAPI_ProjectPointOnSurf* object, you can interrogate it.
943 #### Calling the number of solution points
946 Standard_Integer NumSolutions = Proj.NbPoints();
949 #### Calling the location of a solution point
951 The solutions are indexed in a range from 1 to *Proj.NbPoints()*. The point corresponding to the given index may be found:
954 gp_Pnt Pn = Proj.Point(Index);
957 #### Calling the parameters of a solution point
959 For a given point corresponding to the given index:
963 Proj.Parameters(Index, U, V);
966 #### Calling the distance between the start and end point
969 The distance between the initial point and a point corresponding to the given index may be found:
971 Standard_Real D = Projector.Distance(Index);
974 #### Calling the nearest solution point
976 This class offers a method, which returns the closest solution point to the starting point. This solution is accessed as follows:
978 gp_Pnt P1 = Proj.NearestPoint();
981 #### Calling the parameters of the nearest solution point
985 Proj.LowerDistanceParameters (U, V);
988 #### Calling the minimum distance from a point to the surface
991 Standard_Real D = Proj.LowerDistance();
994 #### Redefined operators
996 Some operators have been redefined to help you find the nearest solution.
998 *Standard_Real()* returns the minimum distance from the point to the surface.
1001 Standard_Real D = GeomAPI_ProjectPointOnSurf (P,S);
1004 *Standard_Integer()* returns the number of solutions.
1007 Standard_Integer N = GeomAPI_ProjectPointOnSurf (P,S);
1010 *gp_Pnt2d()* returns the nearest solution point.
1013 gp_Pnt P1 = GeomAPI_ProjectPointOnSurf (P,S);
1016 Using these operators makes coding easier when you only need the nearest point. In this way,
1019 GeomAPI_ProjectPointOnSurface Proj (P, S);
1020 gp_Pnt P1 = Proj.NearestPoint();
1023 can be written more concisely as:
1026 gp_Pnt P1 = GeomAPI_ProjectPointOnSurface (P,S);
1029 In the second case, however, no intermediate *GeomAPI_ProjectPointOnSurf* object is created, and it is impossible to access other solution points.
1031 #### Access to lower-level functionalities
1033 If you want to use the wider range of functionalities available from the *Extrema* package, a call to the *Extrema()* method will return the algorithmic object for calculating the extrema as follows:
1036 Extrema_ExtPS& TheExtrema = Proj.Extrema();
1039 @subsubsection occt_modalg_2_12_8 Switching from 2d and 3d Curves
1041 The *To2d* and *To3d* methods are used to;
1043 * build a 2d curve from a 3d *Geom_Curve* lying on a *gp_Pln* plane
1044 * build a 3d curve from a *Geom2d_Curve* and a *gp_Pln* plane.
1046 These methods are called as follows:
1048 Handle(Geom2d_Curve) C2d = GeomAPI::To2d(C3d, Pln);
1049 Handle(Geom_Curve) C3d = GeomAPI::To3d(C2d, Pln);
1053 @section occt_modalg_2_topo_tools Topological Tools
1055 Open CASCADE Technology topological tools provide algorithms to
1056 * Create wires from edges;
1057 * Create faces from wires;
1058 * Compute state of the shape relatively other shape;
1059 * Orient shapes in container;
1060 * Create new shapes from the existing ones;
1061 * Build PCurves of edges on the faces;
1062 * Check the validity of the shapes;
1063 * Take the point in the face;
1064 * Get the normal direction for the face.
1067 @subsection occt_modalg_2_topo_tools_1 Creation of the faces from wireframe model
1069 It is possible to create the planar faces from the arbitrary set of planar edges randomly located in 3D space.
1070 This feature might be useful if you need for instance to restore the shape from the wireframe model:
1071 <table align="center">
1073 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_image062.png,"Wireframe model",160}</td>
1074 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_image063.png,"Faces of the model",160}</td>
1078 To make the faces from edges it is, firstly, necessary to create planar wires from the given edges and than create planar faces from each wire.
1079 The static methods *BOPAlgo_Tools::EdgesToWires* and *BOPAlgo_Tools::WiresToFaces* can be used for that:
1081 TopoDS_Shape anEdges = ...; /* The input edges */
1082 Standard_Real anAngTol = 1.e-8; /* The angular tolerance for distinguishing the planes in which the wires are located */
1083 Standard_Boolean bShared = Standard_False; /* Defines whether the edges are shared or not */
1085 TopoDS_Shape aWires; /* resulting wires */
1086 Standard_Integer iErr = BOPAlgo_Tools::EdgesToWires(anEdges, aWires, bShared, anAngTol);
1088 cout << "Error: Unable to build wires from given edges\n";
1092 TopoDS_Shape aFaces; /* resulting faces */
1093 Standard_Boolean bDone = BOPAlgo_Tools::WiresToFaces(aWires, aFaces, anAngTol);
1095 cout << "Error: Unable to build faces from wires\n";
1100 These methods can also be used separately:
1101 * *BOPAlgo_Tools::EdgesToWires* allows creating planar wires from edges.
1102 The input edges may be not shared, but the output wires will be sharing the coinciding vertices and edges. For this the intersection of the edges is performed.
1103 Although, it is possible to skip the intersection stage (if the input edges are already shared) by passing the corresponding flag into the method.
1104 The input edges are expected to be planar, but the method does not check it. Thus, if the input edges are not planar, the output wires will also be not planar.
1105 In general, the output wires are non-manifold and may contain free vertices, as well as multi-connected vertices.
1106 * *BOPAlgo_Tools::WiresToFaces* allows creating planar faces from the planar wires.
1107 In general, the input wires are non-manifold and may be not closed, but should share the coinciding parts.
1108 The wires located in the same plane and completely included into other wires will create holes in the faces built from outer wires:
1110 <table align="center">
1112 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_image064.png,"Wireframe model",160}</td>
1113 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_image065.png,"Two faces (red face has a hole)",160}</td>
1118 @subsection occt_modalg_2_topo_tools_2 Classification of the shapes
1120 The following methods allow classifying the different shapes relatively other shapes:
1121 * The variety of the *BOPTools_AlgoTools::ComputState* methods classify the vertex/edge/face relatively solid;
1122 * *BOPTools_AlgoTools::IsHole* classifies wire relatively face;
1123 * *IntTools_Tools::ClassifyPointByFace* classifies point relatively face.
1125 @subsection occt_modalg_2_topo_tools_3 Orientation of the shapes in the container
1127 The following methods allow reorienting shapes in the containers:
1128 * *BOPTools_AlgoTools::OrientEdgesOnWire* correctly orients edges on the wire;
1129 * *BOPTools_AlgoTools::OrientFacesOnShell* correctly orients faces on the shell.
1131 @subsection occt_modalg_2_topo_tools_4 Making new shapes
1133 The following methods allow creating new shapes from the existing ones:
1134 * The variety of the *BOPTools_AlgoTools::MakeNewVertex* creates the new vertices from other vertices and edges;
1135 * *BOPTools_AlgoTools::MakeSplitEdge* splits the edge by the given parameters.
1137 @subsection occt_modalg_2_topo_tools_5 Building PCurves
1139 The following methods allow building PCurves of edges on faces:
1140 * *BOPTools_AlgoTools::BuildPCurveForEdgeOnFace* computes PCurve for the edge on the face;
1141 * *BOPTools_AlgoTools::BuildPCurveForEdgeOnPlane* and *BOPTools_AlgoTools::BuildPCurveForEdgesOnPlane* allow building PCurves for edges on the planar face;
1142 * *BOPTools_AlgoTools::AttachExistingPCurve* takes PCurve on the face from one edge and attach this PCurve to other edge coinciding with the first one.
1144 @subsection occt_modalg_2_topo_tools_6 Checking the validity of the shapes
1146 The following methods allow checking the validity of the shapes:
1147 * *BOPTools_AlgoTools::IsMicroEdge* detects the small edges;
1148 * *BOPTools_AlgoTools::ComputeTolerance* computes the correct tolerance of the edge on the face;
1149 * *BOPTools_AlgoTools::CorrectShapeTolerances* and *BOPTools_AlgoTools::CorrectTolerances* allow correcting the tolerances of the sub-shapes.
1150 * *BRepLib::FindValidRange* finds a range of 3d curve of the edge not covered by tolerance spheres of vertices.
1152 @subsection occt_modalg_2_topo_tools_7 Taking a point inside the face
1154 The following methods allow taking a point located inside the face:
1155 * The variety of the *BOPTools_AlgoTools3D::PointNearEdge* allows getting a point inside the face located near the edge;
1156 * *BOPTools_AlgoTools3D::PointInFace* allows getting a point inside the face.
1158 @subsection occt_modalg_2_topo_tools_8 Getting normal for the face
1160 The following methods allow getting the normal direction for the face/surface:
1161 * *BOPTools_AlgoTools3D::GetNormalToSurface* computes the normal direction for the surface in the given point defined by UV parameters;
1162 * *BOPTools_AlgoTools3D::GetNormalToFaceOnEdge* computes the normal direction for the face in the point located on the edge of the face;
1163 * *BOPTools_AlgoTools3D::GetApproxNormalToFaceOnEdge* computes the normal direction for the face in the point located near the edge of the face.
1167 @section occt_modalg_3a The Topology API
1169 The Topology API of Open CASCADE Technology (**OCCT**) includes the following six packages:
1177 The classes provided by the API have the following features:
1178 * The constructors of classes provide different construction methods;
1179 * The class retains different tools used to build objects as fields;
1180 * The class provides a casting method to obtain the result automatically with a function-like call.
1182 Let us use the class *BRepBuilderAPI_MakeEdge* to create a linear edge from two points.
1185 gp_Pnt P1(10,0,0), P2(20,0,0);
1186 TopoDS_Edge E = BRepBuilderAPI_MakeEdge(P1,P2);
1189 This is the simplest way to create edge E from two points P1, P2, but the developer can test for errors when he is not as confident of the data as in the previous example.
1192 #include <gp_Pnt.hxx>
1193 #include <TopoDS_Edge.hxx>
1194 #include <BRepBuilderAPI_MakeEdge.hxx>
1199 BRepBuilderAPI_MakeEdge ME(P1,P2);
1202 // doing ME.Edge() or E = ME here
1203 // would raise StdFail_NotDone
1204 Standard_DomainError::Raise
1205 (“ProcessPoints::Failed to createan edge”);
1211 In this example an intermediary object ME has been introduced. This can be tested for the completion of the function before accessing the result. More information on **error handling** in the topology programming interface can be found in the next section.
1213 *BRepBuilderAPI_MakeEdge* provides valuable information. For example, when creating an edge from two points, two vertices have to be created from the points. Sometimes you may be interested in getting these vertices quickly without exploring the new edge. Such information can be provided when using a class. The following example shows a function creating an edge and two vertices from two points.
1216 void MakeEdgeAndVertices(const gp_Pnt& P1,
1222 BRepBuilderAPI_MakeEdge ME(P1,P2);
1224 Standard_DomainError::Raise
1225 (“MakeEdgeAndVerices::Failed to create an edge”);
1232 The class *BRepBuilderAPI_MakeEdge* provides two methods *Vertex1* and *Vertex2*, which return two vertices used to create the edge.
1234 How can *BRepBuilderAPI_MakeEdge* be both a function and a class? It can do this because it uses the casting capabilities of C++. The *BRepBuilderAPI_MakeEdge* class has a method called Edge; in the previous example the line <i>E = ME</i> could have been written.
1240 This instruction tells the C++ compiler that there is an **implicit casting** of a *BRepBuilderAPI_MakeEdge* into a *TopoDS_Edge* using the *Edge* method. It means this method is automatically called when a *BRepBuilderAPI_MakeEdge* is found where a *TopoDS_Edge* is required.
1242 This feature allows you to provide classes, which have the simplicity of function calls when required and the power of classes when advanced processing is necessary. All the benefits of this approach are explained when describing the topology programming interface classes.
1245 @subsection occt_modalg_3a_1 Error Handling in the Topology API
1247 A method can report an error in the two following situations:
1248 * The data or arguments of the method are incorrect, i.e. they do not respect the restrictions specified by the methods in its specifications. Typical example: creating a linear edge from two identical points is likely to lead to a zero divide when computing the direction of the line.
1249 * Something unexpected happened. This situation covers every error not included in the first category. Including: interruption, programming errors in the method or in another method called by the first method, bad specifications of the arguments (i.e. a set of arguments that was not expected to fail).
1251 The second situation is supposed to become increasingly exceptional as a system is debugged and it is handled by the **exception mechanism**. Using exceptions avoids handling error statuses in the call to a method: a very cumbersome style of programming.
1253 In the first situation, an exception is also supposed to be raised because the calling method should have verified the arguments and if it did not do so, there is a bug. For example, if before calling *MakeEdge* you are not sure that the two points are non-identical, this situation must be tested.
1255 Making those validity checks on the arguments can be tedious to program and frustrating as you have probably correctly surmised that the method will perform the test twice. It does not trust you.
1256 As the test involves a great deal of computation, performing it twice is also time-consuming.
1258 Consequently, you might be tempted to adopt the highly inadvisable style of programming illustrated in the following example:
1261 #include <Standard_ErrorHandler.hxx>
1263 TopoDS_Edge E = BRepBuilderAPI_MakeEdge(P1,P2);
1264 // go on with the edge
1267 // process the error.
1271 To help the user, the Topology API classes only raise the exception *StdFail_NotDone*. Any other exception means that something happened which was unforeseen in the design of this API.
1273 The *NotDone* exception is only raised when the user tries to access the result of the computation and the original data is corrupted. At the construction of the class instance, if the algorithm cannot be completed, the internal flag *NotDone* is set. This flag can be tested and in some situations a more complete description of the error can be queried. If the user ignores the *NotDone* status and tries to access the result, an exception is raised.
1276 BRepBuilderAPI_MakeEdge ME(P1,P2);
1278 // doing ME.Edge() or E = ME here
1279 // would raise StdFail_NotDone
1280 Standard_DomainError::Raise
1281 (“ProcessPoints::Failed to create an edge”);
1287 @subsection occt_modalg_hist History support
1289 All topological API algorithms support the history of shape modifications (or just History) for their arguments.
1290 Generally, the history is available for the following types of sub-shapes of input shapes:
1295 Some algorithms also support the history for Solids.
1297 The history information consists of the following information:
1298 * Information about Deleted shapes;
1299 * Information about Modified shapes;
1300 * Information about Generated shapes.
1302 The History is filled basing on the result of the operation. History cannot return any shapes not contained in the result.
1303 If the result of the operation is an empty shape, all input shapes will be considered as Deleted and none will have Modified and Generated shapes.
1305 The history information can be accessed by the API methods:
1306 * *Standard_Boolean IsDeleted(const TopoDS_Shape& theS)* - to check if the shape has been Deleted during the operation;
1307 * *const TopTools_ListOfShape& Modified(const TopoDS_Shape& theS)* - to get the shapes Modified from the given shape;
1308 * *const TopTools_ListOfShape& Generated(const TopoDS_Shape& theS)* - to get the shapes Generated from the given shape.
1310 @subsubsection occt_modalg_hist_del Deleted shapes
1312 The shape is considered as Deleted during the operation if all of the following conditions are met:
1313 * The shape is a part of the argument shapes of the operation;
1314 * The result shape does not contain the shape itself;
1315 * The result shape does not contain any of the splits of the shape.
1317 For example, in the CUT operation between two intersecting solids all vertices/edges/faces located completely inside the Tool solid will be Deleted during the operation.
1319 @subsubsection occt_modalg_hist_mod Modified shapes
1321 The shape is considered as Modified during the operation if the result shape contains the splits of the shape, not the shape itself. The shape can be modified only into the shapes with the same dimension.
1322 The splits of the shape contained in the result shape are Modified from the shape.
1323 The Modified shapes are created from the sub-shapes of the input shapes and, generally, repeat their geometry.
1325 The list of Modified elements will contain only those contributing to the result of the operation. If the list is empty, the shape has not been modified and it is necessary to check if it has been Deleted.
1327 For example, after translation of the shape in any direction all its sub-shapes will be modified into their translated copies.
1329 @subsubsection occt_modalg_hist_gen Generated shapes
1331 The shapes contained in the result shape are considered as Generated from the input shape if they were produced during the operation and have a different dimension from the shapes from which they were created.
1333 The list of Generated elements will contain only those included in the result of the operation. If the list is empty, no new shapes have been Generated from the shape.
1335 For example, extrusion of the edge in some direction will create a face. This face will be generated from the edge.
1337 @subsubsection occt_modalg_hist_tool BRepTools_History
1339 *BRepTools_History* is the general History tool intended for unification of the histories of different algorithms.
1341 *BRepTools_History* can be created from any algorithm supporting the standard history methods *(IsDeleted(), Modified()* and *Generated())*:
1343 // The arguments of the operation
1344 TopoDS_Shape aS = ...;
1346 // Perform transformation on the shape
1348 aTrsf.SetTranslationPart(gp_Vec(0, 0, 1));
1349 BRepBuilderAPI_Transform aTransformer(aS, aTrsf); // Transformation API algorithm
1350 const TopoDS_Shape& aRes = aTransformer.Shape();
1352 // Create the translation history object
1353 TopTools_ListOfShape anArguments;
1354 anArguments.Append(aS);
1355 BRepTools_History aHistory(anArguments, aTransformer);
1358 *BRepTools_History* also allows merging histories. Thus, if you have two or more subsequent operations you can get one final history combined from histories of these operations:
1361 Handle(BRepTools_History) aHist1 = ...; // History of first operation
1362 Handle(BRepTools_History) aHist2 = ...; // History of second operation
1365 It is possible to merge the second history into the first one:
1367 aHist1->Merge(aHist2);
1370 Or create the new history keeping the two histories unmodified:
1372 Handle(BRepTools_History) aResHistory = new BRepTools_History;
1373 aResHistory->Merge(aHist1);
1374 aResHistory->Merge(aHist2);
1377 The possibilities of Merging histories and history creation from the API algorithms allow providing easy History support for the new algorithms.
1379 @subsubsection occt_modalg_hist_draw DRAW history support
1381 DRAW History support for the algorithms is provided by three basic commands:
1386 For more information on the Draw History mechanism, refer to the corresponding chapter in the Draw users guide - @ref occt_draw_hist "History commands".
1389 @section occt_modalg_3 Standard Topological Objects
1391 The following standard topological objects can be created:
1400 There are two root classes for their construction and modification:
1401 * The deferred class *BRepBuilderAPI_MakeShape* is the root of all *BRepBuilderAPI* classes, which build shapes. It inherits from the class *BRepBuilderAPI_Command* and provides a field to store the constructed shape.
1402 * The deferred class *BRepBuilderAPI_ModifyShape* is used as a root for the shape modifications. It inherits *BRepBuilderAPI_MakeShape* and implements the methods used to trace the history of all sub-shapes.
1404 @subsection occt_modalg_3_1 Vertex
1406 *BRepBuilderAPI_MakeVertex* creates a new vertex from a 3D point from gp.
1409 TopoDS_Vertex V = BRepBuilderAPI_MakeVertex(P);
1412 This class always creates a new vertex and has no other methods.
1414 @subsection occt_modalg_3_2 Edge
1416 @subsubsection occt_modalg_3_2_1 Basic edge construction method
1418 Use *BRepBuilderAPI_MakeEdge* to create from a curve and vertices. The basic method constructs an edge from a curve, two vertices, and two parameters.
1421 Handle(Geom_Curve) C = ...; // a curve
1422 TopoDS_Vertex V1 = ...,V2 = ...;// two Vertices
1423 Standard_Real p1 = ..., p2 = ..;// two parameters
1424 TopoDS_Edge E = BRepBuilderAPI_MakeEdge(C,V1,V2,p1,p2);
1427 where C is the domain of the edge; V1 is the first vertex oriented FORWARD; V2 is the second vertex oriented REVERSED; p1 and p2 are the parameters for the vertices V1 and V2 on the curve. The default tolerance is associated with this edge.
1429 @figure{/user_guides/modeling_algos/images/modeling_algos_image022.png,"Basic Edge Construction",220}
1431 The following rules apply to the arguments:
1434 * Must not be a Null Handle.
1435 * If the curve is a trimmed curve, the basis curve is used.
1438 * Can be null shapes. When V1 or V2 is Null the edge is open in the corresponding direction and the corresponding parameter p1 or p2 must be infinite (i.e p1 is RealFirst(), p2 is RealLast()).
1439 * Must be different vertices if they have different 3d locations and identical vertices if they have the same 3d location (identical vertices are used when the curve is closed).
1442 * Must be increasing and in the range of the curve, i.e.:
1445 C->FirstParameter() <= p1 < p2 <= C->LastParameter()
1448 * If the parameters are decreasing, the Vertices are switched, i.e. V2 becomes V1 and V1 becomes V2.
1449 * On a periodic curve the parameters p1 and p2 are adjusted by adding or subtracting the period to obtain p1 in the range of the curve and p2 in the range p1 < p2 <= p1+ Period. So on a parametric curve p2 can be greater than the second parameter, see the figure below.
1450 * Can be infinite but the corresponding vertex must be Null (see above).
1451 * The distance between the Vertex 3d location and the point evaluated on the curve with the parameter must be lower than the default precision.
1453 The figure below illustrates two special cases, a semi-infinite edge and an edge on a periodic curve.
1455 @figure{/user_guides/modeling_algos/images/modeling_algos_image023.png,"Infinite and Periodic Edges",220}
1457 @subsubsection occt_modalg_3_2_2 Supplementary edge construction methods
1459 There exist supplementary edge construction methods derived from the basic one.
1461 *BRepBuilderAPI_MakeEdge* class provides methods, which are all simplified calls of the previous one:
1463 * The parameters can be omitted. They are computed by projecting the vertices on the curve.
1464 * 3d points (Pnt from gp) can be given in place of vertices. Vertices are created from the points. Giving vertices is useful when creating connected vertices.
1465 * The vertices or points can be omitted if the parameters are given. The points are computed by evaluating the parameters on the curve.
1466 * The vertices or points and the parameters can be omitted. The first and the last parameters of the curve are used.
1468 The five following methods are thus derived from the basic construction:
1471 Handle(Geom_Curve) C = ...; // a curve
1472 TopoDS_Vertex V1 = ...,V2 = ...;// two Vertices
1473 Standard_Real p1 = ..., p2 = ..;// two parameters
1474 gp_Pnt P1 = ..., P2 = ...;// two points
1476 // project the vertices on the curve
1477 E = BRepBuilderAPI_MakeEdge(C,V1,V2);
1478 // Make vertices from points
1479 E = BRepBuilderAPI_MakeEdge(C,P1,P2,p1,p2);
1480 // Make vertices from points and project them
1481 E = BRepBuilderAPI_MakeEdge(C,P1,P2);
1482 // Computes the points from the parameters
1483 E = BRepBuilderAPI_MakeEdge(C,p1,p2);
1484 // Make an edge from the whole curve
1485 E = BRepBuilderAPI_MakeEdge(C);
1489 Six methods (the five above and the basic method) are also provided for curves from the gp package in place of Curve from Geom. The methods create the corresponding Curve from Geom and are implemented for the following classes:
1491 *gp_Lin* creates a *Geom_Line*
1492 *gp_Circ* creates a *Geom_Circle*
1493 *gp_Elips* creates a *Geom_Ellipse*
1494 *gp_Hypr* creates a *Geom_Hyperbola*
1495 *gp_Parab* creates a *Geom_Parabola*
1497 There are also two methods to construct edges from two vertices or two points. These methods assume that the curve is a line; the vertices or points must have different locations.
1501 TopoDS_Vertex V1 = ...,V2 = ...;// two Vertices
1502 gp_Pnt P1 = ..., P2 = ...;// two points
1505 // linear edge from two vertices
1506 E = BRepBuilderAPI_MakeEdge(V1,V2);
1508 // linear edge from two points
1509 E = BRepBuilderAPI_MakeEdge(P1,P2);
1512 @subsubsection occt_modalg_3_2_3 Other information and error status
1514 The class *BRepBuilderAPI_MakeEdge* can provide extra information and return an error status.
1516 If *BRepBuilderAPI_MakeEdge* is used as a class, it can provide two vertices. This is useful when the vertices were not provided as arguments, for example when the edge was constructed from a curve and parameters. The two methods *Vertex1* and *Vertex2* return the vertices. Note that the returned vertices can be null if the edge is open in the corresponding direction.
1518 The *Error* method returns a term of the *BRepBuilderAPI_EdgeError* enumeration. It can be used to analyze the error when *IsDone* method returns False. The terms are:
1520 * **EdgeDone** -- No error occurred, *IsDone* returns True.
1521 * **PointProjectionFailed** -- No parameters were given, but the projection of the 3D points on the curve failed. This happens if the point distance to the curve is greater than the precision.
1522 * **ParameterOutOfRange** -- The given parameters are not in the range *C->FirstParameter()*, *C->LastParameter()*
1523 * **DifferentPointsOnClosedCurve** -- The two vertices or points have different locations but they are the extremities of a closed curve.
1524 * **PointWithInfiniteParameter** -- A finite coordinate point was associated with an infinite parameter (see the Precision package for a definition of infinite values).
1525 * **DifferentsPointAndParameter** -- The distance of the 3D point and the point evaluated on the curve with the parameter is greater than the precision.
1526 * **LineThroughIdenticPoints** -- Two identical points were given to define a line (construction of an edge without curve), *gp::Resolution* is used to test confusion .
1528 The following example creates a rectangle centered on the origin of dimensions H, L with fillets of radius R. The edges and the vertices are stored in the arrays *theEdges* and *theVertices*. We use class *Array1OfShape* (i.e. not arrays of edges or vertices). See the image below.
1530 @figure{/user_guides/modeling_algos/images/modeling_algos_image024.png,"Creating a Wire",360}
1533 #include <BRepBuilderAPI_MakeEdge.hxx>
1534 #include <TopoDS_Shape.hxx>
1535 #include <gp_Circ.hxx>
1537 #include <TopoDS_Wire.hxx>
1538 #include <TopTools_Array1OfShape.hxx>
1539 #include <BRepBuilderAPI_MakeWire.hxx>
1541 // Use MakeArc method to make an edge and two vertices
1542 void MakeArc(Standard_Real x,Standard_Real y,
1549 gp_Ax2 Origin = gp::XOY();
1550 gp_Vec Offset(x, y, 0.);
1551 Origin.Translate(Offset);
1552 BRepBuilderAPI_MakeEdge
1553 ME(gp_Circ(Origin,R), ang, ang+PI/2);
1559 TopoDS_Wire MakeFilletedRectangle(const Standard_Real H,
1560 const Standard_Real L,
1561 const Standard_Real R)
1563 TopTools_Array1OfShape theEdges(1,8);
1564 TopTools_Array1OfShape theVertices(1,8);
1566 // First create the circular edges and the vertices
1567 // using the MakeArc function described above.
1568 void MakeArc(Standard_Real, Standard_Real,
1569 Standard_Real, Standard_Real,
1570 TopoDS_Shape&, TopoDS_Shape&, TopoDS_Shape&);
1572 Standard_Real x = L/2 - R, y = H/2 - R;
1573 MakeArc(x,-y,R,3.*PI/2.,theEdges(2),theVertices(2),
1575 MakeArc(x,y,R,0.,theEdges(4),theVertices(4),
1577 MakeArc(-x,y,R,PI/2.,theEdges(6),theVertices(6),
1579 MakeArc(-x,-y,R,PI,theEdges(8),theVertices(8),
1581 // Create the linear edges
1582 for (Standard_Integer i = 1; i <= 7; i += 2)
1584 theEdges(i) = BRepBuilderAPI_MakeEdge
1585 (TopoDS::Vertex(theVertices(i)),TopoDS::Vertex
1586 (theVertices(i+1)));
1588 // Create the wire using the BRepBuilderAPI_MakeWire
1589 BRepBuilderAPI_MakeWire MW;
1590 for (i = 1; i <= 8; i++)
1592 MW.Add(TopoDS::Edge(theEdges(i)));
1598 @subsection occt_modalg_3_3 Edge 2D
1600 Use *BRepBuilderAPI_MakeEdge2d* class to make edges on a working plane from 2d curves. The working plane is a default value of the *BRepBuilderAPI* package (see the *Plane* methods).
1602 *BRepBuilderAPI_MakeEdge2d* class is strictly similar to BRepBuilderAPI_MakeEdge, but it uses 2D geometry from gp and Geom2d instead of 3D geometry.
1604 @subsection occt_modalg_3_4 Polygon
1606 *BRepBuilderAPI_MakePolygon* class is used to build polygonal wires from vertices or points. Points are automatically changed to vertices as in *BRepBuilderAPI_MakeEdge*.
1608 The basic usage of *BRepBuilderAPI_MakePolygon* is to create a wire by adding vertices or points using the Add method. At any moment, the current wire can be extracted. The close method can be used to close the current wire. In the following example, a closed wire is created from an array of points.
1611 #include <TopoDS_Wire.hxx>
1612 #include <BRepBuilderAPI_MakePolygon.hxx>
1613 #include <TColgp_Array1OfPnt.hxx>
1615 TopoDS_Wire ClosedPolygon(const TColgp_Array1OfPnt& Points)
1617 BRepBuilderAPI_MakePolygon MP;
1618 for(Standard_Integer i=Points.Lower();i=Points.Upper();i++)
1627 Short-cuts are provided for 2, 3, or 4 points or vertices. Those methods have a Boolean last argument to tell if the polygon is closed. The default value is False.
1631 Example of a closed triangle from three vertices:
1633 TopoDS_Wire W = BRepBuilderAPI_MakePolygon(V1,V2,V3,Standard_True);
1636 Example of an open polygon from four points:
1638 TopoDS_Wire W = BRepBuilderAPI_MakePolygon(P1,P2,P3,P4);
1641 *BRepBuilderAPI_MakePolygon* class maintains a current wire. The current wire can be extracted at any moment and the construction can proceed to a longer wire. After each point insertion, the class maintains the last created edge and vertex, which are returned by the methods *Edge, FirstVertex* and *LastVertex*.
1643 When the added point or vertex has the same location as the previous one it is not added to the current wire but the most recently created edge becomes Null. The *Added* method can be used to test this condition. The *MakePolygon* class never raises an error. If no vertex has been added, the *Wire* is *Null*. If two vertices are at the same location, no edge is created.
1645 @subsection occt_modalg_3_5 Face
1647 Use *BRepBuilderAPI_MakeFace* class to create a face from a surface and wires. An underlying surface is constructed from a surface and optional parametric values. Wires can be added to the surface. A planar surface can be constructed from a wire. An error status can be returned after face construction.
1649 @subsubsection occt_modalg_3_5_1 Basic face construction method
1651 A face can be constructed from a surface and four parameters to determine a limitation of the UV space. The parameters are optional, if they are omitted the natural bounds of the surface are used. Up to four edges and vertices are created with a wire. No edge is created when the parameter is infinite.
1654 Handle(Geom_Surface) S = ...; // a surface
1655 Standard_Real umin,umax,vmin,vmax; // parameters
1656 TopoDS_Face F = BRepBuilderAPI_MakeFace(S,umin,umax,vmin,vmax);
1659 @figure{/user_guides/modeling_algos/images/modeling_algos_image025.png,"Basic Face Construction",360}
1661 To make a face from the natural boundary of a surface, the parameters are not required:
1664 Handle(Geom_Surface) S = ...; // a surface
1665 TopoDS_Face F = BRepBuilderAPI_MakeFace(S);
1668 Constraints on the parameters are similar to the constraints in *BRepBuilderAPI_MakeEdge*.
1669 * *umin,umax (vmin,vmax)* must be in the range of the surface and must be increasing.
1670 * On a *U (V)* periodic surface *umin* and *umax (vmin,vmax)* are adjusted.
1671 * *umin, umax, vmin, vmax* can be infinite. There will be no edge in the corresponding direction.
1673 @subsubsection occt_modalg_3_5_2 Supplementary face construction methods
1675 The two basic constructions (from a surface and from a surface and parameters) are implemented for all *gp* package surfaces, which are transformed in the corresponding Surface from Geom.
1677 | gp package surface | | Geom package surface |
1678 | :------------------- | :----------- | :------------- |
1679 | *gp_Pln* | | *Geom_Plane* |
1680 | *gp_Cylinder* | | *Geom_CylindricalSurface* |
1681 | *gp_Cone* | creates a | *Geom_ConicalSurface* |
1682 | *gp_Sphere* | | *Geom_SphericalSurface* |
1683 | *gp_Torus* | | *Geom_ToroidalSurface* |
1685 Once a face has been created, a wire can be added using the *Add* method. For example, the following code creates a cylindrical surface and adds a wire.
1688 gp_Cylinder C = ..; // a cylinder
1689 TopoDS_Wire W = ...;// a wire
1690 BRepBuilderAPI_MakeFace MF(C);
1695 More than one wire can be added to a face, provided that they do not cross each other and they define only one area on the surface. (Note that this is not checked). The edges on a Face must have a parametric curve description.
1697 If there is no parametric curve for an edge of the wire on the Face it is computed by projection.
1699 For one wire, a simple syntax is provided to construct the face from the surface and the wire. The above lines could be written:
1702 TopoDS_Face F = BRepBuilderAPI_MakeFace(C,W);
1705 A planar face can be created from only a wire, provided this wire defines a plane. For example, to create a planar face from a set of points you can use *BRepBuilderAPI_MakePolygon* and *BRepBuilderAPI_MakeFace*.
1708 #include <TopoDS_Face.hxx>
1709 #include <TColgp_Array1OfPnt.hxx>
1710 #include <BRepBuilderAPI_MakePolygon.hxx>
1711 #include <BRepBuilderAPI_MakeFace.hxx>
1713 TopoDS_Face PolygonalFace(const TColgp_Array1OfPnt& thePnts)
1715 BRepBuilderAPI_MakePolygon MP;
1716 for(Standard_Integer i=thePnts.Lower();
1717 i<=thePnts.Upper(); i++)
1722 TopoDS_Face F = BRepBuilderAPI_MakeFace(MP.Wire());
1727 The last use of *MakeFace* is to copy an existing face to add new wires. For example, the following code adds a new wire to a face:
1730 TopoDS_Face F = ...; // a face
1731 TopoDS_Wire W = ...; // a wire
1732 F = BRepBuilderAPI_MakeFace(F,W);
1735 To add more than one wire an instance of the *BRepBuilderAPI_MakeFace* class can be created with the face and the first wire and the new wires inserted with the *Add* method.
1737 @subsubsection occt_modalg_3_5_3 Error status
1739 The *Error* method returns an error status, which is a term from the *BRepBuilderAPI_FaceError* enumeration.
1741 * *FaceDone* -- no error occurred.
1742 * *NoFace* -- no initialization of the algorithm; an empty constructor was used.
1743 * *NotPlanar* -- no surface was given and the wire was not planar.
1744 * *CurveProjectionFailed* -- no curve was found in the parametric space of the surface for an edge.
1745 * *ParametersOutOfRange* -- the parameters *umin, umax, vmin, vmax* are out of the surface.
1747 @subsection occt_modalg_3_6 Wire
1748 The wire is a composite shape built not from a geometry, but by the assembly of edges. *BRepBuilderAPI_MakeWire* class can build a wire from one or more edges or connect new edges to an existing wire.
1750 Up to four edges can be used directly, for example:
1753 TopoDS_Wire W = BRepBuilderAPI_MakeWire(E1,E2,E3,E4);
1756 For a higher or unknown number of edges the Add method must be used; for example, to build a wire from an array of shapes (to be edges).
1759 TopTools_Array1OfShapes theEdges;
1760 BRepBuilderAPI_MakeWire MW;
1761 for (Standard_Integer i = theEdge.Lower();
1762 i <= theEdges.Upper(); i++)
1763 MW.Add(TopoDS::Edge(theEdges(i));
1767 The class can be constructed with a wire. A wire can also be added. In this case, all the edges of the wires are added. For example to merge two wires:
1770 #include <TopoDS_Wire.hxx>
1771 #include <BRepBuilderAPI_MakeWire.hxx>
1773 TopoDS_Wire MergeWires (const TopoDS_Wire& W1,
1774 const TopoDS_Wire& W2)
1776 BRepBuilderAPI_MakeWire MW(W1);
1782 *BRepBuilderAPI_MakeWire* class connects the edges to the wire. When a new edge is added if one of its vertices is shared with the wire it is considered as connected to the wire. If there is no shared vertex, the algorithm searches for a vertex of the edge and a vertex of the wire, which are at the same location (the tolerances of the vertices are used to test if they have the same location). If such a pair of vertices is found, the edge is copied with the vertex of the wire in place of the original vertex. All the vertices of the edge can be exchanged for vertices from the wire. If no connection is found the wire is considered to be disconnected. This is an error.
1784 BRepBuilderAPI_MakeWire class can return the last edge added to the wire (Edge method). This edge can be different from the original edge if it was copied.
1786 The Error method returns a term of the *BRepBuilderAPI_WireError* enumeration:
1787 *WireDone* -- no error occurred.
1788 *EmptyWire* -- no initialization of the algorithm, an empty constructor was used.
1789 *DisconnectedWire* -- the last added edge was not connected to the wire.
1790 *NonManifoldWire* -- the wire with some singularity.
1792 @subsection occt_modalg_3_7 Shell
1793 The shell is a composite shape built not from a geometry, but by the assembly of faces.
1794 Use *BRepBuilderAPI_MakeShell* class to build a Shell from a set of Faces. What may be important is that each face should have the required continuity. That is why an initial surface is broken up into faces.
1796 @subsection occt_modalg_3_8 Solid
1797 The solid is a composite shape built not from a geometry, but by the assembly of shells. Use *BRepBuilderAPI_MakeSolid* class to build a Solid from a set of Shells. Its use is similar to the use of the MakeWire class: shells are added to the solid in the same way that edges are added to the wire in MakeWire.
1800 @section occt_modalg_3b Object Modification
1802 @subsection occt_modalg_3b_1 Transformation
1803 *BRepBuilderAPI_Transform* class can be used to apply a transformation to a shape (see class *gp_Trsf*). The methods have a boolean argument to copy or share the original shape, as long as the transformation allows (it is only possible for direct isometric transformations). By default, the original shape is shared.
1805 The following example deals with the rotation of shapes.
1809 TopoDS_Shape myShape1 = ...;
1810 // The original shape 1
1811 TopoDS_Shape myShape2 = ...;
1812 // The original shape2
1814 T.SetRotation(gp_Ax1(gp_Pnt(0.,0.,0.),gp_Vec(0.,0.,1.)),
1816 BRepBuilderAPI_Transformation theTrsf(T);
1817 theTrsf.Perform(myShape1);
1818 TopoDS_Shape myNewShape1 = theTrsf.Shape()
1819 theTrsf.Perform(myShape2,Standard_True);
1820 // Here duplication is forced
1821 TopoDS_Shape myNewShape2 = theTrsf.Shape()
1824 @subsection occt_modalg_3b_2 Duplication
1826 Use the *BRepBuilderAPI_Copy* class to duplicate a shape. A new shape is thus created.
1827 In the following example, a solid is copied:
1830 TopoDS Solid MySolid;
1831 ....// Creates a solid
1833 TopoDS_Solid myCopy = BRepBuilderAPI_Copy(mySolid);
1837 @section occt_modalg_4 Primitives
1839 The <i> BRepPrimAPI</i> package provides an API (Application Programming Interface) for construction of primitives such as:
1845 It is possible to create partial solids, such as a sphere limited by longitude. In real models, primitives can be used for easy creation of specific sub-parts.
1847 * Construction by sweeping along a profile:
1849 * Rotational (through an angle of rotation).
1851 Sweeps are objects obtained by sweeping a profile along a path. The profile can be any topology and the path is usually a curve or a wire. The profile generates objects according to the following rules:
1852 * Vertices generate Edges
1853 * Edges generate Faces.
1854 * Wires generate Shells.
1855 * Faces generate Solids.
1856 * Shells generate Composite Solids.
1858 It is not allowed to sweep Solids and Composite Solids. Swept constructions along complex profiles such as BSpline curves also available in the <i> BRepOffsetAPI </i> package. This API provides simple, high level calls for the most common operations.
1860 @subsection occt_modalg_4_1 Making Primitives
1861 @subsubsection occt_modalg_4_1_1 Box
1863 The class *BRepPrimAPI_MakeBox* allows building a parallelepiped box. The result is either a **Shell** or a **Solid**. There are four ways to build a box:
1865 * From three dimensions *dx, dy* and *dz*. The box is parallel to the axes and extends for <i>[0,dx] [0,dy] [0,dz] </i>.
1866 * From a point and three dimensions. The same as above but the point is the new origin.
1867 * From two points, the box is parallel to the axes and extends on the intervals defined by the coordinates of the two points.
1868 * From a system of axes *gp_Ax2* and three dimensions. Same as the first way but the box is parallel to the given system of axes.
1870 An error is raised if the box is flat in any dimension using the default precision. The following code shows how to create a box:
1872 TopoDS_Solid theBox = BRepPrimAPI_MakeBox(10.,20.,30.);
1875 The four methods to build a box are shown in the figure:
1877 @figure{/user_guides/modeling_algos/images/modeling_algos_image026.png,"Making Boxes",420}
1879 @subsubsection occt_modalg_4_1_2 Wedge
1880 *BRepPrimAPI_MakeWedge* class allows building a wedge, which is a slanted box, i.e. a box with angles. The wedge is constructed in much the same way as a box i.e. from three dimensions dx,dy,dz plus arguments or from an axis system, three dimensions, and arguments.
1882 The following figure shows two ways to build wedges. One is to add a dimension *ltx*, which is the length in *x* of the face at *dy*. The second is to add *xmin, xmax, zmin* and *zmax* to describe the face at *dy*.
1884 The first method is a particular case of the second with *xmin = 0, xmax = ltx, zmin = 0, zmax = dz*.
1885 To make a centered pyramid you can use *xmin = xmax = dx / 2, zmin = zmax = dz / 2*.
1887 @figure{/user_guides/modeling_algos/images/modeling_algos_image027.png,"Making Wedges",420}
1889 @subsubsection occt_modalg_4_1_3 Rotation object
1890 *BRepPrimAPI_MakeOneAxis* is a deferred class used as a root class for all classes constructing rotational primitives. Rotational primitives are created by rotating a curve around an axis. They cover the cylinder, the cone, the sphere, the torus, and the revolution, which provides all other curves.
1892 The particular constructions of these primitives are described, but they all have some common arguments, which are:
1894 * A system of coordinates, where the Z axis is the rotation axis..
1895 * An angle in the range [0,2*PI].
1896 * A vmin, vmax parameter range on the curve.
1898 The result of the OneAxis construction is a Solid, a Shell, or a Face. The face is the face covering the rotational surface. Remember that you will not use the OneAxis directly but one of the derived classes, which provide improved constructions. The following figure illustrates the OneAxis arguments.
1900 @figure{/user_guides/modeling_algos/images/modeling_algos_image028.png,"MakeOneAxis arguments",360}
1902 @subsubsection occt_modalg_4_1_4 Cylinder
1903 *BRepPrimAPI_MakeCylinder* class allows creating cylindrical primitives. A cylinder is created either in the default coordinate system or in a given coordinate system *gp_Ax2*. There are two constructions:
1905 * Radius and height, to build a full cylinder.
1906 * Radius, height and angle to build a portion of a cylinder.
1908 The following code builds the cylindrical face of the figure, which is a quarter of cylinder along the *Y* axis with the origin at *X,Y,Z* the length of *DY* and radius *R*.
1912 Standard_Real X = 20, Y = 10, Z = 15, R = 10, DY = 30;
1913 // Make the system of coordinates
1914 gp_Ax2 axes = gp::ZOX();
1915 axes.Translate(gp_Vec(X,Y,Z));
1917 BRepPrimAPI_MakeCylinder(axes,R,DY,PI/2.);
1919 @figure{/user_guides/modeling_algos/images/modeling_algos_image029.png,"Cylinder",360}
1921 @subsubsection occt_modalg_4_1_5 Cone
1922 *BRepPrimAPI_MakeCone* class allows creating conical primitives. Like a cylinder, a cone is created either in the default coordinate system or in a given coordinate system (gp_Ax2). There are two constructions:
1924 * Two radii and height, to build a full cone. One of the radii can be null to make a sharp cone.
1925 * Radii, height and angle to build a truncated cone.
1927 The following code builds the solid cone of the figure, which is located in the default system with radii *R1* and *R2* and height *H*.
1930 Standard_Real R1 = 30, R2 = 10, H = 15;
1931 TopoDS_Solid S = BRepPrimAPI_MakeCone(R1,R2,H);
1934 @figure{/user_guides/modeling_algos/images/modeling_algos_image030.png,"Cone",360}
1936 @subsubsection occt_modalg_4_1_6 Sphere
1937 *BRepPrimAPI_MakeSphere* class allows creating spherical primitives. Like a cylinder, a sphere is created either in the default coordinate system or in a given coordinate system *gp_Ax2*. There are four constructions:
1939 * From a radius -- builds a full sphere.
1940 * From a radius and an angle -- builds a lune (digon).
1941 * From a radius and two angles -- builds a wraparound spherical segment between two latitudes. The angles *a1* and *a2* must follow the relation: <i>PI/2 <= a1 < a2 <= PI/2 </i>.
1942 * From a radius and three angles -- a combination of two previous methods builds a portion of spherical segment.
1944 The following code builds four spheres from a radius and three angles.
1947 Standard_Real R = 30, ang =
1948 PI/2, a1 = -PI/2.3, a2 = PI/4;
1949 TopoDS_Solid S1 = BRepPrimAPI_MakeSphere(R);
1950 TopoDS_Solid S2 = BRepPrimAPI_MakeSphere(R,ang);
1951 TopoDS_Solid S3 = BRepPrimAPI_MakeSphere(R,a1,a2);
1952 TopoDS_Solid S4 = BRepPrimAPI_MakeSphere(R,a1,a2,ang);
1955 Note that we could equally well choose to create Shells instead of Solids.
1957 @figure{/user_guides/modeling_algos/images/modeling_algos_image031.png,"Examples of Spheres",420}
1960 @subsubsection occt_modalg_4_1_7 Torus
1961 *BRepPrimAPI_MakeTorus* class allows creating toroidal primitives. Like the other primitives, a torus is created either in the default coordinate system or in a given coordinate system *gp_Ax2*. There are four constructions similar to the sphere constructions:
1963 * Two radii -- builds a full torus.
1964 * Two radii and an angle -- builds an angular torus segment.
1965 * Two radii and two angles -- builds a wraparound torus segment between two radial planes. The angles a1, a2 must follow the relation 0 < a2 - a1 < 2*PI.
1966 * Two radii and three angles -- a combination of two previous methods builds a portion of torus segment.
1968 @figure{/user_guides/modeling_algos/images/modeling_algos_image032.png,"Examples of Tori",420}
1970 The following code builds four toroidal shells from two radii and three angles.
1973 Standard_Real R1 = 30, R2 = 10, ang = PI, a1 = 0,
1975 TopoDS_Shell S1 = BRepPrimAPI_MakeTorus(R1,R2);
1976 TopoDS_Shell S2 = BRepPrimAPI_MakeTorus(R1,R2,ang);
1977 TopoDS_Shell S3 = BRepPrimAPI_MakeTorus(R1,R2,a1,a2);
1979 BRepPrimAPI_MakeTorus(R1,R2,a1,a2,ang);
1982 Note that we could equally well choose to create Solids instead of Shells.
1984 @subsubsection occt_modalg_4_1_8 Revolution
1985 *BRepPrimAPI_MakeRevolution* class allows building a uniaxial primitive from a curve. As other uniaxial primitives it can be created in the default coordinate system or in a given coordinate system.
1987 The curve can be any *Geom_Curve*, provided it is planar and lies in the same plane as the Z-axis of local coordinate system. There are four modes of construction:
1989 * From a curve, use the full curve and make a full rotation.
1990 * From a curve and an angle of rotation.
1991 * From a curve and two parameters to trim the curve. The two parameters must be growing and within the curve range.
1992 * From a curve, two parameters, and an angle. The two parameters must be growing and within the curve range.
1995 @subsection occt_modalg_4_2 Sweeping: Prism, Revolution and Pipe
1996 @subsubsection occt_modalg_4_2_1 Sweeping
1998 Sweeps are the objects you obtain by sweeping a **profile** along a **path**. The profile can be of any topology. The path is usually a curve or a wire. The profile generates objects according to the following rules:
2000 * Vertices generate Edges
2001 * Edges generate Faces.
2002 * Wires generate Shells.
2003 * Faces generate Solids.
2004 * Shells generate Composite Solids
2006 It is forbidden to sweep Solids and Composite Solids. A Compound generates a Compound with the sweep of all its elements.
2008 @figure{/user_guides/modeling_algos/images/modeling_algos_image033.png,"Generating a sweep",360}
2010 *BRepPrimAPI_MakeSweep class* is a deferred class used as a root of the the following sweep classes:
2011 * *BRepPrimAPI_MakePrism* -- produces a linear sweep
2012 * *BRepPrimAPI_MakeRevol* -- produces a rotational sweep
2013 * *BRepPrimAPI_MakePipe* -- produces a general sweep.
2016 @subsubsection occt_modalg_4_2_2 Prism
2017 *BRepPrimAPI_MakePrism* class allows creating a linear **prism** from a shape and a vector or a direction.
2018 * A vector allows creating a finite prism;
2019 * A direction allows creating an infinite or semi-infinite prism. The semi-infinite or infinite prism is toggled by a Boolean argument. All constructors have a boolean argument to copy the original shape or share it (by default).
2021 The following code creates a finite, an infinite and a semi-infinite solid using a face, a direction and a length.
2024 TopoDS_Face F = ..; // The swept face
2025 gp_Dir direc(0,0,1);
2026 Standard_Real l = 10;
2027 // create a vector from the direction and the length
2030 TopoDS_Solid P1 = BRepPrimAPI_MakePrism(F,v);
2032 TopoDS_Solid P2 = BRepPrimAPI_MakePrism(F,direc);
2034 TopoDS_Solid P3 = BRepPrimAPI_MakePrism(F,direc,Standard_False);
2038 @figure{/user_guides/modeling_algos/images/modeling_algos_image034.png,"Finite, infinite, and semi-infinite prisms",420}
2040 @subsubsection occt_modalg_4_2_3 Rotational Sweep
2041 *BRepPrimAPI_MakeRevol* class allows creating a rotational sweep from a shape, an axis (gp_Ax1), and an angle. The angle has a default value of 2*PI which means a closed revolution.
2043 *BRepPrimAPI_MakeRevol* constructors have a last argument to copy or share the original shape. The following code creates a a full and a partial rotation using a face, an axis and an angle.
2046 TopoDS_Face F = ...; // the profile
2047 gp_Ax1 axis(gp_Pnt(0,0,0),gp_Dir(0,0,1));
2048 Standard_Real ang = PI/3;
2049 TopoDS_Solid R1 = BRepPrimAPI_MakeRevol(F,axis);
2051 TopoDS_Solid R2 = BRepPrimAPI_MakeRevol(F,axis,ang);
2054 @figure{/user_guides/modeling_algos/images/modeling_algos_image035.png,"Full and partial rotation",420}
2056 @section occt_modalg_5 Boolean Operations
2058 Boolean operations are used to create new shapes from the combinations of two groups of shapes.
2060 | Operation | Result |
2062 | Fuse | all points in S1 or S2 |
2063 | Common | all points in S1 and S2 |
2064 | Cut S1 by S2| all points in S1 and not in S2 |
2066 @figure{/user_guides/modeling_algos/images/modeling_algos_image036.png,"Boolean Operations",420}
2068 From the viewpoint of Topology these are topological operations followed by blending (putting fillets onto edges created after the topological operation).
2070 Topological operations are the most convenient way to create real industrial parts. As most industrial parts consist of several simple elements such as gear wheels, arms, holes, ribs, tubes and pipes. It is usually easy to create those elements separately and then to combine them by Boolean operations in the whole final part.
2072 See @ref occt_user_guides__boolean_operations "Boolean Operations" for detailed documentation.
2074 @subsection occt_modalg_5_1 Input and Result Arguments
2076 Boolean Operations have the following types of the arguments and produce the following results:
2077 * For arguments having the same shape type (e.g. SOLID / SOLID) the type of the resulting shape will be a COMPOUND, containing shapes of this type;
2078 * For arguments having different shape types (e.g. SHELL / SOLID) the type of the resulting shape will be a COMPOUND, containing shapes of the type that is the same as that of the low type of the argument. Example: For SHELL/SOLID the result is a COMPOUND of SHELLs.
2079 * For arguments with different shape types some of Boolean Operations can not be done using the default implementation, because of a non-manifold type of the result. Example: the FUSE operation for SHELL and SOLID can not be done, but the CUT operation can be done, where SHELL is the object and SOLID is the tool.
2080 * It is possible to perform Boolean Operations on arguments of the COMPOUND shape type. In this case each compound must not be heterogeneous, i.e. it must contain equidimensional shapes (EDGEs or/and WIREs, FACEs or/and SHELLs, SOLIDs). SOLIDs inside the COMPOUND must not contact (intersect or touch) each other. The same condition should be respected for SHELLs or FACEs, WIREs or EDGEs.
2081 * Boolean Operations for COMPSOLID type of shape are not supported.
2083 @subsection occt_modalg_5_2 Implementation
2085 *BRepAlgoAPI_BooleanOperation* class is the deferred root class for Boolean operations.
2089 *BRepAlgoAPI_Fuse* performs the Fuse operation.
2092 TopoDS_Shape A = ..., B = ...;
2093 TopoDS_Shape S = BRepAlgoAPI_Fuse(A,B);
2098 *BRepAlgoAPI_Common* performs the Common operation.
2101 TopoDS_Shape A = ..., B = ...;
2102 TopoDS_Shape S = BRepAlgoAPI_Common(A,B);
2106 *BRepAlgoAPI_Cut* performs the Cut operation.
2109 TopoDS_Shape A = ..., B = ...;
2110 TopoDS_Shape S = BRepAlgoAPI_Cut(A,B);
2115 *BRepAlgoAPI_Section* performs the section, described as a *TopoDS_Compound* made of *TopoDS_Edge*.
2117 @figure{/user_guides/modeling_algos/images/modeling_algos_image037.png,"Section operation",220}
2120 TopoDS_Shape A = ..., TopoDS_ShapeB = ...;
2121 TopoDS_Shape S = BRepAlgoAPI_Section(A,B);
2124 @section occt_modalg_6 Fillets and Chamfers
2126 This library provides algorithms to make fillets and chamfers on shape edges.
2127 The following cases are addressed:
2129 * Corners and apexes with different radii;
2130 * Corners and apexes with different concavity.
2132 If there is a concavity, both surfaces that need to be extended and those, which do not, are processed.
2134 @subsection occt_modalg_6_1 Fillets
2135 @subsection occt_modalg_6_1_1 Fillet on shape
2137 A fillet is a smooth face replacing a sharp edge.
2139 *BRepFilletAPI_MakeFillet* class allows filleting a shape.
2141 To produce a fillet, it is necessary to define the filleted shape at the construction of the class and add fillet descriptions using the *Add* method.
2143 A fillet description contains an edge and a radius. The edge must be shared by two faces. The fillet is automatically extended to all edges in a smooth continuity with the original edge. It is not an error to add a fillet twice, the last description holds.
2145 @figure{/user_guides/modeling_algos/images/modeling_algos_image038.png,"Filleting two edges using radii r1 and r2.",360}
2147 In the following example a filleted box with dimensions a,b,c and radius r is created.
2153 #include <TopoDS_Shape.hxx>
2154 #include <TopoDS.hxx>
2155 #include <BRepPrimAPI_MakeBox.hxx>
2156 #include <TopoDS_Solid.hxx>
2157 #include <BRepFilletAPI_MakeFillet.hxx>
2158 #include <TopExp_Explorer.hxx>
2160 TopoDS_Shape FilletedBox(const Standard_Real a,
2161 const Standard_Real b,
2162 const Standard_Real c,
2163 const Standard_Real r)
2165 TopoDS_Solid Box = BRepPrimAPI_MakeBox(a,b,c);
2166 BRepFilletAPI_MakeFillet MF(Box);
2168 // add all the edges to fillet
2169 TopExp_Explorer ex(Box,TopAbs_EDGE);
2172 MF.Add(r,TopoDS::Edge(ex.Current()));
2179 @figure{/user_guides/modeling_algos/images/modeling_algos_image039.png,"Fillet with constant radius",360}
2181 #### Changing radius
2185 void CSampleTopologicalOperationsDoc::OnEvolvedblend1()
2187 TopoDS_Shape theBox = BRepPrimAPI_MakeBox(200,200,200);
2189 BRepFilletAPI_MakeFillet Rake(theBox);
2190 ChFi3d_FilletShape FSh = ChFi3d_Rational;
2191 Rake.SetFilletShape(FSh);
2193 TColgp_Array1OfPnt2d ParAndRad(1, 6);
2194 ParAndRad(1).SetCoord(0., 10.);
2195 ParAndRad(1).SetCoord(50., 20.);
2196 ParAndRad(1).SetCoord(70., 20.);
2197 ParAndRad(1).SetCoord(130., 60.);
2198 ParAndRad(1).SetCoord(160., 30.);
2199 ParAndRad(1).SetCoord(200., 20.);
2201 TopExp_Explorer ex(theBox,TopAbs_EDGE);
2202 Rake.Add(ParAndRad, TopoDS::Edge(ex.Current()));
2203 TopoDS_Shape evolvedBox = Rake.Shape();
2207 @figure{/user_guides/modeling_algos/images/modeling_algos_image040.png,"Fillet with changing radius",360}
2209 @subsection occt_modalg_6_1_2 Chamfer
2211 A chamfer is a rectilinear edge replacing a sharp vertex of the face.
2213 The use of *BRepFilletAPI_MakeChamfer* class is similar to the use of *BRepFilletAPI_MakeFillet*, except for the following:
2214 * The surfaces created are ruled and not smooth.
2215 * The *Add* syntax for selecting edges requires one or two distances, one edge and one face (contiguous to the edge).
2219 Add(d1, d2, E, F) with d1 on the face F.
2222 @figure{/user_guides/modeling_algos/images/modeling_algos_image041.png,"Chamfer",360}
2224 @subsection occt_modalg_6_1_3 Fillet on a planar face
2226 *BRepFilletAPI_MakeFillet2d* class allows constructing fillets and chamfers on planar faces.
2227 To create a fillet on planar face: define it, indicate, which vertex is to be deleted, and give the fillet radius with *AddFillet* method.
2229 A chamfer can be calculated with *AddChamfer* method. It can be described by
2230 * two edges and two distances
2231 * one edge, one vertex, one distance and one angle.
2232 Fillets and chamfers are calculated when addition is complete.
2234 If face F2 is created by 2D fillet and chamfer builder from face F1, the builder can be rebuilt (the builder recovers the status it had before deletion). To do so, use the following syntax:
2236 BRepFilletAPI_MakeFillet2d builder;
2237 builder.Init(F1,F2);
2244 #include “BRepPrimAPI_MakeBox.hxx”
2245 #include “TopoDS_Shape.hxx”
2246 #include “TopExp_Explorer.hxx”
2247 #include “BRepFilletAPI_MakeFillet2d.hxx”
2248 #include “TopoDS.hxx”
2249 #include “TopoDS_Solid.hxx”
2251 TopoDS_Shape FilletFace(const Standard_Real a,
2252 const Standard_Real b,
2253 const Standard_Real c,
2254 const Standard_Real r)
2257 TopoDS_Solid Box = BRepPrimAPI_MakeBox (a,b,c);
2258 TopExp_Explorer ex1(Box,TopAbs_FACE);
2260 const TopoDS_Face& F = TopoDS::Face(ex1.Current());
2261 BRepFilletAPI_MakeFillet2d MF(F);
2262 TopExp_Explorer ex2(F, TopAbs_VERTEX);
2265 MF.AddFillet(TopoDS::Vertex(ex2.Current()),r);
2273 @section occt_modalg_7 Offsets, Drafts, Pipes and Evolved shapes
2275 These classes provide the following services:
2277 * Creation of offset shapes and their variants such as:
2281 * Creation of tapered shapes using draft angles;
2282 * Creation of sweeps.
2284 @subsection occt_modalg_7_1 Offset computation
2286 Offset computation can be performed using *BRepOffsetAPI_MakeOffsetShape*. This class provides API to the two different offset algorithms:
2288 Offset algorithm based on computation of the analytical continuation. Meaning of the parameters can be found in *BRepOffsetAPI_MakeOffsetShape::PerformByJoin* method description. The list below demonstrates principal scheme of this algorithm:
2290 * At the first step, the offsets are computed.
2291 * After this, the analytical continuations are computed for each offset.
2292 * Pairwise intersection is computed according to the original topological information (sharing, number of neighbors, etc.).
2293 * The offset shape is assembled.
2295 The second algorithm is based on the fact that the offset computation for a single face without continuation can always be built. The list below shows simple offset algorithm:
2296 * Each surface is mapped to its geometric offset surface.
2297 * For each edge, pcurves are mapped to the same pcurves on offset surfaces.
2298 * For each edge, 3d curve is constructed by re-approximation of pcurve on the first offset face.
2299 * Position of each vertex in a result shell is computed as average point of all ends of edges sharing that vertex.
2300 * Tolerances are updated according to the resulting geometry.
2301 The possible drawback of the simple algorithm is that it leads, in general case, to tolerance increasing. The tolerances have to grow in order to cover the gaps between the neighbor faces in the output. It should be noted that the actual tolerance growth depends on the offset distance and the quality of joints between the input faces. Anyway the good input shell (smooth connections between adjacent faces) will lead to good result.
2303 The snippets below show usage examples:
2304 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
2305 BRepOffsetAPI_MakeOffsetShape OffsetMaker1;
2306 // Computes offset shape using analytical continuation mechanism.
2307 OffsetMaker1.PerformByJoin(Shape, OffsetValue, Tolerance);
2308 if (OffsetMaker1.IsDone())
2309 NewShape = OffsetMaker1.Shape();
2311 BRepOffsetAPI_MakeOffsetShape OffsetMaker2;
2312 // Computes offset shape using simple algorithm.
2313 OffsetMaker2.PerformBySimple(Shape, OffsetValue);
2314 if (OffsetMaker2.IsDone())
2315 NewShape = OffsetMaker2.Shape();
2316 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2318 @subsection occt_modalg_7_2 Shelling
2320 Shelling is used to offset given faces of a solid by a specific value. It rounds or intersects adjacent faces along its edges depending on the convexity of the edge.
2321 The MakeThickSolidByJoin method of the *BRepOffsetAPI_MakeThickSolid* takes the solid, the list of faces to remove and an offset value as input.
2324 TopoDS_Solid SolidInitial = ...;
2326 Standard_Real Of = ...;
2327 TopTools_ListOfShape LCF;
2328 TopoDS_Shape Result;
2329 Standard_Real Tol = Precision::Confusion();
2331 for (Standard_Integer i = 1 ;i <= n; i++) {
2332 TopoDS_Face SF = ...; // a face from SolidInitial
2336 BRepOffsetAPI_MakeThickSolid SolidMaker;
2337 SolidMaker.MakeThickSolidByJoin(SolidInitial,
2341 if (SolidMaker.IsDone())
2342 Result = SolidMaker.Shape();
2345 @figure{/user_guides/modeling_algos/images/modeling_algos_image042.png,"Shelling",420}
2347 Also it is possible to create solid between shell, offset shell. This functionality can be called using *BRepOffsetAPI_MakeThickSolid::MakeThickSolidBySimple* method. The code below shows usage example:
2349 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
2350 BRepOffsetAPI_MakeThickSolid SolidMaker;
2351 SolidMaker.MakeThickSolidBySimple(Shell, OffsetValue);
2352 if (myDone.IsDone())
2353 Solid = SolidMaker.Shape();
2354 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2356 @subsection occt_modalg_7_3 Draft Angle
2358 *BRepOffsetAPI_DraftAngle* class allows modifying a shape by applying draft angles to its planar, cylindrical and conical faces.
2361 The class is created or initialized from a shape, then faces to be modified are added; for each face, three arguments are used:
2362 * Direction: the direction with which the draft angle is measured
2363 * Angle: value of the angle
2364 * Neutral plane: intersection between the face and the neutral plane is invariant.
2366 The following code places a draft angle on several faces of a shape; the same direction, angle and neutral plane are used for each face:
2369 TopoDS_Shape myShape = ...
2370 // The original shape
2371 TopTools_ListOfShape ListOfFace;
2372 // Creation of the list of faces to be modified
2375 gp_Dir Direc(0.,0.,1.);
2377 Standard_Real Angle = 5.*PI/180.;
2379 gp_Pln Neutral(gp_Pnt(0.,0.,5.), Direc);
2380 // Neutral plane Z=5
2381 BRepOffsetAPI_DraftAngle theDraft(myShape);
2382 TopTools_ListIteratorOfListOfShape itl;
2383 for (itl.Initialize(ListOfFace); itl.More(); itl.Next()) {
2384 theDraft.Add(TopoDS::Face(itl.Value()),Direc,Angle,Neutral);
2385 if (!theDraft.AddDone()) {
2386 // An error has occurred. The faulty face is given by // ProblematicShape
2390 if (!theDraft.AddDone()) {
2391 // An error has occurred
2392 TopoDS_Face guilty = theDraft.ProblematicShape();
2396 if (!theDraft.IsDone()) {
2397 // Problem encountered during reconstruction
2401 TopoDS_Shape myResult = theDraft.Shape();
2406 @figure{/user_guides/modeling_algos/images/modeling_algos_image043.png,"DraftAngle",420}
2408 @subsection occt_modalg_7_4 Pipe Constructor
2410 *BRepOffsetAPI_MakePipe* class allows creating a pipe from a Spine, which is a Wire and a Profile which is a Shape. This implementation is limited to spines with smooth transitions, sharp transitions are precessed by *BRepOffsetAPI_MakePipeShell*. To be more precise the continuity must be G1, which means that the tangent must have the same direction, though not necessarily the same magnitude, at neighboring edges.
2412 The angle between the spine and the profile is preserved throughout the pipe.
2415 TopoDS_Wire Spine = ...;
2416 TopoDS_Shape Profile = ...;
2417 TopoDS_Shape Pipe = BRepOffsetAPI_MakePipe(Spine,Profile);
2420 @figure{/user_guides/modeling_algos/images/modeling_algos_image044.png,"Example of a Pipe",320}
2422 @subsection occt_modalg_7_5 Evolved Solid
2424 *BRepOffsetAPI_MakeEvolved* class allows creating an evolved solid from a Spine (planar face or wire) and a profile (wire).
2426 The evolved solid is an unlooped sweep generated by the spine and the profile.
2428 The evolved solid is created by sweeping the profile’s reference axes on the spine. The origin of the axes moves to the spine, the X axis and the local tangent coincide and the Z axis is normal to the face.
2430 The reference axes of the profile can be defined following two distinct modes:
2432 * The reference axes of the profile are the origin axes.
2433 * The references axes of the profile are calculated as follows:
2434 + the origin is given by the point on the spine which is the closest to the profile
2435 + the X axis is given by the tangent to the spine at the point defined above
2436 + the Z axis is the normal to the plane which contains the spine.
2439 TopoDS_Face Spine = ...;
2440 TopoDS_Wire Profile = ...;
2442 BRepOffsetAPI_MakeEvolved(Spine,Profile);
2445 @section occt_modalg_8 Sewing
2447 @subsection occt_modalg_8_1 Introduction
2449 Sewing allows creation of connected topology (shells and wires) from a set of separate topological elements (faces and edges). For example, Sewing can be used to create of shell from a compound of separate faces.
2451 @figure{/user_guides/modeling_algos/images/modeling_algos_image045.png,"Shapes with partially shared edges",320}
2453 It is important to distinguish between sewing and other procedures, which modify the geometry, such as filling holes or gaps, gluing, bending curves and surfaces, etc.
2455 Sewing does not change geometrical representation of the shapes. Sewing applies to topological elements (faces, edges) which are not connected but can be connected because they are geometrically coincident : it adds the information about topological connectivity. Already connected elements are left untouched in case of manifold sewing.
2457 Let us define several terms:
2458 * **Floating edges** do not belong to any face;
2459 * **Free boundaries** belong to one face only;
2460 * **Shared edges** belong to several faces, (i.e. two faces in a manifold topology).
2461 * **Sewn faces** should have edges shared with each other.
2462 * **Sewn edges** should have vertices shared with each other.
2464 @subsection occt_modalg_8_2 Sewing Algorithm
2466 The sewing algorithm is one of the basic algorithms used for shape processing, therefore its quality is very important.
2468 Sewing algorithm is implemented in the class *BRepBuilder_Sewing*. This class provides the following methods:
2469 * loading initial data for global or local sewing;
2470 * setting customization parameters, such as special operation modes, tolerances and output results;
2471 * applying analysis methods that can be used to obtain connectivity data required by external algorithms;
2472 * sewing of the loaded shapes.
2474 Sewing supports working mode with big value tolerance. It is not necessary to repeat sewing step by step while smoothly increasing tolerance.
2476 It is also possible to sew edges to wire and to sew locally separate faces and edges from a shape.
2478 The Sewing algorithm can be subdivided into several independent stages, some of which can be turned on or off using Boolean or other flags.
2480 In brief, the algorithm should find a set of merge candidates for each free boundary, filter them according to certain criteria, and finally merge the found candidates and build the resulting sewn shape.
2482 Each stage of the algorithm or the whole algorithm can be adjusted with the following parameters:
2483 * **Working tolerance** defines the maximal distance between topological elements which can be sewn. It is not ultimate that such elements will be actually sewn as many other criteria are applied to make the final decision.
2484 * **Minimal tolerance** defines the size of the smallest element (edge) in the resulting shape. It is declared that no edges with size less than this value are created after sewing. If encountered, such topology becomes degenerated.
2485 * **Non-manifold mode** enables sewing of non-manifold topology.
2489 To connect a set of *n* contiguous but independent faces, do the following:
2492 BRepBuilderAPI_Sewing Sew;
2498 TopoDS_Shape result= Sew.SewedShape();
2501 If all faces have been sewn correctly, the result is a shell. Otherwise, it is a compound. After a successful sewing operation all faces have a coherent orientation.
2503 @subsection occt_modalg_8_3 Tolerance Management
2505 To produce a closed shell, Sewing allows specifying the value of working tolerance, exceeding the size of small faces belonging to the shape.
2507 However, if we produce an open shell, it is possible to get incorrect sewing results if the value of working tolerance is too large (i.e. it exceeds the size of faces lying on an open boundary).
2509 The following recommendations can be proposed for tuning-up the sewing process:
2510 - Use as small working tolerance as possible. This will reduce the sewing time and, consequently, the number of incorrectly sewn edges for shells with free boundaries.
2511 - Use as large minimal tolerance as possible. This will reduce the number of small geometry in the shape, both original and appearing after cutting.
2512 - If it is expected to obtain a shell with holes (free boundaries) as a result of sewing, the working tolerance should be set to a value not greater than the size of the smallest element (edge) or smallest distance between elements of such free boundary. Otherwise the free boundary may be sewn only partially.
2513 - It should be mentioned that the Sewing algorithm is unable to understand which small (less than working tolerance) free boundary should be kept and which should be sewn.
2515 @subsection occt_modalg_8_4 Manifold and Non-manifold Sewing
2517 To create one or several shells from a set of faces, sewing merges edges, which belong to different faces or one closed face.
2519 Face sewing supports manifold and non manifold modes. Manifold mode can produce only a manifold shell. Sewing should be used in the non manifold mode to create non manifold shells.
2521 Manifold sewing of faces merges only two nearest edges belonging to different faces or one closed face with each other. Non manifold sewing of faces merges all edges at a distance less than the specified tolerance.
2523 For a complex topology it is advisable to apply first the manifold sewing and then the non manifold sewing a minimum possible working tolerance. However, this is not necessary for a easy topology.
2525 Giving a large tolerance value to non manifold sewing will cause a lot of incorrectness since all nearby geometry will be sewn.
2527 @subsection occt_modalg_8_5 Local Sewing
2529 If a shape still has some non-sewn faces or edges after sewing, it is possible to use local sewing with a greater tolerance.
2531 Local sewing is especially good for open shells. It allows sewing an unwanted hole in one part of the shape and keeping a required hole, which is smaller than the working tolerance specified for the local sewing in the other part of the shape. Local sewing is much faster than sewing on the whole shape.
2533 All preexisting connections of the whole shape are kept after local sewing.
2535 For example, if you want to sew two open shells having coincided free edges using local sewing, it is necessary to create a compound from two shells then load the full compound using method *BRepBuilderAPI_Sewing::Load()*. After that it is necessary to add local sub-shapes, which should be sewn using method *BRepBuilderAPI_Sewing::Add()*. The result of sewing can be obtained using method *BRepBuilderAPI_Sewing::SewedShape()*.
2541 //initial sewn shapes
2542 TopoDS_Shape aS1, aS2; // these shapes are expected to be well sewn shells
2545 aB.MakeCompound(aComp);
2548 ................................
2549 aSewing.Load(aComp);
2551 //sub shapes which should be locally sewed
2557 TopoDS_Shape aRes = aSewing.SewedShape();
2561 @section occt_modalg_9 Features
2563 This library contained in *BRepFeat* package is necessary for creation and manipulation of form and mechanical features that go beyond the classical boundary representation of shapes. In that sense, *BRepFeat* is an extension of *BRepBuilderAPI* package.
2565 @subsection occt_modalg_9_1 Form Features
2567 The form features are depressions or protrusions including the following types:
2575 Depending on whether you wish to make a depression or a protrusion,
2576 you can choose either to remove matter (Boolean cut: Fuse equal to 0) or to add it (Boolean fusion: Fuse equal to 1).
2578 The semantics of form feature creation is based on the construction of shapes:
2580 * for a certain length in a certain direction;
2581 * up to the limiting face;
2582 * from the limiting face at a height;
2583 * above and/or below a plane.
2585 The shape defining the construction of a feature can be either a supporting edge or a concerned area of a face.
2587 In case of supporting edge, this contour can be attached to a face of the basis shape by binding. When the contour is bound to this face, the information that the contour will slide on the face becomes available
2588 to the relevant class methods. In case of the concerned area of a face, you can, for example, cut it out and move it at a different height, which defines the limiting face of a protrusion or depression.
2590 Topological definition with local operations of this sort makes calculations simpler
2591 and faster than a global operation. The latter would entail a second phase
2592 of removing unwanted matter to get the same result.
2594 The *Form* from *BRepFeat* package is a deferred class used as a root for form features. It inherits *MakeShape* from *BRepBuilderAPI* and provides implementation of methods keep track of all sub-shapes.
2596 @subsubsection occt_modalg_9_1_1 Prism
2598 The class *BRepFeat_MakePrism* is used to build a prism interacting with a shape. It is created or initialized from
2599 * a shape (the basic shape),
2600 * the base of the prism,
2601 * a face (the face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not),
2603 * a Boolean indicating the type of operation (fusion=protrusion or cut=depression) on the basic shape,
2604 * another Boolean indicating if the self-intersections have to be found (not used in every case).
2606 There are six Perform methods:
2607 | Method | Description |
2608 | :---------------------- | :------------------------------------- |
2609 | *Perform(Height)* | The resulting prism is of the given length. |
2610 | *Perform(Until)* | The prism is defined between the position of the base and the given face. |
2611 | *Perform(From, Until)* | The prism is defined between the two faces From and Until. |
2612 | *PerformUntilEnd()* | The prism is semi-infinite, limited by the actual position of the base. |
2613 | *PerformFromEnd(Until)* | The prism is semi-infinite, limited by the face Until. |
2614 | *PerformThruAll()* | The prism is infinite. In the case of a depression, the result is similar to a cut with an infinite prism. In the case of a protrusion, infinite parts are not kept in the result. |
2616 **Note** that *Add* method can be used before *Perform* methods to indicate that a face generated by an edge slides onto a face of the base shape.
2618 In the following sequence, a protrusion is performed, i.e. a face of the shape is changed into a prism.
2621 TopoDS_Shape Sbase = ...; // an initial shape
2622 TopoDS_Face Fbase = ....; // a base of prism
2624 gp_Dir Extrusion (.,.,.);
2626 // An empty face is given as the sketch face
2628 BRepFeat_MakePrism thePrism(Sbase, Fbase, TopoDS_Face(), Extrusion, Standard_True, Standard_True);
2630 thePrism, Perform(100.);
2631 if (thePrism.IsDone()) {
2632 TopoDS_Shape theResult = thePrism;
2637 @figure{/user_guides/modeling_algos/images/modeling_algos_image047.png,"Fusion with MakePrism",320}
2639 @figure{/user_guides/modeling_algos/images/modeling_algos_image048.png,"Creating a prism between two faces with Perform()",320}
2641 @subsubsection occt_modalg_9_1_2 Draft Prism
2643 The class *BRepFeat_MakeDPrism* is used to build draft prism topologies interacting with a basis shape. These can be depressions or protrusions. A class object is created or initialized from:
2644 * a shape (basic shape),
2645 * the base of the prism,
2646 * a face (face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not),
2648 * a Boolean indicating the type of operation (fusion=protrusion or cut=depression) on the basic shape,
2649 * another Boolean indicating if self-intersections have to be found (not used in every case).
2651 Evidently the input data for MakeDPrism are the same as for MakePrism except for a new parameter Angle and a missing parameter Direction: the direction of the prism generation is determined automatically as the normal to the base of the prism.
2652 The semantics of draft prism feature creation is based on the construction of shapes:
2654 * up to a limiting face
2655 * from a limiting face to a height.
2657 The shape defining construction of the draft prism feature can be either the supporting edge or the concerned area of a face.
2659 In case of the supporting edge, this contour can be attached to a face of the basis shape by binding. When the contour is bound to this face, the information that the contour will slide on the face becomes available to the relevant class methods.
2660 In case of the concerned area of a face, it is possible to cut it out and move it to a different height, which will define the limiting face of a protrusion or depression direction .
2662 The *Perform* methods are the same as for *MakePrism*.
2665 TopoDS_Shape S = BRepPrimAPI_MakeBox(400.,250.,300.);
2667 Ex.Init(S,TopAbs_FACE);
2673 TopoDS_Face F = TopoDS::Face(Ex.Current());
2674 Handle(Geom_Surface) surf = BRep_Tool::Surface(F);
2676 c(gp_Ax2d(gp_Pnt2d(200.,130.),gp_Dir2d(1.,0.)),50.);
2677 BRepBuilderAPI_MakeWire MW;
2678 Handle(Geom2d_Curve) aline = new Geom2d_Circle(c);
2679 MW.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,PI));
2680 MW.Add(BRepBuilderAPI_MakeEdge(aline,surf,PI,2.*PI));
2681 BRepBuilderAPI_MakeFace MKF;
2682 MKF.Init(surf,Standard_False);
2684 TopoDS_Face FP = MKF.Face();
2685 BRepLib::BuildCurves3d(FP);
2686 BRepFeat_MakeDPrism MKDP (S,FP,F,10*PI180,Standard_True,
2689 TopoDS_Shape res1 = MKDP.Shape();
2692 @figure{/user_guides/modeling_algos/images/modeling_algos_image049.png,"A tapered prism",320}
2694 @subsubsection occt_modalg_9_1_3 Revolution
2696 The class *BRepFeat_MakeRevol* is used to build a revolution interacting with a shape. It is created or initialized from:
2697 * a shape (the basic shape,)
2698 * the base of the revolution,
2699 * a face (the face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not),
2700 * an axis of revolution,
2701 * a boolean indicating the type of operation (fusion=protrusion or cut=depression) on the basic shape,
2702 * another boolean indicating whether the self-intersections have to be found (not used in every case).
2704 There are four Perform methods:
2705 | Method | Description |
2706 | :--------------- | :------------ |
2707 | *Perform(Angle)* | The resulting revolution is of the given magnitude. |
2708 | *Perform(Until)* | The revolution is defined between the actual position of the base and the given face. |
2709 | *Perform(From, Until)* | The revolution is defined between the two faces, From and Until. |
2710 | *PerformThruAll()* | The result is similar to Perform(2*PI). |
2712 **Note** that *Add* method can be used before *Perform* methods to indicate that a face generated by an edge slides onto a face of the base shape.
2715 In the following sequence, a face is revolved and the revolution is limited by a face of the base shape.
2718 TopoDS_Shape Sbase = ...; // an initial shape
2719 TopoDS_Face Frevol = ....; // a base of prism
2720 TopoDS_Face FUntil = ....; // face limiting the revol
2722 gp_Dir RevolDir (.,.,.);
2723 gp_Ax1 RevolAx(gp_Pnt(.,.,.), RevolDir);
2725 // An empty face is given as the sketch face
2727 BRepFeat_MakeRevol theRevol(Sbase, Frevol, TopoDS_Face(), RevolAx, Standard_True, Standard_True);
2729 theRevol.Perform(FUntil);
2730 if (theRevol.IsDone()) {
2731 TopoDS_Shape theResult = theRevol;
2736 @subsubsection occt_modalg_9_1_4 Pipe
2738 The class *BRepFeat_MakePipe* constructs compound shapes with pipe features: depressions or protrusions. A class object is created or initialized from:
2739 * a shape (basic shape),
2740 * a base face (profile of the pipe)
2741 * a face (face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not),
2743 * a Boolean indicating the type of operation (fusion=protrusion or cut=depression) on the basic shape,
2744 * another Boolean indicating if self-intersections have to be found (not used in every case).
2746 There are three Perform methods:
2747 | Method | Description |
2748 | :-------- | :---------- |
2749 | *Perform()* | The pipe is defined along the entire path (spine wire) |
2750 | *Perform(Until)* | The pipe is defined along the path until a given face |
2751 | *Perform(From, Until)* | The pipe is defined between the two faces From and Until |
2753 Let us have a look at the example:
2756 TopoDS_Shape S = BRepPrimAPI_MakeBox(400.,250.,300.);
2758 Ex.Init(S,TopAbs_FACE);
2761 TopoDS_Face F1 = TopoDS::Face(Ex.Current());
2762 Handle(Geom_Surface) surf = BRep_Tool::Surface(F1);
2763 BRepBuilderAPI_MakeWire MW1;
2765 p1 = gp_Pnt2d(100.,100.);
2766 p2 = gp_Pnt2d(200.,100.);
2767 Handle(Geom2d_Line) aline = GCE2d_MakeLine(p1,p2).Value();
2769 MW1.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,p1.Distance(p2)));
2771 p2 = gp_Pnt2d(150.,200.);
2772 aline = GCE2d_MakeLine(p1,p2).Value();
2774 MW1.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,p1.Distance(p2)));
2776 p2 = gp_Pnt2d(100.,100.);
2777 aline = GCE2d_MakeLine(p1,p2).Value();
2779 MW1.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,p1.Distance(p2)));
2780 BRepBuilderAPI_MakeFace MKF1;
2781 MKF1.Init(surf,Standard_False);
2782 MKF1.Add(MW1.Wire());
2783 TopoDS_Face FP = MKF1.Face();
2784 BRepLib::BuildCurves3d(FP);
2785 TColgp_Array1OfPnt CurvePoles(1,3);
2786 gp_Pnt pt = gp_Pnt(150.,0.,150.);
2788 pt = gp_Pnt(200.,100.,150.);
2790 pt = gp_Pnt(150.,200.,150.);
2792 Handle(Geom_BezierCurve) curve = new Geom_BezierCurve
2794 TopoDS_Edge E = BRepBuilderAPI_MakeEdge(curve);
2795 TopoDS_Wire W = BRepBuilderAPI_MakeWire(E);
2796 BRepFeat_MakePipe MKPipe (S,FP,F1,W,Standard_False,
2799 TopoDS_Shape res1 = MKPipe.Shape();
2802 @figure{/user_guides/modeling_algos/images/modeling_algos_image050.png,"Pipe depression",240}
2804 @subsection occt_modalg_9_2 Mechanical Features
2806 Mechanical features include ribs, protrusions and grooves (or slots), depressions along planar (linear) surfaces or revolution surfaces.
2808 The semantics of mechanical features is built around giving thickness to a contour. This thickness can either be symmetrical -- on one side of the contour -- or dissymmetrical -- on both sides. As in the semantics of form features, the thickness is defined by construction of shapes in specific contexts.
2810 The development contexts differ, however, in the case of mechanical features.
2811 Here they include extrusion:
2812 * to a limiting face of the basis shape;
2813 * to or from a limiting plane;
2816 A class object is created or initialized from
2817 * a shape (basic shape);
2818 * a wire (base of rib or groove);
2819 * a plane (plane of the wire);
2820 * direction1 (a vector along which thickness will be built up);
2821 * direction2 (vector opposite to the previous one along which thickness will be built up, may be null);
2822 * a Boolean indicating the type of operation (fusion=rib or cut=groove) on the basic shape;
2823 * another Boolean indicating if self-intersections have to be found (not used in every case).
2825 @subsubsection occt_modalg_9_2_1 Linear Form
2827 Linear form is implemented in *MakeLinearForm* class, which creates a rib or a groove along a planar surface. There is one *Perform()* method, which performs a prism from the wire along the *direction1* and *direction2* interacting with base shape *Sbase*. The height of the prism is *Magnitude(Direction1)+Magnitude(direction2)*.
2830 BRepBuilderAPI_MakeWire mkw;
2831 gp_Pnt p1 = gp_Pnt(0.,0.,0.);
2832 gp_Pnt p2 = gp_Pnt(200.,0.,0.);
2833 mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2));
2835 p2 = gp_Pnt(200.,0.,50.);
2836 mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2));
2838 p2 = gp_Pnt(50.,0.,50.);
2839 mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2));
2841 p2 = gp_Pnt(50.,0.,200.);
2842 mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2));
2844 p2 = gp_Pnt(0.,0.,200.);
2845 mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2));
2847 mkw.Add(BRepBuilderAPI_MakeEdge(p2,gp_Pnt(0.,0.,0.)));
2848 TopoDS_Shape S = BRepBuilderAPI_MakePrism(BRepBuilderAPI_MakeFace
2849 (mkw.Wire()),gp_Vec(gp_Pnt(0.,0.,0.),gp_P
2851 TopoDS_Wire W = BRepBuilderAPI_MakeWire(BRepBuilderAPI_MakeEdge(gp_Pnt
2853 gp_Pnt(100.,45.,50.)));
2854 Handle(Geom_Plane) aplane =
2855 new Geom_Plane(gp_Pnt(0.,45.,0.), gp_Vec(0.,1.,0.));
2856 BRepFeat_MakeLinearForm aform(S, W, aplane, gp_Dir
2857 (0.,5.,0.), gp_Dir(0.,-3.,0.), 1, Standard_True);
2859 TopoDS_Shape res = aform.Shape();
2862 @figure{/user_guides/modeling_algos/images/modeling_algos_image051.png,"Creating a rib",240}
2864 @subsubsection occt_modalg_9_2_3 Gluer
2866 The class *BRepFeat_Gluer* allows gluing two solids along faces. The contact faces of the glued shape must not have parts outside the contact faces of the basic shape. Upon completion the algorithm gives the glued shape with cut out parts of faces inside the shape.
2868 The class is created or initialized from two shapes: the “glued” shape and the basic shape (on which the other shape is glued).
2869 Two *Bind* methods are used to bind a face of the glued shape to a face of the basic shape and an edge of the glued shape to an edge of the basic shape.
2871 **Note** that every face and edge has to be bounded, if two edges of two glued faces are coincident they must be explicitly bounded.
2874 TopoDS_Shape Sbase = ...; // the basic shape
2875 TopoDS_Shape Sglued = ...; // the glued shape
2877 TopTools_ListOfShape Lfbase;
2878 TopTools_ListOfShape Lfglued;
2879 // Determination of the glued faces
2882 BRepFeat_Gluer theGlue(Sglue, Sbase);
2883 TopTools_ListIteratorOfListOfShape itlb(Lfbase);
2884 TopTools_ListIteratorOfListOfShape itlg(Lfglued);
2885 for (; itlb.More(); itlb.Next(), itlg(Next()) {
2886 const TopoDS_Face& f1 = TopoDS::Face(itlg.Value());
2887 const TopoDS_Face& f2 = TopoDS::Face(itlb.Value());
2888 theGlue.Bind(f1,f2);
2889 // for example, use the class FindEdges from LocOpe to
2890 // determine coincident edges
2891 LocOpe_FindEdge fined(f1,f2);
2892 for (fined.InitIterator(); fined.More(); fined.Next()) {
2893 theGlue.Bind(fined.EdgeFrom(),fined.EdgeTo());
2897 if (theGlue.IsDone() {
2898 TopoDS_Shape theResult = theGlue;
2903 @subsubsection occt_modalg_9_2_4 Split Shape
2905 The class *BRepFeat_SplitShape* is used to split faces of a shape into wires or edges. The shape containing the new entities is rebuilt, sharing the unmodified ones.
2907 The class is created or initialized from a shape (the basic shape).
2908 Three Add methods are available:
2909 * *Add(Wire, Face)* -- adds a new wire on a face of the basic shape.
2910 * *Add(Edge, Face)* -- adds a new edge on a face of the basic shape.
2911 * *Add(EdgeNew, EdgeOld)* -- adds a new edge on an existing one (the old edge must contain the new edge).
2913 **Note** The added wires and edges must define closed wires on faces or wires located between two existing edges. Existing edges must not be intersected.
2916 TopoDS_Shape Sbase = ...; // basic shape
2917 TopoDS_Face Fsplit = ...; // face of Sbase
2918 TopoDS_Wire Wsplit = ...; // new wire contained in Fsplit
2919 BRepFeat_SplitShape Spls(Sbase);
2920 Spls.Add(Wsplit, Fsplit);
2921 TopoDS_Shape theResult = Spls;
2926 @section occt_modalg_10 Hidden Line Removal
2928 To provide the precision required in industrial design, drawings need to offer the possibility of removing lines, which are hidden in a given projection.
2930 For this the Hidden Line Removal component provides two algorithms: *HLRBRep_Algo* and *HLRBRep_PolyAlgo*.
2932 These algorithms are based on the principle of comparing each edge of the shape to be visualized with each of its faces, and calculating the visible and the hidden parts of each edge. Note that these are not the algorithms used in generating shading, which calculate the visible and hidden parts of each face in a shape to be visualized by comparing each face in the shape with every other face in the same shape.
2933 These algorithms operate on a shape and remove or indicate edges hidden by faces. For a given projection, they calculate a set of lines characteristic of the object being represented. They are also used in conjunction with extraction utilities, which reconstruct a new, simplified shape from a selection of the results of the calculation. This new shape is made up of edges, which represent the shape visualized in the projection.
2935 *HLRBRep_Algo* allows working with the shape itself, whereas *HLRBRep_PolyAlgo* works with a polyhedral simplification of the shape. When you use *HLRBRep_Algo*, you obtain an exact result, whereas, when you use *HLRBRep_PolyAlgo*, you reduce the computation time, but obtain polygonal segments.
2937 No smoothing algorithm is provided. Consequently, a polyhedron will be treated as such and the algorithms will give the results in form of line segments conforming to the mathematical definition of the polyhedron. This is always the case with *HLRBRep_PolyAlgo*.
2939 *HLRBRep_Algo* and *HLRBRep_PolyAlgo* can deal with any kind of object, for example, assemblies of volumes, surfaces, and lines, as long as there are no unfinished objects or points within it.
2941 However, there some restrictions in HLR use:
2942 * Points are not processed;
2943 * Infinite faces or lines are not processed.
2946 @figure{/user_guides/modeling_algos/images/modeling_algos_image052.png,"Sharp, smooth and sewn edges in a simple screw shape",320}
2948 @figure{/user_guides/modeling_algos/images/modeling_algos_image053.png,"Outline edges and isoparameters in the same shape",320}
2950 @figure{/user_guides/modeling_algos/images/modeling_algos_image054.png,"A simple screw shape seen with shading",320}
2952 @figure{/user_guides/modeling_algos/images/modeling_algos_image055.png,"An extraction showing hidden sharp edges",320}
2955 The following services are related to Hidden Lines Removal :
2959 To pass a *TopoDS_Shape* to an *HLRBRep_Algo* object, use *HLRBRep_Algo::Add*. With an *HLRBRep_PolyAlgo* object, use *HLRBRep_PolyAlgo::Load*. If you wish to add several shapes, use Add or Load as often as necessary.
2961 ### Setting view parameters
2963 *HLRBRep_Algo::Projector* and *HLRBRep_PolyAlgo::Projector* set a projector object which defines the parameters of the view. This object is an *HLRAlgo_Projector*.
2965 ### Computing the projections
2967 *HLRBRep_PolyAlgo::Update* launches the calculation of outlines of the shape visualized by the *HLRBRep_PolyAlgo* framework.
2969 In the case of *HLRBRep_Algo*, use *HLRBRep_Algo::Update*. With this algorithm, you must also call the method *HLRBRep_Algo::Hide* to calculate visible and hidden lines of the shape to be visualized. With an *HLRBRep_PolyAlgo* object, visible and hidden lines are computed by *HLRBRep_PolyHLRToShape*.
2971 ### Extracting edges
2973 The classes *HLRBRep_HLRToShape* and *HLRBRep_PolyHLRToShape* present a range of extraction filters for an *HLRBRep_Algo object* and an *HLRBRep_PolyAlgo* object, respectively. They highlight the type of edge from the results calculated by the algorithm on a shape. With both extraction classes, you can highlight the following types of output:
2974 * visible/hidden sharp edges;
2975 * visible/hidden smooth edges;
2976 * visible/hidden sewn edges;
2977 * visible/hidden outline edges.
2979 To perform extraction on an *HLRBRep_PolyHLRToShape* object, use *HLRBRep_PolyHLRToShape::Update* function.
2981 For an *HLRBRep_HLRToShape* object built from an *HLRBRepAlgo* object you can also highlight:
2982 * visible isoparameters and
2983 * hidden isoparameters.
2985 @subsection occt_modalg_10_1 Examples
2990 // Build The algorithm object
2991 myAlgo = new HLRBRep_Algo();
2993 // Add Shapes into the algorithm
2994 TopTools_ListIteratorOfListOfShape anIterator(myListOfShape);
2995 for (;anIterator.More();anIterator.Next())
2996 myAlgo-Add(anIterator.Value(),myNbIsos);
2998 // Set The Projector (myProjector is a
3000 myAlgo-Projector(myProjector);
3005 // Set The Edge Status
3008 // Build the extraction object :
3009 HLRBRep_HLRToShape aHLRToShape(myAlgo);
3011 // extract the results :
3012 TopoDS_Shape VCompound = aHLRToShape.VCompound();
3013 TopoDS_Shape Rg1LineVCompound =
3014 aHLRToShape.Rg1LineVCompound();
3015 TopoDS_Shape RgNLineVCompound =
3016 aHLRToShape.RgNLineVCompound();
3017 TopoDS_Shape OutLineVCompound =
3018 aHLRToShape.OutLineVCompound();
3019 TopoDS_Shape IsoLineVCompound =
3020 aHLRToShape.IsoLineVCompound();
3021 TopoDS_Shape HCompound = aHLRToShape.HCompound();
3022 TopoDS_Shape Rg1LineHCompound =
3023 aHLRToShape.Rg1LineHCompound();
3024 TopoDS_Shape RgNLineHCompound =
3025 aHLRToShape.RgNLineHCompound();
3026 TopoDS_Shape OutLineHCompound =
3027 aHLRToShape.OutLineHCompound();
3028 TopoDS_Shape IsoLineHCompound =
3029 aHLRToShape.IsoLineHCompound();
3032 ### HLRBRep_PolyAlgo
3037 // Build The algorithm object
3038 myPolyAlgo = new HLRBRep_PolyAlgo();
3040 // Add Shapes into the algorithm
3041 TopTools_ListIteratorOfListOfShape
3042 anIterator(myListOfShape);
3043 for (;anIterator.More();anIterator.Next())
3044 myPolyAlgo-Load(anIterator.Value());
3046 // Set The Projector (myProjector is a
3048 myPolyAlgo->Projector(myProjector);
3051 myPolyAlgo->Update();
3053 // Build the extraction object :
3054 HLRBRep_PolyHLRToShape aPolyHLRToShape;
3055 aPolyHLRToShape.Update(myPolyAlgo);
3057 // extract the results :
3058 TopoDS_Shape VCompound =
3059 aPolyHLRToShape.VCompound();
3060 TopoDS_Shape Rg1LineVCompound =
3061 aPolyHLRToShape.Rg1LineVCompound();
3062 TopoDS_Shape RgNLineVCompound =
3063 aPolyHLRToShape.RgNLineVCompound();
3064 TopoDS_Shape OutLineVCompound =
3065 aPolyHLRToShape.OutLineVCompound();
3066 TopoDS_Shape HCompound =
3067 aPolyHLRToShape.HCompound();
3068 TopoDS_Shape Rg1LineHCompound =
3069 aPolyHLRToShape.Rg1LineHCompound();
3070 TopoDS_Shape RgNLineHCompound =
3071 aPolyHLRToShape.RgNLineHCompound();
3072 TopoDS_Shape OutLineHCompound =
3073 aPolyHLRToShape.OutLineHCompound();
3076 @section occt_modalg_11 Meshing
3078 @subsection occt_modalg_11_1 Mesh presentations
3080 In addition to support of exact geometrical representation of 3D objects Open CASCADE Technology provides functionality to work with tessellated representations of objects in form of meshes.
3082 Open CASCADE Technology mesh functionality provides:
3083 - data structures to store surface mesh data associated to shapes, and some basic algorithms to handle these data
3084 - data structures and algorithms to build surface triangular mesh from *BRep* objects (shapes).
3085 - tools to extend 3D visualization capabilities of Open CASCADE Technology with displaying meshes along with associated pre- and post-processor data.
3087 Open CASCADE Technology includes two mesh converters:
3088 - VRML converter translates Open CASCADE shapes to VRML 1.0 files (Virtual Reality Modeling Language). Open CASCADE shapes may be translated in two representations: shaded or wireframe. A shaded representation present shapes as sets of triangles computed by a mesh algorithm while a wireframe representation present shapes as sets of curves.
3089 - STL converter translates Open CASCADE shapes to STL files. STL (STtereoLithography) format is widely used for rapid prototyping.
3091 Open CASCADE SAS also offers Advanced Mesh Products:
3092 - <a href="http://www.opencascade.com/content/mesh-framework">Open CASCADE Mesh Framework (OMF)</a>
3093 - <a href="http://www.opencascade.com/content/express-mesh">Express Mesh</a>
3095 Besides, we can efficiently help you in the fields of surface and volume meshing algorithms, mesh optimization algorithms etc. If you require a qualified advice about meshing algorithms, do not hesitate to benefit from the expertise of our team in that domain.
3097 The projects dealing with numerical simulation can benefit from using SALOME - an Open Source Framework for CAE with CAD data interfaces, generic Pre- and Post- F.E. processors and API for integrating F.E. solvers.
3099 Learn more about SALOME platform on http://www.salome-platform.org
3101 @subsection occt_modalg_11_2 Meshing algorithm
3103 The algorithm of shape triangulation is provided by the functionality of *BRepMesh_IncrementalMesh* class, which adds a triangulation of the shape to its topological data structure. This triangulation is used to visualize the shape in shaded mode.
3106 #include <IMeshData_Status.hxx>
3107 #include <IMeshTools_Parameters.hxx>
3108 #include <BRepMesh_IncrementalMesh.hxx>
3110 Standard_Boolean meshing_explicit_parameters()
3112 const Standard_Real aRadius = 10.0;
3113 const Standard_Real aHeight = 25.0;
3114 BRepPrimAPI_MakeCylinder aCylinder(aRadius, aHeight);
3115 TopoDS_Shape aShape = aCylinder.Shape();
3117 const Standard_Real aLinearDeflection = 0.01;
3118 const Standard_Real anAngularDeflection = 0.5;
3119 BRepMesh_IncrementalMesh aMesher (aShape, aLinearDeflection, Standard_False, anAngularDeflection, Standard_True);
3120 const Standard_Integer aStatus = aMesher.GetStatusFlags();
3124 Standard_Boolean meshing_imeshtools_parameters()
3126 const Standard_Real aRadius = 10.0;
3127 const Standard_Real aHeight = 25.0;
3128 BRepPrimAPI_MakeCylinder aCylinder(aRadius, aHeight);
3129 TopoDS_Shape aShape = aCylinder.Shape();
3131 IMeshTools_Parameters aMeshParams;
3132 aMeshParams.Deflection = 0.01;
3133 aMeshParams.Angle = 0.5;
3134 aMeshParams.Relative = Standard_False;
3135 aMeshParams.InParallel = Standard_True;
3136 aMeshParams.MinSize = Precision::Confusion();
3137 aMeshParams.InternalVerticesMode = Standard_True;
3138 aMeshParams.ControlSurfaceDeflection = Standard_True;
3140 BRepMesh_IncrementalMesh aMesher (aShape, aMeshParams);
3141 const Standard_Integer aStatus = aMesher.GetStatusFlags();
3146 The default meshing algorithm *BRepMesh_IncrementalMesh* has two major options to define triangulation -- linear and angular deflections.
3148 At the first step all edges from a face are discretized according to the specified parameters.
3150 At the second step, the faces are tessellated. Linear deflection limits the distance between a curve and its tessellation, whereas angular deflection limits the angle between subsequent segments in a polyline.
3152 @figure{/user_guides/modeling_algos/images/modeling_algos_image056.png,"Deflection parameters of BRepMesh_IncrementalMesh algorithm",420}
3154 Linear deflection limits the distance between triangles and the face interior.
3156 @figure{/user_guides/modeling_algos/images/modeling_algos_image057.png,"Linear deflection",420}
3158 Note that if a given value of linear deflection is less than shape tolerance then the algorithm will skip this value and will take into account the shape tolerance.
3160 The application should provide deflection parameters to compute a satisfactory mesh. Angular deflection is relatively simple and allows using a default value (12-20 degrees). Linear deflection has an absolute meaning and the application should provide the correct value for its models. Giving small values may result in a too huge mesh (consuming a lot of memory, which results in a long computation time and slow rendering) while big values result in an ugly mesh.
3162 For an application working in dimensions known in advance it can be reasonable to use the absolute linear deflection for all models. This provides meshes according to metrics and precision used in the application (for example, it it is known that the model will be stored in meters, 0.004 m is enough for most tasks).
3164 However, an application that imports models created in other applications may not use the same deflection for all models. Note that actually this is an abnormal situation and this application is probably just a viewer for CAD models with dimensions varying by an order of magnitude. This problem can be solved by introducing the concept of a relative linear deflection with some LOD (level of detail). The level of detail is a scale factor for absolute deflection, which is applied to model dimensions.
3166 Meshing covers a shape with a triangular mesh. Other than hidden line removal, you can use meshing to transfer the shape to another tool: a manufacturing tool, a shading algorithm, a finite element algorithm, or a collision algorithm.
3168 You can obtain information on the shape by first exploring it. To access triangulation of a face in the shape later, use *BRepTool::Triangulation*. To access a polygon, which is the approximation of an edge of the face, use *BRepTool::PolygonOnTriangulation*.
3170 @subsection occt_modalg_11_3 BRepMesh Architecture
3171 @subsubsection occt_modalg_11_3_1 Goals
3173 The main goals of the chosen architecture are:
3174 * Remove tight connections between data structures, auxiliary tools and algorithms in order to create an extensible solution, easy for maintenance and improvements;
3175 * Separate the code among several functional units responsible for specific operation for the sake of simplification of debugging and readability;
3176 * Introduce new data structures enabling the possibility to manipulate a discrete model of a particular entity (edge, wire, face) in order to perform computations locally instead of processing an entire model;
3177 * Implement a new triangulation algorithm replacing existing functionality that contains too complicated solutions that need to be moved to the upper level. In addition, provide the possibility to change algorithm depending on surface type (initially to speed up meshing of planes).
3179 @subsubsection occt_modalg_11_3_2 General workflow
3180 @figure{/user_guides/modeling_algos/images/modeling_algos_mesh_001.svg,"General workflow of BRepMesh component",500}
3182 Generally, the workflow of the component can be divided on six parts:
3183 * **Creation of model data structure**: source *TopoDS_Shape* passed to algorithm is analyzed and exploded on faces and edges. The reflection corresponding to each topological entity is created in the data model. Note that underlying algorithms use the data model as input and access it via a common interface which allows creating a custom data model with necessary dependencies between particular entities (see the paragraph "Data model interface");
3184 * **Discretize edges 3D & 2D curves**: 3D curve as well as an associated set of 2D curves of each model edge is discretized in order to create a coherent skeleton used as a base in face meshing process. If an edge of the source shape already contains polygonal data which suits the specified parameters, it is extracted from the shape and stored in the model as is. Each edge is processed separately, adjacency is not taken into account;
3185 * **Heal discrete model**: the source *TopoDS_Shape* can contain problems, such as open wires or self-intersections, introduced during design, exchange or modification of model. In addition, some problems like self-intersections can be introduced by roughly discretized edges. This stage is responsible for analysis of a discrete model in order to detect and repair problems or to refuse further processing of a model part in case if a problem cannot be solved;
3186 * **Preprocess discrete model**: defines actions specific to the implemented approach to be performed before meshing of faces. By default, this operation iterates over model faces, checks the consistency of existing triangulations and cleans topological faces and adjacent edges from polygonal data in case of inconsistency or marks a face of the discrete model as not required for the computation;
3187 * **Discretize faces**: represents the core part performing mesh generation for a particular face based on 2D discrete data. This operation caches polygonal data associated with face edges in the data model for further processing and stores the generated mesh to *TopoDS_Face*;
3188 * **Postprocess discrete model**: defines actions specific for the implemented approach to be performed after meshing of faces. By default, this operation stores polygonal data obtained at the previous stage to *TopoDS_Edge* objects of the source model.
3190 @subsubsection occt_modalg_11_3_3 Common interfaces
3191 The component structure contains two units: <i>IMeshData</i> (see Data model interface) and <i>IMeshTools</i>, defining common interfaces for the data model and algorithmic tools correspondingly. Class *IMeshTools_Context* represents a connector between these units. The context class caches the data model as well as the tools corresponding to each of six stages of the workflow mentioned above and provides methods to call the corresponding tool safely (designed similarly to *IntTools_Context* in order to keep consistency with OCCT core tools). All stages, except for the first one use data model as input and perform a specific action on the entire structure. Thus, API class *IMeshTools_ModelAlgo* is defined in order to unify the interface of tools manipulating the data model. Each tool supposed to process the data model should inherit this interface enabling the possibility to cache it in context. In contrast to others, the model builder interface is defined by another class *IMeshTools_ModelBuilder* due to a different meaning of the stage. The entry point starting the entire workflow is represented by *IMeshTools_MeshBuilder*.
3193 The default implementation of *IMeshTools_Context* is given in *BRepMesh_Context* class initializing the context by instances of default algorithmic tools.
3195 The factory interface *IMeshTools_MeshAlgoFactory* gives the possibility to change the triangulation algorithm for a specific surface. The factory returns an instance of the triangulation algorithm via *IMeshTools_MeshAlgo* interface depending on the type of surface passed as parameter. It is supposed to be used at the face discretization stage.
3197 The default implementation of AlgoFactory is given in *BRepMesh_MeshAlgoFactory* returning algorithms of different complexity chosen according to the passed surface type. In its turn, it is used as the initializer of *BRepMesh_FaceDiscret* algorithm representing the starter of face discretization stage.
3199 @figure{/user_guides/modeling_algos/images/modeling_algos_mesh_002.svg,"Interface describing entry point to meshing workflow",500}
3201 Remaining interfaces describe auxiliary tools:
3202 * *IMeshTools_CurveTessellator*: provides a common interface to the algorithms responsible for creation of discrete polygons on 3D and 2D curves as well as tools for extraction of existing polygons from *TopoDS_Edge* allowing to obtain discrete points and the corresponding parameters on curve regardless of the implementation details (see examples of usage of derived classes *BRepMesh_CurveTessellator*, *BRepMesh_EdgeTessellationExtractor* in *BRepMesh_EdgeDiscret*);
3203 * *IMeshTools_ShapeExplorer*: the last two interfaces represent visitor design pattern and are intended to separate iteration over elements of topological shape (edges and faces) from the operations performed on a particular element;
3204 * *IMeshTools_ShapeVisitor*: provides a common interface for operations on edges and faces of the target topological shape. It can be used in couple with *IMeshTools_ShapeExplorer*. The default implementation available in *BRepMesh_ShapeVisitor* performs initialization of the data model. The advantage of such approach is that the implementation of *IMeshTools_ShapeVisitor* can be changed according to the specific data model whereas the shape explorer implementation remains the same.
3206 @subsubsection occt_modalg_11_3_4 Create model data structure
3207 The data structures intended to keep discrete and temporary data required by underlying algorithms are created at the first stage of the meshing procedure. Generally, the model represents dependencies between entities of the source topological shape suitable for the target task.
3209 #### Data model interface
3210 Unit <i>IMeshData</i> provides common interfaces specifying the data model API used on different stages of the entire workflow. Dependencies and references of the designed interfaces are given in the figure below. A specific interface implementation depends on the target application which allows the developer to implement different models and use custom low-level data structures, e.g. different collections, either <i>NCollection</i> or STL. *IMeshData_Shape* is used as the base class for all data structures and tools keeping the topological shape in order to avoid possible copy-paste.
3212 The default implementation of interfaces is given in <i>BRepMeshData</i> unit. The main aim of the default data model is to provide features performing discretization of edges in a parallel mode. Thus, curve, pcurve and other classes are based on STL containers and smart-pointers as far as <i>NCollection</i> does not provide thread-safety for some cases (e.g. *NCollection_Sequence*). In addition, it closely reflects topology of the source shape, i.e. the number of edges in the data model is equal to the number of edges in the source model; each edge contains a set of pcurves associated with its adjacent faces which allows creation of discrete polygons for all pcurves or the 3D curve of a particular edge in a separate thread.
3215 In case of necessity, the data model (probably with algorithms for its processing) can be easily substituted by another implementation supporting another kind of dependencies between elements.
3217 An additional example of a different data model is the case when it is not required to create a mesh with discrete polygons synchronized between adjacent faces, i.e. in case of necessity to speed up creation of a rough per-face tessellation used for visualization or quick computation only (the approach used in *XDEDRAW_Props*).
3219 @figure{/user_guides/modeling_algos/images/modeling_algos_mesh_003.svg,"Common API of data model",500}
3221 #### Collecting data model
3222 At this stage the data model is filled by entities according to the topological structure of the source shape. A default implementation of the data model is given in <i>BRepMeshData</i> unit and represents the model as two sets: a set of edges and a set of faces. Each face consists of one or several wires, the first of which always represents the outer wire, while others are internal. In its turn, each wire depicts the ordered sequence of oriented edges. Each edge is characterized by a single 3D curve and zero (in case of free edge) or more 2D curves associated with faces adjacent to this edge. Both 3D and 2D curves represent a set of pairs point-parameter defined in 3D and 2D space of the reference face correspondingly. An additional difference between a curve and a pcurve is that the latter has a reference to the face it is defined for.
3224 Model filler algorithm is represented by *BRepMesh_ShapeVisitor* class creating the model as a reflection to topological shape with help of *BRepMesh_ShapeExplorer* performing iteration over edges and faces of the target shape. Note that the algorithm operates on a common interface of the data model and creates a structure without any knowledge about the implementation details and underlying data structures. The entry point to collecting functionality is *BRepMesh_ModelBuilder* class.
3226 @subsubsection occt_modalg_11_3_5 Discretize edges 3D & 2D curves
3227 At this stage only the edges of the data model are considered. Each edge is processed separately (with the possibility to run processing in multiple threads). The edge is checked for existing polygonal data. In case if at least one representation exists and suits the meshing parameters, it is recuperated and used as reference data for tessellation of the whole set of pcurves as well as 3D curve assigned to the edge (see *BRepMesh_EdgeTessellationExtractor*). Otherwise, a new tessellation algorithm is created and used to generate the initial polygon (see *BRepMesh_CurveTessellator*) and the edge is marked as outdated. In addition, the model edge is updated by deflection as well as recomputed same range, same parameter and degeneracy parameters. See *BRepMesh_EdgeDiscret* for implementation details.
3229 <i>IMeshData</i> unit defines interface *IMeshData_ParametersListArrayAdaptor*, which is intended to adapt arbitrary data structures to the *NCollection_Array1* container API. This solution is made to use both *NCollection_Array1* and *IMeshData_Curve* as the source for *BRepMesh_EdgeParameterProvider* tool intended to generate a consistent parametrization taking into account the same parameter property.
3231 @subsubsection occt_modalg_11_3_6 Heal discrete model
3232 In general, this stage represents a set of operations performed on the entire discrete model in order to resolve inconsistencies due to the problems caused by design, translation or rough discretization. A different sequence of operations can be performed depending on the target triangulation algorithm, e.g. there are different approaches to process self-intersections – either to amplify edges discretization by decreasing the target precision or to split links at the intersection points. At this stage the whole set of edges is considered in aggregate and their adjacency is taken into account. A default implementation of the model healer is given in *BRepMesh_ModelHealer* which performs the following actions:
3233 * Iterates over model faces and checks their wires for consistency, i.e. whether the wires are closed and do not contain self-intersections. The data structures are designed free of collisions, thus it is possible to run processing in a parallel mode;
3234 * Forcibly connects the ends of adjacent edges in the parametric space, closing gaps between possible disconnected parts. The aim of this operation is to create a correct discrete model defined relatively to the parametric space of the target face taking into account connectivity and tolerances of 3D space only. This means that no specific computations are made to determine U and V tolerance;
3235 * Registers intersections on edges forming the face shape. Two solutions are possible in order to resolve self-intersection:
3236 * Decrease deflection of a particular edge and update its discrete model. After that the workflow "intersection check – amplification" is repeated up to 5 times. As the result, target edges contain a finer tessellation and meshing continues or the face is marked by *IMeshData_SelfIntersectingWire* status and refused from further processing;
3237 * Split target edges by intersection point and synchronize the updated polygon with curve and remaining pcurves associated to each edge. This operation presents a more robust solution comparing to the amplification procedure with a guaranteed result, but it is more difficult for implementation from the point of view of synchronization functionality.
3239 @subsubsection occt_modalg_11_3_7 Preprocess discrete model
3240 This stage implements actions to be performed before meshing of faces. Depending on target goals it can be changed or omitted. By default, *BRepMesh_ModelPreProcessor* implements the functionality checking topological faces for consistency of existing triangulation, i.e.: consistency with the target deflection parameter; indices of nodes referenced by triangles do not exceed the number of nodes stored in a triangulation. If the face fails some checks, it is cleaned from triangulation and its adjacent edges are cleaned from existing polygons. This does not affect a discrete model and does not require any recomputation as the model keeps tessellations for the whole set of edges despite consistency of their polygons.
3242 @subsubsection occt_modalg_11_3_8 Discretize faces
3243 Discretization of faces is the general part of meshing algorithm. At this stage edges tessellation data obtained and processed on previous steps is used to form contours of target faces and passed as input to the triangulation algorithm. Default implementation is provided by *BRepMesh_FaceDiscret* class which represents a starter for triangulation algorithm. It iterates over faces available in the data model, creates an instance of the triangulation algorithm according to the type of surface associated with each face via *IMeshTools_MeshAlgoFactory* and executes it. Each face is processed separately, thus it is possible to process faces in a parallel mode. The class diagram of face discretization is given in the figure below.
3245 @figure{/user_guides/modeling_algos/images/modeling_algos_mesh_004.svg,"Class diagram of face discrete stage",300}
3247 In general, face meshing algorithms have the following structure:
3248 * *BRepMesh_BaseMeshAlgo* implements *IMeshTools_MeshAlgo* interface and the base functionality for inherited algorithms. The main goal of this class is to initialize an instance of *BRepMesh_DataStructureOfDelaun* as well as auxiliary data structures suitable for nested algorithms using face model data passed as input parameter. Despite implementation of triangulation algorithm this structure is currently supposed as common for OCCT. However, the user is free to implement a custom algorithm and supporting data structure accessible via *IMeshTools_MeshAlgo* interface, e.g. to connect a 3-rd party meshing tool that does not support *TopoDS_Shape* out of box. For this, such structure provides the possibility to distribute connectors to various algorithms in the form of plugins;
3249 * *BRepMesh_DelaunayBaseMeshAlgo* and *BRepMesh_SweepLineMeshAlgo* classes implement core meshing functionality operating directly on an instance of *BRepMesh_DataStructureOfDelaun*. The algorithms represent mesh generation tools adding new points from the data structure to the final mesh;
3250 * *BRepMesh_NodeInsertionMeshAlgo* class represents a wrapper intended to extend the algorithm inherited from *BRepMesh_BaseMeshAlgo* to enable the functionality generating surface nodes and inserting them into the structure. On this level, an instance of the classification tool is created and can be used to accept-reject internal nodes. In addition, computations necessary for scaling UV coordinates of points relatively to the range specified for the corresponding direction are performed. As far as both triangulation algorithms work on static data provided by the structure, new nodes are added at the initialization stage. Surface nodes are generated by an auxiliary tool called range splitter and passed as template parameter (see Range splitter);
3251 * Classes *BRepMesh_DelaunayNodeInsertionMeshAlgo* and *BRepMesh_SweepLineNodeInsertionMeshAlgo* implement algorithm-specific functionality related to addition of internal nodes supplementing functionality provided by *BRepMesh_NodeInsertionMeshAlgo*;
3252 * *BRepMesh_DelaunayDeflectionControlMeshAlgo* extends functionality of *BRepMesh_DelaunayNodeInsertionMeshAlgo* by additional procedure controlling deflection of generated triangles.
3255 Range splitter tools provide functionality to generate internal surface nodes defined within the range computed using discrete model data. The base functionality is provided by *BRepMesh_DefaultRangeSplitter* which can be used without modifications in case of planar surface. The default splitter does not generate any internal node.
3257 *BRepMesh_ConeRangeSplitter*, *BRepMesh_CylinderRangeSplitter* and *BRepMesh_SphereRangeSplitter* are specializations of the default splitter intended for quick generation of internal nodes for the corresponding type of analytical surface.
3259 *BRepMesh_UVParamRangeSplitter* implements base functionality taking discretization points of face border into account for node generation. Its successors BRepMesh_TorusRangeSplitter and *BRepMesh_NURBSRangeSplitter* extend the base functionality for toroidal and NURBS surfaces correspondingly.
3261 @subsubsection occt_modalg_11_3_9 Postprocess discrete model
3262 This stage implements actions to be performed after meshing of faces. Depending on target goals it can be changed or omitted. By default, *BRepMesh_ModelPostProcessor* commits polygonal data stored in the data model to *TopoDS_Edge*.
3265 @section occt_modalg_defeaturing 3D Model Defeaturing
3267 The Open CASCADE Technology Defeaturing algorithm is intended for removal of the unwanted parts or features from the model. These parts can be holes, protrusions, gaps, chamfers, fillets, etc.
3269 Feature detection is not performed, and all features to be removed should be defined by the user. The input shape is not modified during Defeaturing, the new shape is built in the result.
3271 On the API level the Defeaturing algorithm is implemented in the *BRepAlgoAPI_Defeaturing* class. At input the algorithm accepts the shape to remove the features from and the features (one or many) to be removed from the shape.
3272 Currently, the input shape should be either SOLID, or COMPSOLID, or COMPOUND of SOLIDs.
3273 The features to be removed are defined by the sets of faces forming them. It does not matter how the feature faces are given: as separate faces or their collections. The faces should belong to the initial shape, else they are ignored.
3275 The actual features removal is performed by the low-level *BOPAlgo_RemoveFeatures* algorithm. On the API level, all inputs are passed into the tool and the method *BOPAlgo_RemoveFeatures::Perform()* is called.
3277 Before removing features, all faces to be removed from the shape are sorted into connected blocks - each block represents a single feature to be removed.
3278 The features are removed from the shape one by one, which allows removing all possible features even if there are some problems with their removal (e.g. due to incorrect input data).
3280 The removed feature is filled by the extension of the faces adjacent to it. In general, the algorithm removing a single feature from the shape goes as follows:
3281 * Find the faces adjacent to the feature;
3282 * Extend the adjacent faces to cover the feature;
3283 * Trim the extended faces by the bounds of the original face (except for the bounds common with the feature), so that they cover the feature only;
3284 * Rebuild the solids with reconstructed adjacent faces avoiding the feature faces.
3286 If the single feature removal was successful, the result shape is overwritten with the new shape, otherwise the results are not kept, and the warning is given.
3287 Either way the process continues with the next feature.
3289 The Defeaturing algorithm has the following options:
3292 and the options available from base class (*BOPAlgo_Options*):
3293 * Error/Warning reporting system;
3294 * Parallel processing mode.
3296 Note that the other options of the base class are not supported here and will have no effect.
3298 <b>History support</b> allows tracking modification of the input shape in terms of Modified, IsDeleted and Generated. By default, the history is collected, but it is possible to disable it using the method *SetToFillHistory(false)*.
3299 On the low-level the history information is collected by the history tool *BRepTools_History*, which can be accessed through the method *BOPAlgo_RemoveFeatures::History()*.
3301 <b>Error/Warning reporting system</b> allows obtaining the extended overview of the Errors/Warnings occurred during the operation. As soon as any error appears, the algorithm stops working. The warnings allow continuing the job and informing the user that something went wrong. The algorithm returns the following errors/warnings:
3302 * *BOPAlgo_AlertUnsupportedType* - the alert will be given as an error if the input shape does not contain any solids, and as a warning if the input shape contains not only solids, but also other shapes;
3303 * *BOPAlgo_AlertNoFacesToRemove* - the error alert is given in case there are no faces to remove from the shape (nothing to do);
3304 * *BOPAlgo_AlertUnableToRemoveTheFeature* - the warning alert is given to inform the user the removal of the feature is not possible. The algorithm will still try to remove the other features;
3305 * *BOPAlgo_AlertRemoveFeaturesFailed* - the error alert is given in case if the operation was aborted by the unknown reason.
3307 For more information on the error/warning reporting system, see the chapter @ref occt_algorithms_ers "Errors and warnings reporting system" of Boolean operations user guide.
3309 <b>Parallel processing mode</b> - allows running the algorithm in parallel mode obtaining the result faster.
3311 The algorithm has certain limitations:
3312 * Intersection of the surfaces of the connected faces adjacent to the feature should not be empty. It means, that such faces should not be tangent to each other.
3313 If the intersection of the adjacent faces will be empty, the algorithm will be unable to trim the faces correctly and, most likely, the feature will not be removed.
3314 * The algorithm does not process the INTERNAL parts of the solids, they are simply removed during reconstruction.
3316 Note, that for successful removal of the feature, the extended faces adjacent to the feature should cover the feature completely, otherwise the solids will not be rebuild.
3317 Take a look at the simple shape on the image below:
3318 @figure{/user_guides/modeling_algos/images/modeling_algos_rf_im001.png,"",220}
3320 Removal of all three faces of the gap is not going to work, because there will be no face to fill the transverse part of the step.
3321 Although, removal of only two faces, keeping one of the transverse faces, will fill the gap with the kept face:
3322 <table align="center">
3324 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im002.png,"Keeping the right transverse face",220}</td>
3325 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im003.png,"Keeping the left transverse face",220}</td>
3329 @subsection occt_modalg_defeaturing_usage Usage
3331 Here is the example of usage of the *BRepAlgoAPI_Defeaturing* algorithm on the C++ level:
3333 TopoDS_Shape aSolid = ...; // Input shape to remove the features from
3334 TopTools_ListOfShape aFeatures = ...; // Features to remove from the shape
3335 Standard_Boolean bRunParallel = ...; // Parallel processing mode
3336 Standard_Boolean isHistoryNeeded = ...; // History support
3338 BRepAlgoAPI_Defeaturing aDF; // Defeaturing algorithm
3339 aDF.SetShape(aSolid); // Set the shape
3340 aDF.AddFacesToRemove(aFaces); // Add faces to remove
3341 aDF.SetRunParallel(bRunParallel); // Define the processing mode (parallel or single)
3342 aDF.SetToFillHistory(isHistoryNeeded); // Define whether to track the shapes modifications
3343 aDF.Build(); // Perform the operation
3344 if (!aDF.IsDone()) // Check for the errors
3347 Standard_SStream aSStream;
3348 aDF.DumpErrors(aSStream);
3351 if (aDF.HasWarnings()) // Check for the warnings
3353 // warnings treatment
3354 Standard_SStream aSStream;
3355 aDF.DumpWarnings(aSStream);
3357 const TopoDS_Shape& aResult = aDF.Shape(); // Result shape
3360 Use the API history methods to track the history of a shape:
3362 // Obtain modification of the shape
3363 const TopTools_ListOfShape& BRepAlgoAPI_Defeaturing::Modified(const TopoDS_Shape& theS);
3365 // Obtain shapes generated from the shape
3366 const TopTools_ListOfShape& BRepAlgoAPI_Defeaturing::Generated(const TopoDS_Shape& theS);
3368 // Check if the shape is removed or not
3369 Standard_Boolean BRepAlgoAPI_Defeaturing::IsDeleted(const TopoDS_Shape& theS);
3372 The command <b>removefeatures</b> allows using the Defeaturing algorithm on the Draw level.
3374 The @ref occt_draw_hist "standard history commands" can be used to track the history of shape modification during Defeaturing.
3376 For more details on commands above, refer to the @ref occt_draw_defeaturing "Defeaturing commands" of the Draw test harness user guide.
3378 @subsection occt_modalg_defeaturing_examples Examples
3380 Here are the examples of defeaturing of the ANC101 model:
3382 @figure{/user_guides/modeling_algos/images/modeling_algos_rf_im004.png,"ANC101 model",220}</td>
3384 <table align="center">
3386 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im005.png,"Removing the cylindrical protrusion",220}</td>
3387 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im006.png,"Result",220}</td></td>
3390 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im007.png,"Removing the cylindrical holes",220}</td>
3391 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im008.png,"Result",220}</td></td>
3394 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im009.png,"Removing the cylindrical holes",220}</td>
3395 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im010.png,"Result",220}</td></td>
3398 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im011.png,"Removing the small gaps in the front",220}</td>
3399 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im012.png,"Result",220}</td></td>
3402 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im013.png,"Removing the gaps in the front completely",220}</td>
3403 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im014.png,"Result",220}</td></td>
3406 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im015.png,"Removing the cylindrical protrusion",220}</td>
3407 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im016.png,"Result",220}</td></td>
3411 Here are the few examples of defeaturing of the model containing boxes with blends:
3413 @figure{/user_guides/modeling_algos/images/modeling_algos_rf_im017.png,"Box blend model",220}</td>
3415 <table align="center">
3417 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im018.png,"Removing the blend",220}</td>
3418 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im019.png,"Result",220}</td></td>
3421 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im020.png,"Removing the blend",220}</td>
3422 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im021.png,"Result",220}</td></td>
3425 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im022.png,"Removing the blend",220}</td>
3426 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im023.png,"Result",220}</td></td>
3429 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im024.png,"Removing the blend",220}</td>
3430 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im025.png,"Result",220}</td></td>
3433 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im026.png,"Removing the blend",220}</td>
3434 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im027.png,"Result",220}</td></td>
3437 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im028.png,"Removing the blend",220}</td>
3438 <td>@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im029.png,"Result",220}</td></td>