7f7ed3ff53b4bac45f3b16676569f8be1d105dfc
[occt.git] / dox / user_guides / modeling_algos / modeling_algos.md
1 Modeling Algorithms  {#occt_user_guides__modeling_algos}
2 =========================
3
4 @tableofcontents
5
6 @section occt_modalg_1 Introduction
7
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 offerings  on our web site at <a href="http://www.opencascade.org/support/training/">www.opencascade.org/support/training/</a> 
9
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. 
11
12 @section occt_modalg_2 Geometric Tools
13
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.
20   
21 @subsection occt_modalg_2_2 Intersections
22
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.
28
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. 
30
31 @image html /user_guides/modeling_algos/images/modeling_algos_image003.png  "Intersection and self-intersection of curves"
32 @image latex /user_guides/modeling_algos/images/modeling_algos_image003.png  "Intersection and self-intersection of curves"
33
34 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
36 @image html /user_guides/modeling_algos/images/modeling_algos_image004.png "Intersection and tangent intersection"
37 @image latex /user_guides/modeling_algos/images/modeling_algos_image004.png "Intersection and tangent intersection"
38
39 The algorithm returns a  point in the case of an intersection and a segment in the case of tangent  intersection. 
40
41 @subsubsection occt_modalg_2_2_1 Intersection of two curves
42
43 *Geom2dAPI_InterCurveCurve* class may be instantiated for intersection of curves *C1* and *C2*.
44 ~~~~~
45 Geom2dAPI_InterCurveCurve Intersector(C1,C2,tolerance); 
46 ~~~~~
47
48 or for self-intersection of curve *C3*.
49 ~~~~~
50 Geom2dAPI_InterCurveCurve Intersector(C3,tolerance); 
51 ~~~~~
52
53 ~~~~~
54 Standard_Integer N = Intersector.NbPoints(); 
55 ~~~~~
56 Calls the number of intersection points
57
58 To select the desired intersection point, pass an integer index value in argument. 
59 ~~~~~
60 gp_Pnt2d P = Intersector.Point(Index); 
61 ~~~~~
62
63 To call the number of intersection segments, use
64 ~~~~~
65 Standard_Integer M = Intersector.NbSegments(); 
66 ~~~~~
67
68 To select the desired intersection segment pass integer index values in argument. 
69 ~~~~~
70 Handle(Geom2d_Curve) Seg1, Seg2; 
71 Intersector.Segment(Index,Seg1,Seg2); 
72 // if intersection of 2 curves 
73 Intersector.Segment(Index,Seg1); 
74 // if self-intersection of a curve 
75 ~~~~~
76
77 If you need access to a wider range of functionalities the following method will return the algorithmic  object for the calculation of intersections: 
78
79 ~~~~~
80 Geom2dInt_GInter& TheIntersector = Intersector.Intersector(); 
81 ~~~~~
82
83 @subsubsection occt_modalg_2_2_2 Intersection of Curves and Surfaces
84
85 The *GeomAPI_IntCS* class  is used to compute the intersection points between a curve and a surface. 
86
87 This class is  instantiated as follows: 
88 ~~~~~
89 GeomAPI_IntCS Intersector(C, S); 
90 ~~~~~
91
92 To call the number of intersection points, use:
93 ~~~~~
94 Standard_Integer nb = Intersector.NbPoints(); 
95 ~~~~~
96
97
98 ~~~~~
99 gp_Pnt& P = Intersector.Point(Index); 
100 ~~~~~
101
102 Where *Index* is an  integer between 1 and *nb*, calls the intersection points.
103
104 @subsubsection occt_modalg_2_2_3 Intersection of two Surfaces
105 The *GeomAPI_IntSS* class  is used to compute the intersection of two surfaces from *Geom_Surface* with  respect to a given tolerance. 
106
107 This class is  instantiated as follows: 
108 ~~~~~
109 GeomAPI_IntSS Intersector(S1, S2, Tolerance); 
110 ~~~~~
111 Once the *GeomAPI_IntSS* object has been created, it can be interpreted. 
112
113 ~~~~~
114 Standard_Integer nb = Intersector. NbLines(); 
115 ~~~~~
116 Calls the number of intersection curves.
117
118 ~~~~~
119 Handle(Geom_Curve) C = Intersector.Line(Index) 
120 ~~~~~
121 Where *Index* is an  integer between 1 and *nb*, calls the intersection curves.
122
123
124 @subsection occt_modalg_2_3  Interpolations
125
126 The Interpolation Laws component provides definitions of functions: <i> y=f(x) </i>.
127
128 In particular, it provides definitions of:
129   * a linear function,
130   * an <i> S </i> function, and
131   * an interpolation function for a range of values.
132
133 Such functions can be used to define, for example, the evolution law of a fillet along the edge of a shape.
134
135 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.
136
137 @subsubsection occt_modalg_2_3_1 Geom2dAPI_Interpolate
138 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. 
139 This class may be  instantiated as follows: 
140 ~~~~~
141 Geom2dAPI_Interpolate 
142 (const  Handle_TColgp_HArray1OfPnt2d& Points, 
143 const  Standard_Boolean PeriodicFlag, 
144 const Standard_Real  Tolerance); 
145
146 Geom2dAPI_Interpolate Interp(Points, Standard_False, 
147                                     Precision::Confusion()); 
148 ~~~~~
149
150
151 It is possible to call the BSpline curve from the object defined  above it. 
152 ~~~~~
153 Handle(Geom2d_BSplineCurve) C = Interp.Curve(); 
154 ~~~~~
155
156 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
158 ~~~~~
159 Handle(Geom2d_BSplineCurve) C = 
160 Geom2dAPI_Interpolate(Points, 
161     Standard_False, 
162     Precision::Confusion()); 
163 ~~~~~
164
165 @subsubsection occt_modalg_2_3_2 GeomAPI_Interpolate
166
167 This class may be  instantiated as follows: 
168 ~~~~~
169 GeomAPI_Interpolate 
170 (const  Handle_TColgp_HArray1OfPnt& Points, 
171 const  Standard_Boolean PeriodicFlag, 
172 const Standard_Real  Tolerance); 
173
174 GeomAPI_Interpolate Interp(Points, Standard_False, 
175                                     Precision::Confusion()); 
176 ~~~~~
177
178 It is possible to call the BSpline curve from the object defined  above it. 
179 ~~~~~
180 Handle(Geom_BSplineCurve) C = Interp.Curve(); 
181 ~~~~~
182 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. 
183
184 Handle(Geom_BSplineCurve) C = 
185         GeomAPI_Interpolate(Points,  
186                                                 Standard_False,
187                                                 1.0e-7); 
188
189 Boundary conditions may  be imposed with the method Load. 
190 ~~~~~
191 GeomAPI_Interpolate AnInterpolator 
192 (Points, Standard_False, 1.0e-5); 
193 AnInterpolator.Load (StartingTangent, EndingTangent); 
194 ~~~~~
195
196 @subsection occt_modalg_2_4 Lines and  Circles from Constraints
197
198 @subsibsection occt_modalg_2_4_1 Types of constraints
199
200 The algorithms for construction of 2D circles or lines can be described with numeric or geometric constraints in relation to other curves. 
201
202 These constraints can impose the following :
203   * the radius of a circle,
204   * the angle that a straight line makes with another straight line,
205   * the tangency of a straight line or circle in relation to a curve,
206   * the passage of a straight line or circle through a point,
207   * the circle with center in a point or curve.
208
209 For example, these algorithms enable to easily construct a circle of a given radius, centered on a straight line and tangential to another circle.
210
211 The implemented algorithms are more complex than those provided by the Direct Constructions component for building 2D circles or lines.
212
213 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
214 case of a circle of a given radius (a small one) which is tangential to two secant circles C1 and C2:
215
216 @figure{/user_guides/modeling_algos/images/modeling_algos_image058.png,"Example of a Tangency Constraint"}
217
218 This diagram clearly shows that there are 8 possible solutions.
219
220 In order to limit the number of solutions, we can try to express the relative position
221 of the required solution in relation to the circles to which it is tangential. For
222 example, if we specify that the solution is inside the circle C1 and outside the
223 circle C2, only two solutions referenced 3 and 4 on the diagram respond to the problem
224 posed.
225
226 These definitions are very easy to interpret on a circle, where it is easy to identify
227 the interior and exterior sides. In fact, for any kind of curve the interior is defined
228 as the left-hand side of the curve in relation to its orientation.
229
230 This technique of qualification of a solution, in relation to the curves to which
231 it is tangential, can be used in all algorithms for constructing a circle or a straight
232 line by geometric constraints. Four qualifiers are used:
233   * **Enclosing** - the solution(s) must enclose the argument;
234   * **Enclosed** - the solution(s) must be enclosed by the argument;
235   * **Outside** - the solution(s) and the argument must be external to one another;
236   * **Unqualified** - the relative position is not qualified, i.e. all solutions apply.
237     
238 It is possible to create expressions using the qualifiers,  for example:
239 ~~~~~
240 GccAna_Circ2d2TanRad 
241         Solver(GccEnt::Outside(C1), 
242                 GccEnt::Enclosing(C2),  Rad, Tolerance); 
243 ~~~~~
244
245 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.
246   
247 @subsection occt_modalg_2_4_2 Available types of lines and circles
248
249 The following analytic algorithms using value-handled entities for creation of 2D lines or circles with geometric constraints are available: 
250   * circle tangent to three  elements (lines, circles, curves, points),
251   * circle tangent to two  elements and having a radius,
252   * circle tangent to two  elements and centered on a third element,
253   * circle tangent to two  elements and centered on a point,
254   * circle tangent to one element  and centered on a second,
255   * bisector of two points,
256   * bisector of two lines,
257   * bisector of two circles,
258   * bisector of a line and a  point,
259   * bisector of a circle and a  point,
260   * bisector of a line and a  circle,
261   * line tangent to two elements  (points, circles, curves),
262   * line tangent to one element  and parallel to a line,
263   * line tangent to one element  and perpendicular to a line,
264   * line tangent to one element  and forming angle with a line.
265
266 #### Exterior/Interior
267 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 &quot;material&quot;). 
268
269 @image html /user_guides/modeling_algos/images/modeling_algos_image006.png "Exterior/Interior of a Circle"
270 @image latex /user_guides/modeling_algos/images/modeling_algos_image006.png "Exterior/Interior of a Circle"
271
272 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: 
273
274 @image html /user_guides/modeling_algos/images/modeling_algos_image007.png "Exterior/Interior of a Line and a Curve"
275 @image latex /user_guides/modeling_algos/images/modeling_algos_image007.png "Exterior/Interior of a Line and a Curve"
276
277 #### Orientation of a Line
278 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. 
279
280 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. 
281
282 @image html /user_guides/modeling_algos/images/modeling_algos_image008.png "An Oriented Line"
283 @image latex /user_guides/modeling_algos/images/modeling_algos_image008.png "An Oriented Line"
284
285
286 #### Line tangent to two circles
287 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.
288
289
290 **Example 1 Case 1** 
291
292 @image html /user_guides/modeling_algos/images/modeling_algos_image009.png "Both circles outside"
293 @image latex /user_guides/modeling_algos/images/modeling_algos_image009.png "Both circles outside"
294
295 Constraints: 
296 Tangent and Exterior to  C1. 
297 Tangent and Exterior to  C2. 
298
299 Syntax: 
300
301 ~~~~~
302 GccAna_Lin2d2Tan 
303         Solver(GccEnt::Outside(C1), 
304                 GccEnt::Outside(C2), 
305                 Tolerance); 
306 ~~~~~
307
308 **Example 1 Case 2** 
309
310 @image html /user_guides/modeling_algos/images/modeling_algos_image010.png "Both circles enclosed"
311 @image latex /user_guides/modeling_algos/images/modeling_algos_image010.png "Both circles enclosed"
312
313 Constraints: 
314 Tangent and Including  C1. 
315 Tangent and Including  C2. 
316
317 Syntax: 
318
319 ~~~~~
320 GccAna_Lin2d2Tan 
321         Solver(GccEnt::Enclosing(C1), 
322                 GccEnt::Enclosing(C2), 
323                 Tolerance); 
324 ~~~~~
325
326 **Example  1 Case 3**
327  
328 @image html /user_guides/modeling_algos/images/modeling_algos_image011.png "C1 enclosed, C2 outside"
329 @image latex /user_guides/modeling_algos/images/modeling_algos_image011.png "C1 enclosed, C2 outside"
330
331 Constraints: 
332 Tangent and Including C1. 
333 Tangent and Exterior to C2. 
334
335 Syntax: 
336 ~~~~~
337 GccAna_Lin2d2Tan 
338         Solver(GccEnt::Enclosing(C1), 
339                 GccEnt::Outside(C2), 
340                 Tolerance); 
341 ~~~~~
342
343 **Example 1 Case 4** 
344
345 @image html /user_guides/modeling_algos/images/modeling_algos_image012.png "C1 outside, C2 enclosed"
346 @image latex /user_guides/modeling_algos/images/modeling_algos_image012.png "C1 outside, C2 enclosed"
347 Constraints: 
348 Tangent and Exterior to  C1. 
349 Tangent and Including  C2. 
350
351 Syntax: 
352 ~~~~~
353 GccAna_Lin2d2Tan 
354         Solver(GccEnt::Outside(C1), 
355                 GccEnt::Enclosing(C2), 
356                 Tolerance); 
357 ~~~~~
358
359 **Example 1 Case 5** 
360
361 @image html /user_guides/modeling_algos/images/modeling_algos_image013.png "With no qualifiers specified"
362 @image latex /user_guides/modeling_algos/images/modeling_algos_image013.png "With no qualifiers specified"
363
364 Constraints: 
365 Tangent and Undefined  with respect to C1. 
366 Tangent and Undefined  with respect to C2. 
367
368 Syntax: 
369 ~~~~~
370 GccAna_Lin2d2Tan 
371         Solver(GccEnt::Unqualified(C1), 
372                 GccEnt::Unqualified(C2), 
373                 Tolerance); 
374 ~~~~~
375
376 #### Circle of given radius tangent to two circles
377 The following four  diagrams show the four cases in using qualifiers in the creation of a circle. 
378
379 **Example 2 Case 1** 
380 @image html /user_guides/modeling_algos/images/modeling_algos_image014.png "Both solutions outside"
381 @image latex /user_guides/modeling_algos/images/modeling_algos_image014.png "Both solutions outside"
382
383 Constraints: 
384 Tangent and Exterior to  C1. 
385 Tangent and Exterior to  C2. 
386
387 Syntax: 
388 ~~~~~
389 GccAna_Circ2d2TanRad 
390         Solver(GccEnt::Outside(C1), 
391         GccEnt::Outside(C2),  Rad, Tolerance); 
392 ~~~~~
393
394 **Example 2 Case 2** 
395
396 @image html /user_guides/modeling_algos/images/modeling_algos_image015.png "C2 encompasses C1"
397 @image latex /user_guides/modeling_algos/images/modeling_algos_image015.png "C2 encompasses C1"
398
399 Constraints: 
400 Tangent and Exterior to  C1. 
401 Tangent and Included by  C2. 
402
403 Syntax: 
404 ~~~~~
405 GccAna_Circ2d2TanRad 
406         Solver(GccEnt::Outside(C1), 
407                 GccEnt::Enclosed(C2),  Rad, Tolerance); 
408 ~~~~~
409
410 **Example  2 Case 3**
411 @image html /user_guides/modeling_algos/images/modeling_algos_image016.png "Solutions enclose C2"
412 @image latex /user_guides/modeling_algos/images/modeling_algos_image016.png "Solutions enclose C2"
413
414 Constraints: 
415 Tangent and Exterior to  C1. 
416 Tangent and Including  C2. 
417
418 Syntax: 
419 ~~~~~
420 GccAna_Circ2d2TanRad 
421         Solver(GccEnt::Outside(C1), 
422                 GccEnt::Enclosing(C2),  Rad, Tolerance); 
423 ~~~~~
424                 
425 **Example 2 Case 4**
426 @image html /user_guides/modeling_algos/images/modeling_algos_image017.png "Solutions enclose C1"
427 @image latex /user_guides/modeling_algos/images/modeling_algos_image017.png "Solutions enclose C1"
428
429 Constraints: 
430 Tangent and Enclosing  C1. 
431 Tangent and Enclosing  C2. 
432
433 Syntax: 
434 ~~~~~
435 GccAna_Circ2d2TanRad 
436         Solver(GccEnt::Enclosing(C1), 
437                 GccEnt::Enclosing(C2),  Rad, Tolerance); 
438 ~~~~~
439
440 **Example 2 Case 5**
441
442 The following syntax  will give all the circles of radius *Rad*, which are tangent to *C1* and *C2* without discrimination of relative position: 
443
444 ~~~~~
445 GccAna_Circ2d2TanRad  Solver(GccEnt::Unqualified(C1), 
446                                                         GccEnt::Unqualified(C2), 
447                                                         Rad,Tolerance); 
448 ~~~~~                                                   
449
450
451 @subsection occt_modalg_2_4_2 Types of  algorithms
452
453 OCCT implements several categories of algorithms:
454
455 * **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;
456 * **Geometric** algorithms, where the solution is generally obtained by calculating the intersection of parallel or bisecting curves built from geometric arguments;
457 * **Iterative** algorithms, where the solution is obtained by a process of iteration.
458   
459 For each kind of geometric construction of a constrained line or circle, OCCT provides two types of access:
460
461   * 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;
462   * 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.
463
464 The provided algorithms compute all solutions, which correspond to the stated geometric problem, unless the solution is found by an iterative algorithm.
465
466 Iterative algorithms compute only one solution, closest to an initial position. They can be used in the following cases:
467   * 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;
468   * to build a line, when a tangency argument is more complex than a line or a circle.
469
470 Qualified curves (for tangency arguments) are provided either by:
471   * the <i> GccEnt</i> package, for direct use by <i> GccAna</i> algorithms, or
472   * the <i> Geom2dGcc </i> package, for general use by <i> Geom2dGcc </i> algorithms.
473
474 The <i> GccEnt</i> and <i> Geom2dGcc</i> packages also provide simple functions for building qualified curves in a very efficient way.
475
476 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
477 are typically curves, such as circles, lines or conics for <i> GccAna</i> algorithms. 
478 Each elementary solution is given as an elementary bisecting locus object (line, circle, ellipse, hyperbola, parabola), described by the <i>GccInt</i> package.
479
480 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.
481
482 @subsection occt_modalg_2_5 Curves and Surfaces from Constraints
483
484 The Curves and Surfaces from Constraints component groups together high level functions used in 2D and 3D geometry for:
485   * creation of faired and minimal variation 2D curves
486   * construction of ruled surfaces
487   * construction of pipe surfaces
488   * filling of surfaces
489   * construction of plate surfaces
490   * extension of a 3D curve or surface beyond its original bounds.
491   
492 OPEN CASCADE company also provides a product known as <a href="http://www.opencascade.org/support/products/ssp/">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.
493
494 SSP product is not supplied with Open CASCADE Technology, but can be purchased separately.
495
496 @subsubsection occt_modalg_2_5_1 Faired and Minimal Variation 2D Curves
497
498 Elastic beam curves have their origin in traditional methods of modeling applied 
499 in boat-building, where a long thin piece of wood, a lathe, was forced to pass
500 between two sets of nails and in this way, take the form of a curve based on the
501 two points, the directions of the forces applied at those points, and the properties
502 of the wooden lathe itself.
503
504 Maintaining these constraints requires both longitudinal and transversal forces to
505 be applied to the beam in order to compensate for its internal elasticity. The longitudinal
506 forces can be a push or a pull and the beam may or may not be allowed to slide over
507 these fixed points.
508
509 #### Batten Curves
510
511 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. 
512 The following constraint orders are available: 
513
514   * 0 the curve must pass through  a point
515   * 1 the curve must pass through  a point and have a given tangent
516   * 2 the curve must pass through  a point, have a given tangent and a given curvature.
517
518 Only 0 and 1 constraint orders are used. 
519 The function Curve  returns the result as a 2D BSpline curve. 
520
521 #### Minimal Variation Curves
522
523 The class *FairCurve_MinimalVariation* allows producing curves with minimal variation in  curvature at each reference point. The following constraint  orders are available: 
524
525   * 0 the curve must pass through  a point
526   * 1 the curve must pass through  a point and have a given tangent
527   * 2 the curve must pass through  a point, have a given tangent and a given curvature.
528
529 Constraint orders of 0, 1 and 2 can be used. The algorithm minimizes tension, sagging and jerk energy. 
530
531 The function *Curve* returns  the result as a 2D BSpline curve. 
532
533 If you want to give a  specific length to a batten curve, use: 
534
535 ~~~~~
536 b.SetSlidingFactor(L / b.SlidingOfReference()) 
537 ~~~~~
538 where *b* is the name of  the batten curve object 
539
540 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. 
541
542 In other cases, when  sliding is imposed and the sliding factor is too large, the batten can  collapse. 
543
544 The constructor parameters, *Tolerance* and *NbIterations*, control how precise the computation is,  and how long it will take. 
545
546 @subsubsection occt_modalg_2_5_2 Ruled Surfaces 
547
548 A ruled surface is built by ruling a line along the length of two curves.
549
550 #### Creation of Bezier surfaces
551
552 The class *GeomFill_BezierCurves* allows producing a Bezier surface from contiguous Bezier curves. Note  that problems may occur with rational Bezier Curves. 
553
554 #### Creation of BSpline surfaces
555
556 The class *GeomFill_BSplineCurves* allows producing a BSpline surface from contiguous BSpline curves.  Note that problems may occur with rational BSplines. 
557
558 @subsubsection occt_modalg_2_5_2 Pipe Surfaces
559
560 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. 
561
562 The following types of construction are available:
563   * pipes with a circular section of constant radius,
564   * pipes with a constant section,
565   * pipes with a section evolving between two given curves.
566   
567   
568 @subsubsection occt_modalg_2_5_3 Filling a contour
569
570 It is often convenient to create a surface from two or more curves which will form the boundaries that define the new surface.
571 This is done by the class *GeomFill_ConstrainedFilling*, which allows filling a contour defined by two, three or four curves as well  as by tangency constraints. The resulting surface is a BSpline. 
572
573 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.
574
575 @figure{/technical_overview/images/modeling_algos_image059.png,"Intersecting filleted edges with differing radiuses"}
576
577 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.
578
579 #### Creation of a Boundary
580
581 The class *GeomFill_SimpleBound* allows you defining a boundary for the surface to be constructed. 
582
583 #### Creation of a Boundary with an adjoining surface
584
585 The class *GeomFill_BoundWithSurf* allows defining a boundary for the surface to be constructed. This boundary will already be joined to another surface. 
586
587 #### Filling styles
588
589 The enumerations *FillingStyle* specify the styles used to build the surface. These include: 
590
591   * *Stretch* - the style with the flattest patches
592   * *Coons* - a rounded style with less depth than *Curved*
593   * *Curved* - the style with the most rounded patches.
594
595 @image html /user_guides/modeling_algos/images/modeling_algos_image018.png "Intersecting filleted edges with different radii leave a gap, is filled by a surface"
596 @image latex /user_guides/modeling_algos/images/modeling_algos_image018.png "Intersecting filleted edges with different radii leave a gap, is filled by a surface"
597
598 @subsubsection occt_modalg_2_5_4 Plate surfaces
599
600 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.
601
602 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
603 curve constraints and the point constraint respectively. The resulting surface can be converted into a BSpline surface by using the function <i> MakeApprox </i>.
604
605 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
606 to deformation. Then, the algorithm is called to calculate the final surface. It looks for a solution satisfying constraints and minimizing energy input.
607
608 @figure{/technical_overview/images/modeling_algos_image061.png,"Surface generated from two curves and a point"}
609
610 The package *GeomPlate*   provides the following services for creating surfaces respecting curve and  point constraints: 
611
612 #### Definition of a Framework
613
614 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*. 
615
616 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. 
617
618 #### Definition of a Curve Constraint
619
620 The class *CurveConstraint* allows defining curves as constraints to the surface, which you want  to build. 
621
622 #### Definition of a Point Constraint
623
624 The class *PointConstraint* allows defining points as constraints to the surface, which you want  to build. 
625
626 #### Applying Geom_Surface to Plate Surfaces
627
628 The class *Surface* allows describing the characteristics of plate surface objects returned by **BuildPlateSurface::Surface** using the methods of *Geom_Surface* 
629
630 #### Approximating a Plate surface to a BSpline
631
632 The class *MakeApprox* allows converting a *GeomPlate* surface into a *Geom_BSplineSurface*. 
633
634 @figure{/technical_overview/images/modeling_algos_image060.png,"Surface generated from four curves and a point"}
635
636 Let us create a Plate surface  and approximate it from a polyline as a curve constraint and a point constraint 
637
638 ~~~~~
639 Standard_Integer NbCurFront=4, 
640 NbPointConstraint=1; 
641 gp_Pnt P1(0.,0.,0.); 
642 gp_Pnt P2(0.,10.,0.); 
643 gp_Pnt P3(0.,10.,10.); 
644 gp_Pnt P4(0.,0.,10.); 
645 gp_Pnt P5(5.,5.,5.); 
646 BRepBuilderAPI_MakePolygon W; 
647 W.Add(P1); 
648 W.Add(P2); 
649 W.Add(P3); 
650 W.Add(P4); 
651 W.Add(P1); 
652 // Initialize a BuildPlateSurface 
653 GeomPlate_BuildPlateSurface BPSurf(3,15,2); 
654 // Create the curve constraints 
655 BRepTools_WireExplorer anExp; 
656 for(anExp.Init(W); anExp.More(); anExp.Next()) 
657
658 TopoDS_Edge E = anExp.Current(); 
659 Handle(BRepAdaptor_HCurve) C = new 
660 BRepAdaptor_HCurve(); 
661 C-ChangeCurve().Initialize(E); 
662 Handle(BRepFill_CurveConstraint) Cont= new 
663 BRepFill_CurveConstraint(C,0); 
664 BPSurf.Add(Cont); 
665
666 // Point constraint 
667 Handle(GeomPlate_PointConstraint) PCont= new 
668 GeomPlate_PointConstraint(P5,0); 
669 BPSurf.Add(PCont); 
670 // Compute the Plate surface 
671 BPSurf.Perform(); 
672 // Approximation of the Plate surface 
673 Standard_Integer MaxSeg=9; 
674 Standard_Integer MaxDegree=8; 
675 Standard_Integer CritOrder=0; 
676 Standard_Real dmax,Tol; 
677 Handle(GeomPlate_Surface) PSurf = BPSurf.Surface(); 
678 dmax = Max(0.0001,10*BPSurf.G0Error()); 
679 Tol=0.0001; 
680 GeomPlate_MakeApprox 
681 Mapp(PSurf,Tol,MaxSeg,MaxDegree,dmax,CritOrder); 
682 Handle (Geom_Surface) Surf (Mapp.Surface()); 
683 // create a face corresponding to the approximated Plate 
684 Surface 
685 Standard_Real Umin, Umax, Vmin, Vmax; 
686 PSurf-Bounds( Umin, Umax, Vmin, Vmax); 
687 BRepBuilderAPI_MakeFace MF(Surf,Umin, Umax, Vmin, Vmax); 
688 ~~~~~
689
690 @subsection occt_modalg_2_6 Projections
691
692 Projections provide for computing the following:
693   * the projections of a 2D point onto a 2D curve
694   * the projections of a 3D point onto a 3D curve or surface
695   * the projection of a 3D curve onto a surface.
696   * the planar curve transposition from the 3D to the 2D parametric space of an underlying plane and v. s.
697   * the positioning of a 2D gp object in the 3D geometric space.
698
699 @subsubsection occt_modalg_2_6_1 Projection of a 2D Point on a Curve
700
701 *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. 
702
703 @image html /user_guides/modeling_algos/images/modeling_algos_image020.png  "Normals from a point to a curve"
704 @image latex /user_guides/modeling_algos/images/modeling_algos_image020.png  "Normals from a point to a curve"
705
706 The  curve does not have to be a *Geom2d_TrimmedCurve*. The algorithm will function with any class inheriting *Geom2d_Curve*. 
707
708 The class *Geom2dAPI_ProjectPointOnCurve* may be instantiated as in the following example: 
709
710 ~~~~~
711 gp_Pnt2d P; 
712 Handle(Geom2d_BezierCurve) C = 
713         new  Geom2d_BezierCurve(args); 
714 Geom2dAPI_ProjectPointOnCurve Projector (P, C); 
715 ~~~~~
716
717 To restrict the search  for normals to a given domain <i>[U1,U2]</i>, use the following constructor: 
718 ~~~~~
719 Geom2dAPI_ProjectPointOnCurve Projector (P, C, U1, U2); 
720 ~~~~~
721 Having thus created the *Geom2dAPI_ProjectPointOnCurve* object, we can now interrogate it. 
722
723 #### Calling the number of solution points
724
725 ~~~~~
726 Standard_Integer NumSolutions = Projector.NbPoints(); 
727 ~~~~~
728
729 #### Calling the location of a solution point
730
731 The solutions are  indexed in a range from *1* to *Projector.NbPoints()*. The point,  which corresponds to a given *Index* may be found: 
732 ~~~~~
733 gp_Pnt2d Pn = Projector.Point(Index); 
734 ~~~~~
735
736 #### Calling the parameter of a solution point
737
738 For a given point  corresponding to a given *Index*: 
739
740 ~~~~~
741 Standard_Real U = Projector.Parameter(Index); 
742 ~~~~~
743
744 This can also be  programmed as: 
745
746 ~~~~~
747 Standard_Real U; 
748 Projector.Parameter(Index,U); 
749 ~~~~~
750
751 #### Calling the distance between the start and end points
752
753 We can find the distance  between the initial point and a point, which corresponds to the given *Index*: 
754
755 ~~~~~
756 Standard_Real D = Projector.Distance(Index); 
757 ~~~~~
758
759 #### Calling the nearest solution point
760
761
762 This class offers a  method to return the closest solution point to the starting point. This  solution is accessed as follows: 
763 ~~~~~
764 gp_Pnt2d P1 = Projector.NearestPoint(); 
765 ~~~~~
766
767 #### Calling the parameter of the nearest solution point
768
769 ~~~~~
770 Standard_Real U = Projector.LowerDistanceParameter(); 
771 ~~~~~
772
773 #### Calling the minimum distance from the point to the curve
774
775 ~~~~~
776 Standard_Real D = Projector.LowerDistance(); 
777 ~~~~~
778
779 #### Redefined operators
780
781 Some operators have been  redefined to find the closest solution. 
782
783 *Standard_Real()* returns  the minimum distance from the point to the curve. 
784
785 ~~~~~
786 Standard_Real D = Geom2dAPI_ProjectPointOnCurve (P,C); 
787 ~~~~~
788
789 *Standard_Integer()* returns the number of solutions. 
790
791 ~~~~~
792 Standard_Integer N = 
793 Geom2dAPI_ProjectPointOnCurve (P,C); 
794 ~~~~~
795
796 *gp_Pnt2d()* returns the  nearest solution point. 
797
798 ~~~~~
799 gp_Pnt2d P1 = Geom2dAPI_ProjectPointOnCurve (P,C); 
800 ~~~~~
801
802 Using these operators  makes coding easier when you only need the nearest point. Thus: 
803 ~~~~~
804 Geom2dAPI_ProjectPointOnCurve Projector (P, C); 
805 gp_Pnt2d P1 = Projector.NearestPoint(); 
806 ~~~~~
807 can be written more  concisely as: 
808 ~~~~~
809 gp_Pnt2d P1 = Geom2dAPI_ProjectPointOnCurve (P,C); 
810 ~~~~~
811 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. 
812
813
814 #### Access to lower-level functionalities
815
816 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: 
817
818 ~~~~~
819 Extrema_ExtPC2d& TheExtrema = Projector.Extrema(); 
820 ~~~~~
821
822 @subsubsection occt_modalg_2_6_2 Projection of a 3D Point on a Curve
823
824 The class *GeomAPI_ProjectPointOnCurve* is  instantiated as in the following example: 
825
826 ~~~~~
827 gp_Pnt P; 
828 Handle(Geom_BezierCurve) C = 
829         new  Geom_BezierCurve(args); 
830 GeomAPI_ProjectPointOnCurve Projector (P, C); 
831 ~~~~~
832
833 If you wish to restrict  the search for normals to the given domain [U1,U2], use the following  constructor: 
834
835 ~~~~~
836 GeomAPI_ProjectPointOnCurve Projector (P, C, U1, U2); 
837 ~~~~~
838 Having thus created the  *GeomAPI_ProjectPointOnCurve* object, you can now interrogate it. 
839
840 #### Calling the number of solution points
841
842 ~~~~~
843 Standard_Integer NumSolutions = Projector.NbPoints(); 
844 ~~~~~
845
846 #### Calling the location of a solution point
847
848 The solutions are  indexed in a range from 1 to *Projector.NbPoints()*. The point, which corresponds  to a given index, may be found: 
849 ~~~~~
850 gp_Pnt Pn = Projector.Point(Index); 
851 ~~~~~
852
853 #### Calling the parameter of a solution point
854
855 For a given point  corresponding to a given index: 
856
857 ~~~~~
858 Standard_Real U = Projector.Parameter(Index); 
859 ~~~~~
860
861 This can also be  programmed as: 
862 ~~~~~
863 Standard_Real U; 
864 Projector.Parameter(Index,U); 
865 ~~~~~
866
867 #### Calling the distance between the start and end point
868
869 The distance between the  initial point and a point, which corresponds to a given index, may be found: 
870 ~~~~~
871 Standard_Real D = Projector.Distance(Index); 
872 ~~~~~
873
874 #### Calling the nearest solution point
875
876 This class offers a  method to return the closest solution point to the starting point. This  solution is accessed as follows: 
877 ~~~~~
878 gp_Pnt P1 = Projector.NearestPoint(); 
879 ~~~~~
880
881 #### Calling the parameter of the nearest solution point
882
883 ~~~~~
884 Standard_Real U = Projector.LowerDistanceParameter(); 
885 ~~~~~
886
887 #### Calling the minimum distance from the point to the curve
888
889 ~~~~~
890 Standard_Real D =  Projector.LowerDistance(); 
891 ~~~~~
892
893 #### Redefined  operators 
894
895 Some operators have been  redefined to find the nearest solution. 
896
897 *Standard_Real()* returns  the minimum distance from the point to the curve. 
898
899 ~~~~~
900 Standard_Real D = GeomAPI_ProjectPointOnCurve (P,C); 
901 ~~~~~
902
903 *Standard_Integer()* returns  the number of solutions. 
904 ~~~~~
905 Standard_Integer N =  GeomAPI_ProjectPointOnCurve (P,C); 
906 ~~~~~
907
908 *gp_Pnt2d()* returns the  nearest solution point. 
909
910 ~~~~~
911 gp_Pnt P1 = GeomAPI_ProjectPointOnCurve (P,C); 
912 ~~~~~
913 Using these operators  makes coding easier when you only need the nearest point. In this way, 
914
915 ~~~~~
916 GeomAPI_ProjectPointOnCurve Projector (P, C); 
917 gp_Pnt P1 = Projector.NearestPoint(); 
918 ~~~~~
919
920 can be written more  concisely as: 
921 ~~~~~
922 gp_Pnt P1 = GeomAPI_ProjectPointOnCurve (P,C); 
923 ~~~~~
924 In the second case,  however, no intermediate *GeomAPI_ProjectPointOnCurve* object is created, and it  is impossible to access other solutions points. 
925
926 #### Access to lower-level functionalities
927
928 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: 
929
930 ~~~~~
931 Extrema_ExtPC& TheExtrema = Projector.Extrema(); 
932 ~~~~~
933
934 @subsubsection occt_modalg_2_6_3 Projection of a Point on a Surface
935
936 The class *GeomAPI_ProjectPointOnSurf*  allows calculation of all normals  projected from a point from *gp_Pnt* onto a geometric surface from *Geom_Surface*. 
937
938 @image html /user_guides/modeling_algos/images/modeling_algos_image021.png  "Projection of normals from a point to a surface"
939 @image latex /user_guides/modeling_algos/images/modeling_algos_image021.png  "Projection of normals from a point to a surface"
940
941 Note that the  surface does not have to be of *Geom_RectangularTrimmedSurface* type.  
942 The algorithm  will function with any class inheriting *Geom_Surface*.
943
944 *GeomAPI_ProjectPointOnSurf* is instantiated as in the following  example: 
945 ~~~~~
946 gp_Pnt P; 
947 Handle (Geom_Surface) S = new Geom_BezierSurface(args); 
948 GeomAPI_ProjectPointOnSurf Proj (P, S); 
949 ~~~~~
950
951 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>
952
953 The values of *U1, U2, V1*  and *V2* lie at or within their maximum and minimum limits, i.e.: 
954 ~~~~~
955 Umin <=  U1 < U2 <= Umax 
956 Vmin <=  V1 < V2 <= Vmax 
957 ~~~~~
958 Having thus created the  *GeomAPI_ProjectPointOnSurf* object, you can interrogate it. 
959
960 #### Calling the number of solution points
961
962 ~~~~~
963 Standard_Integer NumSolutions = Proj.NbPoints(); 
964 ~~~~~
965
966 #### Calling the location of a solution point
967
968 The solutions are  indexed in a range from 1 to *Proj.NbPoints()*. The point corresponding to the  given index may be found: 
969
970 ~~~~~
971 gp_Pnt Pn = Proj.Point(Index); 
972 ~~~~~
973
974 #### Calling the parameters of a solution point
975
976 For a given point  corresponding to the given index: 
977
978 ~~~~~
979 Standard_Real U,V; 
980 Proj.Parameters(Index, U, V); 
981 ~~~~~
982
983 #### Calling the distance between the start and end point
984
985
986 The distance between the  initial point and a point corresponding to the given index may be found: 
987 ~~~~~
988 Standard_Real D = Projector.Distance(Index); 
989 ~~~~~
990
991 #### Calling the nearest solution point
992
993 This class offers a  method, which returns the closest solution point to the starting point. This  solution is accessed as follows: 
994 ~~~~~
995 gp_Pnt P1 = Proj.NearestPoint(); 
996 ~~~~~
997
998 #### Calling the parameters of the nearest solution point
999
1000 ~~~~~
1001 Standard_Real U,V; 
1002 Proj.LowerDistanceParameters (U, V); 
1003 ~~~~~
1004
1005 #### Calling the minimum distance from a point to the surface
1006
1007 ~~~~~
1008 Standard_Real D = Proj.LowerDistance(); 
1009 ~~~~~
1010
1011 #### Redefined operators
1012
1013 Some operators have been  redefined to help you find the nearest solution. 
1014
1015 *Standard_Real()* returns  the minimum distance from the point to the surface. 
1016
1017 ~~~~~
1018 Standard_Real D = GeomAPI_ProjectPointOnSurf (P,S); 
1019 ~~~~~
1020
1021 *Standard_Integer()* returns  the number of solutions. 
1022
1023 ~~~~~
1024 Standard_Integer N = GeomAPI_ProjectPointOnSurf (P,S); 
1025 ~~~~~
1026
1027 *gp_Pnt2d()* returns the  nearest solution point. 
1028
1029 ~~~~~
1030 gp_Pnt P1 = GeomAPI_ProjectPointOnSurf (P,S); 
1031 ~~~~~
1032
1033 Using these operators  makes coding easier when you only need the nearest point. In this way, 
1034
1035 ~~~~~
1036 GeomAPI_ProjectPointOnSurface Proj (P, S); 
1037 gp_Pnt P1 = Proj.NearestPoint(); 
1038 ~~~~~
1039
1040 can be written more concisely as: 
1041
1042 ~~~~~
1043 gp_Pnt P1 = GeomAPI_ProjectPointOnSurface (P,S); 
1044 ~~~~~
1045
1046 In the second case,  however, no intermediate *GeomAPI_ProjectPointOnSurf* object is created,  and it is impossible to access other solution points. 
1047
1048 #### Access to lower-level functionalities
1049
1050 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: 
1051
1052 ~~~~~
1053 Extrema_ExtPS& TheExtrema = Proj.Extrema(); 
1054 ~~~~~
1055
1056 @subsubsection occt_modalg_2_12_8 Switching from 2d and 3d Curves
1057
1058 The *To2d* and *To3d* methods are used to; 
1059
1060   * build a 2d curve from a 3d  *Geom_Curve* lying on a *gp_Pln* plane
1061   * build a 3d curve from a  *Geom2d_Curve* and a *gp_Pln* plane.
1062
1063 These methods are called  as follows: 
1064 ~~~~~
1065 Handle(Geom2d_Curve) C2d = GeomAPI::To2d(C3d, Pln); 
1066 Handle(Geom_Curve) C3d = GeomAPI::To3d(C2d, Pln); 
1067 ~~~~~
1068
1069 @section occt_modalg_3a The Topology API
1070   
1071 The Topology  API of Open  CASCADE Technology (**OCCT**) includes the following six packages: 
1072   * *BRepAlgoAPI*
1073   * *BRepBuilderAPI*
1074   * *BRepFilletAPI*
1075   * *BRepFeat*
1076   * *BRepOffsetAPI*
1077   * *BRepPrimAPI*
1078
1079 The classes provided by the API have the following features:
1080   * The constructors of classes provide different construction methods;
1081   * The class retains different tools used to build objects as fields;
1082   * The class provides a casting method to obtain the result automatically with a function-like call.   
1083   
1084 Let us use the class *BRepBuilderAPI_MakeEdge* to create a linear edge from two  points. 
1085
1086 ~~~~~
1087 gp_Pnt P1(10,0,0), P2(20,0,0); 
1088 TopoDS_Edge E = BRepBuilderAPI_MakeEdge(P1,P2);
1089 ~~~~~
1090
1091 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. 
1092
1093 ~~~~~
1094 #include <gp_Pnt.hxx> 
1095 #include <TopoDS_Edge.hxx> 
1096 #include <BRepBuilderAPI_MakeEdge.hxx> 
1097 void EdgeTest() 
1098
1099 gp_Pnt P1; 
1100 gp_Pnt P2; 
1101 BRepBuilderAPI_MakeEdge ME(P1,P2); 
1102 if (!ME.IsDone()) 
1103
1104 // doing ME.Edge() or E = ME here 
1105 // would raise StdFail_NotDone 
1106 Standard_DomainError::Raise 
1107 (“ProcessPoints::Failed to createan edge”); 
1108
1109 TopoDS_Edge E = ME; 
1110
1111 ~~~~~
1112
1113 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. 
1114
1115 *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. 
1116
1117 ~~~~~
1118 void MakeEdgeAndVertices(const gp_Pnt& P1, 
1119 const gp_Pnt& P2, 
1120 TopoDS_Edge& E, 
1121 TopoDS_Vertex& V1, 
1122 TopoDS_Vertex& V2) 
1123
1124 BRepBuilderAPI_MakeEdge ME(P1,P2); 
1125 if (!ME.IsDone()) { 
1126 Standard_DomainError::Raise 
1127 (“MakeEdgeAndVerices::Failed  to create an edge”); 
1128
1129 E = ME; 
1130 V1 = ME.Vextex1(); 
1131 V2 = ME.Vertex2(); 
1132 ~~~~~
1133
1134 The class *BRepBuilderAPI_MakeEdge*  provides two methods *Vertex1* and  *Vertex2*, which return two vertices used to create the edge. 
1135
1136 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. 
1137
1138 ~~~~~
1139 E = ME.Edge(); 
1140 ~~~~~
1141
1142 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. 
1143
1144 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. 
1145
1146
1147 @subsection occt_modalg_3a_1 Error Handling in the Topology API
1148
1149 A method can report an  error in the two following situations: 
1150   * 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.
1151   * 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).
1152
1153 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. 
1154
1155 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. 
1156
1157 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. 
1158 As the test involves a  great deal of computation, performing it twice is also time-consuming. 
1159
1160 Consequently, you might be tempted to adopt the highly inadvisable style of programming  illustrated in the following example: 
1161
1162 ~~~~~
1163 #include <Standard_ErrorHandler.hxx> 
1164 try { 
1165 TopoDS_Edge E = BRepBuilderAPI_MakeEdge(P1,P2); 
1166 // go on with the edge 
1167
1168 catch { 
1169 // process the error. 
1170
1171 ~~~~~
1172
1173 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. 
1174
1175 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. 
1176
1177 ~~~~~
1178 BRepBuilderAPI_MakeEdge ME(P1,P2); 
1179 if (!ME.IsDone()) { 
1180 // doing ME.Edge() or E = ME here 
1181 // would raise StdFail_NotDone 
1182 Standard_DomainError::Raise 
1183 (“ProcessPoints::Failed to create an edge”); 
1184
1185 TopoDS_Edge E = ME; 
1186 ~~~~~
1187
1188 @section occt_modalg_3 Standard  Topological Objects
1189
1190 The following  standard topological objects can be created:
1191   * Vertices
1192   * Edges
1193   * Faces
1194   * Wires
1195   * Polygonal wires
1196   * Shells
1197   * Solids.
1198
1199 There are two root classes for their construction and modification: 
1200 * 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. 
1201 * 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. 
1202
1203 @subection occt_modalg_3_1 Vertex
1204
1205 *BRepBuilderAPI_MakeVertex*  creates a new vertex from a 3D point from gp. 
1206 ~~~~~
1207 gp_Pnt P(0,0,10); 
1208 TopoDS_Vertex V = BRepBuilderAPI_MakeVertex(P); 
1209 ~~~~~
1210
1211 This class always creates a new vertex and has no other methods.
1212
1213 @subsection occt_modalg_3_2 Edge
1214
1215 @subsubsection occt_modalg_3_2_1 Basic edge construction method
1216
1217 Use *BRepBuilderAPI_MakeEdge* to create from a curve and vertices. The basic method constructs an edge from a curve, two vertices, and two parameters. 
1218
1219 ~~~~~
1220 Handle(Geom_Curve) C = ...; // a curve 
1221 TopoDS_Vertex V1 = ...,V2 = ...;// two Vertices 
1222 Standard_Real p1 = ..., p2 = ..;// two parameters 
1223 TopoDS_Edge E = BRepBuilderAPI_MakeEdge(C,V1,V2,p1,p2); 
1224 ~~~~~
1225
1226 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. 
1227
1228 @image html /user_guides/modeling_algos/images/modeling_algos_image022.png "Basic Edge Construction"
1229 @image latex /user_guides/modeling_algos/images/modeling_algos_image022.png "Basic Edge Construction"
1230
1231 The following rules  apply to the arguments: 
1232
1233 **The curve**
1234   * Must not be a Null Handle.
1235   * If the curve is a trimmed  curve, the basis curve is used.
1236
1237 **The vertices** 
1238   * 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()).
1239   * 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).
1240
1241 **The parameters**
1242   * Must be increasing and in the  range of the curve, i.e.:
1243
1244 ~~~~~
1245   C->FirstParameter() <=  p1 < p2 <= C->LastParameter() 
1246 ~~~~~  
1247   
1248   * If the parameters are  decreasing, the Vertices are switched, i.e. V2 becomes V1 and V1 becomes V2.
1249   * 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.
1250   * Can be infinite but the  corresponding vertex must be Null (see above).
1251   * The distance between the Vertex 3d location and the point  evaluated on the curve with the parameter must be lower than the default  precision.
1252
1253 The figure below  illustrates two special cases, a semi-infinite edge and an edge on a periodic  curve. 
1254
1255 @image html /user_guides/modeling_algos/images/modeling_algos_image023.png   "Infinite and Periodic Edges"
1256 @image latex /user_guides/modeling_algos/images/modeling_algos_image023.png   "Infinite and Periodic Edges"
1257
1258 @subsubsection occt_modalg_3_2_2 Supplementary edge construction methods
1259
1260 There exist supplementary edge construction methods derived from the basic one. 
1261
1262 *BRepBuilderAPI_MakeEdge* class provides methods, which are all simplified calls  of the previous one: 
1263
1264   * The parameters can be  omitted. They are computed by projecting the vertices on the curve.
1265   * 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.
1266   * The vertices or points can be  omitted if the parameters are given. The points are computed by evaluating the  parameters on the curve.
1267   * The vertices or points and  the parameters can be omitted. The first and the last parameters of the curve are used.
1268
1269 The five following  methods are thus derived from the basic construction: 
1270
1271 ~~~~~
1272 Handle(Geom_Curve) C = ...; // a curve 
1273 TopoDS_Vertex V1 = ...,V2 = ...;// two Vertices 
1274 Standard_Real p1 = ..., p2 = ..;// two parameters 
1275 gp_Pnt P1 = ..., P2 = ...;// two points 
1276 TopoDS_Edge E; 
1277 // project the vertices on the curve 
1278 E = BRepBuilderAPI_MakeEdge(C,V1,V2); 
1279 // Make vertices from points 
1280 E = BRepBuilderAPI_MakeEdge(C,P1,P2,p1,p2); 
1281 // Make vertices from points and project them 
1282 E = BRepBuilderAPI_MakeEdge(C,P1,P2); 
1283 // Computes the points from the parameters 
1284 E = BRepBuilderAPI_MakeEdge(C,p1,p2); 
1285 // Make an edge from the whole curve 
1286 E = BRepBuilderAPI_MakeEdge(C); 
1287 ~~~~~
1288
1289
1290 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: 
1291
1292 *gp_Lin*       creates a  *Geom_Line* 
1293 *gp_Circ*      creates a  *Geom_Circle* 
1294 *gp_Elips*    creates a  *Geom_Ellipse* 
1295 *gp_Hypr*    creates a  *Geom_Hyperbola* 
1296 *gp_Parab*   creates a  *Geom_Parabola* 
1297
1298 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. 
1299
1300 ~~~~~
1301
1302 TopoDS_Vertex V1 = ...,V2 = ...;// two Vertices 
1303 gp_Pnt P1 = ..., P2 = ...;// two points 
1304 TopoDS_Edge E; 
1305
1306 // linear edge from two vertices 
1307 E = BRepBuilderAPI_MakeEdge(V1,V2); 
1308
1309 // linear edge from two points 
1310 E = BRepBuilderAPI_MakeEdge(P1,P2); 
1311 ~~~~~
1312
1313 @subsubsection occt_modalg_3_2_3 Other information and error status
1314
1315 The class *BRepBuilderAPI_MakeEdge* can provide extra information and return an error status. 
1316
1317 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. 
1318
1319 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: 
1320
1321   * **EdgeDone** - No error occurred, *IsDone* returns True. 
1322   * **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. 
1323   * **ParameterOutOfRange** - The given parameters are not in the range  *C->FirstParameter()*, *C->LastParameter()* 
1324   * **DifferentPointsOnClosedCurve** -  The  two vertices or points have different locations but they are the extremities of  a closed curve. 
1325   * **PointWithInfiniteParameter** - A finite coordinate point was associated with an  infinite parameter (see the Precision package for a definition of infinite  values). 
1326   * **DifferentsPointAndParameter**  - The distance of the 3D point and the point  evaluated on the curve with the parameter is greater than the precision. 
1327   * **LineThroughIdenticPoints** - Two identical points were given to define a line  (construction of an edge without curve), *gp::Resolution* is used to test confusion . 
1328
1329 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. 
1330
1331 @image html /user_guides/modeling_algos/images/modeling_algos_image024.png "Creating a Wire"
1332 @image latex /user_guides/modeling_algos/images/modeling_algos_image024.png "Creating a Wire"
1333
1334 ~~~~~
1335 #include <BRepBuilderAPI_MakeEdge.hxx> 
1336 #include <TopoDS_Shape.hxx> 
1337 #include <gp_Circ.hxx> 
1338 #include <gp.hxx> 
1339 #include <TopoDS_Wire.hxx> 
1340 #include <TopTools_Array1OfShape.hxx> 
1341 #include <BRepBuilderAPI_MakeWire.hxx> 
1342
1343 // Use MakeArc method to make an edge and two vertices 
1344 void MakeArc(Standard_Real x,Standard_Real y, 
1345 Standard_Real R, 
1346 Standard_Real ang, 
1347 TopoDS_Shape& E, 
1348 TopoDS_Shape& V1, 
1349 TopoDS_Shape& V2) 
1350
1351 gp_Ax2 Origin = gp::XOY(); 
1352 gp_Vec Offset(x, y, 0.); 
1353 Origin.Translate(Offset); 
1354 BRepBuilderAPI_MakeEdge 
1355 ME(gp_Circ(Origin,R),  ang, ang+PI/2); 
1356 E = ME; 
1357 V1 = ME.Vertex1(); 
1358 V2 = ME.Vertex2(); 
1359
1360
1361 TopoDS_Wire MakeFilletedRectangle(const Standard_Real H, 
1362 const Standard_Real L, 
1363 const Standard_Real  R) 
1364
1365 TopTools_Array1OfShape theEdges(1,8); 
1366 TopTools_Array1OfShape theVertices(1,8); 
1367
1368 // First create the circular edges and the vertices 
1369 // using the MakeArc function described above. 
1370 void MakeArc(Standard_Real, Standard_Real, 
1371 Standard_Real, Standard_Real, 
1372 TopoDS_Shape&, TopoDS_Shape&,  TopoDS_Shape&); 
1373
1374 Standard_Real x = L/2 - R, y = H/2 - R; 
1375 MakeArc(x,-y,R,3.*PI/2.,theEdges(2),theVertices(2), 
1376 theVertices(3)); 
1377 MakeArc(x,y,R,0.,theEdges(4),theVertices(4), 
1378 theVertices(5)); 
1379 MakeArc(-x,y,R,PI/2.,theEdges(6),theVertices(6), 
1380 theVertices(7)); 
1381 MakeArc(-x,-y,R,PI,theEdges(8),theVertices(8), 
1382 theVertices(1)); 
1383 // Create the linear edges 
1384 for (Standard_Integer i = 1; i <= 7; i += 2) 
1385
1386 theEdges(i) = BRepBuilderAPI_MakeEdge 
1387 (TopoDS::Vertex(theVertices(i)),TopoDS::Vertex 
1388 (theVertices(i+1))); 
1389
1390 // Create the wire using the BRepBuilderAPI_MakeWire 
1391 BRepBuilderAPI_MakeWire MW; 
1392 for (i = 1; i <= 8; i++) 
1393
1394 MW.Add(TopoDS::Edge(theEdges(i))); 
1395
1396 return MW.Wire(); 
1397
1398 ~~~~~
1399
1400 @subsection occt_modalg_3_3 Edge 2D
1401
1402 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). 
1403
1404 *BRepBuilderAPI_MakeEdge2d* class is strictly similar to BRepBuilderAPI_MakeEdge, but it uses 2D geometry from gp and Geom2d instead of  3D geometry. 
1405
1406 @subsection occt_modalg_3_4 Polygon
1407
1408 *BRepBuilderAPI_MakePolygon* class is used to build polygonal wires from vertices  or points. Points are automatically changed to vertices as in  *BRepBuilderAPI_MakeEdge*. 
1409
1410 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. 
1411
1412 ~~~~~
1413 #include <TopoDS_Wire.hxx> 
1414 #include <BRepBuilderAPI_MakePolygon.hxx> 
1415 #include <TColgp_Array1OfPnt.hxx> 
1416
1417 TopoDS_Wire ClosedPolygon(const TColgp_Array1OfPnt&  Points) 
1418
1419 BRepBuilderAPI_MakePolygon MP; 
1420 for(Standard_Integer i=Points.Lower();i=Points.Upper();i++) 
1421
1422 MP.Add(Points(i)); 
1423
1424 MP.Close(); 
1425 return MP; 
1426
1427 ~~~~~
1428
1429 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. 
1430
1431 Two examples: 
1432
1433 Example of a closed  triangle from three vertices:
1434 ~~~~~ 
1435 TopoDS_Wire W =  BRepBuilderAPI_MakePolygon(V1,V2,V3,Standard_True); 
1436 ~~~~~
1437
1438 Example of an open  polygon from four points:
1439 ~~~~~
1440 TopoDS_Wire W = BRepBuilderAPI_MakePolygon(P1,P2,P3,P4); 
1441 ~~~~~
1442
1443 *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*. 
1444
1445 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. 
1446
1447 @subsection occt_modalg_3_5 Face
1448
1449 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. 
1450
1451 @subsubsection occt_modalg_3_5_1 Basic face construction method
1452
1453 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. 
1454
1455 ~~~~~
1456 Handle(Geom_Surface) S = ...; // a surface 
1457 Standard_Real umin,umax,vmin,vmax; // parameters 
1458 TopoDS_Face F =  BRepBuilderAPI_MakeFace(S,umin,umax,vmin,vmax); 
1459 ~~~~~
1460
1461 @image html /user_guides/modeling_algos/images/modeling_algos_image025.png "Basic Face Construction"
1462 @image latex /user_guides/modeling_algos/images/modeling_algos_image025.png "Basic Face Construction"
1463
1464 To make a face from the  natural boundary of a surface, the parameters are not required: 
1465
1466 ~~~~~
1467 Handle(Geom_Surface) S = ...; // a surface 
1468 TopoDS_Face F = BRepBuilderAPI_MakeFace(S); 
1469 ~~~~~
1470
1471 Constraints on the  parameters are similar to the constraints in *BRepBuilderAPI_MakeEdge*. 
1472   * *umin,umax (vmin,vmax)* must be  in the range of the surface and must be increasing.
1473   * On a *U (V)* periodic surface  *umin* and *umax (vmin,vmax)* are adjusted.
1474   * *umin, umax, vmin, vmax* can be  infinite. There will be no edge in the corresponding direction.
1475
1476 @subsubsection occt_modalg_3_5_2 Supplementary face construction methods
1477
1478 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. 
1479
1480 | gp package surface | | Geom package surface |
1481 | :------------------- | :----------- | :------------- |
1482 | *gp_Pln*             |    | *Geom_Plane* |
1483 | *gp_Cylinder*        |   | *Geom_CylindricalSurface* |
1484 | *gp_Cone*            |   creates  a | *Geom_ConicalSurface* |
1485 | *gp_Sphere*          |    | *Geom_SphericalSurface* |
1486 | *gp_Torus*           |    | *Geom_ToroidalSurface* |
1487
1488 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. 
1489
1490 ~~~~~
1491 gp_Cylinder C = ..; // a cylinder 
1492 TopoDS_Wire W = ...;// a wire 
1493 BRepBuilderAPI_MakeFace MF(C); 
1494 MF.Add(W); 
1495 TopoDS_Face F = MF; 
1496 ~~~~~
1497
1498 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. 
1499
1500 If there is no  parametric curve for an edge of the wire on the Face it is computed by  projection. 
1501
1502 For one wire, a simple  syntax is provided to construct the face from the surface and the wire. The  above lines could be written: 
1503
1504 ~~~~~
1505 TopoDS_Face F = BRepBuilderAPI_MakeFace(C,W); 
1506 ~~~~~
1507
1508 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*.
1509
1510 ~~~~~
1511 #include <TopoDS_Face.hxx> 
1512 #include <TColgp_Array1OfPnt.hxx> 
1513 #include <BRepBuilderAPI_MakePolygon.hxx> 
1514 #include <BRepBuilderAPI_MakeFace.hxx> 
1515
1516 TopoDS_Face PolygonalFace(const TColgp_Array1OfPnt&  thePnts) 
1517
1518 BRepBuilderAPI_MakePolygon MP; 
1519 for(Standard_Integer i=thePnts.Lower(); 
1520 i<=thePnts.Upper(); i++) 
1521
1522 MP.Add(thePnts(i)); 
1523
1524 MP.Close(); 
1525 TopoDS_Face F = BRepBuilderAPI_MakeFace(MP.Wire()); 
1526 return F; 
1527
1528 ~~~~~
1529
1530 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: 
1531
1532 ~~~~~
1533 TopoDS_Face F = ...; // a face 
1534 TopoDS_Wire W = ...; // a wire 
1535 F = BRepBuilderAPI_MakeFace(F,W); 
1536 ~~~~~
1537
1538 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. 
1539
1540 @subsubsection occt_modalg_3_5_3 Error status
1541
1542 The *Error* method returns  an error status, which is a term from the *BRepBuilderAPI_FaceError* enumeration. 
1543
1544 * *FaceDone* - no  error occurred. 
1545 * *NoFace* - no initialization of the algorithm; an empty constructor was used. 
1546 * *NotPlanar* - no  surface was given and the wire was not planar. 
1547 * *CurveProjectionFailed* - no curve was found  in the parametric space of the surface for an edge. 
1548 * *ParametersOutOfRange* - the parameters  *umin, umax, vmin, vmax* are out of the surface. 
1549
1550 @subsection occt_modalg_3_6 Wire
1551 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. 
1552
1553 Up to four edges can be used directly, for example: 
1554
1555 ~~~~~
1556 TopoDS_Wire W = BRepBuilderAPI_MakeWire(E1,E2,E3,E4); 
1557 ~~~~~
1558
1559 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). 
1560
1561 ~~~~~
1562 TopTools_Array1OfShapes theEdges; 
1563 BRepBuilderAPI_MakeWire MW; 
1564 for (Standard_Integer i = theEdge.Lower(); 
1565 i <= theEdges.Upper(); i++) 
1566 MW.Add(TopoDS::Edge(theEdges(i)); 
1567 TopoDS_Wire W = MW; 
1568 ~~~~~
1569
1570 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: 
1571
1572 ~~~~~
1573 #include <TopoDS_Wire.hxx> 
1574 #include <BRepBuilderAPI_MakeWire.hxx> 
1575
1576 TopoDS_Wire MergeWires (const TopoDS_Wire& W1, 
1577 const  TopoDS_Wire& W2) 
1578
1579 BRepBuilderAPI_MakeWire MW(W1); 
1580 MW.Add(W2); 
1581 return MW; 
1582
1583 ~~~~~
1584
1585 *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. 
1586
1587 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. 
1588
1589 The Error method returns  a term of the *BRepBuilderAPI_WireError* enumeration: 
1590 *WireDone* - no  error occurred. 
1591 *EmptyWire* - no  initialization of the algorithm, an empty constructor was used. 
1592 *DisconnectedWire* - the last added edge was not connected to the wire. 
1593 *NonManifoldWire* - the  wire with some singularity. 
1594
1595 @subsection occt_modalg_3_7 Shell
1596 The shell is a composite shape built not from a geometry, but by the assembly of faces.
1597 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. 
1598
1599 @subsection occt_modalg_3_8 Solid
1600 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. 
1601
1602
1603 @section occt_modalg_3b Object Modification
1604
1605 @subsection occt_modalg_3b_1 Transformation
1606 *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. 
1607
1608 The following example  deals with the rotation of shapes. 
1609
1610 ~~~~~
1611
1612 TopoDS_Shape myShape1 = ...; 
1613 // The original shape 1 
1614 TopoDS_Shape myShape2 = ...; 
1615 // The original shape2 
1616 gp_Trsf T; 
1617 T.SetRotation(gp_Ax1(gp_Pnt(0.,0.,0.),gp_Vec(0.,0.,1.)), 
1618 2.*PI/5.); 
1619 BRepBuilderAPI_Transformation theTrsf(T); 
1620 theTrsf.Perform(myShape1); 
1621 TopoDS_Shape myNewShape1 = theTrsf.Shape() 
1622 theTrsf.Perform(myShape2,Standard_True); 
1623 // Here duplication is forced 
1624 TopoDS_Shape myNewShape2 = theTrsf.Shape() 
1625 ~~~~~
1626
1627 @subsection occt_modalg_3b_2 Duplication
1628
1629 Use the  *BRepBuilderAPI_Copy* class to duplicate a shape. A new shape is thus created. 
1630 In the following example, a  solid is copied: 
1631
1632 ~~~~~
1633 TopoDS Solid MySolid; 
1634 ....// Creates a solid 
1635
1636 TopoDS_Solid myCopy = BRepBuilderAPI_Copy(mySolid); 
1637 ~~~~~
1638
1639
1640 @section occt_modalg_4 Primitives
1641
1642 The <i> BRepPrimAPI</i> package provides an API (Application Programming Interface) for construction of primitives such as:
1643     * Boxes;
1644     * Cones;
1645     * Cylinders;
1646     * Prisms.
1647
1648 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.
1649
1650   * Construction by sweeping along a profile:
1651     * Linear;
1652     * Rotational (through an angle of rotation).
1653
1654 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:
1655   * Vertices generate Edges
1656   * Edges generate Faces.
1657   * Wires generate Shells.
1658   * Faces generate Solids.
1659   * Shells generate Composite Solids.
1660
1661 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.
1662
1663 @subsection occt_modalg_4_1 Making  Primitives
1664 @subsubsection occt_modalg_4_1_1 Box
1665
1666 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: 
1667
1668 * 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>. 
1669 * From a point and three  dimensions. The same as above but the point is the new origin. 
1670 * From two points, the box  is parallel to the axes and extends on the intervals defined by the coordinates  of the two points. 
1671 * 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. 
1672
1673 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: 
1674 ~~~~~
1675 TopoDS_Solid theBox = BRepPrimAPI_MakeBox(10.,20.,30.); 
1676 ~~~~~
1677
1678 The four methods to build a box are shown in the figure: 
1679
1680 @image html /user_guides/modeling_algos/images/modeling_algos_image026.png  "Making Boxes"
1681 @image latex /user_guides/modeling_algos/images/modeling_algos_image026.png  "Making Boxes"
1682
1683 @subsubsection occt_modalg_4_1_2 Wedge
1684 *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. 
1685
1686 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*. 
1687
1688 The first method is a  particular case of the second with *xmin = 0, xmax = ltx, zmin = 0, zmax = dz*. 
1689 To make a centered  pyramid you can use *xmin = xmax = dx / 2, zmin = zmax = dz / 2*. 
1690
1691 @image html /user_guides/modeling_algos/images/modeling_algos_image027.png "Making Wedges"
1692 @image latex /user_guides/modeling_algos/images/modeling_algos_image027.png "Making Wedges"
1693
1694 @subsubsection occt_modalg_4_1_3 Rotation object
1695 *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. 
1696
1697 The particular  constructions of these primitives are described, but they all have some common  arguments, which are: 
1698
1699   * A system of coordinates,  where the Z axis is the rotation axis..
1700   * An angle in the range  [0,2*PI].
1701   * A vmin, vmax parameter range  on the curve.
1702
1703 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. 
1704
1705 @image html /user_guides/modeling_algos/images/modeling_algos_image028.png  "MakeOneAxis  arguments"
1706 @image latex /user_guides/modeling_algos/images/modeling_algos_image028.png  "MakeOneAxis  arguments"
1707
1708 @subsubsection occt_modalg_4_1_4 Cylinder
1709 *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: 
1710
1711   * Radius and height, to build a  full cylinder.
1712   * Radius, height and angle to  build a portion of a cylinder.
1713
1714 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*. 
1715
1716 ~~~~~
1717
1718 Standard_Real X = 20, Y = 10, Z = 15, R = 10, DY = 30; 
1719 // Make the system of coordinates 
1720 gp_Ax2 axes = gp::ZOX(); 
1721 axes.Translate(gp_Vec(X,Y,Z)); 
1722 TopoDS_Face F = 
1723 BRepPrimAPI_MakeCylinder(axes,R,DY,PI/2.); 
1724 ~~~~~
1725 @image html /user_guides/modeling_algos/images/modeling_algos_image029.png  "Cylinder"
1726 @image latex /user_guides/modeling_algos/images/modeling_algos_image029.png  "Cylinder"
1727
1728 @subsubsection occt_modalg_4_1_5 Cone
1729 *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: 
1730
1731   * Two radii and height, to  build a full cone. One of the radii can be null to make a sharp cone.
1732   * Radii, height and angle to  build a truncated cone.
1733
1734 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*. 
1735
1736 ~~~~~
1737 Standard_Real R1 = 30, R2 = 10, H = 15; 
1738 TopoDS_Solid S = BRepPrimAPI_MakeCone(R1,R2,H); 
1739 ~~~~~
1740
1741 @image html /user_guides/modeling_algos/images/modeling_algos_image030.png "Cone"
1742 @image latex /user_guides/modeling_algos/images/modeling_algos_image030.png "Cone"
1743
1744 @subsubsection occt_modalg_4_1_6 Sphere
1745 *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: 
1746
1747   * From a radius - builds a full  sphere. 
1748   * From a radius and an angle - builds  a lune (digon).
1749   * 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>. 
1750   * From a radius and three angles - a combination of two previous methods builds a portion of spherical segment. 
1751
1752 The following code  builds four spheres from a radius and three angles. 
1753
1754 ~~~~~
1755 Standard_Real R = 30, ang = 
1756         PI/2, a1 = -PI/2.3,  a2 = PI/4; 
1757 TopoDS_Solid S1 = BRepPrimAPI_MakeSphere(R); 
1758 TopoDS_Solid S2 = BRepPrimAPI_MakeSphere(R,ang); 
1759 TopoDS_Solid S3 = BRepPrimAPI_MakeSphere(R,a1,a2); 
1760 TopoDS_Solid S4 = BRepPrimAPI_MakeSphere(R,a1,a2,ang); 
1761 ~~~~~
1762
1763 Note that we could  equally well choose to create Shells instead of Solids. 
1764
1765 @image html /user_guides/modeling_algos/images/modeling_algos_image031.png  "Examples of  Spheres"
1766 @image latex /user_guides/modeling_algos/images/modeling_algos_image031.png  "Examples of  Spheres"
1767
1768
1769 @subsubsection occt_modalg_4_1_7 Torus
1770 *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: 
1771
1772   * Two radii - builds a full  torus.
1773   * Two radii and an angle - builds  an angular torus segment.
1774   * 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. 
1775   * Two radii and three angles - a combination of two previous methods builds a portion of torus segment.
1776
1777 @image html /user_guides/modeling_algos/images/modeling_algos_image032.png "Examples of Tori"
1778 @image latex /user_guides/modeling_algos/images/modeling_algos_image032.png "Examples of Tori"
1779
1780 The following code  builds four toroidal shells from two radii and three angles. 
1781
1782 ~~~~~
1783 Standard_Real R1 = 30, R2 = 10, ang = PI, a1 = 0, 
1784         a2 = PI/2; 
1785 TopoDS_Shell S1 = BRepPrimAPI_MakeTorus(R1,R2); 
1786 TopoDS_Shell S2 = BRepPrimAPI_MakeTorus(R1,R2,ang); 
1787 TopoDS_Shell S3 = BRepPrimAPI_MakeTorus(R1,R2,a1,a2); 
1788 TopoDS_Shell S4 = 
1789         BRepPrimAPI_MakeTorus(R1,R2,a1,a2,ang); 
1790 ~~~~~
1791
1792 Note that we could  equally well choose to create Solids instead of Shells. 
1793
1794 @subsubsection occt_modalg_4_1_8 Revolution
1795 *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. 
1796
1797 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: 
1798
1799   * From a curve, use the full  curve and make a full rotation.
1800   * From a curve and an angle of  rotation.
1801   * From a curve and two  parameters to trim the curve. The two parameters must be growing and within the  curve range.
1802   * From a curve, two parameters,  and an angle. The two parameters must be growing and within the curve range.
1803
1804
1805 @subsection occt_modalg_4_2 Sweeping:  Prism, Revolution and Pipe
1806 @subsubsection occt_modalg_4_2_1 Sweeping
1807
1808 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: 
1809
1810   * Vertices generate Edges
1811   * Edges generate Faces.
1812   * Wires generate Shells.
1813   * Faces generate Solids.
1814   * Shells generate Composite Solids
1815
1816 It is forbidden to sweep  Solids and Composite Solids. A Compound generates a Compound with the sweep of  all its elements. 
1817
1818 @image html /user_guides/modeling_algos/images/modeling_algos_image033.png "Generating a  sweep"
1819 @image latex /user_guides/modeling_algos/images/modeling_algos_image033.png "Generating a  sweep"
1820
1821 *BRepPrimAPI_MakeSweep class* is a deferred class used as a root of the the following sweep classes:
1822 * *BRepPrimAPI_MakePrism* - produces a linear sweep
1823 * *BRepPrimAPI_MakeRevol* - produces a rotational sweep
1824 * *BRepPrimAPI_MakePipe* - produces a general sweep. 
1825
1826
1827 @subsubsection occt_modalg_4_2_2 Prism
1828 *BRepPrimAPI_MakePrism* class allows creating a linear **prism** from a shape and a vector or a direction. 
1829 * A vector allows creating a finite  prism;
1830 * 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). 
1831
1832 The following code creates a finite, an infinite and a semi-infinite solid using a face, a  direction and a length. 
1833
1834 ~~~~~
1835 TopoDS_Face F = ..; // The swept face 
1836 gp_Dir direc(0,0,1); 
1837 Standard_Real l = 10; 
1838 // create a vector from the direction and the length 
1839 gp_Vec v = direc; 
1840 v *= l; 
1841 TopoDS_Solid P1 = BRepPrimAPI_MakePrism(F,v); 
1842 // finite 
1843 TopoDS_Solid P2 = BRepPrimAPI_MakePrism(F,direc); 
1844 // infinite 
1845 TopoDS_Solid P3 =  BRepPrimAPI_MakePrism(F,direc,Standard_False); 
1846 // semi-infinite 
1847 ~~~~~
1848
1849 @image html /user_guides/modeling_algos/images/modeling_algos_image034.png   "Finite, infinite, and semi-infinite prisms"
1850 @image latex /user_guides/modeling_algos/images/modeling_algos_image034.png   "Finite, infinite, and semi-infinite prisms"
1851
1852 @subsubsection occt_modalg_4_2_3 Rotational Sweep 
1853 *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. 
1854
1855 *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.
1856
1857 ~~~~~
1858 TopoDS_Face F = ...; // the profile 
1859 gp_Ax1 axis(gp_Pnt(0,0,0),gp_Dir(0,0,1)); 
1860 Standard_Real ang = PI/3; 
1861 TopoDS_Solid R1 = BRepPrimAPI_MakeRevol(F,axis); 
1862 // Full revol 
1863 TopoDS_Solid R2 = BRepPrimAPI_MakeRevol(F,axis,ang); 
1864 ~~~~~
1865
1866 @image html /user_guides/modeling_algos/images/modeling_algos_image035.png "Full and partial  rotation"
1867 @image latex /user_guides/modeling_algos/images/modeling_algos_image035.png "Full and partial  rotation"
1868
1869 @section occt_modalg_5 Boolean  Operations
1870
1871 Boolean operations are  used to create new shapes from the combinations of two shapes. 
1872
1873 | Operation | Result |
1874 | :---- | :------ |
1875 | Fuse   |  all points in S1 or S2  |
1876 | Common |  all points in S1 and S2 |
1877 | Cut S1 by S2| all points in S1 and not in S2 | 
1878
1879 @image html /user_guides/modeling_algos/images/modeling_algos_image036.png  "Boolean Operations"
1880 @image latex /user_guides/modeling_algos/images/modeling_algos_image036.png  "Boolean Operations"
1881
1882 From the viewpoint of Topology these are topological operations followed by blending (putting fillets onto edges created after the topological operation).
1883
1884 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.
1885
1886 See @ref occt_user_guides__boolean_operations "Boolean Operations" for detailed documentation.
1887
1888 @subsection occt_modalg_5_1 Input and Result Arguments
1889
1890 Boolean Operations have the following types of the arguments and produce the following results:
1891 * 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;
1892 * 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. 
1893 * 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.
1894 * 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.
1895 * Boolean Operations for COMPSOLID type of shape are not supported.
1896
1897 @subsection occt_modalg_5_2 Implementation
1898
1899 *BRepAlgoAPI_BooleanOperation* class is the deferred root class for Boolean  operations.
1900
1901 #### Fuse
1902
1903 *BRepAlgoAPI_Fuse* performs the Fuse operation. 
1904
1905 ~~~~~
1906 TopoDS_Shape A = ..., B = ...; 
1907 TopoDS_Shape S = BRepAlgoAPI_Fuse(A,B); 
1908 ~~~~~
1909
1910 #### Common
1911
1912 *BRepAlgoAPI_Common*  performs the Common operation. 
1913
1914 ~~~~~
1915 TopoDS_Shape A = ..., B = ...; 
1916 TopoDS_Shape S = BRepAlgoAPI_Common(A,B); 
1917 ~~~~~
1918
1919 #### Cut
1920 *BRepAlgoAPI_Cut* performs the Cut operation. 
1921
1922 ~~~~~
1923 TopoDS_Shape A = ..., B = ...; 
1924 TopoDS_Shape S = BRepAlgoAPI_Cut(A,B); 
1925 ~~~~~
1926
1927 #### Section
1928
1929 *BRepAlgoAPI_Section* performs the section, described as a *TopoDS_Compound* made of *TopoDS_Edge*. 
1930
1931 @image html /user_guides/modeling_algos/images/modeling_algos_image037.png "Section  operation"
1932 @image latex /user_guides/modeling_algos/images/modeling_algos_image037.png "Section  operation"
1933
1934 ~~~~~
1935 TopoDS_Shape A = ...,  TopoDS_ShapeB = ...; 
1936 TopoDS_Shape S =  BRepAlgoAPI_Section(A,B); 
1937 ~~~~~
1938
1939 @section occt_modalg_6 Fillets and  Chamfers
1940
1941 This library provides algorithms to make fillets and chamfers on shape edges.
1942 The following cases are addressed:
1943
1944   * Corners and apexes with different radii; 
1945   * Corners and apexes with different concavity. 
1946
1947 If there is a concavity, both surfaces that need to be extended and those, which do not, are processed.
1948
1949 @subsection occt_modalg_6_1 Fillets  
1950 @subsection occt_modalg_6_1_1 Fillet on shape
1951
1952 A fillet is a smooth  face replacing a sharp edge.
1953
1954 *BRepFilletAPI_MakeFillet* class allows filleting a shape.  
1955
1956 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.
1957
1958 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. 
1959
1960 @image html /user_guides/modeling_algos/images/modeling_algos_image038.png "Filleting two edges using radii r1 and  r2."
1961 @image latex /user_guides/modeling_algos/images/modeling_algos_image038.png "Filleting two edges using radii r1 and  r2."
1962
1963 In the following example  a filleted box with dimensions a,b,c and radius r is created. 
1964
1965 ### Constant  radius 
1966
1967
1968 ~~~~~
1969 #include <TopoDS_Shape.hxx> 
1970 #include <TopoDS.hxx> 
1971 #include <BRepPrimAPI_MakeBox.hxx> 
1972 #include <TopoDS_Solid.hxx> 
1973 #include <BRepFilletAPI_MakeFillet.hxx> 
1974 #include <TopExp_Explorer.hxx> 
1975
1976 TopoDS_Shape FilletedBox(const Standard_Real a, 
1977                                                 const Standard_Real  b, 
1978                                                 const Standard_Real  c, 
1979                                                 const Standard_Real  r) 
1980
1981         TopoDS_Solid Box =  BRepPrimAPI_MakeBox(a,b,c); 
1982         BRepFilletAPI_MakeFillet  MF(Box); 
1983
1984         // add all the edges  to fillet 
1985         TopExp_Explorer  ex(Box,TopAbs_EDGE); 
1986         while (ex.More()) 
1987         { 
1988         MF.Add(r,TopoDS::Edge(ex.Current())); 
1989         ex.Next(); 
1990         } 
1991         return MF.Shape(); 
1992         } 
1993 ~~~~~
1994
1995 @image html /user_guides/modeling_algos/images/modeling_algos_image039.png "Fillet with constant radius"
1996 @image latex /user_guides/modeling_algos/images/modeling_algos_image039.png "Fillet with constant radius"
1997
1998 #### Changing radius
1999
2000
2001 ~~~~~
2002 void CSampleTopologicalOperationsDoc::OnEvolvedblend1() 
2003
2004         TopoDS_Shape theBox  = BRepPrimAPI_MakeBox(200,200,200); 
2005
2006         BRepFilletAPI_MakeFillet  Rake(theBox); 
2007         ChFi3d_FilletShape  FSh = ChFi3d_Rational; 
2008         Rake.SetFilletShape(FSh); 
2009
2010         TColgp_Array1OfPnt2d  ParAndRad(1, 6); 
2011         ParAndRad(1).SetCoord(0.,  10.); 
2012         ParAndRad(1).SetCoord(50.,  20.); 
2013         ParAndRad(1).SetCoord(70.,  20.); 
2014         ParAndRad(1).SetCoord(130.,  60.); 
2015         ParAndRad(1).SetCoord(160.,  30.); 
2016         ParAndRad(1).SetCoord(200.,  20.); 
2017
2018         TopExp_Explorer  ex(theBox,TopAbs_EDGE); 
2019         Rake.Add(ParAndRad, TopoDS::Edge(ex.Current())); 
2020         TopoDS_Shape  evolvedBox = Rake.Shape(); 
2021
2022 ~~~~~
2023
2024 @image html /user_guides/modeling_algos/images/modeling_algos_image040.png      "Fillet with changing radius"
2025 @image latex /user_guides/modeling_algos/images/modeling_algos_image040.png     "Fillet with changing radius"
2026  
2027 @subsection occt_modalg_6_1_2 Chamfer
2028
2029 A chamfer is a rectilinear edge  replacing a sharp vertex of the face.
2030
2031 The use of *BRepFilletAPI_MakeChamfer* class is similar to the use of  *BRepFilletAPI_MakeFillet*, except for the following: 
2032 * The surfaces created are  ruled and not smooth. 
2033 * The *Add* syntax for  selecting edges requires one or two distances, one edge and one face  (contiguous to the edge).
2034
2035 ~~~~~ 
2036 Add(dist,  E, F) 
2037 Add(d1,  d2, E, F) with d1 on the face F. 
2038 ~~~~~
2039
2040 @image html /user_guides/modeling_algos/images/modeling_algos_image041.png      "Chamfer"
2041 @image latex /user_guides/modeling_algos/images/modeling_algos_image041.png     "Chamfer"
2042
2043 @subsection occt_modalg_6_1_3 Fillet on a planar face
2044
2045 *BRepFilletAPI_MakeFillet2d* class allows constructing fillets and chamfers on planar faces. 
2046 To create a fillet on planar face: define it, indicate, which vertex is  to be deleted, and give the fillet radius with *AddFillet* method. 
2047
2048 A chamfer can be calculated with *AddChamfer* method. It can be  described by 
2049   * two edges and two distances
2050   * one edge, one vertex, one  distance and one angle.
2051 Fillets and chamfers are calculated when addition is  complete. 
2052
2053 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: 
2054 ~~~~~
2055 BRepFilletAPI_MakeFillet2d builder; 
2056 builder.Init(F1,F2); 
2057 ~~~~~
2058
2059 Planar Fillet
2060 -------------
2061
2062 ~~~~~
2063 #include “BRepPrimAPI_MakeBox.hxx” 
2064 #include “TopoDS_Shape.hxx” 
2065 #include “TopExp_Explorer.hxx” 
2066 #include “BRepFilletAPI_MakeFillet2d.hxx” 
2067 #include “TopoDS.hxx” 
2068 #include “TopoDS_Solid.hxx” 
2069
2070 TopoDS_Shape FilletFace(const Standard_Real a, 
2071                                                 const Standard_Real  b, 
2072                                                 const Standard_Real c, 
2073                                                 const Standard_Real  r) 
2074
2075
2076         TopoDS_Solid Box =  BRepPrimAPI_MakeBox (a,b,c); 
2077         TopExp_Explorer  ex1(Box,TopAbs_FACE); 
2078
2079         const  TopoDS_Face& F = TopoDS::Face(ex1.Current()); 
2080         BRepFilletAPI_MakeFillet2d  MF(F); 
2081         TopExp_Explorer  ex2(F, TopAbs_VERTEX); 
2082         while (ex2.More()) 
2083         { 
2084         MF.AddFillet(TopoDS::Vertex(ex2.Current()),r); 
2085         ex2.Next(); 
2086         } 
2087         // while... 
2088         return MF.Shape(); 
2089
2090 ~~~~~
2091
2092 @section occt_modalg_7 Offsets, Drafts, Pipes and Evolved shapes
2093
2094 These classes provide the following services:
2095
2096   * Creation of offset shapes and their variants such as: 
2097     * Hollowing; 
2098     * Shelling; 
2099     * Lofting; 
2100   * Creation of tapered shapes using draft angles;
2101   * Creation of sweeps.
2102   
2103 @subsection occt_modalg_7_1 Shelling 
2104
2105 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. 
2106
2107 The constructor *BRepOffsetAPI_MakeThickSolid* shelling operator takes the solid, the list of faces to remove and an offset value as input.
2108
2109 ~~~~~
2110 TopoDS_Solid SolidInitial = ...;
2111
2112 Standard_Real                   Of              = ...;
2113 TopTools_ListOfShape    LCF;
2114 TopoDS_Shape                    Result;
2115 Standard_Real                   Tol = Precision::Confusion();
2116
2117 for (Standard_Integer i = 1 ;i <= n; i++) {
2118         TopoDS_Face SF = ...; // a face from SolidInitial
2119         LCF.Append(SF);
2120 }
2121
2122 Result = BRepOffsetAPI_MakeThickSolid   (SolidInitial,
2123                                                                                 LCF,
2124                                                                                 Of,
2125                                                                                 Tol);
2126 ~~~~~
2127
2128 @image html /user_guides/modeling_algos/images/modeling_algos_image042.png      "Shelling"
2129 @image latex /user_guides/modeling_algos/images/modeling_algos_image042.png     "Shelling"
2130
2131
2132 @subsection occt_modalg_7_2  Draft Angle
2133
2134 *BRepOffsetAPI_DraftAngle* class allows modifying a shape by applying draft angles to its planar, cylindrical and conical faces. 
2135
2136
2137 The class is created or  initialized from a shape, then faces to be modified are added; for each face,  three arguments are used: 
2138   * Direction: the direction with  which the draft angle is measured
2139   * Angle: value of the angle
2140   * Neutral plane: intersection  between the face and the neutral plane is invariant.
2141
2142 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: 
2143
2144 ~~~~~
2145 TopoDS_Shape myShape = ... 
2146 // The original shape 
2147 TopTools_ListOfShape ListOfFace; 
2148 // Creation of the list of faces to be modified 
2149 ... 
2150
2151 gp_Dir Direc(0.,0.,1.); 
2152 // Z direction 
2153 Standard_Real Angle = 5.*PI/180.; 
2154 // 5 degree angle 
2155 gp_Pln Neutral(gp_Pnt(0.,0.,5.), Direc); 
2156 // Neutral plane Z=5 
2157 BRepOffsetAPI_DraftAngle theDraft(myShape); 
2158 TopTools_ListIteratorOfListOfShape itl; 
2159 for (itl.Initialize(ListOfFace); itl.More(); itl.Next())  { 
2160         theDraft.Add(TopoDS::Face(itl.Value()),Direc,Angle,Neutral); 
2161         if  (!theDraft.AddDone()) { 
2162                 // An error has occurred. The faulty face is given by //  ProblematicShape 
2163                 break; 
2164                 } 
2165
2166 if (!theDraft.AddDone()) { 
2167         // An error has  occurred 
2168         TopoDS_Face guilty =  theDraft.ProblematicShape(); 
2169         ... 
2170
2171 theDraft.Build(); 
2172 if (!theDraft.IsDone()) { 
2173         // Problem  encountered during reconstruction 
2174         ... 
2175
2176 else { 
2177         TopoDS_Shape  myResult = theDraft.Shape(); 
2178         ... 
2179
2180 ~~~~~
2181
2182 @image html /user_guides/modeling_algos/images/modeling_algos_image043.png  "DraftAngle"
2183 @image latex /user_guides/modeling_algos/images/modeling_algos_image043.png  "DraftAngle"
2184
2185 @subsection occt_modalg_7_3 Pipe  Constructor
2186
2187 *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. 
2188
2189 The angle between the spine and the profile is preserved throughout the pipe. 
2190
2191 ~~~~~
2192 TopoDS_Wire Spine = ...; 
2193 TopoDS_Shape Profile = ...; 
2194 TopoDS_Shape Pipe =  BRepOffsetAPI_MakePipe(Spine,Profile); 
2195 ~~~~~
2196
2197 @image html /user_guides/modeling_algos/images/modeling_algos_image044.png "Example of a Pipe"
2198 @image latex /user_guides/modeling_algos/images/modeling_algos_image044.png "Example of a Pipe"
2199
2200 @subsection occt_modalg_7_4 Evolved Solid
2201
2202 *BRepOffsetAPI_MakeEvolved* class allows creating an evolved solid from a Spine (planar face or wire) and a profile (wire). 
2203
2204 The evolved solid is an unlooped sweep generated by the spine and the profile. 
2205
2206 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. 
2207
2208 The reference axes of  the profile can be defined following two distinct modes: 
2209
2210 * The reference axes of the  profile are the origin axes. 
2211 * The references axes of  the profile are calculated as follows: 
2212   + the origin is given by the  point on the spine which is the closest to the profile
2213   + the X axis is given by the  tangent to the spine at the point defined above
2214   + the Z axis is the normal to  the plane which contains the spine.
2215
2216 ~~~~~
2217 TopoDS_Face Spine = ...; 
2218 TopoDS_Wire Profile = ...; 
2219 TopoDS_Shape Evol = 
2220 BRepOffsetAPI_MakeEvolved(Spine,Profile); 
2221 ~~~~~
2222
2223 @section occt_modalg_8 Sewing
2224
2225 @subsection occt_modalg_8_1 Introduction
2226
2227 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. 
2228
2229 @image html /user_guides/modeling_algos/images/modeling_algos_image045.png "Shapes with partially shared edges"
2230 @image latex /user_guides/modeling_algos/images/modeling_algos_image045.png "Shapes with partially shared edges"
2231
2232 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.
2233
2234 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.
2235
2236 Let us define several terms:
2237 * **Floating edges** do not belong to any face;
2238 * **Free boundaries** belong to one face only;
2239 * **Shared edges** belong to several faces, (i.e. two faces in a manifold topology).
2240 * **Sewn faces** should have edges shared with each other.
2241 * **Sewn edges** should have vertices shared with each other.
2242
2243 @subsection occt_modalg_8_2 Sewing Algorithm
2244
2245 The sewing algorithm is one of the basic algorithms used for shape processing, therefore its quality is very important.
2246
2247 Sewing algorithm is implemented in the class *BRepBuilder_Sewing*. This class provides the following methods: 
2248 * loading initial data for global or local sewing; 
2249 * setting customization parameters, such as special operation modes, tolerances and output results;
2250 * applying analysis methods that can be used to obtain connectivity data required by external algorithms;
2251 * sewing of the loaded shapes. 
2252
2253 Sewing supports working mode with big value tolerance. It is not necessary to repeat sewing step by step while smoothly increasing tolerance.
2254
2255 It is also possible to sew edges to wire and to sew locally separate faces and edges from a shape.
2256
2257 The Sewing algorithm can be subdivided into several independent stages, some of which can be turned on or off using Boolean or other flags. 
2258
2259 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.
2260
2261 Each stage of the algorithm or the whole algorithm can be adjusted with the following parameters: 
2262 * **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.
2263 * **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.
2264 * **Non-manifold mode** enables sewing of non-manifold topology. 
2265
2266 #### Example
2267
2268 To connect a set of *n* contiguous but independent faces, do the following: 
2269
2270 ~~~~~
2271     BRepBuilderAPI_Sewing Sew;
2272     Sew.Add(Face1); 
2273     Sew.Add(Face2); 
2274     ...
2275     Sew.Add(Facen); 
2276     Sew.Perform();
2277     TopoDS_Shape result= Sew.SewedShape();
2278 ~~~~~
2279
2280 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.
2281
2282 @subsection occt_modalg_8_3 Tolerance Management
2283
2284 To produce a closed shell, Sewing allows specifying the value of working tolerance, exceeding the size of small faces belonging to the shape.
2285
2286 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).
2287
2288 The following recommendations can be proposed for tuning-up the sewing process:
2289 - 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.
2290 - Use as large minimal tolerance as possible. This will reduce the number of small geometry in the shape, both original and appearing after cutting.
2291 - 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.
2292 - 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.
2293
2294 @subsection occt_modalg_8_4 Manifold and Non-manifold Sewing
2295
2296 To create one or several shells from a set of faces, sewing merges edges, which belong to different faces or one closed face. 
2297
2298 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.
2299
2300 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.
2301
2302 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. 
2303
2304 Giving a large tolerance value to non manifold sewing will cause a lot of incorrectness since all nearby geometry will be sewn.
2305
2306 @subsection occt_modalg_8_5 Local Sewing
2307
2308 If a shape still has some non-sewn faces or edges after sewing, it is possible to use local sewing with a greater tolerance.
2309
2310 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.
2311
2312 All preexisting connections of the whole shape are kept after local sewing. 
2313
2314 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()*.
2315
2316 See the example:
2317
2318 ~~~~
2319
2320 //initial sewn shapes
2321 TopoDS_Shape aS1, aS2;  // these shapes are expected to be well sewn shells
2322 TopoDS_Shape aComp;
2323 BRep_Builder aB;
2324 aB.MakeCompound(aComp);
2325 aB.Add(aComp, aS1);
2326 aB.Add(aComp, aS2);
2327 ................................
2328 aSewing.Load(aComp);
2329
2330 //sub shapes which should be locally sewed
2331 aSewing.Add(aF1);
2332 aSewing.Add(aF2);
2333 //performing sewing
2334 aSewing.Perform();
2335 //result shape
2336 TopoDS_Shape aRes = aSewing.SewedShape();
2337
2338 ~~~~
2339
2340 @section occt_modalg_9 Features
2341
2342 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. 
2343
2344 @subsection occt_modalg_9_1 Form Features
2345
2346 The form features are depressions or protrusions including the following types:
2347
2348   * Cylinder;
2349   * Draft Prism;
2350   * Prism;
2351   * Revolved feature;
2352   * Pipe.
2353
2354 Depending on whether you wish to make a depression or a protrusion, 
2355 you can choose either to remove matter (Boolean cut: Fuse equal to 0) or to add it (Boolean fusion: Fuse equal to 1).
2356
2357 The semantics of form feature creation is based on the construction of shapes:
2358
2359   * for a certain length in a certain direction;
2360   * up to the limiting face;
2361   * from the limiting face at a height;
2362   * above and/or below a plane.
2363
2364 The shape defining the construction of a feature can be either a supporting edge or a concerned area of a face.
2365
2366 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 
2367 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.
2368
2369 Topological definition with local operations of this sort makes calculations simpler 
2370 and faster than a global operation. The latter would entail a second phase 
2371 of removing unwanted matter to get the same result.
2372
2373 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. 
2374
2375 @subsubsection occt_modalg_9_1_1 Prism
2376
2377 The class *BRepFeat_MakePrism* is used to build a prism interacting with a shape. It is created  or initialized from 
2378   * a shape (the basic shape),
2379   * the base of the prism,
2380   * 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),
2381   * a direction,
2382   * a Boolean indicating the type  of operation (fusion=protrusion or cut=depression) on the basic shape,
2383   * another Boolean indicating if  the self-intersections have to be found (not used in every case).
2384
2385 There are six Perform  methods: 
2386 | Method | Description |
2387 | :---------------------- | :------------------------------------- |
2388 | *Perform(Height)*       | The  resulting prism is of the given length. |
2389 | *Perform(Until)*        | The  prism is defined between the position of the base and the given face. |
2390 | *Perform(From, Until)*  | The  prism is defined between the two faces From and Until. |
2391 | *PerformUntilEnd()*     | The  prism is semi-infinite, limited by the actual position of the base. |
2392 | *PerformFromEnd(Until)* | The  prism is semi-infinite, limited by the face Until. |
2393 | *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. |
2394
2395 **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.
2396
2397 In the following  sequence, a protrusion is performed, i.e. a face of the shape is changed into a  prism. 
2398
2399 ~~~~~
2400 TopoDS_Shape Sbase = ...;  // an initial shape 
2401 TopoDS_Face Fbase = ....; // a base of prism 
2402
2403 gp_Dir Extrusion (.,.,.); 
2404
2405 // An empty face is given as the sketch face 
2406
2407 BRepFeat_MakePrism thePrism(Sbase, Fbase, TopoDS_Face(),  Extrusion, Standard_True, Standard_True); 
2408
2409 thePrism, Perform(100.); 
2410 if (thePrism.IsDone()) { 
2411         TopoDS_Shape  theResult = thePrism; 
2412         ... 
2413
2414 ~~~~~
2415
2416 @image html /user_guides/modeling_algos/images/modeling_algos_image047.png  "Fusion with MakePrism"
2417 @image latex /user_guides/modeling_algos/images/modeling_algos_image047.png  "Fusion with MakePrism"
2418
2419 @image html /user_guides/modeling_algos/images/modeling_algos_image048.png  "Creating a  prism between two faces with Perform(From, Until)"
2420 @image latex /user_guides/modeling_algos/images/modeling_algos_image048.png  "Creating a  prism between two faces with Perform(From, Until)"
2421
2422 @subsubsection occt_modalg_9_1_2 Draft Prism
2423
2424 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: 
2425   * a shape (basic shape),
2426   * the base of the prism,
2427   * 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),
2428   * an angle,
2429   * a Boolean indicating the type  of operation (fusion=protrusion or cut=depression) on the basic shape,
2430   * another Boolean indicating if  self-intersections have to be found (not used in every case).
2431   
2432 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. 
2433 The semantics of draft  prism feature creation is based on the construction of shapes: 
2434   * along a length
2435   * up to a limiting face
2436   * from a limiting face to a  height.
2437
2438 The shape defining  construction of the draft prism feature can be either the supporting edge or the concerned area of a face. 
2439
2440 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. 
2441 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 . 
2442
2443 The *Perform* methods are the same as for *MakePrism*. 
2444
2445 ~~~~~
2446 TopoDS_Shape S = BRepPrimAPI_MakeBox(400.,250.,300.); 
2447 TopExp_Explorer Ex; 
2448 Ex.Init(S,TopAbs_FACE); 
2449 Ex.Next(); 
2450 Ex.Next(); 
2451 Ex.Next(); 
2452 Ex.Next(); 
2453 Ex.Next(); 
2454 TopoDS_Face F = TopoDS::Face(Ex.Current()); 
2455 Handle(Geom_Surface) surf = BRep_Tool::Surface(F); 
2456 gp_Circ2d 
2457 c(gp_Ax2d(gp_Pnt2d(200.,130.),gp_Dir2d(1.,0.)),50.); 
2458 BRepBuilderAPI_MakeWire MW; 
2459 Handle(Geom2d_Curve) aline = new Geom2d_Circle(c); 
2460 MW.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,PI)); 
2461 MW.Add(BRepBuilderAPI_MakeEdge(aline,surf,PI,2.*PI)); 
2462 BRepBuilderAPI_MakeFace MKF; 
2463 MKF.Init(surf,Standard_False); 
2464 MKF.Add(MW.Wire()); 
2465 TopoDS_Face FP = MKF.Face(); 
2466 BRepLib::BuildCurves3d(FP); 
2467 BRepFeat_MakeDPrism MKDP (S,FP,F,10*PI180,Standard_True, 
2468                                                         Standard_True); 
2469 MKDP.Perform(200); 
2470 TopoDS_Shape res1 = MKDP.Shape(); 
2471 ~~~~~
2472
2473 @image html /user_guides/modeling_algos/images/modeling_algos_image049.png  "A tapered prism"
2474 @image latex /user_guides/modeling_algos/images/modeling_algos_image049.png  "A tapered prism"
2475
2476 @subsubsection occt_modalg_9_1_3 Revolution
2477
2478 The class *BRepFeat_MakeRevol* is used to build a revolution interacting with a shape. It is created or initialized from:
2479   * a shape (the basic shape,)
2480   * the base of the revolution,
2481   * 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),
2482   * an axis of revolution,
2483   * a boolean indicating the type  of operation (fusion=protrusion or cut=depression) on the basic shape,
2484   * another boolean indicating  whether the self-intersections have to be found (not used in every case).
2485
2486 There are four Perform  methods: 
2487 | Method | Description |
2488 | :--------------- | :------------ |
2489 | *Perform(Angle)*       | The  resulting revolution is of the given magnitude. |
2490 | *Perform(Until)*       | The  revolution is defined between the actual position of the base and the given face. |
2491 | *Perform(From, Until)* | The  revolution is defined between the two faces, From and Until. |
2492 | *PerformThruAll()*     |          The  result is similar to Perform(2*PI). |
2493
2494 **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.
2495
2496
2497 In the following sequence, a face is revolved and  the revolution is limited by a face of the base shape. 
2498
2499 ~~~~~
2500 TopoDS_Shape Sbase = ...;  // an initial shape 
2501 TopoDS_Face Frevol = ....; // a base of prism 
2502 TopoDS_Face FUntil = ....; // face limiting the revol 
2503
2504 gp_Dir RevolDir (.,.,.); 
2505 gp_Ax1 RevolAx(gp_Pnt(.,.,.), RevolDir); 
2506
2507 // An empty face is given as the sketch face 
2508
2509 BRepFeat_MakeRevol theRevol(Sbase, Frevol, TopoDS_Face(), RevolAx,  Standard_True, Standard_True); 
2510
2511 theRevol.Perform(FUntil); 
2512 if (theRevol.IsDone()) { 
2513         TopoDS_Shape  theResult = theRevol; 
2514         ... 
2515
2516 ~~~~~
2517
2518 @subsubsection occt_modalg_9_1_4 Pipe
2519
2520 The class *BRepFeat_MakePipe* constructs compound  shapes with pipe features: depressions or protrusions. A class object is created or initialized from: 
2521   * a shape (basic shape),
2522   * a base face (profile of the  pipe)
2523   * 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),
2524   * a spine wire
2525   * a Boolean indicating the type  of operation (fusion=protrusion or cut=depression) on the basic shape,
2526   * another Boolean indicating if  self-intersections have to be found (not used in every case).
2527
2528 There are three Perform  methods: 
2529 | Method | Description |
2530 | :-------- | :---------- |
2531 | *Perform()*            | The  pipe is defined along the entire path (spine wire)   |
2532 | *Perform(Until)*       | The  pipe is defined along the path until a given face    |
2533 | *Perform(From, Until)* | The  pipe is defined between the two faces From and Until | 
2534
2535 Let us have a look at the example:
2536
2537 ~~~~~
2538 TopoDS_Shape S = BRepPrimAPI_MakeBox(400.,250.,300.); 
2539 TopExp_Explorer Ex; 
2540 Ex.Init(S,TopAbs_FACE); 
2541 Ex.Next(); 
2542 Ex.Next(); 
2543 TopoDS_Face F1 = TopoDS::Face(Ex.Current()); 
2544 Handle(Geom_Surface) surf = BRep_Tool::Surface(F1); 
2545 BRepBuilderAPI_MakeWire MW1; 
2546 gp_Pnt2d p1,p2; 
2547 p1 = gp_Pnt2d(100.,100.); 
2548 p2 = gp_Pnt2d(200.,100.); 
2549 Handle(Geom2d_Line) aline = GCE2d_MakeLine(p1,p2).Value(); 
2550
2551 MW1.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,p1.Distance(p2))); 
2552 p1 = p2; 
2553 p2 = gp_Pnt2d(150.,200.); 
2554 aline = GCE2d_MakeLine(p1,p2).Value(); 
2555
2556 MW1.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,p1.Distance(p2))); 
2557 p1 = p2; 
2558 p2 = gp_Pnt2d(100.,100.); 
2559 aline = GCE2d_MakeLine(p1,p2).Value(); 
2560
2561 MW1.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,p1.Distance(p2))); 
2562 BRepBuilderAPI_MakeFace MKF1; 
2563 MKF1.Init(surf,Standard_False); 
2564 MKF1.Add(MW1.Wire()); 
2565 TopoDS_Face FP = MKF1.Face(); 
2566 BRepLib::BuildCurves3d(FP); 
2567 TColgp_Array1OfPnt CurvePoles(1,3); 
2568 gp_Pnt pt = gp_Pnt(150.,0.,150.); 
2569 CurvePoles(1) = pt; 
2570 pt = gp_Pnt(200.,100.,150.); 
2571 CurvePoles(2) = pt; 
2572 pt = gp_Pnt(150.,200.,150.); 
2573 CurvePoles(3) = pt; 
2574 Handle(Geom_BezierCurve) curve = new Geom_BezierCurve 
2575 (CurvePoles); 
2576 TopoDS_Edge E = BRepBuilderAPI_MakeEdge(curve); 
2577 TopoDS_Wire W = BRepBuilderAPI_MakeWire(E); 
2578 BRepFeat_MakePipe MKPipe (S,FP,F1,W,Standard_False, 
2579 Standard_True); 
2580 MKPipe.Perform(); 
2581 TopoDS_Shape res1 = MKPipe.Shape(); 
2582 ~~~~~
2583
2584 @image html /user_guides/modeling_algos/images/modeling_algos_image050.png  "Pipe depression"
2585 @image latex /user_guides/modeling_algos/images/modeling_algos_image050.png  "Pipe depression"
2586
2587 @subsection occt_modalg_9_2 Mechanical Features
2588
2589 Mechanical features include ribs, protrusions and grooves (or slots), depressions along planar (linear) surfaces or revolution surfaces. 
2590
2591 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. 
2592
2593 The development contexts  differ, however, in the case of mechanical features. 
2594 Here they include  extrusion: 
2595   * to a limiting face of the  basis shape;
2596   * to or from a limiting plane;
2597   * to a height.
2598
2599 A class object is  created or initialized from 
2600   * a shape (basic shape);
2601   * a wire (base of rib or  groove);
2602   * a plane (plane of the wire);
2603   * direction1 (a vector along  which thickness will be built up);
2604   * direction2 (vector opposite  to the previous one along which thickness will be built up, may be null);
2605   * a Boolean indicating the type  of operation (fusion=rib or cut=groove) on the basic shape;
2606   * another Boolean indicating  if self-intersections have to be found (not used in every case).
2607   
2608 @subsubsection occt_modalg_9_2_1 Linear Form
2609   
2610 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)*.  
2611
2612 ~~~~~
2613 BRepBuilderAPI_MakeWire mkw; 
2614 gp_Pnt p1 = gp_Pnt(0.,0.,0.); 
2615 gp_Pnt p2 = gp_Pnt(200.,0.,0.); 
2616 mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); 
2617 p1 = p2; 
2618 p2 = gp_Pnt(200.,0.,50.); 
2619 mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); 
2620 p1 = p2; 
2621 p2 = gp_Pnt(50.,0.,50.); 
2622 mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); 
2623 p1 = p2; 
2624 p2 = gp_Pnt(50.,0.,200.); 
2625 mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); 
2626 p1 = p2; 
2627 p2 = gp_Pnt(0.,0.,200.); 
2628 mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); 
2629 p1 = p2; 
2630 mkw.Add(BRepBuilderAPI_MakeEdge(p2,gp_Pnt(0.,0.,0.))); 
2631 TopoDS_Shape S = BRepBuilderAPI_MakePrism(BRepBuilderAPI_MakeFace 
2632         (mkw.Wire()),gp_Vec(gp_Pnt(0.,0.,0.),gp_P 
2633          nt(0.,100.,0.))); 
2634 TopoDS_Wire W = BRepBuilderAPI_MakeWire(BRepBuilderAPI_MakeEdge(gp_Pnt 
2635         (50.,45.,100.), 
2636 gp_Pnt(100.,45.,50.))); 
2637 Handle(Geom_Plane) aplane = 
2638         new Geom_Plane(gp_Pnt(0.,45.,0.),  gp_Vec(0.,1.,0.)); 
2639 BRepFeat_MakeLinearForm aform(S, W, aplane, gp_Dir 
2640         (0.,5.,0.), gp_Dir(0.,-3.,0.),  1, Standard_True); 
2641 aform.Perform(); 
2642 TopoDS_Shape res = aform.Shape(); 
2643 ~~~~~
2644
2645 @image html /user_guides/modeling_algos/images/modeling_algos_image051.png  "Creating a rib"
2646 @image latex /user_guides/modeling_algos/images/modeling_algos_image051.png  "Creating a rib"
2647
2648 @subsubsection occt_modalg_9_2_3 Gluer
2649
2650 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.
2651
2652 The class is created or  initialized from two shapes: the “glued” shape and the basic shape (on which  the other shape is glued). 
2653 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. 
2654
2655 **Note** that every face and edge has to be  bounded, if two edges of two glued faces are  coincident they must be explicitly bounded.
2656
2657 ~~~~~
2658 TopoDS_Shape Sbase = ...; // the basic shape 
2659 TopoDS_Shape Sglued = ...; // the glued shape 
2660
2661 TopTools_ListOfShape Lfbase; 
2662 TopTools_ListOfShape Lfglued; 
2663 // Determination of the glued faces 
2664 ... 
2665
2666 BRepFeat_Gluer theGlue(Sglue, Sbase); 
2667 TopTools_ListIteratorOfListOfShape itlb(Lfbase); 
2668 TopTools_ListIteratorOfListOfShape itlg(Lfglued); 
2669 for (; itlb.More(); itlb.Next(), itlg(Next()) { 
2670 const TopoDS_Face& f1 = TopoDS::Face(itlg.Value()); 
2671 const TopoDS_Face& f2 = TopoDS::Face(itlb.Value()); 
2672 theGlue.Bind(f1,f2); 
2673 // for example, use the class FindEdges from LocOpe to 
2674 // determine coincident edges 
2675 LocOpe_FindEdge fined(f1,f2); 
2676 for (fined.InitIterator(); fined.More(); fined.Next()) { 
2677 theGlue.Bind(fined.EdgeFrom(),fined.EdgeTo()); 
2678
2679
2680 theGlue.Build(); 
2681 if (theGlue.IsDone() { 
2682 TopoDS_Shape  theResult = theGlue; 
2683 ... 
2684
2685 ~~~~~
2686
2687 @subsubsection occt_modalg_9_2_4 Split Shape
2688
2689 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. 
2690
2691 The class is created or  initialized from a shape (the basic shape). 
2692 Three Add methods are  available: 
2693 * *Add(Wire, Face)* - adds  a new wire on a face of the basic shape. 
2694 * *Add(Edge, Face)* - adds  a new edge on a face of the basic shape. 
2695 * *Add(EdgeNew, EdgeOld)* - adds  a new edge on an existing one (the old edge must contain the new edge). 
2696
2697 **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. 
2698
2699 ~~~~~
2700 TopoDS_Shape Sbase = ...; // basic shape 
2701 TopoDS_Face Fsplit = ...; // face of Sbase 
2702 TopoDS_Wire Wsplit = ...; // new wire contained in Fsplit 
2703 BRepFeat_SplitShape Spls(Sbase); 
2704 Spls.Add(Wsplit, Fsplit); 
2705 TopoDS_Shape theResult = Spls; 
2706 ...
2707 ~~~~~
2708
2709
2710 @section occt_modalg_10 Hidden Line  Removal
2711
2712 To provide the  precision required in industrial design, drawings need to offer the possibility  of removing lines, which are hidden in a given projection. 
2713
2714 For this the Hidden Line Removal component provides two algorithms: *HLRBRep_Algo*  and *HLRBRep_PolyAlgo*. 
2715
2716 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. 
2717 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. 
2718
2719 *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.
2720
2721 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*. 
2722
2723 *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. 
2724
2725 However, there some restrictions in HLR use:
2726   * Points are not processed;
2727   * Z-clipping planes are not used;
2728   * Infinite faces or lines are not processed.
2729
2730   
2731 @image html /user_guides/modeling_algos/images/modeling_algos_image052.png "Sharp, smooth and sewn edges  in a simple screw shape"
2732 @image latex /user_guides/modeling_algos/images/modeling_algos_image052.png "Sharp, smooth and sewn edges  in a simple screw shape"
2733
2734 @image html /user_guides/modeling_algos/images/modeling_algos_image053.png "Outline edges  and isoparameters in the same shape"
2735 @image latex /user_guides/modeling_algos/images/modeling_algos_image053.png "Outline edges  and isoparameters in the same shape"
2736
2737 @image html /user_guides/modeling_algos/images/modeling_algos_image054.png "A simple screw shape seen with shading"
2738 @image latex /user_guides/modeling_algos/images/modeling_algos_image054.png "A simple screw shape seen with shading"
2739
2740 @image html /user_guides/modeling_algos/images/modeling_algos_image055.png "An extraction  showing hidden sharp edges"
2741 @image latex /user_guides/modeling_algos/images/modeling_algos_image055.png "An extraction  showing hidden sharp edges"
2742
2743
2744 The following services are related to Hidden Lines Removal : 
2745
2746 ### Loading Shapes
2747
2748 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. 
2749
2750 ### Setting view parameters
2751
2752 *HLRBRep_Algo::Projector* and *HLRBRep_PolyAlgo::Projector* set a projector object which defines the  parameters of the view. This object is an *HLRAlgo_Projector*. 
2753
2754 ### Computing the projections
2755
2756 *HLRBRep_PolyAlgo::Update* launches the calculation of outlines of the shape visualized by the *HLRBRep_PolyAlgo* framework. 
2757
2758 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*. 
2759
2760 ### Extracting edges
2761
2762 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: 
2763   * visible/hidden sharp edges;
2764   * visible/hidden smooth edges;
2765   * visible/hidden sewn edges;
2766   * visible/hidden outline edges. 
2767
2768 To perform extraction on an *HLRBRep_PolyHLRToShape* object, use *HLRBRep_PolyHLRToShape::Update*  function. 
2769
2770 For an *HLRBRep_HLRToShape* object built from an *HLRBRepAlgo* object you can also highlight: 
2771   * visible isoparameters and
2772   * hidden isoparameters.
2773
2774 @subsection occt_modalg_10_1 Examples
2775
2776 ### HLRBRep_Algo
2777
2778 ~~~~~
2779 // Build The algorithm object 
2780 myAlgo = new HLRBRep_Algo(); 
2781
2782 // Add Shapes into the algorithm 
2783 TopTools_ListIteratorOfListOfShape anIterator(myListOfShape); 
2784 for (;anIterator.More();anIterator.Next()) 
2785 myAlgo-Add(anIterator.Value(),myNbIsos); 
2786
2787 // Set The Projector (myProjector is a 
2788 HLRAlgo_Projector) 
2789 myAlgo-Projector(myProjector); 
2790
2791 // Build HLR 
2792 myAlgo->Update(); 
2793
2794 // Set The Edge Status 
2795 myAlgo->Hide(); 
2796
2797 // Build the extraction object : 
2798 HLRBRep_HLRToShape aHLRToShape(myAlgo); 
2799
2800 // extract the results : 
2801 TopoDS_Shape VCompound           = aHLRToShape.VCompound(); 
2802 TopoDS_Shape Rg1LineVCompound                            = 
2803 aHLRToShape.Rg1LineVCompound(); 
2804 TopoDS_Shape RgNLineVCompound                            = 
2805 aHLRToShape.RgNLineVCompound(); 
2806 TopoDS_Shape OutLineVCompound                            = 
2807 aHLRToShape.OutLineVCompound(); 
2808 TopoDS_Shape IsoLineVCompound                            = 
2809 aHLRToShape.IsoLineVCompound(); 
2810 TopoDS_Shape HCompound           = aHLRToShape.HCompound(); 
2811 TopoDS_Shape Rg1LineHCompound                            = 
2812 aHLRToShape.Rg1LineHCompound(); 
2813 TopoDS_Shape RgNLineHCompound                            = 
2814 aHLRToShape.RgNLineHCompound(); 
2815 TopoDS_Shape OutLineHCompound                            = 
2816 aHLRToShape.OutLineHCompound(); 
2817 TopoDS_Shape IsoLineHCompound                            = 
2818 aHLRToShape.IsoLineHCompound(); 
2819 ~~~~~
2820
2821 ### HLRBRep_PolyAlgo
2822
2823
2824 ~~~~~
2825
2826 // Build The algorithm object 
2827 myPolyAlgo = new HLRBRep_PolyAlgo(); 
2828
2829 // Add Shapes into the algorithm 
2830 TopTools_ListIteratorOfListOfShape 
2831 anIterator(myListOfShape); 
2832 for (;anIterator.More();anIterator.Next()) 
2833 myPolyAlgo-Load(anIterator.Value()); 
2834
2835 // Set The Projector (myProjector is a 
2836 HLRAlgo_Projector) 
2837 myPolyAlgo->Projector(myProjector); 
2838
2839 // Build HLR 
2840 myPolyAlgo->Update(); 
2841
2842 // Build the extraction object : 
2843 HLRBRep_PolyHLRToShape aPolyHLRToShape; 
2844 aPolyHLRToShape.Update(myPolyAlgo); 
2845
2846 // extract the results : 
2847 TopoDS_Shape VCompound = 
2848 aPolyHLRToShape.VCompound(); 
2849 TopoDS_Shape Rg1LineVCompound = 
2850 aPolyHLRToShape.Rg1LineVCompound(); 
2851 TopoDS_Shape RgNLineVCompound = 
2852 aPolyHLRToShape.RgNLineVCompound(); 
2853 TopoDS_Shape OutLineVCompound = 
2854 aPolyHLRToShape.OutLineVCompound(); 
2855 TopoDS_Shape HCompound = 
2856 aPolyHLRToShape.HCompound(); 
2857 TopoDS_Shape Rg1LineHCompound = 
2858 aPolyHLRToShape.Rg1LineHCompound(); 
2859 TopoDS_Shape RgNLineHCompound = 
2860 aPolyHLRToShape.RgNLineHCompound(); 
2861 TopoDS_Shape OutLineHCompound = 
2862 aPolyHLRToShape.OutLineHCompound(); 
2863 ~~~~~
2864
2865 @section occt_modalg_11 Meshing 
2866
2867 @subsection occt_modalg_11_1 Mesh presentations
2868
2869 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.
2870
2871 Open CASCADE Technology mesh functionality provides:
2872 - data structures to store surface mesh data associated to shapes, and some basic algorithms to handle these data
2873 - data structures and algorithms to build surface triangular mesh from *BRep* objects (shapes).
2874 - tools to extend 3D visualization capabilities of Open CASCADE Technology with displaying meshes along with associated pre- and post-processor data.
2875
2876 Open CASCADE Technology includes two mesh converters:
2877 - 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.
2878 - STL converter translates Open CASCADE shapes to STL files. STL (STtereoLithography) format is widely used for rapid prototyping.
2879
2880 Open CASCADE SAS also offers Advanced Mesh Products:
2881 - <a href="http://www.opencascade.org/support/products/omf">Open CASCADE Mesh Framework (OMF)</a>
2882 - <a href="http://www.opencascade.org/support/products/emesh">Express Mesh</a>
2883
2884 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.
2885
2886 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.
2887
2888 Learn more about SALOME platform on http://www.salome-platform.org
2889
2890 @subsection occt_modalg_11_2 Meshing algorithm
2891
2892 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.
2893
2894 ~~~~~
2895 const Standard_Real aRadius = 10.0; 
2896 const Standard_Real aHeight = 25.0; 
2897 BRepBuilderAPI_MakeCylinder aCylinder(aRadius, aHeight); 
2898 TopoDS_Shape aShape = aCylinder.Shape();
2899  
2900 const Standard_Real aLinearDeflection   = 0.01;
2901 const Standard_Real anAngularDeflection = 0.5;
2902
2903 BRepMesh_IncrementalMesh aMesh(aShape, aLinearDeflection, Standard_False, anAngularDeflection);
2904 ~~~~~
2905
2906 The default meshing algorithm *BRepMesh_IncrementalMesh* has two major options to define triangulation – linear and angular deflections. 
2907
2908 At the first step all edges from a face are discretized according to the specified parameters. 
2909
2910 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.
2911
2912 @figure{/user_guides/modeling_algos/images/modeling_algos_image056.png, "Deflection parameters of BRepMesh_IncrementalMesh algorithm"}
2913
2914 Linear deflection limits the distance between triangles and the face interior.
2915
2916 @figure{/user_guides/modeling_algos/images/modeling_algos_image057.png, "Linear deflection"}
2917
2918 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.
2919
2920 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.
2921
2922 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).
2923
2924 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.
2925
2926 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. 
2927
2928 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*.