0024960: Value of result tolerance after "fixshape" is bigger than value of set ...
[occt.git] / dox / user_guides / shape_healing / shape_healing.md
CommitLineData
ba06f8bb 1Shape Healing {#occt_user_guides__shape_healing}
72b7576f 2===================
e5bd0d98 3
4@tableofcontents
5
72b7576f 6@section occt_shg_1 Overview
7
8This manual explains how to use Shape Healing. It provides basic documentation on its operation. For advanced information on Shape Healing and its applications, see our offerings on our web site at <a href="http://www.opencascade.org/support/training/">www.opencascade.org/support/training/</a>
9
10The **Shape Healing** toolkit provides a set of tools to work on the geometry and topology of Open CASCADE Technology (**OCCT**) shapes. Shape Healing adapts shapes so as to make them as appropriate for use by Open CASCADE Technology as possible.
11**Shape Healing** currently includes several packages that are designed to help you to:
12 * analyze shape characteristics and, in particular, identify shapes that do not comply with Open CASCADE Technology validity rules
13 * fix some of the problems shapes may have
dba69de2 14 * upgrade shape characteristics for users needs, for example a C0 supporting surface can be upgraded so that it becomes C1 continuous.
72b7576f 15
16The following diagram shows dependencies of API packages:
3d68eaf5 17
18@figure{/user_guides/shape_healing/images/shape_healing_image009.svg, "Shape Healing packages"}
72b7576f 19
20Each sub-domain has its own scope of functionality:
dba69de2 21* analysis - exploring shape properties, computing shape features, detecting violation of OCCT requirements (shape itself is not modified);
22* fixing - fixing shape to meet the OCCT requirements (the shape may change its original form: modifying, removing, constructing sub-shapes, etc.);
23* upgrade - shape improvement for better usability in Open CASCADE Technology or other algorithms (the shape is replaced with a new one, but geometrically they are the same);
72b7576f 24* customization - modifying shape representation to fit specific needs (shape is not modified, only the form of its representation is modified);
dba69de2 25* processing - mechanism of managing shape modification via a user-editable resource file.
72b7576f 26
27Message management is used for creating messages, filling them with various parameters and storing them in the trace file. This tool provides functionality for attaching messages to the shapes for deferred analysis of various run-time events. In this document only general principles of using Shape Healing will be described. For more detailed information please see the corresponding CDL files.
dba69de2 28
72b7576f 29Tools responsible for analysis, fixing and upgrading of shapes can give the information about how these operations were performed. This information can be obtained by the user with the help of mechanism of status querying.
30
31@subsection occt_shg_1_1 Querying the statuses
32
33Each fixing and upgrading tool has its own status, which is reset when their methods are called. The status can contain several flags, which give the information about how the method was performed. For exploring the statuses, a set of methods named *Status...()* is provided. These methods accept enumeration *ShapeExtend_Status* and return True if the status has the corresponding flag set. The meaning of flags for each method is described below.
dba69de2 34
72b7576f 35The status may contain a set of Boolean flags (internally represented by bits). Flags are coded by enumeration ShapeExtend_Status. This enumeration provides the following families of statuses:
e5bd0d98 36* *ShapeExtend_OK* - The situation is OK, no operation is necessary and has not been performed.
37* *ShapeExtend_DONE* - The operation has been successfully performed.
38* *ShapeExtend_FAIL* - An error has occurred during operation.
72b7576f 39
40It is possible to test the status for the presence of some flag(s), using Status...() method(s) provided by the class:
41
42~~~~~
43if ( object.Status.. ( ShapeExtend_DONE ) ) {// something was done
44}
45~~~~~
46
478 'DONE' and 8 'FAIL' flags, named ShapeExtend_DONE1 ... ShapeExtend_FAIL8, are defined for a detailed analysis of the encountered situation. Each method assigns its own meaning to each flag, documented in the CDL for that method. There are also three enumerative values used for testing several flags at a time:
e5bd0d98 48* *ShapeExtend_OK* - if no flags have been set;
49* *ShapeExtend_DONE* - if at least one ShapeExtend_DONEi has been set;
50* *ShapeExtend_FAIL* - if at least one ShapeExtend_FAILi has been set.
72b7576f 51
52@section occt_shg_2 Repair
53
dba69de2 54Algorithms for fixing problematic (violating the OCCT requirements) shapes are placed in package *ShapeFix*.
55
56Each class of package *ShapeFix* deals with one certain type of shapes or with some family of problems.
57
58There is no necessity for you to detect problems before using *ShapeFix* because all components of package *ShapeFix* make an analysis of existing problems before fixing them by a corresponding tool from package of *ShapeAnalysis* and then fix the discovered problems.
59
60The *ShapeFix* package currently includes functions that:
72b7576f 61 * add a 2D curve or a 3D curve where one is missing,
62 * correct a deviation of a 2D curve from a 3D curve when it exceeds a given tolerance value,
63 * limit the tolerance value of shapes within a given range,
64 * set a given tolerance value for shapes,
65 * repair the connections between adjacent edges of a wire,
66 * correct self–intersecting wires,
67 * add seam edges,
68 * correct gaps between 3D and 2D curves,
69 * merge and remove small edges,
70 * correct orientation of shells and solids.
71
72@subsection occt_shg_2_1 Basic Shape Repair
73
74The simplest way for fixing shapes is to use classes *ShapeFix_Shape* and *ShapeFix_Wireframe* on a whole shape with default parameters. A combination of these tools can fix most of the problems that shapes may have.
75The sequence of actions is as follows :
76
771. Create tool *ShapeFix_Shape* and initialize it by shape:
dc244065 78
79 Handle(ShapeFix_Shape) sfs = new ShapeFix_Shape;
80 sfs->Init ( shape );
81
822. Set the basic precision, the maximum allowed tolerance, the minimal allowed tolerance:
83
84 sfs->SetPrecision ( Prec );
85 sfs->SetMaxTolerance ( maxTol );
86 sfs->SetMinTolerance ( mintol );
87
88 where *Prec* – basic precision, *maxTol* – maximum allowed tolerance, *minTol* – minimal allowed tolerance.
89 * *maxTol* - All problems will be detected for cases when a dimension of invalidity is larger than the basic precision or a tolerance of sub-shape on that problem is detected.
90 The maximum tolerance value limits the increasing tolerance for fixing a problem such as fix of not connenected and self-intersected wires. If a value larger than the maximum allowed tolerance is necessary for correcting a detected problem the problem can not be fixed.
91 The maximal tolerance is not taking into account during computation of tolerance of edges in ShapeFix_SameParameter() method and ShapeFix_Edge::FixVertexTolerance() method.
92 See @ref occt_shg_2_3_8 for details.
93 * *minTol* - The minimal allowed tolerance defines minimal allowed length of edges. Detected edges having length less than specified minimal tolerance will be removed if ModifyTopologyMode in Repairing tool for wires is set to true.
94 See @ref occt_shg_2_3_7 for details.
95
72b7576f 963. Launch fixing:
dc244065 97
98 sfs->Perform();
99
72b7576f 1004. Get the result:
dc244065 101
102 TopoDS_Shape aResult = sfs->Shape();
103
104 In some cases using only *ShapeFix_Shape* can be insufficient. It is possible to use tools for merging and removing small edges and fixing gaps between 2D and 3D curves.
105
72b7576f 1065. Create *ShapeFix_Wireframe* tool and initialize it by shape:
72b7576f 107~~~~~
108Handle(ShapeFix_Wirefarme) SFWF = new ShapeFix_Wirefarme(shape);
109Or
110Handle(ShapeFix_Wirefarme) SFWF = new ShapeFix_Wirefarme;
111SFWF->Load(shape);
112~~~~~
72b7576f 1136. Set the basic precision and the maximum allowed tolerance:
114~~~~~
115sfs->SetPrecision ( Prec );
116sfs->SetMaxTolerance ( maxTol );
117~~~~~
dba69de2 118See the description for *Prec* and *maxTol* above.
72b7576f 1197. Merge and remove small edges:
120~~~~~
4ee1bdf4 121SFWF->DropSmallEdgesMode() = Standard_True;
122SFWF->FixSmallEdges();
72b7576f 123~~~~~
72b7576f 124**Note:** Small edges are not removed with the default mode, but in many cases removing small edges is very useful for fixing a shape.
72b7576f 1258. Fix gaps for 2D and 3D curves
126~~~~~
4ee1bdf4 127SFWF->FixWireGaps();
72b7576f 128~~~~~
72b7576f 1299. Get the result
130~~~~~
4ee1bdf4 131TopoDS_Shape Result = SFWF->Shape();
72b7576f 132~~~~~
133
134
135@subsection occt_shg_2_2 Shape Correction.
136
137If you do not want to make fixes on the whole shape or make a definite set of fixes you can set flags for separate fix cases (marking them ON or OFF) and you can also use classes for fixing specific types of sub-shapes such as solids, shells, faces, wires, etc.
dba69de2 138
72b7576f 139For each type of sub-shapes there are specific types of fixing tools such as *ShapeFix_Solid, ShapeFix_Shell, ShapeFix_Face, ShapeFix_Wire,* etc.
140
141@subsubsection occt_shg_2_2_1 Fixing sub-shapes
142If you want to make a fix on one subshape of a certain shape it is possible to take the following steps:
143 * create a tool for a specified subshape type and initialize this tool by the subshape;
144 * create a tool for rebuilding the shape and initialize it by the whole shape (section 5.1);
145 * set a tool for rebuilding the shape in the tool for fixing the subshape;
146 * fix the subshape;
147 * get the resulting whole shape containing a new corrected subshape.
148
dba69de2 149For example, in the following way it is possible to fix face *Face1* of shape *Shape1*:
72b7576f 150
151~~~~~
152//create tools for fixing a face
dba69de2 153Handle(ShapeFix_Face) SFF= new ShapeFix_Face;
72b7576f 154
155// create tool for rebuilding a shape and initialize it by shape
dba69de2 156Handle(ShapeBuild_ReShape) Context = new ShapeBuild_ReShape;
4ee1bdf4 157Context->Apply(Shape1);
72b7576f 158
159//set a tool for rebuilding a shape in the tool for fixing
4ee1bdf4 160SFF->SetContext(Context);
dba69de2 161
72b7576f 162//initialize the fixing tool by one face
4ee1bdf4 163SFF->Init(Face1);
72b7576f 164
165//fix the set face
4ee1bdf4 166SFF->Perform();
dba69de2 167
72b7576f 168//get the result
4ee1bdf4 169TopoDS_Shape NewShape = Context->Apply(Shape1);
72b7576f 170//Resulting shape contains the fixed face.
171~~~~~
172
173A set of required fixes and invalid sub-shapes can be obtained with the help of tools responsible for the analysis of shape validity (section 3.2).
174
175@subsection occt_shg_2_3 Repairing tools
176
177Each class of package ShapeFix deals with one certain type of shapes or with a family of problems. Each repairing tool makes fixes for the specified shape and its sub-shapes with the help of method *Perform()* containing an optimal set of fixes. The execution of these fixes in the method Perform can be managed with help of a set of control flags (fixes can be either forced or forbidden).
178
179@subsubsection occt_shg_2_3_1 General Workflow
180
181The following sequence of actions should be applied to perform fixes:
1821. Create a tool.
1832. Set the following values:
dba69de2 184 + the working precision by method *SetPrecision()* (default 1.e-7)
72b7576f 185 + set the maximum allowed tolerance by method *SetMaxTolerance()* (by default it is equal to the working precision).
186 + set the minimum tolerance by method *SetMinTolerance()* (by default it is equal to the working precision).
187 + set a tool for rebuilding shapes after the modification (tool *ShapeBuild_ReShape*) by method *SetContext()*. For separate faces, wires and edges this tool is set optionally.
188 + to force or forbid some of fixes, set the corresponding flag to 0 or 1.
1893. Initialize the tool by the shape with the help of methods Init or Load
1904. Use method *Perform()* or create a custom set of fixes.
1915. Check the statuses of fixes by the general method *Status* or specialized methods *Status_*(for example *StatusSelfIntersection* (*ShapeExtentd_DONE*)). See the description of statuses below.
1926. Get the result in two ways :
193 - with help of a special method *Shape(),Face(),Wire().Edge()*.
194 - from the rebuilding tool by method *Apply* (for access to rebuilding tool use method *Context()*):
195~~~~~
4ee1bdf4 196 TopoDS_Shape resultShape = fixtool->Context()->Apply(initialShape);
72b7576f 197~~~~~
198Modification fistory for the shape and its sub-shapes can be obtained from the tool for shape re-building (*ShapeBuild_ReShape*).
199
200~~~~~
4ee1bdf4 201TopoDS_Shape modifsubshape = fixtool->Context() -> Apply(initsubshape);
72b7576f 202~~~~~
203
204
205@subsubsection occt_shg_2_3_2 Flags Management
206
207The flags *Fix...Mode()* are used to control the execution of fixing procedures from the API fixing methods. By default, these flags have values equal to -1, this means that the corresponding procedure will either be called or not called, depending on the situation. If the flag is set to 1, the procedure is executed anyway; if the flag is 0, the procedure is not executed. The name of the flag corresponds to the fixing procedure that is controlled. For each fixing tool there exists its own set of flags. To set a flag to the desired value, get a tool containing this flag and set the flag to the required value.
208
209For example, it is possible to forbid performing fixes to remove small edges - *FixSmall*
210
211~~~~~
212Handle(ShapeFix_Shape) Sfs = new ShapeFix_Shape(shape);
4ee1bdf4 213Sfs-> FixWireTool ()->FixSmallMode () =0;
214if(Sfs->Perform())
215 TopoDS_Shape resShape = Sfs->Shape();
72b7576f 216~~~~~
217
218
219@subsubsection occt_shg_2_3_3 Repairing tool for shapes
220
dba69de2 221Class *ShapeFix_Shape* allows using repairing tools for all sub-shapes of a shape. It provides access to all repairing tools for fixing sub-shapes of the specified shape and to all control flags from these tools.
72b7576f 222
223For example, it is possible to force the removal of invalid 2D curves from a face.
224
225~~~~~
226TopoDS_Face face … // face with invalid 2D curves.
227//creation of tool and its initialization by shape.
228Handle(ShapeFix_Shape) sfs = new ShapeFix_Shape(face);
229//set work precision and max allowed tolerance.
230sfs->SetPrecision(prec);
231sfs->SetMaxTolerance(maxTol);
232//set the value of flag for forcing the removal of 2D curves
4ee1bdf4 233sfs->FixWireTool()->FixRemovePCurveMode() =1;
72b7576f 234//reform fixes
235sfs->Perform();
236//getting the result
237if(sfs->Status(ShapeExtend_DONE) ) {
4ee1bdf4 238 cout << "Shape was fixed" << endl;
72b7576f 239 TopoDS_Shape resFace = sfs->Shape();
240}
241else if(sfs->Status(ShapeExtend_FAIL)) {
4ee1bdf4 242cout<< "Shape could not be fixed" << endl;
72b7576f 243}
244else if(sfs->Status(ShapeExtent_OK)) {
4ee1bdf4 245cout<< "Initial face is valid with specified precision ="<< precendl;
72b7576f 246}
247~~~~~
248
249@subsubsection occt_shg_2_3_4 Repairing tool for solids
250
251Class *ShapeFix_Solid* allows fixing solids and building a solid from a shell to obtain a valid solid with a finite volume. The tool *ShapeFix_Shell* is used for correction of shells belonging to a solid.
252
253This tool has the following control flags:
254* *FixShellMode* - Mode for applying fixes of ShapeFix_Shell, True by default.
255* *CreateOpenShellMode* - If it is equal to true solids are created from open shells, else solids are created from closed shells only, False by default.
256
257@subsubsection occt_shg_2_3_5 Repairing tool for shells
dba69de2 258Class *ShapeFix_Shell* allows fixing wrong orientation of faces in a shell. It changes the orientation of faces in the shell so that all faces in the shell have coherent orientations. If it is impossible to orient all faces in the shell (like in case of Mebious tape), then a few manifold or non-manifold shells will be created depending on the specified Non-manifold mode. The *ShapeFix_Face* tool is used to correct faces in the shell.
72b7576f 259This tool has the following control flags:
dba69de2 260* *FixFaceMode* - mode for applying the fixes of *ShapeFix_Face*, *True* by default.
261* *FixOrientationMode* - mode for applying a fix for the orientation of faces in the shell.
72b7576f 262
263@subsubsection occt_shg_2_3_6 Repairing tool for faces
264
dba69de2 265Class *ShapeFix_Face* allows fixing the problems connected with wires of a face. It allows controlling the creation of a face (adding wires), and fixing wires by means of tool *ShapeFix_Wire*.
72b7576f 266When a wire is added to a face, it can be reordered and degenerated edges can be fixed. This is performed or not depending on the user-defined flags (by default, False).
267The following fixes are available:
268 * fixing of wires orientation on the face. If the face has no wire, the natural bounds are computed. If the face is on a spherical surface and has two or more wires on it describing holes, the natural bounds are added. In case of a single wire, it is made to be an outer one. If the face has several wires, they are oriented to lay one outside another (if possible). If the supporting surface is periodic, 2D curves of internal wires can be shifted on integer number of periods to put them inside the outer wire.
dba69de2 269 * fixing the case when the face on the closed surface is defined by a set of closed wires, and the seam is missing (this is not valid in OCCT). In that case, these wires are connected by means of seam edges into the same wire.
72b7576f 270
271This tool has the following control flags:
dba69de2 272* *FixWireMode* - mode for applying fixes of a wire, True by default.
273* *FixOrientationMode* - mode for orienting a wire to border a limited square, True by default.
72b7576f 274* *FixAddNaturalBoundMode* - mode for adding natural bounds to a face, False by default.
275* *FixMissingSeamMode* – mode to fix a missing seam, True by default. If True, tries to insert a seam.
dba69de2 276* *FixSmallAreaWireMode* - mode to fix a small-area wire, False by default. If True, drops wires bounding small areas.
72b7576f 277
278~~~~~
279
280TopoDS_Face face = ...;
281TopoDS_Wire wire = ...;
282
283//Creates a tool and adds a wire to the face
284ShapeFix_Face sff (face);
285sff.Add (wire);
286
287//use method Perform to fix the wire and the face
288sff.Perfom();
289
290//or make a separate fix for the orientation of wire on the face
291sff.FixOrientation();
292
293//Get the resulting face
294TopoDS_Face newface = sff.Face();
295~~~~~
296
dba69de2 297@subsubsection occt_shg_2_3_7 Repairing tool for wires
72b7576f 298
dba69de2 299Class *ShapeFix_Wire* allows fixing a wire. Its method *Perform()* performs all the available fixes in addition to the geometrical filling of gaps. The geometrical filling of gaps can be made with the help of the tool for fixing the wireframe of shape *ShapeFix_Wireframe*.
72b7576f 300
301The fixing order and the default behavior of *Perform()* is as follows:
dba69de2 302 * Edges in the wire are reordered by *FixReorder*. Most of fixing methods expect edges in a wire to be ordered, so it is necessary to make call to *FixReorder()* before making any other fixes. Even if it is forbidden, the analysis of whether the wire is ordered or not is performed anyway.
303 * Small edges are removed by *FixSmall* .
304 * Edges in the wire are connected (topologically) by *FixConnected* (if the wire is ordered).
305 * Edges (3Dcurves and 2D curves) are fixed by *FixEdgeCurves* (without *FixShifted* if the wire is not ordered).
306 * Degenerated edges are added by *FixDegenerated*(if the wire is ordered).
307 * Self-intersection is fixed by *FixSelfIntersection* (if the wire is ordered and *ClosedMode* is True).
308 * Lacking edges are fixed by *FixLacking* (if the wire is ordered).
309
310 The flag *ClosedWireMode* specifies whether the wire is (or should be) closed or not. If that flag is True (by default), fixes that require or force connection between edges are also executed for the last and the first edges.
311
312The fixing methods can be turned on/off by using their corresponding control flags:
313* *FixReorderMode,*
314* *FixSmallMode,*
315* *FixConnectedMode,*
316* *FixEdgeCurvesMode,*
317* *FixDegeneratedMode,*
318* *FixSelfIntersectionMode*
72b7576f 319
320Some fixes can be made in three ways:
321 * Increasing the tolerance of an edge or a vertex.
322 * Changing topology (adding/removing/replacing an edge in the wire and/or replacing the vertex in the edge, copying the edge etc.).
323 * Changing geometry (shifting a vertex or adjusting ends of an edge curve to vertices, or re-computing a 3D curve or 2D curves of the edge).
324
325When it is possible to make a fix in more than one way (e.g., either by increasing the tolerance or shifting a vertex), it is chosen according to the user-defined flags:
dba69de2 326* *ModifyTopologyMode* - allows modifying topology, False by default.
327* *ModifyGeometryMode* - allows modifying geometry. Now this flag is used only in fixing self-intersecting edges (allows to modify 2D curves) and is True by default.
72b7576f 328
dba69de2 329#### Fixing disordered edges
330
331*FixReorder* is necessary for most other fixes (but is not necessary for Open CASCADE Technology). It checks whether edges in the wire go in a sequential order (the end of a preceding edge is the start of a following one). If it is not so, an attempt to reorder the edges is made.
72b7576f 332
dba69de2 333#### Fixing small edges
334
335*FixSmall* method searches for the edges, which have a length less than the given value (degenerated edges are ignored). If such an edge is found, it is removed provided that one of the following conditions is satisfied:
72b7576f 336 * both end vertices of that edge are one and the same vertex,
337 * end vertices of the edge are different, but the flag *ModifyTopologyMode* is True. In the latter case, method *FixConnected* is applied to the preceding and the following edges to ensure their connection.
338
dba69de2 339#### Fixing disconnected edges
340
341*FixConnected* method forces two adjacent edges to share the same common vertex (if they do not have a common one). It checks whether the end vertex of the preceding edge coincides with the start vertex of the following edge with the given precision, and then creates a new vertex and sets it as a common vertex for the fixed edges. At that point, edges are copied, hence the wire topology is changed (regardless of the *ModifyTopologyMode* flag). If the vertices do not coincide, this method fails.
342
343#### Fixing the consistency of edge curves
344
345*FixEdgeCurves* method performs a set of fixes dealing with 3D curves and 2D curves of edges in a wire.
346
347These fixes will be activated with the help of a set of fixes from the repairing tool for edges called *ShapeFix_Edge*. Each of these fixes can be forced or forbidden by means of setting the corresponding flag to either True or False.
348
349The mentioned fixes and the conditions of their execution are:
350 * fixing a disoriented 2D curve by call to *ShapeFix_Edge::FixReversed2d* - if not forbidden by flag *FixReversed2dMode*;
351 * removing a wrong 2D curve by call to *ShapeFix_Edge::FixRemovePCurve* - only if forced by flag *FixRemovePCurveMode*;
352 * fixing a missing 2D curve by call to *ShapeFix_Edge::FixAddPCurve* - if not forbidden by flag *FixAddPCurveMode*;
353 * removing a wrong 3D curve by call to *ShapeFix_Edge::FixRemoveCurve3d* - only if forced by flag *FixRemoveCurve3dMode*;
354 * fixing a missing 3D curve by call to *ShapeFix_Edge::FixAddCurve3d* - if not forbidden by flag *FixAddCurve3dMode*;
355 * fixing 2D curves of seam edges - if not forbidden by flag *FixSeamMode*;
356 * fixing 2D curves which can be shifted at an integer number of periods on the closed surface by call to *ShapeFix_Edge::FixShifted* - if not forbidden by flag *FixShiftedMode*.
357
358This fix is required if 2D curves of some edges in a wire lying on a closed surface were recomputed from 3D curves. In that case, the 2D curve for the edge, which goes along the seam of the surface, can be incorrectly shifted at an integer number of periods. The method *FixShifted* detects such cases and shifts wrong 2D curves back, ensuring that the 2D curves of the edges in the wire are connected.
359
360 * fixing the SameParameter problem by call to *ShapeFix_Edge::FixSameParameter* - if not forbidden by flag *FixSameParameterMode*.
361
72b7576f 362
dba69de2 363#### Fixing degenerated edges
364
365*FixDegenerated* method checks whether an edge in a wire lies on a degenerated point of the supporting surface, or whether there is a degenerated point between the edges. If one of these cases is detected for any edge, a new degenerated edge is created and it replaces the current edge in the first case or is added to the wire in the second case. The newly created degenerated edge has a straight 2D curve, which goes from the end of the 2D curve of the preceding edge to the start of the following one.
72b7576f 366
dba69de2 367#### Fixing intersections of 2D curves of the edges
368
369*FixSelfIntersection* method detects and fixes the following problems:
72b7576f 370 * self-intersection of 2D curves of individual edges. If the flag *ModifyGeometryMode()* is False this fix will be performed by increasing the tolerance of one of end vertices to a value less then *MaxTolerance()*.
371 * intersection of 2D curves of each of the two adjacent edges (except the first and the last edges if the flag ClosedWireMode is False). If such intersection is found, the common vertex is modified in order to comprise the intersection point. If the flag *ModifyTopologyMode* is False this fix will be performed by increasing the tolerance of the vertex to a value less then *MaxTolerance()*.
dba69de2 372 * intersection of 2D curves of non-adjacent edges. If such intersection is found the tolerance of the nearest vertex is increased to comprise the intersection point. If such increase cannot be done with a tolerance less than *MaxTolerance* this fix will not be performed.
72b7576f 373
dba69de2 374#### Fixing a lacking edge
72b7576f 375
dba69de2 376*FixLacking* method checks whether a wire is not closed in the parametrical space of the surface (while it can be closed in 3D). This is done by checking whether the gap between 2D curves of each of the two adjacent edges in the wire is smaller than the tolerance of the corresponding vertex. The algorithm computes the gap between the edges, analyses positional relationship of the ends of these edges and (if possible) tries to insert a new edge into the gap or increases the tolerance.
377
378#### Fixing gaps in 2D and 3D wire by geometrical filling
379The following methods check gaps between the ends of 2D or 3D curves of adjacent edges:
380* Method *FixGap2d* moves the ends of 2D curves to the middle point.
381* Method *FixGaps3d* moves the ends of 3D curves to a common vertex.
382
383Boolean flag *FixGapsByRanges* is used to activate an additional mode applied before converting to B-Splines. When this mode is on, methods try to find the most precise intersection of curves, or the most precise projection of a target point, or an extremity point between two curves (to modify their parametric range accordingly). This mode is off by default. Independently of the additional mode described above, if gaps remain, these methods convert curves to B-Spline form and shift their ends if a gap is detected.
384
385#### Example: A custom set of fixes
72b7576f 386
72b7576f 387
388Let us create a custom set of fixes as an example.
389~~~~~
390TopoDS_Face face = ...;
391TopoDS_Wire wire = ...;
392Standard_Real precision = 1e-04;
393ShapeFix_Wire sfw (wire, face, precision);
394//Creates a tool and loads objects into it
395sfw.FixReorder();
4ee1bdf4 396//Orders edges in the wire so that each edge starts at the end of the one before it.
72b7576f 397sfw.FixConnected();
398//Forces all adjacent edges to share
399//the same vertex
400Standard_Boolean LockVertex = Standard_True;
4ee1bdf4 401 if (sfw.FixSmall (LockVertex, precision)) {
402 //Removes all edges which are shorter than the given precision and have the same vertex at both ends.
72b7576f 403}
4ee1bdf4 404 if (sfw.FixSelfIntersection()) {
405 //Fixes self-intersecting edges and intersecting adjacent edges.
406 cout <<"Wire was slightly self-intersecting. Repaired"<<endl;
72b7576f 407}
4ee1bdf4 408 if ( sfw.FixLacking ( Standard_False ) ) {
409 //Inserts edges to connect adjacent non-continuous edges.
72b7576f 410}
411TopoDS_Wire newwire = sfw.Wire();
412//Returns the corrected wire
413~~~~~
414
dba69de2 415#### Example: Correction of a wire
72b7576f 416
417Let us correct the following wire:
418
dba69de2 419@image html /user_guides/shape_healing/images/shape_healing_image013.png "Initial shape"
420@image latex /user_guides/shape_healing/images/shape_healing_image013.png "Initial shape"
72b7576f 421
dba69de2 422It is necessary to apply the <a href="#_3_1_2">Tools for the analysis of validity of wires</a> to check that:
72b7576f 423* the edges are correctly oriented;
424* there are no edges that are too short;
425* there are no intersecting adjacent edges;
426and then immediately apply fixing tools.
427
428~~~~~
429TopoDS_Face face = ...;
430TopoDS_Wire wire = ...;
431Standard_Real precision = 1e-04;
432ShapeAnalysis_Wire saw (wire, face, precision);
433ShapeFix_Wire sfw (wire, face, precision);
434if (saw.CheckOrder()) {
435 cout<<“Some edges in the wire need to be reordered”<<endl;
436 // Two edges are incorrectly oriented
437 sfw.FixReorder();
438 cout<<“Reordering is done”<<endl;
439}
440// their orientation is corrected
441if (saw.CheckSmall (precision)) {
442 cout<<“Wire contains edge(s) shorter than “<<precision<<endl;
4ee1bdf4 443 // An edge that is shorter than the given tolerance is found.
72b7576f 444 Standard_Boolean LockVertex = Standard_True;
445 if (sfw.FixSmall (LockVertex, precision)) {
446 cout<<“Edges shorter than “<<precision<<“ have been removed”
447<<endl;
448 //The edge is removed
449 }
450}
451if (saw.CheckSelfIntersection()) {
452 cout<<“Wire has self-intersecting or intersecting
453adjacent edges”<<endl;
4ee1bdf4 454 // Two intersecting adjacent edges are found.
72b7576f 455 if (sfw.FixSelfIntersection()) {
456 cout<<“Wire was slightly self-intersecting. Repaired”<<endl;
4ee1bdf4 457 // The edges are cut at the intersection point so that they no longer intersect.
72b7576f 458 }
459}
460~~~~~
461
462As the result all failures have been fixed.
463
dba69de2 464@image html /user_guides/shape_healing/images/shape_healing_image014.png "Resulting shape"
465@image latex /user_guides/shape_healing/images/shape_healing_image014.png "Resulting shape"
72b7576f 466
467@subsubsection occt_shg_2_3_8 Repairing tool for edges
468
469Class *ShapeFix_Edge* provides tools for fixing invalid edges. The following geometrical and/or topological inconsistencies are detected and fixed:
470 * missing 3D curve or 2D curve,
471 * mismatching orientation of a 3D curve and a 2D curve,
dba69de2 472 * incorrect SameParameter flag (curve deviation is greater than the edge tolerance).
72b7576f 473Each fixing method first checks whether the problem exists using methods of the *ShapeAnalysis_Edge* class. If the problem is not detected, nothing is done.
474This tool does not have the method *Perform()*.
475
476To see how this tool works, it is possible to take an edge, where the maximum deviation between the 3D curve and 2D curve P1 is greater than the edge tolerance.
477
dba69de2 478@image html /user_guides/shape_healing/images/shape_healing_image011.png "Initial shape"
479@image latex /user_guides/shape_healing/images/shape_healing_image011.png "Initial shape"
72b7576f 480
dba69de2 481First it is necessary to apply the <a href="#_3_1_3">Tool for checking the validity of edges</a> to find that maximum deviation between pcurve and 3D curve is greater than tolerance. Then we can use the repairing tool to increase the tolerance and make the deviation acceptable.
72b7576f 482
483~~~~~
484ShapeAnalysis_Edge sae;
485TopoDS_Face face = ...;
486TopoDS_Wire wire = ...;
487Standard_Real precision = 1e-04;
488ShapeFix_Edge sfe;
489Standard_Real maxdev;
490if (sae.CheckSameParameter (edge, maxdev)) {
491 cout<<“Incorrect SameParameter flag”<<endl;
492 cout<<“Maximum deviation “<<maxdev<< “, tolerance “
493<<BRep_Tool::Tolerance(edge)<<endl;
494 sfe.FixSameParameter();
495 cout<<“New tolerance “<<BRep_Tool::Tolerance(edge)<<endl;
496}
497~~~~~
498
dba69de2 499@image html /user_guides/shape_healing/images/shape_healing_image012.png "Resulting shape"
500@image latex /user_guides/shape_healing/images/shape_healing_image012.png "Resulting shape"
72b7576f 501
502As the result, the edge tolerance has been increased.
503
504
505@subsubsection occt_shg_2_3_9 Repairing tool for the wireframe of a shape
506
4ee1bdf4 507Class *ShapeFix_Wireframe* provides methods for geometrical fixing of gaps and merging small edges in a shape. This class performs the following operations:
72b7576f 508 * fills gaps in the 2D and 3D wireframe of a shape.
509 * merges and removes small edges.
510
511Fixing of small edges can be managed with the help of two flags:
512 * *ModeDropSmallEdges()* – mode for removing small edges that can not be merged, by default it is equal to Standard_False.
513 * *LimitAngle* – maximum possible angle for merging two adjacent edges, by default no limit angle is applied (-1).
514To perform fixes it is necessary to:
515 * create a tool and initialize it by shape,
516 * set the working precision problems will be detected with and the maximum allowed tolerance
517 * perform fixes
518
519~~~~~
520//creation of a tool
521Handle(ShapeFix_Wireframe) sfwf = new ShapeFix_Wireframe(shape);
4ee1bdf4 522//sets the working precision problems will be detected with and the maximum allowed tolerance
72b7576f 523sfwf->SetPrecision(prec);
524sfwf->SetMaxTolerance(maxTol);
525//fixing of gaps
526sfwf->FixWireGaps();
527//fixing of small edges
528//setting of the drop mode for the fixing of small edges and max possible angle between merged edges.
529sfwf->ModeDropSmallEdges = Standard_True;
530sfwf->SetLimliteAngle(angle);
531//performing the fix
532sfwf->FixSmallEdges();
533//getting the result
534TopoDS_Shape resShape = sfwf->Shape();
535~~~~~
536
537It is desirable that a shape is topologically correct before applying the methods of this class.
538
539@subsubsection occt_shg_2_3_10 Tool for removing small faces from a shape
540
541Class ShapeFix_FixSmallFaceThis tool is intended for dropping small faces from the shape. The following cases are processed:
542* Spot face: if the size of the face is less than the given precision;
543* Strip face: if the size of the face in one dimension is less then the given precision.
544
545The sequence of actions for performing the fix is the same as for the fixes described above:
546
547~~~~~
548//creation of a tool
549Handle(ShapeFix_FixSmallFace) sff = new ShapeFix_FixSmallFace(shape);
550//setting of tolerances
551sff->SetPrecision(prec);
552sff->SetMaxTolerance(maxTol);
553//performing fixes
554sff.Perform();
555//getting the result
556TopoDS_Shape resShape = sff.FixShape();
557~~~~~
558
dba69de2 559@subsubsection occt_shg_2_3_11 Tool to modify tolerances of shapes (Class ShapeFix_ShapeTolerance).
72b7576f 560
561This tool provides a functionality to set tolerances of a shape and its sub-shapes.
562In Open CASCADE Technology only vertices, edges and faces have tolerances.
563
564This tool allows processing each concrete type of sub-shapes or all types at a time.
565You set the tolerance functionality as follows:
566 * set a tolerance for sub-shapes, by method SetTolerance,
567 * limit tolerances with given ranges, by method LimitTolerance.
568
569~~~~~
570//creation of a tool
571ShapeFix_ShapeTolerance Sft;
572//setting a specified tolerance on shape and all of its sub-shapes.
573Sft.SetTolerance(shape,toler);
574//setting a specified tolerance for vertices only
575Sft.SetTolerance(shape,toler,TopAbs_VERTEX);
4ee1bdf4 576//limiting the tolerance on the shape and its sub-shapes between minimum and maximum tolerances
72b7576f 577Sft.LimitTolerance(shape,tolermin,tolermax);
578~~~~~
579
580
581@section occt_shg_3 Analysis
582
dba69de2 583@subsection occt_shg_3_1 Analysis of shape validity
72b7576f 584
585The *ShapeAnalysis* package provides tools for the analysis of topological shapes.
586It is not necessary to check a shape by these tools before the execution of repairing tools because these tools are used for the analysis before performing fixes inside the repairing tools.
587However, if you want, these tools can be used for detecting some of shape problems independently from the repairing tools.
dba69de2 588
589 It can be done in the following way:
72b7576f 590 * create an analysis tool.
591 * initialize it by shape and set a tolerance problems will be detected with if it is necessary.
592 * check the problem that interests you.
593
594~~~~~
595TopoDS_Face face = ...;
596ShapeAnalysis_Edge sae;
597//Creates a tool for analyzing an edge
598for(TopExp_Explorer Exp(face,TopAbs_EDGE);Exp.More();Exp.Next()) {
dba69de2 599 TopoDS_Edge edge = TopoDS::Edge (Exp.Current());
600 if (!sae.HasCurve3d (edge)) {
4ee1bdf4 601 cout <<"Edge has no 3D curve"<< endl; }
72b7576f 602}
603~~~~~
604
605@subsubsection occt_shg_3_1_1 Analysis of orientation of wires on a face.
606
607It is possible to check whether a face has an outer boundary with the help of method *ShapeAnalysis::IsOuterBound*.
608
609~~~~~
610TopoDS_Face face … //analyzed face
611if(!ShapeAnalysis::IsOuterBound(face)) {
4ee1bdf4 612cout<<"Face has not outer boundary"<<endl;
72b7576f 613}
614~~~~~
615
616@subsubsection occt_shg_3_1_2 Analysis of wire validity
617
618Class *ShapeAnalysis_Wire* is intended to analyze a wire. It provides functionalities both to explore wire properties and to check its conformance to Open CASCADE Technology requirements.
619These functionalities include:
620 * checking the order of edges in the wire,
621 * checking for the presence of small edges (with a length less than the given value),
622 * checking for the presence of disconnected edges (adjacent edges having different vertices),
623 * checking the consistency of edge curves,
624 * checking for the presence or missing of degenerated edges,
625 * checking for the presence of self-intersecting edges and intersecting edges (edges intersection is understood as intersection of their 2D curves),
626 * checking for lacking edges to fill gaps in the surface parametrical space,
627 * analyzing the wire orientation (to define the outer or the inner bound on the face),
628 * analyzing the orientation of the shape (edge or wire) being added to an already existing wire.
629
dba69de2 630**Note** that all checking operations except for the first one are based on the assumption that edges in the wire are ordered. Thus, if the wire is detected as non-ordered it is necessary to order it before calling other checking operations. This can be done, for example, with the help of the *ShapeFix_Wire::FixOrder()* method.
631
72b7576f 632This tool should be initialized with wire, face (or a surface with a location) or precision.
633Once the tool has been initialized, it is possible to perform the necessary checking operations. In order to obtain all information on a wire at a time the global method *Perform* is provided. It calls all other API checking operations to check each separate case.
dba69de2 634
72b7576f 635API methods check for corresponding cases only, the value and the status they return can be analyzed to understand whether the case was detected or not.
dba69de2 636
72b7576f 637Some methods in this class are:
638 * *CheckOrder* checks whether edges in the wire are in the right order
639 * *CheckConnected* checks whether edges are disconnected
640 * *CheckSmall* checks whether there are edges that are shorter than the given value
641 * *CheckSelfIntersection* checks, whether there are self-intersecting or adjacent intersecting edges. If the intersection takes place due to nonadjacent edges, it is not detected.
dba69de2 642
643This class maintains status management. Each API method stores the status of its last execution which can be queried by the corresponding *Status..()* method. In addition, each API method returns a Boolean value, which is True when a case being analyzed is detected (with the set *ShapeExtend_DONE* status), otherwise it is False.
72b7576f 644
645~~~~~
646TopoDS_Face face = ...;
647TopoDS_Wire wire = ...;
648Standard_Real precision = 1e-04;
649ShapeAnalysis_Wire saw (wire, face, precision);
650//Creates a tool and loads objects into it
651if (saw.CheckOrder()) {
4ee1bdf4 652 cout<<"Some edges in the wire need to be reordered"<<endl;
653 cout<<"Please ensure that all the edges are correctly ordered before further analysis"<<endl;
dba69de2 654 return;
72b7576f 655}
656if (saw.CheckSmall (precision)) {
4ee1bdf4 657 cout<<"Wire contains edge(s) shorter than "<<precisionendl;
72b7576f 658}
659if (saw.CheckConnected()) {
4ee1bdf4 660 cout<<"Wire is disconnected"<<endl;
72b7576f 661}
662if (saw.CheckSelfIntersection()) {
4ee1bdf4 663 cout<<"Wire has self-intersecting or intersecting adjacent edges"<< endl;
72b7576f 664}
665~~~~~
666
667@subsubsection occt_shg_3_1_3 Analysis of edge validity
668
669Class *ShapeAnalysis_Edge* is intended to analyze edges. It provides the following functionalities to work with an edge:
670 * querying geometrical representations (3D curve and pcurve(s) on a given face or surface),
671 * querying topological sub-shapes (bounding vertices),
672 * checking overlapping edges,
673 * analyzing the curves consistency:
674 + mutual orientation of the 3D curve and 2D curve (co-directions or opposite directions),
675 + correspondence of 3D and 2D curves to vertices.
676
677This class supports status management described above.
678
679~~~~~
680TopoDS_Face face = ...;
681ShapeAnalysis_Edge sae;
682//Creates a tool for analyzing an edge
683for(TopExp_Explorer Exp(face,TopAbs_EDGE);Exp.More();Exp.Next()) {
dba69de2 684 TopoDS_Edge edge = TopoDS::Edge (Exp.Current());
685 if (!sae.HasCurve3d (edge)) {
4ee1bdf4 686 cout << "Edge has no 3D curve" << endl;
dba69de2 687 }
688 Handle(Geom2d_Curve) pcurve;
689 Standard_Real cf, cl;
690 if (sae.PCurve (edge, face, pcurve, cf, cl, Standard_False)) {
691 //Returns the pcurve and its range on the given face
4ee1bdf4 692 cout<<"Pcurve range ["<<cf<<", "<<cl<<"]"<< endl;
dba69de2 693 }
694 Standard_Real maxdev;
695 if (sae.CheckSameParameter (edge, maxdev)) {
4ee1bdf4 696 //Checks the consistency of all the curves in the edge
697 cout<<"Incorrect SameParameter flag"<<endl;
dba69de2 698 }
4ee1bdf4 699 cout<<"Maximum deviation "<<maxdev<<", tolerance"
700 <<BRep_Tool::Tolerance(edge)<<endl;
72b7576f 701}
702//checks the overlapping of two edges
703if(sae.CheckOverlapping(edge1,edge2,prec,dist)) {
4ee1bdf4 704 cout<<"Edges are overlapped with tolerance = "<<prec<<endl;
705 cout<<"Domain of overlapping ="<<dist<<endl;
72b7576f 706}
707~~~~~
708
709@subsubsection occt_shg_3_1_4 Analysis of presence of small faces
710
711Class *ShapeAnalysis_CheckSmallFace* class is intended for analyzing small faces from the shape using the following methods:
712* *CheckSpotFace()* checks if the size of the face is less than the given precision;
713* *CheckStripFace* checks if the size of the face in one dimension is less than the given precision.
714
715~~~~~
716TopoDS_Shape shape … // checked shape
717//Creation of a tool
718ShapeAnalysis_CheckSmallFace saf;
719//exploring the shape on faces and checking each face
720Standard_Integer numSmallfaces =0;
721for(TopExp_Explorer aExp(shape,TopAbs_FACE); aExp.More(); aExp.Next()) {
722 TopoDS_Face face = TopoDS::Face(aexp.Current());
723 TopoDS_Edge E1,E2;
724if(saf.CheckSpotFace(face,prec) ||
725saf.CheckStripFace(face,E1,E2,prec))
726NumSmallfaces++;
727}
728if(numSmallfaces)
4ee1bdf4 729 cout<<"Number of small faces in the shape ="<< numSmallfaces <<endl;
72b7576f 730~~~~~
731
732@subsubsection occt_shg_3_1_5 Analysis of shell validity and closure
733
734Class *ShapeAnalysis_Shell* allows checking the orientation of edges in a manifold shell. With the help of this tool, free edges (edges entered into one face) and bad edges (edges entered into the shell twice with the same orientation) can be found. By occurrence of bad and free edges a conclusion about the shell validity and the closure of the shell can be made.
735
736~~~~~
737TopoDS_Shell shell // checked shape
738ShapeAnalysis_Shell sas(shell);
739//analysis of the shell , second parameter is set to True for //getting free edges,(default False)
740sas.CheckOrientedShells(shell,Standard_True);
741//getting the result of analysis
742if(sas.HasBadEdges()) {
743cout<<"Shell is invalid"<<endl;
744TopoDS_Compound badEdges = sas.BadEdges();
745}
746if(sas.HasFreeEdges()) {
747 cout<<"Shell is open"<<endl;
748 TopoDS_Compound freeEdges = sas.FreeEdges();
749}
750~~~~~
751
752@subsection occt_shg_3_2 Analysis of shape properties.
753@subsubsection occt_shg_3_2_1 Analysis of tolerance on shape
754
755Class *ShapeAnalysis_ShapeTolerance* allows computing tolerances of the shape and its sub-shapes. In Open CASCADE Technology only vertices, edges and faces have tolerances:
756
757This tool allows analyzing each concrete type of sub-shapes or all types at a time.
758The analysis of tolerance functionality is the following:
759 * computing the minimum, maximum and average tolerances of sub-shapes,
760 * finding sub-shapes with tolerances exceeding the given value,
761 * finding sub-shapes with tolerances in the given range.
762
763~~~~~
764TopoDS_Shape shape = ...;
765ShapeAnalysis_ShapeTolerance sast;
766Standard_Real AverageOnShape = sast.Tolerance (shape, 0);
4ee1bdf4 767cout<<"Average tolerance of the shape is "<<AverageOnShape<<endl;
72b7576f 768Standard_Real MinOnEdge = sast.Tolerance (shape,-1,TopAbs_EDGE);
4ee1bdf4 769cout<<"Minimum tolerance of the edges is "<<MinOnEdge<<endl;
72b7576f 770Standard_Real MaxOnVertex = sast.Tolerance (shape,1,TopAbs_VERTEX);
4ee1bdf4 771cout<<"Maximum tolerance of the vertices is "<<MaxOnVertex<<endl;
72b7576f 772Standard_Real MaxAllowed = 0.1;
4ee1bdf4 773if (MaxOnVertex > MaxAllowed) {
774 cout<<"Maximum tolerance of the vertices exceeds maximum allowed"<<endl;
72b7576f 775}
776~~~~~
777
778@subsubsection occt_shg_3_2_2 Analysis of free boundaries.
779
780Class ShapeAnalysis_FreeBounds is intended to analyze and output the free bounds of a shape. Free bounds are wires consisting of edges referenced only once by only one face in the shape.
781This class works on two distinct types of shapes when analyzing their free bounds:
782* Analysis of possible free bounds taking the specified tolerance into account. This analysis can be applied to a compound of faces. The analyzer of the sewing algorithm (*BRepAlgo_Sewing*) is used to forecast what free bounds would be obtained after the sewing of these faces is performed. The following method should be used for this analysis:
783~~~~~
784ShapeAnalysis_FreeBounds safb(shape,toler);
785~~~~~
786* Analysis of already existing free bounds. Actual free bounds (edges shared by the only face in the shell) are output in this case. *ShapeAnalysis_Shell* is used for that.
787~~~~~
788ShapeAnalysis_FreeBounds safb(shape);
789~~~~~
dba69de2 790
72b7576f 791When connecting edges into wires this algorithm tries to build wires of maximum length. Two options are provided for the user to extract closed sub-contours out of closed and/or open contours. Free bounds are returned as two compounds, one for closed and one for open wires. To obtain a result it is necessary to use methods:
792~~~~~
dba69de2 793TopoDS_Compound ClosedWires = safb.GetClosedWires();
72b7576f 794TopoDS_Compound OpenWires = safb.GetOpenWires();
795~~~~~
796This class also provides some static methods for advanced use: connecting edges/wires to wires, extracting closed sub-wires from wires, distributing wires into compounds for closed and open wires.
797
798~~~~~
799TopoDS_Shape shape = ...;
800Standard_Real SewTolerance = 1.e-03;
801//Tolerance for sewing
802Standard_Boolean SplitClosed = Standard_False;
803Standard_Boolean SplitOpen = Standard_True;
804//in case of analysis of possible free boundaries
805ShapeAnalysis_FreeBounds safb (shape, SewTolerance,
806SplitClosed, SplitOpen);
807//in case of analysis of existing free bounds
808ShapeAnalysis_FreeBounds safb (shape, SplitClosed, SplitOpen);
809//getting the results
810TopoDS_Compound ClosedWires = safb.GetClosedWires();
811//Returns a compound of closed free bounds
812TopoDS_Compound OpenWires = safb.GetClosedWires();
813//Returns a compound of open free bounds
814~~~~~
815
816@subsubsection occt_shg_3_2_3 Analysis of shape contents
817
dba69de2 818Class *ShapeAnalysis_ShapeContents* provides tools counting the number of sub-shapes and selecting a sub-shape by the following criteria:
819
72b7576f 820Methods for getting the number of sub-shapes:
821 * number of solids,
822 * number of shells,
823 * number of faces,
824 * number of edges,
825 * number of vertices.
dba69de2 826
72b7576f 827Methods for calculating the number of geometrical objects or sub-shapes with a specified type:
828 * number of free faces,
829 * number of free wires,
830 * number of free edges,
831 * number of C0 surfaces,
832 * number of C0 curves,
833 * number of BSpline surfaces,… etc
dba69de2 834
72b7576f 835and selecting sub-shapes by various criteria.
836
837The corresponding flags should be set to True for storing a shape by a specified criteria:
838 * faces based on indirect surfaces - *safc.MofifyIndirectMode() = Standard_True*;
839 * faces based on offset surfaces - *safc.ModifyOffsetSurfaceMode() = Standard_True*;
840 * edges if their 3D curves are trimmed - *safc.ModifyTrimmed3dMode() = Standard_True*;
841 * edges if their 3D curves and 2D curves are offset curves - *safc.ModifyOffsetCurveMode() = Standard_True*;
842 * edges if their 2D curves are trimmed - *safc.ModifyTrimmed2dMode() = Standard_True*;
843
844Let us, for example, select faces based on offset surfaces.
845
846~~~~~
847ShapeAnalysis_ShapeContents safc;
848//set a corresponding flag for storing faces based on the offset surfaces
849safc.ModifyOffsetSurfaceMode() = Standard_True;
850safc.Perform(shape);
851//getting the number of offset surfaces in the shape
852Standard_Integer NbOffsetSurfaces = safc.NbOffsetSurf();
853//getting the sequence of faces based on offset surfaces.
854Handle(TopTools_HSequenceOfShape) seqFaces = safc.OffsetSurfaceSec();
855~~~~~
856
857@section occt_shg_4 Upgrading
858
859Upgrading tools are intended for adaptation of shapes for better use by Open CASCADE Technology or for customization to particular needs, i.e. for export to another system. This means that not only it corrects and upgrades but also changes the definition of a shape with regard to its geometry, size and other aspects. Convenient API allows you to create your own tools to perform specific upgrading. Additional tools for particular cases provide an ability to divide shapes and surfaces according to certain criteria.
860
861@subsection occt_shg_4_1 Tools for splitting a shape according to a specified criterion
862
863@subsubsection occt_shg_4_1_1 Overview
864
865These tools provide such modifications when one topological object can be divided or converted to several ones according to specified criteria. Besides, there are high level API tools for particular cases which:
866 * Convert the geometry of shapes up to a given continuity,
867 * split revolutions by U to segments less than the given value,
868 * convert to Bezier surfaces and Bezier curves,
869 * split closed faces,
870 * convert C0 BSpline curve to a sequence of C1 BSpline curves.
dba69de2 871
72b7576f 872All tools for particular cases are based on general tools for shape splitting but each of them has its own tools for splitting or converting geometry in accordance with the specified criteria.
873
874General tools for shape splitting are:
875 * tool for splitting the whole shape,
876 * tool for splitting a face,
877 * tool for splitting wires.
dba69de2 878
72b7576f 879Tools for shape splitting use tools for geometry splitting:
880 * tool for splitting surfaces,
881 * tool for splitting 3D curves,
882 * tool for splitting 2D curves.
883
884@subsubsection occt_shg_4_1_2 Using tools available for shape splitting.
885If it is necessary to split a shape by a specified continuity, split closed faces in the shape, split surfaces of revolution in the shape by angle or to convert all surfaces, all 3D curves, all 2D curves in the shape to Bezier, it is possible to use the existing/available tools.
dba69de2 886
72b7576f 887The usual way to use these tools exception for the tool of converting a C0 BSpline curve is the following:
888 * a tool is created and initialized by shape.
889 * work precision for splitting and the maximum allowed tolerance are set
890 * the value of splitting criterion Is set (if necessary)
891 * splitting is performed.
892 * splitting statuses are obtained.
893 * result is obtained
894 * the history of modification of the initial shape and its sub-shapes is output (this step is optional).
895
896Let us, for example, split all surfaces and all 3D and 2D curves having a continuity of less the C2.
897
898~~~~~
899//create a tool and initializes it by shape.
900ShapeUpgrade_ShapeDivideContinuity ShapeDivedeCont(initShape);
901
902//set the working 3D and 2D precision and the maximum allowed //tolerance
903ShapeDivideCont.SetTolerance(prec);
904ShapeDivideCont.SetTolerance2D(prec2d);
905ShapeDivideCont.SetMaxTolerance(maxTol);
906
907//set the values of criteria for surfaces, 3D curves and 2D curves.
908ShapeDivideCont.SetBoundaryCriterion(GeomAbs_C2);
909ShapeDivideCont.SetPCurveCriterion(GeomAbs_C2);
910ShapeDivideCont.SetSurfaceCriterion(GeomAbs_C2);
911
912//perform the splitting.
913ShapeDivideCont.Perform();
914
915//check the status and gets the result
916if(ShapeDivideCont.Status(ShapeExtend_DONE)
917 TopoDS_Shape result = ShapeDivideCont.GetResult();
918//get the history of modifications made to faces
919for(TopExp_Explorer aExp(initShape,TopAbs_FACE); aExp.More(0; aExp.Next()) {
4ee1bdf4 920 TopoDS_Shape modifShape = ShapeDivideCont.GetContext()-> Apply(aExp.Current());
72b7576f 921}
922~~~~~
923
924@subsubsection occt_shg_4_1_3 Creation of a new tool for splitting a shape.
dba69de2 925To create a new splitting tool it is necessary to create tools for geometry splitting according to a desirable criterion. The new tools should be inherited from basic tools for geometry splitting. Then the new tools should be set into corresponding tools for shape splitting.
926 * a new tool for surface splitting should be set into the tool for face splitting
927 * new tools for splitting of 3D and 2D curves should be set into the splitting tool for wires.
928
929To change the value of criterion of shape splitting it is necessary to create a new tool for shape splitting that should be inherited from the general splitting tool for shapes.
72b7576f 930
931Let us split a shape according to a specified criterion.
932
933~~~~~
4ee1bdf4 934//creation of new tools for geometry splitting by a specified criterion.
935Handle(MyTools_SplitSurfaceTool) MySplitSurfaceTool = new MyTools_SplitSurfaceTool;
936Handle(MyTools_SplitCurve3DTool) MySplitCurve3Dtool = new MyTools_SplitCurve3DTool;
937Handle(MyTools_SplitCurve2DTool) MySplitCurve2Dtool = new MyTools_SplitCurve2DTool;
72b7576f 938
4ee1bdf4 939//creation of a tool for splitting the shape and initialization of that tool by shape.
72b7576f 940TopoDS_Shape initShape
941MyTools_ShapeDivideTool ShapeDivide (initShape);
942
4ee1bdf4 943//setting of work precision for splitting and maximum allowed tolerance.
72b7576f 944ShapeDivide.SetPrecision(prec);
945ShapeDivide.SetMaxTolerance(MaxTol);
946
4ee1bdf4 947//setting of new splitting geometry tools in the shape splitting tools
948Handle(ShapeUpgrade_FaceDivide) FaceDivide = ShapeDivide->GetSplitFaceTool();
949Handle(ShapeUpgrade_WireDivide) WireDivide = FaceDivide->GetWireDivideTool();
950FaceDivide->SetSplitSurfaceTool(MySplitSurfaceTool);
951WireDivide->SetSplitCurve3dTool(MySplitCurve3DTool);
952WireDivide->SetSplitCurve2dTool(MySplitCurve2DTool);
72b7576f 953
954//setting of the value criterion.
dba69de2 955 ShapeDivide.SetValCriterion(val);
956
72b7576f 957//shape splitting
958ShapeDivide.Perform();
959
960//getting the result
961TopoDS_Shape splitShape = ShapeDivide.GetResult();
962
963//getting the history of modifications of faces
964for(TopExp_Explorer aExp(initShape,TopAbs_FACE); aExp.More(0; aExp.Next()) {
4ee1bdf4 965TopoDS_Shape modifShape = ShapeDivide.GetContext()-> Apply(aExp.Current());
72b7576f 966}
967~~~~~
968
969@subsection occt_shg_4_2 General splitting tools.
970
971@subsubsection occt_shg_4_2_1 General tool for shape splitting
972
dba69de2 973Class *ShapeUpgrade_ShapeDivide* provides shape splitting and converting according to the given criteria. It performs these operations for each face with the given tool for face splitting (*ShapeUpgrade_FaceDivide* by default).
974
975This tool provides access to the tool for dividing faces with the help of the methods *SetSplitFaceTool* and *GetSpliFaceTool.*
72b7576f 976
977@subsubsection occt_shg_4_2_2 General tool for face splitting
dba69de2 978
979Class *ShapeUpgrade_FaceDivide* divides a Face (edges in the wires, by splitting 3D and 2D curves, as well as the face itself, by splitting the supporting surface) according to the given criteria.
980
72b7576f 981The area of the face intended for division is defined by 2D curves of the wires on the Face.
982All 2D curves are supposed to be defined (in the parametric space of the supporting surface).
983The result is available after the call to the *Perform* method. It is a Shell containing all resulting Faces. All modifications made during the splitting operation are recorded in the external context (*ShapeBuild_ReShape*).
dba69de2 984
985This tool provides access to the tool for wire division and surface splitting by means of the following methods:
986* *SetWireDivideTool,*
987* *GetWireDivideTool,*
988* *SetSurfaceSplitTool,*
989* *GetSurfaceSplitTool*.
72b7576f 990
991@subsubsection occt_shg_4_2_3 General tool for wire splitting
992Class *ShapeUpgrade_WireDivide* divides edges in the wire lying on the face or free wires or free edges with a given criterion. It splits the 3D curve and 2D curve(s) of the edge on the face. Other 2D curves, which may be associated with the edge, are simply copied. If the 3D curve is split then the 2D curve on the face is split as well, and vice-versa. The original shape is not modified. Modifications made are recorded in the context (*ShapeBuild_ReShape*).
dba69de2 993
994This tool provides access to the tool for dividing and splitting 3D and 2D curves by means of the following methods:
995* *SetEdgeDivdeTool,*
996* *GetEdgeDivideTool,*
997* *SetSplitCurve3dTool,*
998* *GetSplitCurve3dTool,*
999* *SetSplitCurve2dTool,*
1000* *GetSplitCurve2dTool*
1001
1002and it also provides access to the mode for splitting edges by methods *SetEdgeMode* and *GetEdgeMode*.
1003
72b7576f 1004This mode sets whether only free edges, only shared edges or all edges are split.
1005
dba69de2 1006@subsubsection occt_shg_4_2_4 General tool for edge splitting
1007
72b7576f 1008Class *ShapeUpgrade_EdgeDivide* divides edges and their geometry according to the specified criteria. It is used in the wire-dividing tool.
dba69de2 1009
72b7576f 1010This tool provides access to the tool for dividing and splitting 3D and 2D curves by the following methods:
dba69de2 1011* *SetSplitCurve3dTool,*
1012* *GetSplitCurve3dTool,*
1013* *SetSplitCurve2dTool,*
1014* *GetSplitCurve2dTool*.
72b7576f 1015
1016@subsubsection occt_shg_4_2_5 General tools for geometry splitting
4ee1bdf4 1017
72b7576f 1018There are three general tools for geometry splitting.
1019 * General tool for surface splitting.(*ShapeUpgrade_SplitSurface*)
1020 * General tool for splitting 3D curves.(*ShapeUpgrade_SplitCurve3d*)
1021 * General tool for splitting 2D curves.(*ShapeUpgrade_SplitCurve2d*)
dba69de2 1022
72b7576f 1023All these tools are constructed the same way:
1024They have methods:
1025 * for initializing by geometry (method *Init*)
1026 * for splitting (method *Perform*)
1027 * for getting the status after splitting and the results:
dba69de2 1028 + *Status* – for getting the result status;
1029 + *ResSurface* - for splitting surfaces;
72b7576f 1030 + *GetCurves* - for splitting 3D and 2D curves.
1031During the process of splitting in the method *Perform* :
dba69de2 1032 * splitting values in the parametric space are computed according to a specified criterion (method *Compute*)
72b7576f 1033 * splitting is made in accordance with the values computed for splitting (method *Build*).
1034
1035To create new tools for geometry splitting it is enough to inherit a new tool from the general tool for splitting a corresponding type of geometry and to re-define the method for computation of splitting values according to the specified criterion in them. (method *Compute*).
1036
1037Header file for the tool for surface splitting by continuity:
1038
1039~~~~~
1040class ShapeUpgrade_SplitSurfaceContinuity : public ShapeUpgrade_SplitSurface {
1041Standard_EXPORT ShapeUpgrade_SplitSurfaceContinuity();
1042
4ee1bdf4 1043//methods to set the criterion and the tolerance into the splitting tool
dba69de2 1044Standard_EXPORT void SetCriterion(const GeomAbs_Shape Criterion) ;
1045Standard_EXPORT void SetTolerance(const Standard_Real Tol) ;
72b7576f 1046
4ee1bdf4 1047//redefinition of method Compute
72b7576f 1048Standard_EXPORT virtual void Compute(const Standard_Boolean Segment) ;
1049Standard_EXPORT ~ShapeUpgrade_SplitSurfaceContinuity();
1050private:
1051GeomAbs_Shape myCriterion;
1052Standard_Real myTolerance;
1053Standard_Integer myCont;
1054};
1055~~~~~
1056
1057@subsection occt_shg_4_3 Specific splitting tools.
1058
1059@subsubsection occt_shg_4_3_1 Conversion of shape geometry to the target continuity
1060Class *ShapeUpgrade_ShapeDivideContinuity* allows converting geometry with continuity less than the specified continuity to geometry with target continuity. If converting is not possible than geometrical object is split into several ones, which satisfy the given criteria. A topological object based on this geometry is replaced by several objects based on the new geometry.
1061
1062~~~~~
1063ShapeUpgrade_ShapeDivideContinuity sdc (shape);
1064sdc.SetTolerance (tol3d);
1065sdc.SetTolerance3d (tol2d); // if known, else 1.e-09 is taken
1066sdc.SetBoundaryCriterion (GeomAbs_C2); // for Curves 3D
1067sdc.SetPCurveCriterion (GeomAbs_C2); // for Curves 2D
1068sdc.SetSurfaceCriterion (GeomAbs_C2); // for Surfaces
1069sdc.Perform ();
1070TopoDS_Shape bshape = sdc.Result();
4ee1bdf4 1071//.. to also get the correspondances before/after
72b7576f 1072Handle(ShapeBuild_ReShape) ctx = sdc.Context();
4ee1bdf4 1073//.. on a given shape
72b7576f 1074if (ctx.IsRecorded (sh)) {
dba69de2 1075 TopoDS_Shape newsh = ctx->Value (sh);
4ee1bdf4 1076// if there are several results, they are recorded inside a Compound.
72b7576f 1077// .. process as needed
1078}
1079~~~~~
1080
1081@subsubsection occt_shg_4_3_2 Splitting by angle
1082Class *ShapeUpgrade_ShapeDivideAngle* allows splitting all surfaces of revolution, cylindrical, toroidal, conical, spherical surfaces in the given shape so that each resulting segment covers not more than the defined angle (in radians).
1083
1084@subsubsection occt_shg_4_3_3 Conversion of 2D, 3D curves and surfaces to Bezier
1085
dba69de2 1086Class *ShapeUpgrade_ShapeConvertToBezier* is an API tool for performing a conversion of 3D, 2D curves to Bezier curves and surfaces to Bezier based surfaces (Bezier surface, surface of revolution based on Bezier curve, offset surface based on any of previous types).
1087
72b7576f 1088This tool provides access to various flags for conversion of different types of curves and surfaces to Bezier by methods:
dba69de2 1089* For 3D curves:
1090 * *Set3dConversion,*
1091 * *Get3dConversion,*
1092 * *Set3dLineConversion,*
1093 * *Get3dLineConversion,*
1094 * *Set3dCircleConversion,*
1095 * *Get3dCircleConversion,*
1096 * *Set3dConicConversion,*
1097 * *Get3dConicConversion*
1098* For 2D curves:
1099 * *Set2dConversion,*
1100 * *Get2dConversion*
1101* For surfaces :
1102 * *GetSurfaceConversion,*
1103 * *SetPlaneMode,*
1104 * *GetPlaneMode,*
1105 * *SetRevolutionMode,*
1106 * *GetRevolutionMode,*
1107 * *SetExtrusionMode,*
1108 * *GetExtrusionMode,*
1109 * *SetBSplineMode,*
1110 * *GetBSplineMode,*
72b7576f 1111
1112Let us attempt to produce a conversion of planes to Bezier surfaces.
1113~~~~~
1114//Creation and initialization of a tool.
1115ShapeUpgrade_ShapeConvertToBezier SCB (Shape);
1116//setting tolerances
4ee1bdf4 1117...
72b7576f 1118//setting mode for conversion of planes
1119SCB.SetSurfaceConversion (Standard_True);
1120SCB.SetPlaneMode(Standard_True);
1121SCB.Perform();
1122If(SCB.Status(ShapeExtend_DONE)
dba69de2 1123 TopoDS_Shape result = SCB.GetResult();
72b7576f 1124~~~~~
1125
1126@subsubsection occt_shg_4_3_4 Tool for splitting closed faces
1127
1128Class *ShapeUpgrade_ShapeDivideClosed* provides splitting of closed faces in the shape to a defined number of components by the U and V parameters. It topologically and (partially) geometrically processes closed faces and performs splitting with the help of class *ShapeUpgrade_ClosedFaceDivide*.
1129
1130~~~~~
1131TopoDS_Shape aShape = …;
1132ShapeUpgrade_ShapeDivideClosed tool (aShape );
1133Standard_Real closeTol = …;
1134tool.SetPrecision(closeTol);
1135Standard_Real maxTol = …;
1136tool.SetMaxTolerance(maxTol);
1137Standard_Integer NbSplitPoints = …;
1138tool.SetNbSplitPoints(num);
e5bd0d98 1139if ( ! tool.Perform() && tool.Status (ShapeExtend_FAIL) ) {
4ee1bdf4 1140 cout<<"Splitting of closed faces failed"<<endl;
dba69de2 1141 . . .
72b7576f 1142}
1143TopoDS_Shape aResult = tool.Result();
1144~~~~~
1145
1146@subsubsection occt_shg_4_3_5 Tool for splitting a C0 BSpline 2D or 3D curve to a sequence C1 BSpline curves
1147
1148The API methods for this tool is a package of methods *ShapeUpgrade::C0BSplineToSequenceOfC1BsplineCurve*, which converts a C0 B-Spline curve into a sequence of C1 B-Spline curves. This method splits a B-Spline at the knots with multiplicities equal to degree, it does not use any tolerance and therefore does not change the geometry of the B-Spline. The method returns True if C0 B-Spline was successfully split, otherwise returns False (if BS is C1 B-Spline).
1149
1150@subsubsection occt_shg_4_3_6 Tool for splitting faces
1151
1152*ShapeUpgrade_ShapeDivideArea* can work with compounds, solids, shells and faces.
dba69de2 1153During the work this tool examines each face of a specified shape and if the face area exceeds the specified maximal area, this face is divided. Face splitting is performed in the parametric space of this face. The values of splitting in U and V directions are calculated with the account of translation of the bounding box form parametric space to 3D space.
1154
1155Such calculations are necessary to avoid creation of strip faces. In the process of splitting the holes on the initial face are taken into account. After the splitting all new faces are checked by area again and the splitting procedure is repeated for the faces whose area still exceeds the max allowed area. Sharing between faces in the shape is preserved and the resulting shape is of the same type as the source shape.
1156
72b7576f 1157An example of using this tool is presented in the figures below:
1158
e5bd0d98 1159@image html /user_guides/shape_healing/images/shape_healing_image003.png "Source Face"
1160@image latex /user_guides/shape_healing/images/shape_healing_image003.png "Source Face"
72b7576f 1161
e5bd0d98 1162@image html /user_guides/shape_healing/images/shape_healing_image004.png "Resulting shape"
1163@image latex /user_guides/shape_healing/images/shape_healing_image004.png "Resulting shape"
72b7576f 1164
1165
1166*ShapeUpgrade_ShapeDivideArea* is inherited from the base class *ShapeUpgrade_ShapeDivide* and should be used in the following way:
1167* This class should be initialized on a shape with the help of the constructor or method *Init()* from the base class.
1168* The maximal allowed area should be specified by the method *MaxArea()*.
1169* To produce a splitting use method Perform from the base class.
1170* The result shape can be obtained with the help the method *Result()*.
1171
1172~~~~~
1173ShapeUpgrade_ShapeDivideArea tool (inputShape);
1174tool.MaxArea() = aMaxArea;
1175tool.Perform();
1176if(tool.Status(ShapeExtend_DONE)) {
dba69de2 1177 TopoDS_Shape ResultShape = tool.Result();
1178 ShapeFix::SameParameter ( ResultShape, Standard_False );
72b7576f 1179}
1180~~~~~
1181
1182**Note** that the use of method *ShapeFix::SameParameter* is necessary, otherwise the parameter edges obtained as a result of splitting can be different.
1183
dba69de2 1184#### Additional methods
1185
72b7576f 1186* Class *ShapeUpgrade_FaceDivideArea* inherited from *ShapeUpgrade_FaceDivide* is intended for splitting a face by the maximal area criterion.
1187* Class *ShapeUpgrade_SplitSurfaceArea* inherited from *ShapeUpgrade_SplitSurface* calculates the parameters of face splitting in the parametric space.
1188
1189
1190@subsection occt_shg_4_4 Customization of shapes
1191
1192Customization tools are intended for adaptation of shape geometry in compliance with the customer needs. They modify a geometrical object to another one in the shape.
1193
1194To implement the necessary shape modification it is enough to initialize the appropriate tool by the shape and desirable parameters and to get the resulting shape. For example for conversion of indirect surfaces in the shape do the following:
1195
1196~~~~~
1197TopoDS_Shape initialShape ..
1198TopoDS_Shape resultShape = ShapeCustom::DirectFaces(initialShape);
1199~~~~~
1200
dba69de2 1201@subsubsection occt_shg_4_4_1 Conversion of indirect surfaces.
72b7576f 1202
1203~~~~~
1204ShapeCustom::DirectFaces
1205 static TopoDS_Shape DirectFaces(const TopoDS_Shape& S);
1206~~~~~
1207
4ee1bdf4 1208This method provides conversion of indirect elementary surfaces (elementary surfaces with left-handed coordinate systems) in the shape into direct ones. New 2d curves (recomputed for converted surfaces) are added to the same edges being shared by both the resulting shape and the original shape *S*.
72b7576f 1209
dba69de2 1210@subsubsection occt_shg_4_4_2 Shape Scaling
72b7576f 1211
1212~~~~~
1213ShapeCustom::ScaleShape
1214 TopoDS_Shape ShapeCustom::ScaleShape(const TopoDS_Shape& S,
1215 const Standard_Real scale);
1216~~~~~
1217
1218This method returns a new shape, which is a scaled original shape with a coefficient equal to the specified value of scale. It uses the tool *ShapeCustom_TrsfModification*.
1219
dba69de2 1220@subsubsection occt_shg_4_4_3 Conversion of curves and surfaces to BSpline
1221
1222*ShapeCustom_BSplineRestriction* allows approximation of surfaces, curves and 2D curves with a specified degree, maximum number of segments, 2d tolerance and 3d tolerance. If the approximation result cannot be achieved with the specified continuity, the latter can be reduced.
72b7576f 1223
1224The method with all parameters looks as follows:
1225~~~~~
1226ShapeCustom::BsplineRestriction
e5bd0d98 1227 TopoDS_Shape ShapeCustom::BSplineRestriction (const TopoDS_Shape& S,
72b7576f 1228 const Standard_Real Tol3d, const Standard_Real Tol2d,
1229 const Standard_Integer MaxDegree,
1230 const Standard_Integer MaxNbSegment,
1231 const GeomAbs_Shape Continuity3d,
1232 const GeomAbs_Shape Continuity2d,
1233 const Standard_Boolean Degree,
1234 const Standard_Boolean Rational,
e5bd0d98 1235 const Handle(ShapeCustom_RestrictionParameters)& aParameters)
72b7576f 1236~~~~~
1237
dba69de2 1238It returns a new shape with all surfaces, curves and 2D curves of BSpline/Bezier type or based on them, converted with a degree less than *MaxDegree* or with a number of spans less then *NbMaxSegment* depending on the priority parameter *Degree*. If this parameter is equal to True then *Degree* will be increased to the value *GmaxDegree*, otherwise *NbMaxSegments* will be increased to the value *GmaxSegments*. *GmaxDegree* and *GMaxSegments* are the maximum possible degree and the number of spans correspondingly. These values will be used in cases when an approximation with specified parameters is impossible and either *GmaxDegree* or *GMaxSegments* is selected depending on the priority.
1239
4ee1bdf4 1240Note that if approximation is impossible with *GMaxDegree*, even then the number of spans can exceed the specified *GMaxSegment*. *Rational* specifies whether Rational BSpline/Bezier should be converted into polynomial B-Spline.
dba69de2 1241
72b7576f 1242Also note that the continuity of surfaces in the resulting shape can be less than the given value.
1243
dba69de2 1244#### Flags
1245
72b7576f 1246To convert other types of curves and surfaces to BSpline with required parameters it is necessary to use flags from class ShapeCustom_RestrictionParameters, which is just a container of flags.
1247The following flags define whether a specified-type geometry has been converted to BSpline with the required parameters:
4ee1bdf4 1248* *ConvertPlane,*
1249* *ConvertBezierSurf,*
1250* *ConvertRevolutionSurf,*
1251* *ConvertExtrusionSurf,*
dba69de2 1252* *ConvertOffsetSurf,*
1253* *ConvertCurve3d,* - for conversion of all types of 3D curves.
1254* *ConvertOffsetCurv3d,* - for conversion of offset 3D curves.
1255* *ConvertCurve2d,* - for conversion of all types of 2D curves.
1256* *ConvertOffsetCurv2d,* - for conversion of offset 2D curves.
1257* *SegmentSurfaceMode* - defines whether the surface would be approximated within the boundaries of the face lying on this surface.
72b7576f 1258
72b7576f 1259
dba69de2 1260
1261@subsubsection occt_shg_4_4_4 Conversion of elementary surfaces into surfaces of revolution
72b7576f 1262
1263~~~~~
1264ShapeCustom::ConvertToRevolution()
1265 TopoDS_Shape ShapeCustom::ConvertToRevolution(const TopoDS_Shape& S) ;
1266~~~~~
1267
dba69de2 1268This method returns a new shape with all elementary periodic surfaces converted to *Geom_SurfaceOfRevolution*. It uses the tool *ShapeCustom_ConvertToRevolution*.
72b7576f 1269
dba69de2 1270@subsubsection occt_shg_4_4_5 Conversion of elementary surfaces into Bspline surfaces
72b7576f 1271
1272~~~~~
1273ShapeCustom::ConvertToBSpline()
e5bd0d98 1274 TopoDS_Shape ShapeCustom::ConvertToBSpline( const TopoDS_Shape& S,
72b7576f 1275 const Standard_Boolean extrMode,
1276 const Standard_Boolean revolMode,
1277 const Standard_Boolean offsetMode);
dba69de2 1278~~~~~
1279
1280This method returns a new shape with all surfaces of linear extrusion, revolution and offset surfaces converted according to flags to *Geom_BSplineSurface* (with the same parameterization). It uses the tool *ShapeCustom_ConvertToBSpline*.
72b7576f 1281
dba69de2 1282@subsubsection occt_shg_4_4_6 Getting the history of modification of sub-shapes.
72b7576f 1283If, in addition to the resulting shape, you want to get the history of modification of sub-shapes you should not use the package methods described above and should use your own code instead:
12841. Create a tool that is responsible for the necessary modification.
dba69de2 12852. Create the tool *BRepTools_Modifier* that performs a specified modification in the shape.
72b7576f 12863. To get the history and to keep the assembly structure use the method *ShapeCustom::ApplyModifier*.
1287
1288
1289The general calling syntax for scaling is
1290~~~~~
1291TopoDS_Shape scaled_shape = ShapeCustom::ScaleShape(shape, scale);
1292~~~~~
1293
1294Note that scale is a real value. You can refine your mapping process by using additional calls to follow shape mapping subshape by subshape. The following code along with pertinent includes can be used:
1295
1296~~~~~
1297p_Trsf T;
1298Standard_Real scale = 100; // for example!
1299T.SetScale (gp_Pnt (0, 0, 0), scale);
1300Handle(ShapeCustom_TrsfModification) TM = new
1301ShapeCustom_TrsfModification(T);
1302TopTools_DataMapOfShapeShape context;
1303BRepTools_Modifier MD;
1304TopoDS_Shape res = ShapeCustom::ApplyModifier (
1305Shape, TM, context,MD );
1306~~~~~
1307
1308The map, called context in our example, contains the history.
1309Substitutions are made one by one and all shapes are transformed.
1310To determine what happens to a particular subshape, it is possible to use:
1311
1312~~~~~
1313TopoDS_Shape oneres = context.Find (oneshape);
1314//In case there is a doubt, you can also add:
1315if (context.IsBound(oneshape)) oneres = context.Find(oneshape);
1316//You can also sweep the entire data map by using:
1317TopTools_DataMapIteratorOfDataMapOfShapeShape
1318//To do this, enter:
1319for(TopTools_DataMapIteratorOfDataMapOfShapeShape
1320iter(context);iter(more ();iter.next ()) {
dba69de2 1321 TopoDs_Shape oneshape = iter.key ();
1322 TopoDs_Shape oneres = iter.value ();
72b7576f 1323}
1324~~~~~
1325
1326
dba69de2 1327@subsubsection occt_shg_4_4_7 Remove internal wires
72b7576f 1328
1329*ShapeUpgrade_RemoveInternalWires* tool removes internal wires with contour area less than the specified minimal area. It can work with compounds, solids, shells and faces.
dba69de2 1330
72b7576f 1331If the flag *RemoveFaceMode* is set to TRUE, separate faces or a group of faces with outer wires, which consist only of edges that belong to the removed internal wires, are removed (seam edges are not taken into account). Such faces can be removed only for a sewed shape.
dba69de2 1332
72b7576f 1333Internal wires can be removed by the methods *Perform*. Both methods *Perform* can not be carried out if the class has not been initialized by the shape. In such case the status of *Perform* is set to FAIL .
dba69de2 1334
72b7576f 1335The method *Perform* without arguments removes from all faces in the specified shape internal wires whose area is less than the minimal area.
dba69de2 1336
72b7576f 1337The other method *Perform* has a sequence of shapes as an argument. This sequence can contain faces or wires.
1338If the sequence of shapes contains wires, only the internal wires are removed.
dba69de2 1339
72b7576f 1340If the sequence of shapes contains faces, only the internal wires from these faces are removed.
dba69de2 1341
72b7576f 1342* The status of the performed operation can be obtained using method *Status()*;
1343* The resulting shape can be obtained using method *GetResult()*.
1344
1345An example of using this tool is presented in the figures below:
1346
e5bd0d98 1347@image html /user_guides/shape_healing/images/shape_healing_image005.png "Source Face"
1348@image latex /user_guides/shape_healing/images/shape_healing_image005.png "Source Face"
1349@image html /user_guides/shape_healing/images/shape_healing_image006.png "Resulting shape"
1350@image latex /user_guides/shape_healing/images/shape_healing_image006.png "Resulting shape"
72b7576f 1351
1352After the processing three internal wires with contour area less than the specified minimal area have been removed. One internal face has been removed. The outer wire of this face consists of the edges belonging to the removed internal wires and a seam edge.
1353Two other internal faces have not been removed because their outer wires consist not only of edges belonging to the removed wires.
1354
e5bd0d98 1355@image html /user_guides/shape_healing/images/shape_healing_image007.png "Source Face"
1356@image latex /user_guides/shape_healing/images/shape_healing_image007.png "Source Face"
dba69de2 1357
e5bd0d98 1358@image html /user_guides/shape_healing/images/shape_healing_image008.png "Resulting shape"
1359@image latex /user_guides/shape_healing/images/shape_healing_image008.png "Resulting shape"
72b7576f 1360
1361After the processing six internal wires with contour area less than the specified minimal area have been removed. Six internal faces have been removed. These faces can be united into groups of faces. Each group of faces has an outer wire consisting only of edges belonging to the removed internal wires. Such groups of faces are also removed.
1362
1363The example of method application is also given below:
1364
1365~~~~~
4ee1bdf4 1366//Initialization of the class by shape.
72b7576f 1367Handle(ShapeUpgrade_RemoveInternalWires) aTool = new ShapeUpgrade_RemoveInternalWires(inputShape);
1368//setting parameters
4ee1bdf4 1369aTool->MinArea() = aMinArea;
1370aTool->RemoveFaceMode() = aModeRemoveFaces;
72b7576f 1371
1372//when method Perform is carried out on separate shapes.
4ee1bdf4 1373aTool->Perform(aSeqShapes);
72b7576f 1374
1375//when method Perform is carried out on whole shape.
4ee1bdf4 1376aTool->Perform();
72b7576f 1377//check status set after method Perform
4ee1bdf4 1378if(aTool->Status(ShapeExtend_FAIL) {
1379 cout<<"Operation failed"<< <<"\n";
dba69de2 1380 return;
72b7576f 1381}
1382
4ee1bdf4 1383if(aTool->Status(ShapeExtend_DONE1)) {
1384 const TopTools_SequenceOfShape& aRemovedWires =aTool->RemovedWires();
1385 cout<<aRemovedWires.Length()<<" internal wires were removed"<<"\n";
dba69de2 1386
1387 }
72b7576f 1388
4ee1bdf4 1389 if(aTool->Status(ShapeExtend_DONE2)) {
1390 const TopTools_SequenceOfShape& aRemovedFaces =aTool->RemovedFaces();
1391 cout<<aRemovedFaces.Length()<<" small faces were removed"<<"\n";
dba69de2 1392
1393 }
1394 //getting result shape
4ee1bdf4 1395 TopoDS_Shape res = aTool->GetResult();
72b7576f 1396~~~~~
1397
dba69de2 1398@subsubsection occt_shg_4_4_8 Conversion of surfaces
72b7576f 1399
1400Class ShapeCustom_Surface allows:
1401 * converting BSpline and Bezier surfaces to the analytical form (using method *ConvertToAnalytical())*
1402 * converting closed B-Spline surfaces to periodic ones.(using method *ConvertToPeriodic*)
1403
1404To convert surfaces to analytical form this class analyzes the form and the closure of the source surface and defines whether it can be approximated by analytical surface of one of the following types:
1405* *Geom_Plane,*
1406* *Geom_SphericalSurface,*
1407* *Geom_CylindricalSurface,*
1408* *Geom_ConicalSurface,*
1409* *Geom_ToroidalSurface*.
1410
1411The conversion is done only if the new (analytical) surface does not deviate from the source one more than by the given precision.
1412
1413~~~~~
1414Handle(Geom_Surface) initSurf;
1415ShapeCustom_Surface ConvSurf(initSurf);
1416//conversion to analytical form
dba69de2 1417Handle(Geom_Surface) newSurf = ConvSurf.ConvertToAnalytical(allowedtol,Standard_False);
72b7576f 1418//or conversion to a periodic surface
dba69de2 1419Handle(Geom_Surface) newSurf = ConvSurf.ConvertToPeriodic(Standard_False);
72b7576f 1420//getting the maximum deviation of the new surface from the initial surface
1421Standard_Real maxdist = ConvSurf.Gap();
1422~~~~~
1423
1424@section occt_shg_5_ Auxiliary tools for repairing, analysis and upgrading
ba06f8bb 1425
72b7576f 1426@subsection occt_shg_5_1 Tool for rebuilding shapes
1427
ba06f8bb 1428 Class *ShapeBuild_ReShape* rebuilds a shape by making pre-defined substitutions on some of its components. During the first phase, it records requests to replace or remove some individual shapes. For each shape, the last given request is recorded. Requests may be applied as *Oriented* (i.e. only to an item with the same orientation) or not (the orientation of the replacing shape corresponds to that of the original one). Then these requests may be applied to any shape, which may contain one or more of these individual shapes.
dba69de2 1429
72b7576f 1430This tool has a flag for taking the location of shapes into account (for keeping the structure of assemblies) (*ModeConsiderLocation*). If this mode is equal to Standard_True, the shared shapes with locations will be kept. If this mode is equal to Standard_False, some different shapes will be produced from one shape with different locations after rebuilding. By default, this mode is equal to Standard_False.
dba69de2 1431
72b7576f 1432To use this tool for the reconstruction of shapes it is necessary to take the following steps:
14331. Create this tool and use method *Apply()* for its initialization by the initial shape. Parameter *until* sets the level of shape type and requests are taken into account up to this level only. Sub-shapes of the type standing beyond the *line* set by parameter until will not be rebuilt and no further exploration will be done
14342. Replace or remove sub-shapes of the initial shape. Each sub-shape can be replaced by a shape of the same type or by shape containing shapes of that type only (for example, *TopoDS_Edge* can be replaced by *TopoDS_Edge, TopoDS_Wire* or *TopoDS_Compound* containing *TopoDS_Edges*). If an incompatible shape type is encountered, it is ignored and flag FAIL1 is set in Status.
1435For a sub-shape it is recommended to use method *Apply* before methods *Replace* and *Remove*, because the sub-shape has already been changed for the moment by its previous modifications or modification of its sub-shape (for example *TopoDS_Edge* can be changed by a modification of its *TopoDS_Vertex*, etc.).
14363. Use method *Apply* for the initial shape again to get the resulting shape after all modifications have been made.
14374. Use method *Apply* to obtain the history of sub-shape modification.
1438
1439**Note** that in fact class *ShapeBuild_ReShape* is an alias for class *BRepTools_ReShape*. They differ only in queries of statuses in the *ShapeBuild_ReShape* class.
1440
1441Let us use the tool to get the result shape after modification of sub-shapes of the initial shape:
1442
1443~~~~~
1444TopoDS_Shape initialShape…
1445//creation of a rebuilding tool
1446Handle(ShapeBuild_ReShape) Context = new ShapeBuild_ReShape.
1447
4ee1bdf4 1448//next step is optional. It can be used for keeping the assembly structure.
1449Context-> ModeConsiderLocation = Standard_True;
72b7576f 1450
1451//initialization of this tool by the initial shape
4ee1bdf4 1452Context->Apply(initialShape);
72b7576f 1453
4ee1bdf4 1454//getting the intermediate result for replacing subshape1 with the modified subshape1.
1455TopoDS_Shape tempshape1 = Context->Apply(subshape1);
72b7576f 1456
4ee1bdf4 1457//replacing the intermediate shape obtained from subshape1 with the newsubshape1.
1458Context->Replace(tempsubshape1,newsubshape1);
72b7576f 1459
1460//for removing the subshape
4ee1bdf4 1461TopoDS_Shape tempshape2 = Context->Apply(subshape2);
1462Context->Remove(tempsubshape2);
72b7576f 1463
1464//getting the result and the history of modification
4ee1bdf4 1465TopoDS_Shape resultShape = Context->Apply(initialShape);
72b7576f 1466
4ee1bdf4 1467//getting the resulting subshape from the subshape1 of the initial shape.
1468TopoDS_Shape result_subshape1 = Context->Apply(subshape1);
72b7576f 1469~~~~~
1470
1471@subsection occt_shg_5_2 Status definition
1472
4ee1bdf4 1473*ShapExtend_Status* is used to report the status after executing some methods that can either fail, do something, or do nothing. The status is a set of flags *DONEi* and *FAILi*. Any combination of them can be set at the same time. For exploring the status, enumeration is used.
dba69de2 1474
72b7576f 1475The values have the following meaning:
4ee1bdf4 1476
e5bd0d98 1477| Value | Meaning |
1478| :----- | :----------------- |
4ee1bdf4 1479| *OK,* | Nothing is done, everything OK |
1480| *DONE1,* | Something was done, case 1 |
1481| *DONE8*, | Something was done, case 8 |
1482| *DONE*, | Something was done (any of DONE#) |
1483| *FAIL1*, | The method failed, case 1 |
1484| *FAIL8*, | The method failed, case 8 |
1485| *FAIL* | The method failed (any of FAIL# occurred) |
72b7576f 1486
1487
1488@subsection occt_shg_5_3 Tool representing a wire
1489Class *ShapeExtend_WireData* provides a data structure necessary to work with the wire as with an ordered list of edges, and that is required for many algorithms. The advantage of this class is that it allows to work with incorrect wires.
dba69de2 1490
72b7576f 1491The object of the class *ShapeExtend_WireData* can be initialized by *TopoDS_Wire* and converted back to *TopoDS_Wire*.
dba69de2 1492
72b7576f 1493An edge in the wire is defined by its rank number. Operations of accessing, adding and removing an edge at/to the given rank number are provided. Operations of circular permutation and reversing (both orientations of all edges and the order of edges) are provided on the whole wire as well.
dba69de2 1494
72b7576f 1495This class also provides a method to check if the edge in the wire is a seam (if the wire lies on a face).
dba69de2 1496
72b7576f 1497Let us remove edges from the wire and define whether it is seam edge
1498
1499~~~~~
1500TopoDS_Wire ini = ..
1501Handle(ShapeExtend_Wire) asewd = new ShapeExtend_Wire(initwire);
1502//Removing edge Edge1 from the wire.
1503
1504Standard_Integer index_edge1 = asewd->Index(Edge1);
1505asewd.Remove(index_edge1);
1506//Definition of whether Edge2 is a seam edge
1507Standard_Integer index_edge2 = asewd->Index(Edge2);
1508asewd->IsSeam(index_edge2);
1509~~~~~
1510
1511
1512@subsection occt_shg_5_4 Tool for exploring shapes
1513Class *ShapeExtend_Explorer* is intended to explore shapes and convert different representations (list, sequence, compound) of complex shapes. It provides tools for:
1514 * obtaining the type of the shapes in the context of *TopoDS_Compound*,
1515 * exploring shapes in the context of *TopoDS_Compound*,
1516 * converting different representations of shapes (list, sequence, compound).
1517
1518@subsection occt_shg_5_5 Tool for attaching messages to objects
1519Class *ShapeExtend_MsgRegistrator* attaches messages to objects (generic Transient or shape). The objects of this class are transmitted to the Shape Healing algorithms so that they could collect messages occurred during shape processing. Messages are added to the Maps (stored as a field) that can be used, for instance, by Data Exchange processors to attach those messages to initial file entities.
1520
1521Let us send and get a message attached to object:
1522
1523~~~~~
1524Handle(ShapeExtend_MsgRegistrator) MessageReg = new ShapeExtend_MsgRegistrator;
1525//attaches messages to an object (shape or entity)
1526Message_Msg msg..
1527TopoDS_Shape Shape1…
4ee1bdf4 1528MessageReg->Send(Shape1,msg,Message_WARNING);
72b7576f 1529Handle(Standard_Transient) ent ..
4ee1bdf4 1530MessageReg->Send(ent,msg,Message_WARNING);
72b7576f 1531//gets messages attached to shape
4ee1bdf4 1532const ShapeExtend_DataMapOfShapeListOfMsg& msgmap = MessageReg->MapShape();
72b7576f 1533if (msgmap.IsBound (Shape1)) {
e5bd0d98 1534 const Message_ListOfMsg &msglist = msgmap.Find (Shape1);
72b7576f 1535 for (Message_ListIteratorOfListOfMsg iter (msglist);
1536iter.More(); iter.Next()) {
dba69de2 1537 Message_Msg msg = iter.Value();
1538 }
1539 }
72b7576f 1540~~~~~
1541
1542@subsection occt_shg_5_6 Tools for performance measurement
1543
1544Classes *MoniTool_Timer* and *MoniTool_TimerSentry* are used for measuring the performance of a current operation or any part of code, and provide the necessary API. Timers are used for debugging and performance optimizing purposes.
1545
1546Let us try to use timers in *XSDRAWIGES.cxx* and *IGESBRep_Reader.cxx* to analyse the performance of command *igesbrep*:
1547
1548~~~~~
1549XSDRAWIGES.cxx
1550 ...
1551 #include <MoniTool_Timer.hxx>
1552 #include <MoniTool_TimerSentry.hxx>
1553 ...
1554 MoniTool_Timer::ClearTimers();
1555 ...
1556 MoniTool_TimerSentry MTS("IGES_LoadFile");
1557 Standard_Integer status = Reader.LoadFile(fnom.ToCString());
1558 MTS.Stop();
1559 ...
1560 MoniTool_Timer::DumpTimers(cout);
1561 return;
1562
1563
1564IGESBRep_Reader.cxx
1565 ...
1566 #include <MoniTool_TimerSentry.hxx>
1567 ...
1568 Standard_Integer nb = theModel->NbEntities();
1569 ...
1570 for (Standard_Integer i=1; i<=nb; i++) {
1571 MoniTool_TimerSentry MTS("IGESToBRep_Transfer");
1572 ...
1573 try {
1574 TP.Transfer(ent);
1575 shape = TransferBRep::ShapeResult (theProc,ent);
1576 }
1577 ...
1578 }
1579~~~~~
1580
4ee1bdf4 1581The result of *DumpTimer()* after file translation is as follows:
1582
1583| TIMER | Elapsed | CPU User | CPU Sys | Hits |
1584| :--- | :---- | :----- | :---- | :---- |
1585| *IGES_LoadFile* | 1.0 sec | 0.9 sec | 0.0 sec | 1 |
1586| *IGESToBRep_Transfer* | 14.5 sec | 4.4 sec | 0.1 sec | 1311 |
72b7576f 1587
1588
1589@section occt_shg_6 Shape Processing
1590
1591@subsection occt_shg_6_1 Usage Workflow
1592
1593The Shape Processing module allows defining and applying the general Shape Processing as a customizable sequence of Shape Healing operators. The customization is implemented via the user-editable resource file, which defines the sequence of operators to be executed and their parameters.
dba69de2 1594
72b7576f 1595The Shape Processing functionality is implemented with the help of the *XSAlgo* interface. The main function *XSAlgo_AlgoContainer::ProcessShape()* does shape processing with specified tolerances and returns the resulting shape and associated information in the form of *Transient*.
1596
1597This function is used in the following way:
1598
1599~~~~~
1600TopoDS_Shape aShape = …;
1601Standard_Real Prec = …,
1602Standard_Real MaxTol = …;
1603TopoDS_Shape aResult;
1604Handle(Standard_Transient) info;
4ee1bdf4 1605TopoDS_Shape aResult = XSAlgo::AlgoContainer()->ProcessShape(aShape, Prec, MaxTol., "Name of ResourceFile", "NameSequence", info );
72b7576f 1606~~~~~
1607
1608Let us create a custom sequence of operations:
1609
dba69de2 16101. Create a resource file with the name *ResourceFile*, which includes the following string:
72b7576f 1611~~~~~
dba69de2 1612NameSequence.exec.op: MyOper
72b7576f 1613~~~~~
1614where *MyOper* is the name of operation.
72b7576f 16152. Input a custom parameter for this operation in the resource file, for example:
1616~~~~~
1617NameSequence.MyOper.Tolerance: 0.01
1618~~~~~
dba69de2 1619where *Tolerance* is the name of the parameter and 0.01 is its value.
72b7576f 16203. Add the following string into *void ShapeProcess_OperLibrary::Init()*:
72b7576f 1621~~~~~
1622ShapeProcess::RegisterOperator(;MyOper;,
1623new ShapeProcess_UOperator(myfunction));
1624~~~~~
1625where *myfunction* is a function which implements the operation.
72b7576f 16264. Create this function in *ShapeProcess_OperLibrary* as follows:
1627~~~~~
1628static Standard_Boolean myfunction (const
e5bd0d98 1629 Handle(ShapeProcess_Context)& context)
72b7576f 1630{
4ee1bdf4 1631 Handle(ShapeProcess_ShapeContext) ctx = Handle(ShapeProcess_ShapeContext)::DownCast(context);
dba69de2 1632 if(ctx.IsNull()) return Standard_False;
1633 TopoDS_Shape aShape = ctx->Result();
1634 //receive our parameter:
1635 Standard_Real toler;
1636 ctx->GetReal(;Tolerance;, toler);
72b7576f 1637~~~~~
dba69de2 16385. Make the necessary operations with *aShape* using the received value of parameter *Tolerance* from the resource file.
72b7576f 1639~~~~~
dba69de2 1640 return Standard_True;
72b7576f 1641}
1642~~~~~
dba69de2 16436. Define some operations (with their parameters) *MyOper1, MyOper2, MyOper3*, etc. and describe the corresponding functions in *ShapeProcess_OperLibrary*.
16447. Perform the required sequence using the specified name of operations and values of parameters in the resource file.
72b7576f 1645
1646For example: input of the following string:
1647~~~~~
dba69de2 1648NameSequence.exec.op: MyOper1,MyOper3
72b7576f 1649~~~~~
4ee1bdf4 1650means that the corresponding functions from *ShapeProcess_OperLibrary* will be performed with the original shape *aShape* using parameters defined for *MyOper1* and *MyOper3* in the resource file.
dba69de2 1651
72b7576f 1652It is necessary to note that these operations will be performed step by step and the result obtained after performing the first operation will be used as the initial shape for the second operation.
1653
1654@subsection occt_shg_6_2 Operators
dba69de2 1655
1656### DirectFaces
1657This operator sets all faces based on indirect surfaces, defined with left-handed coordinate systems as direct faces. This concerns surfaces defined by Axis Placement (Cylinders, etc). Such Axis Placement may be indirect, which is allowed in Cascade, but not allowed in some other systems. This operator reverses indirect placements and recomputes PCurves accordingly.
1658
1659### SameParameter
1660This operator is required after calling some other operators, according to the computations they do. Its call is explicit, so each call can be removed according to the operators, which are either called or not afterwards. This mainly concerns splitting operators that can split edges.
1661
1662The operator applies the computation *SameParameter* which ensures that various representations of each edge (its 3d curve, the pcurve on each of the faces on which it lies) give the same 3D point for the same parameter, within a given tolerance.
1663* For each edge coded as *same parameter*, deviation of curve representation is computed and if the edge tolerance is less than that deviation, the tolerance is increased so that it satisfies the deviation. No geometry modification, only an increase of tolerance is possible.
1664* For each edge coded as *not same parameter* the deviation is computed as in the first case. Then an attempt is made to achieve the edge equality to *same parameter* by means of modification of 2d curves. If the deviation of this modified edge is less than the original deviation then this edge is returned, otherwise the original edge (with non-modified 2d curves) is returned with an increased (if necessary) tolerance. Computation is done by call to the standard algorithm *BRepLib::SameParameter*.
1665
72b7576f 1666This operator can be called with the following parameters:
1667 * *Boolean : Force* (optional) - if True, encodes all edges as *not same parameter* then runs the computation. Else, the computation is done only for those edges already coded as *not same parameter*.
dba69de2 1668 * *Real : Tolerance3d* (optional) - if not defined, the local tolerance of each edge is taken for its own computation. Else, this parameter gives the global tolerance for the whole shape.
1669
1670### BSplineRestriction
1671
1672This operator is used for conversion of surfaces, curves 2d curves to BSpline surfaces with a specified degree and a specified number of spans. It performs approximations on surfaces, curves and 2d curves with a specified degree, maximum number of segments, 2d tolerance, 3d tolerance. The specified continuity can be reduced if the approximation with a specified continuity was not done successfully.
1673
72b7576f 1674This operator can be called with the following parameters:
1675* *Boolean : SurfaceMode* allows considering the surfaces;
1676* *Boolean : Curve3dMode* allows considering the 3d curves;
1677* *Boolean : Curve2dMode* allows considering the 2d curves;
1678* *Real : Tolerance3d* defines 3d tolerance to be used in computation;
1679* *Real : Tolerance2d* defines 2d tolerance to be used when computing 2d curves;
1680* *GeomAbs_Shape (C0 G1 C1 G2 C2 CN) : Continuity3d* is the continuity required in 2d;
1681* *GeomAbs_Shape (C0 G1 C1 G2 C2 CN) : Continuity2d* is the continuity required in 3d;
1682* *Integer : RequiredDegree* gives the required degree;
1683* *Integer : RequiredNbSegments* gives the required number of segments;
1684* *Boolean : PreferDegree* if true, *RequiredDegree* has a priority, else *RequiredNbSegments* has a priority;
1685* *Boolean : RationalToPolynomial* serves for conversion of BSplines to polynomial form;
1686* *Integer : MaxDegree* gives the maximum allowed Degree, if *RequiredDegree* cannot be reached;
dba69de2 1687* *Integer : MaxNbSegments* gives the maximum allowed NbSegments, if *RequiredNbSegments* cannot be reached.
72b7576f 1688
dba69de2 1689The following flags allow managing the conversion of special types of curves or surfaces, in addition to BSpline. They are controlled by *SurfaceMode, Curve3dMode* or *Curve2dMode* respectively; by default, only BSplines and Bezier Geometries are considered:
1690* *Boolean : OffsetSurfaceMode*
1691* *Boolean : LinearExtrusionMode*
1692* *Boolean : RevolutionMode*
1693* *Boolean : OffsetCurve3dMode*
1694* *Boolean : OffsetCurve2dMode*
1695* *Boolean : PlaneMode*
1696* *Boolean : BezierMode*
1697* *Boolean : ConvCurve3dMode*
1698* *Boolean : ConvCurve2dMode*
1699
1700For each of the Mode parameters listed above, if it is True, the specified geometry is converted to BSpline, otherwise only its basic geometry is checked and converted (if necessary) keeping the original type of geometry (revolution, offset, etc).
1701
1702* *Boolean :SegmentSurfaceMode* has effect only for Bsplines and Bezier surfaces. When False a surface will be replaced by a Trimmed Surface, else new geometry will be created by splitting the original Bspline or Bezier surface.
1703
1704### ElementaryToRevolution
1705
1706This operator converts elementary periodic surfaces to SurfaceOfRevolution.
1707
1708### SplitAngle
1709
1710This operator splits surfaces of revolution, cylindrical, toroidal, conical, spherical surfaces in the given shape so that each resulting segment covers not more than the defined number of degrees.
1711
1712It can be called with the following parameters:
72b7576f 1713* *Real : Angle* - the maximum allowed angle for resulting faces;
1714* *Real : MaxTolerance* - the maximum tolerance used in computations.
1715
dba69de2 1716### SurfaceToBSpline
1717This operator converts some specific types of Surfaces, to BSpline (according to parameters).
1718It can be called with the following parameters:
72b7576f 1719* *Boolean : LinearExtrusionMode* allows converting surfaces of Linear Extrusion;
1720* *Boolean : RevolutionMode* allows converting surfaces of Revolution;
1721* *Boolean : OffsetMode* allows converting Offset Surfaces
1722
dba69de2 1723### ToBezier
1724
1725This operator is used for data supported as Bezier only and converts various types of geometries to Bezier. It can be called with the following parameters used in computation of conversion :
72b7576f 1726* *Boolean : SurfaceMode*
1727* *Boolean : Curve3dMode*
1728* *Boolean : Curve2dMode*
1729* *Real : MaxTolerance*
dba69de2 1730* *Boolean : SegmentSurfaceMode* (default is True) has effect only for Bsplines and Bezier surfaces. When False a surface will be replaced by a Trimmed Surface, else new geometry will be created by splitting the original Bspline or Bezier surface.
72b7576f 1731
1732The following parameters are controlled by *SurfaceMode, Curve3dMode* or *Curve2dMode* (according to the case):
1733* *Boolean : Line3dMode*
1734* *Boolean : Circle3dMode*
1735* *Boolean : Conic3dMode*
1736* *Boolean : PlaneMode*
1737* *Boolean : RevolutionMode*
1738* *Boolean : ExtrusionMode*
1739* *Boolean : BSplineMode*
1740
dba69de2 1741### SplitContinuity
1742This operator splits a shape in order to have each geometry (surface, curve 3d, curve 2d) correspond the given criterion of continuity. It can be called with the following parameters:
72b7576f 1743* *Real : Tolerance3d*
1744* *Integer (GeomAbs_Shape ) : CurveContinuity*
1745* *Integer (GeomAbs_Shape ) : SurfaceContinuity*
1746* *Real : MaxTolerance*
1747
72b7576f 1748Because of algorithmic limitations in the operator *BSplineRestriction* (in some particular cases, this operator can produce unexpected C0 geometry), if *SplitContinuity* is called, it is recommended to call it after *BSplineRestriction*.
1749Continuity Values will be set as *GeomAbs_Shape* (i.e. C0 G1 C1 G2 C2 CN) besides direct integer values (resp. 0 1 2 3 4 5).
1750
dba69de2 1751### SplitClosedFaces
1752This operator splits faces, which are closed even if they are not revolutionary or cylindrical, conical, spherical, toroidal. This corresponds to BSpline or Bezier surfaces which can be closed (whether periodic or not), hence they have a seam edge. As a result, no more seam edges remain. The number of points allows to control the minimum count of faces to be produced per input closed face.
1753
72b7576f 1754This operator can be called with the following parameters:
1755* *Integer : NbSplitPoints* gives the number of points to use for splitting (the number of intervals produced is *NbSplitPoints+1*);
1756* *Real : CloseTolerance* tolerance used to determine if a face is closed;
1757* *Real : MaxTolerance* is used in the computation of splitting.
1758
dba69de2 1759### FixGaps
1760
1761This operator must be called when *FixFaceSize* and/or *DropSmallEdges* are called. Using Surface Healing may require an additional call to *BSplineRestriction* to ensure that modified geometries meet the requirements for BSpline.
72b7576f 1762This operators repairs geometries which contain gaps between edges in wires (always performed) or gaps on faces, controlled by parameter *SurfaceMode*, Gaps on Faces are fixed by using algorithms of Surface Healing
1763This operator can be called with the following parameters:
1764* *Real : Tolerance3d* sets the tolerance to reach in 3d. If a gap is less than this value, it is not fixed.
1765* *Boolean : SurfaceMode* sets the mode of fixing gaps between edges and faces (yes/no) ;
1766* *Integer : SurfaceAddSpans* sets the number of spans to add to the surface in order to fix gaps ;
1767* *GeomAbs_Shape (C0 G1 C1 G2 C2 CN) : SurfaceContinuity* sets the minimal continuity of a resulting surface ;
1768* *Integer : NbIterations* sets the number of iterations
1769* *Real : Beta* sets the elasticity coefficient for modifying a surface [1-1000] ;
1770* *Reals : Coeff1 to Coeff6* sets energy coefficients for modifying a surface [0-10000] ;
1771* *Real : MaxDeflection* sets maximal deflection of surface from an old position.
1772
1773This operator may change the original geometry. In addition, it is CPU consuming, and it may fail in some cases. Also **FixGaps** can help only when there are gaps obtained as a result of removal of small edges that can be removed by **DropSmallEdges** or **FixFaceSize**.
1774
dba69de2 1775### FixFaceSize
1776This operator removes faces, which are small in all directions (spot face) or small in one direction (strip face). It can be called with the parameter *Real : Tolerance*, which sets the minimal dimension, which is used to consider a face, is small enough to be removed.
1777
1778### DropSmallEdges
1779This operator drops edges in a wire, and merges them with adjacent edges, when they are smaller than the given value (*Tolerance3d*) and when the topology allows such merging (i.e. same adjacent faces for each of the merged edges). Free (non-shared by adjacent faces) small edges can be also removed in case if they share the same vertex Parameters.
1780
1781It can be called with the parameter *Real : Tolerance3d*, which sets the dimension used to determine if an edge is small.
72b7576f 1782
dba69de2 1783### FixShape
1784
1785This operator may be added for fixing invalid shapes. It performs various checks and fixes, according to the modes listed hereafter. Management of a set of fixes can be performed by flags as follows:
1786* if the flag for a fixing tool is set to 0 , it is not performed;
1787* if set to 1 , it is performed in any case;
1788* if not set, or set to -1 , for each shape to be applied on, a check is done to evaluate whether a fix is needed. The fix is performed if the check is positive.
1789
1790By default, the flags are not set, the checks are carried out each individual shape.
72b7576f 1791
72b7576f 1792This operator can be called with the following parameters:
1793* *Real : Tolerance3d* sets basic tolerance used for fixing;
1794* *Real : MaxTolerance3d* sets maximum allowed value for the resulting tolerance;
1795* *Real : MinTolerance3d* sets minimum allowed value for the resulting tolerance.
1796* *Boolean : FixFreeShellMode*
1797* *Boolean : FixFreeFaceMode*
1798* *Boolean : FixFreeWireMode*
1799* *Boolean : FixSameParameterMode*
1800* *Boolean : FixSolidMode*
1801* *Boolean : FixShellMode*
1802* *Boolean : FixFaceMode*
1803* *Boolean : FixWireMode*
1804* *Boolean : FixOrientationMode*
1805* *Boolean : FixMissingSeamMode*
1806* *Boolean : FixSmallAreaWireMode*
1807* *Boolean (not checked) : ModifyTopologyMode* specifies the mode for modifying topology. Should be False (default) for shapes with shells and can be True for free faces.
1808* *Boolean (not checked) : ModifyGeometryMode* specifies the mode for modifying geometry. Should be False if geometry is to be kept and True if it can be modified.
1809* *Boolean (not checked) : ClosedWireMode* specifies the mode for wires. Should be True for wires on faces and False for free wires.
1810* *Boolean (not checked) : PreferencePCurveMode (not used)* specifies the preference of 3d or 2d representations for an edge
1811* *Boolean : FixReorderMode*
1812* *Boolean : FixSmallMode*
1813* *Boolean : FixConnectedMode*
1814* *Boolean : FixEdgeCurvesMode*
1815* *Boolean : FixDegeneratedMode*
1816* *Boolean : FixLackingMode*
1817* *Boolean : FixSelfIntersectionMode*
1818* *Boolean : FixGaps3dMode*
1819* *Boolean : FixGaps2dMode*
1820* *Boolean : FixReversed2dMode*
1821* *Boolean : FixRemovePCurveMode*
1822* *Boolean : FixRemoveCurve3dMode*
1823* *Boolean : FixAddPCurveMode*
1824* *Boolean : FixAddCurve3dMode*
1825* *Boolean : FixSeamMode*
1826* *Boolean : FixShiftedMode*
1827* *Boolean : FixEdgeSameParameterMode*
1828* *Boolean : FixSelfIntersectingEdgeMode*
1829* *Boolean : FixIntersectingEdgesMode*
1830* *Boolean : FixNonAdjacentIntersectingEdgesMode*
1831
dba69de2 1832### SplitClosedEdges
1833This operator handles closed edges i.e. edges with one vertex. Such edges are not supported in some receiving systems. This operator splits topologically closed edges (i.e. edges having one vertex) into two edges. Degenerated edges and edges with a size of less than Tolerance are not processed.
72b7576f 1834
e5bd0d98 1835@section occt_shg_7 Messaging mechanism
72b7576f 1836
1837Various messages about modification, warnings and fails can be generated in the process of shape fixing or upgrade. The messaging mechanism allows generating messages, which will be sent to the chosen target medium a file or the screen. The messages may report failures and/or warnings or provide information on events such as analysis, fixing or upgrade of shapes.
1838
dba69de2 1839@subsection occt_shg_7_1 Message Gravity
72b7576f 1840Enumeration *Message_Gravity* is used for defining message gravity.
1841It provides the following message statuses:
1842* *Message_FAIL* - the message reports a fail;
1843* *Message_WARNING* - the message reports a warning;
1844* *Message_INFO* - the message supplies information.
1845
dba69de2 1846@subsection occt_shg_7_2 Tool for loading a message file into memory
72b7576f 1847Class *Message_MsgFile* allows defining messages by loading a custom message file into memory. It is necessary to create a custom message file before loading it into memory, as its path will be used as the argument to load it. Each message in the message file is identified by a key. The user can get the text content of the message by specifying the message key.
1848
dba69de2 1849### Format of the message file
1850
72b7576f 1851The message file is an ASCII file, which defines a set of messages. Each line of the file must have a length of less than 255 characters.
1852All lines in the file starting with the exclamation sign (perhaps preceded by spaces and/or tabs) are considered as comments and are ignored.
1853A message file may contain several messages. Each message is identified by its key (string).
4ee1bdf4 1854Each line in the file starting with the *dot* character (perhaps preceded by spaces and/or tabs) defines the key. The key is a string starting with a symbol placed after the dot and ending with the symbol preceding the ending of the newline character <i>\\n.</i>
1855All lines in the file after the key and before the next keyword (and which are not comments) define the message for that key. If the message consists of several lines, the message string will contain newline symbols <i>\\n</i> between each line (but not at the end).
1856
72b7576f 1857The following example illustrates the structure of a message file:
1858
1859~~~~~
1860!This is a sample message file
1861!------------------------------
1862!Messages for ShapeAnalysis package
1863!
1864.SampleKeyword
1865Your message string goes here
1866!
1867!...
1868!
4ee1bdf4 1869!End of the message file
72b7576f 1870~~~~~
1871
dba69de2 1872### Loading the message file
1873
72b7576f 1874A custom file can be loaded into memory using the method *Message_MsgFile::LoadFile*, taking as an argument the path to your file as in the example below:
1875~~~~~
1876Standard_CString MsgFilePath = ;(path)/sample.file;;
1877Message_MsgFile::LoadFile (MsgFilePath);
1878~~~~~
1879
dba69de2 1880@subsection occt_shg_7_3 Tool for managing filling messages
72b7576f 1881
1882The class *Message_Msg* allows using the message file loaded as a template. This class provides a tool for preparing the message, filling it with parameters, storing and outputting to the default trace file.
1883A message is created from a key: this key identifies the message to be created in the message file. The text of the message is taken from the loaded message file (class *Message_MsgFile* is used).
1884The text of the message can contain places for parameters, which are to be filled by the proper values when the message is prepared. These parameters can be of the following types:
4ee1bdf4 1885* string - coded in the text as \%s,
1886* integer - coded in the text as \%d,
1887* real - coded in the text as \%f.
72b7576f 1888The parameter fields are filled by the message text by calling the corresponding methods *AddInteger, AddReal* and *AddString*. Both the original text of the message and the input text with substituted parameters are stored in the object. The prepared and filled message can be output to the default trace file. The text of the message (either original or filled) can be also obtained.
1889~~~~~
1890Message_Msg msg01 (;SampleKeyword;);
1891//Creates the message msg01, identified in the file by the keyword SampleKeyword
1892msg1.AddInteger (73);
1893msg1.AddString (;SampleFile;);
1894//fills out the code areas
1895~~~~~
1896
dba69de2 1897@subsection occt_shg_7_4 Tool for managing trace files
72b7576f 1898
4ee1bdf4 1899Class *Message_TraceFile* is intended to manage the trace file (or stream) for outputting messages and the current trace level. Trace level is an integer number, which is used when messages are sent. Generally, 0 means minimum, \> 0 various levels. If the current trace level is lower than the level of the message it is not output to the trace file. The trace level is to be managed and used by the users.
72b7576f 1900There are two ways of using trace files:
1901* define an object of *Message_TraceFile*, with its own definition (file name or cout, trace level), and use it where it is defined,
1902* use the default trace file (file name or cout, trace level), usable from anywhere.
1903Use the constructor method to define the target file and the level of the messages as in the example below:
1904~~~~~
1905Message_TraceFile myTF
4ee1bdf4 1906 (tracelevel, "tracefile.log", Standard_False);
72b7576f 1907~~~~~
1908The parameters are as follows:
1909* *tracelevel* is a Standard_Integer and modifies the level of messages. It has the following values and semantics:
1910 + 0: gives general information such as the start and end of process;
1911 + 1: gives exceptions raised and fail messages;
1912 + 2: gives the same information as 1 plus warning messages.
1913* *filename* is the string containing the path to the log file.
1914The Boolean set to False will rewrite the existing file. When set to True, new messages will be appended to the existing file.
1915
1916A new default log file can be added using method *SetDefault* with the same arguments as in the constructor.
1917The default trace level can be changed by using method *SetDefLevel*. In this way, the information received in the log file is modified.
1918It is possible to close the log file and set the default trace output to the screen display instead of the log file using the method *SetDefault* without any arguments.
1919