0025122: Expose internal static function ComputeDeviation from ShapeAnalysis_Edge.cxx
[occt.git] / src / ShapeAnalysis / ShapeAnalysis_Edge.cdl
1 -- Created on: 1998-06-08
2 -- Created by: data exchange team
3 -- Copyright (c) 1998-1999 Matra Datavision
4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
5 --
6 -- This file is part of Open CASCADE Technology software library.
7 --
8 -- This library is free software; you can redistribute it and/or modify it under
9 -- the terms of the GNU Lesser General Public License version 2.1 as published
10 -- by the Free Software Foundation, with special exception defined in the file
11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 -- distribution for complete text of the license and disclaimer of any warranty.
13 --
14 -- Alternatively, this file may be used under the terms of Open CASCADE
15 -- commercial license or contractual agreement.
16
17 class Edge from ShapeAnalysis 
18
19     ---Purpose: Tool for analyzing the edge.
20     --          Queries geometrical representations of the edge (3d curve, pcurve
21     --          on the given face or surface) and topological sub-shapes (bounding
22     --          vertices).
23     --          Provides methods for analyzing geometry and topology consistency
24     --          (3d and pcurve(s) consistency, their adjacency to the vertices).
25
26 uses
27     Curve    from Adaptor3d,
28     Pnt      from gp,
29     Pnt2d    from gp,
30     Vec2d    from gp,
31     Curve    from Geom2d,
32     Curve    from Geom,
33     Surface  from Geom,
34     Vertex   from TopoDS,
35     Edge     from TopoDS,
36     Face     from TopoDS,
37     Location from TopLoc,
38     Status   from ShapeExtend
39
40 is
41
42     Create returns Edge from ShapeAnalysis;
43         ---Purpose: Empty constructor; initialises Status to OK
44     
45     HasCurve3d (me; edge: Edge from TopoDS) returns Boolean;
46         ---Purpose: Tells if the edge has a 3d curve
47
48     Curve3d (me; edge  : Edge from TopoDS;
49                  C3d   : out Curve from Geom;
50                  cf, cl: out Real;
51                  orient: Boolean = Standard_True)
52     returns Boolean;
53         ---Purpose: Returns the 3d curve and bounding parameteres for the edge
54         --          Returns False if no 3d curve.
55         --          If <orient> is True (default), takes orientation into account:
56         --          if the edge is reversed, cf and cl are toggled
57         
58     IsClosed3d (me; edge: Edge from TopoDS) returns Boolean;
59         ---Purpose: Gives True if the edge has a 3d curve, this curve is closed,
60         --          and the edge has the same vertex at start and end
61
62     HasPCurve (me; edge: Edge from TopoDS;
63                    face: Face from TopoDS)
64     returns Boolean;
65         ---Purpose: Tells if the Edge has a pcurve on the face.
66
67     HasPCurve (me; edge    : Edge from TopoDS;
68                    surface : Surface from Geom;
69                    location: Location from TopLoc)
70     returns Boolean;
71         ---Purpose: Tells if the edge has a pcurve on the surface (with location).
72
73     PCurve (me; edge  : Edge from TopoDS;
74                 face  : Face from TopoDS;
75                 C2d   : out Curve from Geom2d;
76                 cf, cl: out Real;
77                 orient: Boolean = Standard_True)
78     returns Boolean;
79
80     PCurve (me; edge    : Edge from TopoDS;
81                 surface : Surface from Geom;
82                 location: Location from TopLoc;
83                 C2d     : out Curve from Geom2d;
84                 cf, cl  : out Real;
85                 orient  : Boolean = Standard_True)
86     returns Boolean;
87         ---Purpose: Returns the pcurve and bounding parameteres for the edge
88         --          lying on the surface.
89         --          Returns False if the edge has no pcurve on this surface.
90         --          If <orient> is True (default), takes orientation into account:
91         --          if the edge is reversed, cf and cl are toggled
92  
93     BoundUV (me; edge       : Edge from TopoDS;
94                  face       : Face from TopoDS;
95                  first, last: out Pnt2d from gp)
96     returns Boolean;
97
98     BoundUV (me; edge    : Edge from TopoDS;
99                  surface : Surface from Geom;
100                  location: Location from TopLoc;
101                  first, last: out Pnt2d from gp)
102     returns Boolean;
103         ---Purpose: Returns the ends of pcurve
104         --          Calls method PCurve with <orient> equal to True
105         
106     IsSeam (me; edge: Edge from TopoDS;
107                 face: Face from TopoDS)
108     returns Boolean;
109     
110     IsSeam (me; edge    : Edge from TopoDS;
111                 surface : Surface from Geom;
112                 location: Location from TopLoc)
113     returns Boolean;
114         ---Purpose: Returns True if the edge has two pcurves on one surface
115         ---Remark : Calls BRep_Tool::IsClosed()
116     
117     FirstVertex (me; edge: Edge from TopoDS) returns Vertex from TopoDS;
118         ---Purpose: Returns start vertex of the edge (taking edge orientation
119         --          into account).
120         ---Remark:  Vertex orientation is always FORWARD
121
122     LastVertex (me; edge: Edge from TopoDS) returns Vertex from TopoDS;
123         ---Purpose: Returns end vertex of the edge (taking edge orientation
124         --          into account).
125         ---Remark:  Vertex orientation is always REVERSED
126     
127     GetEndTangent2d (me; edge: Edge from TopoDS; 
128                          face: Face from TopoDS;
129                          atEnd: Boolean; 
130                          pos : out Pnt2d from gp;
131                          tang: out Vec2d from gp;
132                          dparam: Real from Standard =0.0)
133     returns Boolean;
134
135     GetEndTangent2d (me; edge: Edge from TopoDS; 
136                          surface : Surface from Geom;
137                          location: Location from TopLoc;
138                          atEnd: Boolean; 
139                          pos : out Pnt2d from gp;
140                          tang: out Vec2d from gp;
141                          dparam: Real from Standard =0.0)
142     returns Boolean;
143         ---Purpose: Returns tangent of the edge pcurve at its start (if atEnd is
144         --          False) or end (if True), regarding the orientation of edge.
145         --          If edge is REVERSED, tangent is reversed before return.
146         --          Returns True if pcurve is available and tangent is computed
147         --          and is not null, else False.
148                 
149     CheckVerticesWithCurve3d (me: in out; edge : Edge from TopoDS;
150                                           preci: Real = -1;
151                                           vtx  : Integer = 0)
152     returns Boolean;
153         ---Purpose: Checks the start and/or end vertex of the edge for matching
154         --          with 3d curve with the given precision.
155         --          <vtx> = 1 : start vertex only
156         --          <vtx> = 2 : end vertex only
157         --          <vtx> = 0 : both (default)
158         --          If preci < 0 the vertices are considered with their own
159         --          tolerances, else with the given <preci>.
160         ---Returns: True if mismatching of the vertex to the curve was detected
161         --          else returns False (OK)
162         ---Status : OK - ends of the 3d curve are comprised by checked vertices
163         --          FAIL1 - edge has no 3d curve
164         --          DONE1 - if first vertex of the edge does not comprise start of 3d curve
165         --          DONE2 - if last vertex of the edge does not comprise end of 3d curve
166
167     CheckVerticesWithPCurve (me: in out; edge : Edge from TopoDS;
168                                          face : Face from TopoDS;
169                                          preci: Real = -1;
170                                          vtx  : Integer = 0)
171     returns Boolean;
172
173     CheckVerticesWithPCurve (me: in out; edge    : Edge from TopoDS;
174                                          surface : Surface from Geom;
175                                          location: Location from TopLoc;
176                                          preci   : Real = -1;
177                                          vtx     : Integer = 0)
178     returns Boolean;
179         ---Purpose: Checks the start and/or end vertex of the edge for matching
180         --          with pcurve with the given precision.
181         --          <vtx> = 1 : start vertex
182         --          <vtx> = 2 : end vertex
183         --          <vtx> = 0 : both
184         --          If preci < 0 the vertices are considered with their own
185         --          tolerances, else with the given <preci>.
186         ---Returns: True if mismatching of the curves to the vertex was detected
187         --          else returns False (OK)
188         ---Status : OK - ends of the 3d curve are comprised by checked vertices
189         --          FAIL1 - edge has no pcurve on a given (sur)face
190         --          DONE1 - if first vertex of the edge does not comprise start of pcurve
191         --          DONE2 - if last vertex of the edge does not comprise end of pcurve
192         
193     CheckVertexTolerance(me: in out; edge  : Edge from TopoDS;
194                                      face  : Face from TopoDS;
195                                      toler1: out Real;
196                                      toler2: out Real)
197     returns Boolean;
198     CheckVertexTolerance(me: in out; edge  : Edge from TopoDS;
199                                      toler1: out Real;
200                                      toler2: out Real)
201     returns Boolean;
202         ---Purpose: Checks if it is necessary to increase tolerances of the edge
203         --          vertices to comprise the ends of 3d curve and pcurve on
204         --          the given face (first method) or all pcurves stored in an edge
205         --          (second one)
206         --          toler1 returns necessary tolerance for first vertex,
207         --          toler2 returns necessary tolerance for last vertex.
208         ---Returns: True, if tolerances should be increased, otherwise False
209         ---Status:
210         --          OK   : the original tolerances are sufficient
211         --          DONE1: the tolerance of first vertex should be increased
212         --          DONE2: the tolerance of last  vertex should be increased
213         --          FAIL1: edge has no vertice(s), no check is done
214         --          FAIL2: edge has no 3d curve, only pcurves are checked
215         --          FAIL3: edge has no pcurve on a given face, only 3d curve is checked
216
217     CheckCurve3dWithPCurve (me: in out; edge: Edge from TopoDS;
218                                         face: Face from TopoDS)
219     returns Boolean;
220
221     CheckCurve3dWithPCurve (me: in out; edge    :Edge from TopoDS;
222                                         surface : Surface from Geom;
223                                         location: Location from TopLoc)
224     returns Boolean;
225         ---Purpose: Checks mutual orientation of 3d curve and pcurve on the
226         --          analysis of curves bounding points
227         ---Returns: Returns True if mismatching of orientation was detected,
228         --          else returns False (if OK or no curve)
229         ---Status:
230         --          OK   : orientations match each other (both go in the same
231         --                 directions), or edge is closed
232         --          DONE1: orientations mismatch each other (curves go in
233         --                 opposite directions)
234         --          FAIL1: no pcurve
235         --          FAIL2: no 3d curve
236
237     CheckPoints (me: in out; P1A, P1B: Pnt from gp;
238                              P2A, P2B: Pnt from gp;
239                              preci1, preci2: Real)
240     returns Boolean is private;
241         ---Purpose: Check points by pairs (A and A, B and B) with precisions
242         --          (preci1 and preci2).
243         --          P1 are the points either from 3d curve or from vertices,
244         --          P2 are the points from pcurve
245         ---Returns: False if status is OK, else True
246         --- Status:
247         --          OK   : distances (P1A, P2A) and (P1B, P2B) are within
248         --                 precisions
249         --          DONE1: distance (P1A, P2B) + (P1B, P2A) is less than
250         --                 distance (P1A, P2A) + (P1B, P2B),
251         --                 the precisions are not taken into account in this case
252     
253
254
255     Status (me; status: Status from ShapeExtend) returns Boolean;
256         ---Purpose: Returns the status (in the form of True/False) of last Check
257         ---Returns: True if status contains bit corresponding to enumerated argument
258
259     CheckSameParameter (me: in out; edge  : Edge from TopoDS;
260                                     maxdev: out Real;
261                                     NbControl: Integer = 23)
262     returns Boolean;
263         ---Purpose: Checks the edge to be SameParameter.
264         --          Calculates the maximal deviation between 3d curve and each
265         --          pcurve of the edge on <NbControl> equidistant points (the same
266         --          algorithm as in BRepCheck; default value is 23 as in BRepCheck). 
267         --          This deviation is returned in <maxdev> parameter.
268         --          If deviation is greater than tolerance of the edge (i.e.
269         --          incorrect flag) returns False, else returns True.
270         ---Returns: True if edge has either SameParameter False and/or its real
271         --          deviation of curves is more than tolerance
272         ---Status : OK - Edge is SameParameter with the associated tolerance
273         --          DONE1 - if deviation of the pcurves from 3d curve is greater 
274         --                  than tolerance of edge
275         --          DONE2 - if SameParameter flag in edge is False
276         --          FAIL1 - edge does not have 3d curve
277         --          FAIL2 - if some computational problems were encountered (when
278         --                  projecting points on curves)
279
280     ComputeDeviation (myclass; CRef         : Curve from Adaptor3d;
281                                Other        : Curve from Adaptor3d;
282                                SameParameter: Boolean;
283                                dev          : in out Real;
284                                NCONTROL     : Integer)
285     returns Boolean;
286         ---Purpose: Computes the maximal deviation between the two curve
287         --          representations.
288         --          dev is an input/output parameter and contains the computed
289         --          deviation (should be initialized with 0. for the first call).
290         --          Used by CheckSameParameter().
291         ---Returns: True if the computation has been successful and False otherwise.
292         
293     CheckOverlapping(me :in out; theEdge1, theEdge2 : Edge from TopoDS; 
294                      theTolOverlap:in out Real; theDomainDist : Real =0.0) returns Boolean;
295         ---Purpose: Checks the first edge is overlapped with second edge.
296         --          If distance between two edges is less then theTolOverlap 
297         --          edges is overlapped.
298         --          theDomainDis - length of part of edges on wich edges is overlapped.
299         ---Status : DONE3 - edges is overlapped on whole length
300         --        : DONE4 - edges is overlapped on the length equal to theDomainDist
301
302
303 fields
304
305     myStatus: Integer is protected;
306     
307 end Edge;