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