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