1 // Created on: 1998-06-03
2 // Created by: data exchange team
3 // Copyright (c) 1998-1999 Matra Datavision
4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
6 // This file is part of Open CASCADE Technology software library.
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.
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
17 #ifndef _ShapeAnalysis_Surface_HeaderFile
18 #define _ShapeAnalysis_Surface_HeaderFile
20 #include <Standard.hxx>
21 #include <Standard_Type.hxx>
23 #include <Extrema_ExtPS.hxx>
24 #include <GeomAdaptor_Surface.hxx>
25 #include <Standard_Boolean.hxx>
26 #include <Standard_Integer.hxx>
27 #include <Standard_Real.hxx>
29 #include <gp_Pnt2d.hxx>
30 #include <Bnd_Box.hxx>
31 #include <Standard_Transient.hxx>
32 #include <TColgp_SequenceOfPnt.hxx>
33 #include <TColgp_SequenceOfPnt2d.hxx>
35 class GeomAdaptor_HSurface;
42 class ShapeAnalysis_Surface;
43 DEFINE_STANDARD_HANDLE(ShapeAnalysis_Surface, Standard_Transient)
45 //! Complements standard tool Geom_Surface by providing additional
46 //! functionality for detection surface singularities, checking
47 //! spatial surface closure and computing projections of 3D points
50 //! * The singularities
51 //! Each singularity stores the precision with which corresponding
52 //! surface iso-line is considered as degenerated.
53 //! The number of singularities is determined by specifying precision
54 //! and always not greater than 4.
56 //! * The spatial closure
57 //! The check for spatial closure is performed with given precision
58 //! (default value is Precision::Confusion).
59 //! If Geom_Surface says that the surface is closed, this class
60 //! also says this. Otherwise additional analysis is performed.
62 //! * The parameters of 3D point on the surface
63 //! The projection of the point is performed with given precision.
64 //! This class tries to find a solution taking into account possible
66 //! Additional method for searching the solution from already built
67 //! one is also provided.
69 //! This tool is optimised: computes most information only once
70 class ShapeAnalysis_Surface : public Standard_Transient
76 //! Creates an analyzer object on the basis of existing surface
77 Standard_EXPORT ShapeAnalysis_Surface(const Handle(Geom_Surface)& S);
79 //! Loads existing surface
80 Standard_EXPORT void Init (const Handle(Geom_Surface)& S);
82 //! Reads all the data from another Surface, without recomputing
83 Standard_EXPORT void Init (const Handle(ShapeAnalysis_Surface)& other);
85 Standard_EXPORT void SetDomain (const Standard_Real U1, const Standard_Real U2,
86 const Standard_Real V1, const Standard_Real V2);
88 //! Returns a surface being analyzed
89 const Handle(Geom_Surface)& Surface() const;
91 //! Returns the Adaptor.
92 //! Creates it if not yet done.
93 Standard_EXPORT const Handle(GeomAdaptor_HSurface)& Adaptor3d();
95 //! Returns the Adaptor (may be Null if method Adaptor() was not called)
96 const Handle(GeomAdaptor_HSurface)& TrueAdaptor3d() const;
98 //! Returns 3D distance found by one of the following methods.
99 //! IsDegenerated, DegeneratedValues, ProjectDegenerated
100 //! (distance between 3D point and found or last (if not found)
102 //! IsUClosed, IsVClosed (minimum value of precision to consider
103 //! the surface to be closed),
104 //! ValueOfUV (distance between 3D point and found solution).
105 Standard_Real Gap() const;
107 //! Returns a 3D point specified by parameters in surface
108 //! parametrical space
109 gp_Pnt Value (const Standard_Real u, const Standard_Real v);
111 //! Returns a 3d point specified by a point in surface
112 //! parametrical space
113 gp_Pnt Value (const gp_Pnt2d& p2d);
115 //! Returns True if the surface has singularities for the given
116 //! precision (i.e. if there are surface singularities with sizes
117 //! not greater than precision).
118 Standard_EXPORT Standard_Boolean HasSingularities (const Standard_Real preci);
120 //! Returns the number of singularities for the given precision
121 //! (i.e. number of surface singularities with sizes not greater
123 Standard_EXPORT Standard_Integer NbSingularities (const Standard_Real preci);
125 //! Returns the characteristics of the singularity specified by
126 //! its rank number <num>.
127 //! That means, that it is not neccessary for <num> to be in the
128 //! range [1, NbSingularities] but must be not greater than
129 //! possible (see ComputeSingularities).
130 //! The returned characteristics are:
131 //! preci: the smallest precision with which the iso-line is
132 //! considered as degenerated,
133 //! P3d: 3D point of singularity (middle point of the surface
135 //! firstP2d and lastP2d: first and last 2D points of the
136 //! iso-line in parametrical surface,
137 //! firstpar and lastpar: first and last parameters of the
138 //! iso-line in parametrical surface,
139 //! uisodeg: if the degenerated iso-line is U-iso (True) or
141 //! Returns False if <num> is out of range, else returns True.
142 Standard_EXPORT Standard_Boolean Singularity (const Standard_Integer num,
143 Standard_Real& preci,
147 Standard_Real& firstpar,
148 Standard_Real& lastpar,
149 Standard_Boolean& uisodeg);
151 //! Returns True if there is at least one surface boundary which
152 //! is considered as degenerated with <preci> and distance
153 //! between P3d and corresponding singular point is less than
155 Standard_EXPORT Standard_Boolean IsDegenerated (const gp_Pnt& P3d, const Standard_Real preci);
157 //! Returns True if there is at least one surface iso-line which
158 //! is considered as degenerated with <preci> and distance
159 //! between P3d and corresponding singular point is less than
160 //! <preci> (like IsDegenerated).
161 //! Returns characteristics of the first found boundary matching
163 Standard_EXPORT Standard_Boolean DegeneratedValues (const gp_Pnt& P3d,
164 const Standard_Real preci,
167 Standard_Real& firstpar,
168 Standard_Real& lastpar,
169 const Standard_Boolean forward = Standard_True);
171 //! Projects a point <P3d> on a singularity by computing
172 //! one of the coordinates of preliminary computed <result>.
174 //! Finds the iso-line which is considered as degenerated with
176 //! a. distance between P3d and corresponding singular point is
177 //! less than <preci> (like IsDegenerated) or
178 //! b. difference between already computed <result>'s coordinate
179 //! and iso-coordinate of the boundary is less than 2D
180 //! resolution (computed from <preci> by Geom_Adaptor).
181 //! Then sets not yet computed <result>'s coordinate taking it
182 //! from <neighbour> and returns True.
183 Standard_EXPORT Standard_Boolean ProjectDegenerated (const gp_Pnt& P3d,
184 const Standard_Real preci,
185 const gp_Pnt2d& neighbour,
188 //! Checks points at the beginning (direct is True) or end
189 //! (direct is False) of array <points> to lie in singularity of
190 //! surface, and if yes, adjusts the indeterminate 2d coordinate
191 //! of these points by nearest point which is not in singularity.
192 //! Returns True if some points were adjusted.
193 Standard_EXPORT Standard_Boolean ProjectDegenerated (const Standard_Integer nbrPnt,
194 const TColgp_SequenceOfPnt& points,
195 TColgp_SequenceOfPnt2d& pnt2d,
196 const Standard_Real preci, const Standard_Boolean direct);
198 //! Returns True if straight pcurve going from point p2d1 to p2d2
199 //! is degenerate, i.e. lies in the singularity of the surface.
200 //! NOTE: it uses another method of detecting singularity than
201 //! used by ComputeSingularities() et al.!
202 //! For that, maximums of distances between points p2d1, p2d2
203 //! and 0.5*(p2d1+p2d2) and between corresponding 3d points are
205 //! The pcurve (p2d1, p2d2) is considered as degenerate if:
206 //! - max distance in 3d is less than <tol>
207 //! - max distance in 2d is at least <ratio> times greather than
208 //! the Resolution computed from max distance in 3d
209 //! (max3d < tol && max2d > ratio * Resolution(max3d))
210 //! NOTE: <ratio> should be >1 (e.g. 10)
211 Standard_EXPORT Standard_Boolean IsDegenerated (const gp_Pnt2d& p2d1,
212 const gp_Pnt2d& p2d2,
213 const Standard_Real tol,
214 const Standard_Real ratio);
216 //! Returns the bounds of the surface
217 //! (from Bounds from Surface, but buffered)
218 void Bounds (Standard_Real& ufirst, Standard_Real& ulast,
219 Standard_Real& vfirst, Standard_Real& vlast) const;
221 //! Computes bound isos (protected against exceptions)
222 Standard_EXPORT void ComputeBoundIsos();
224 //! Returns a U-Iso. Null if not possible or failed
225 //! Remark : bound isos are buffered
226 Standard_EXPORT Handle(Geom_Curve) UIso (const Standard_Real U);
228 //! Returns a V-Iso. Null if not possible or failed
229 //! Remark : bound isos are buffered
230 Standard_EXPORT Handle(Geom_Curve) VIso (const Standard_Real V);
232 //! Tells if the Surface is spatially closed in U with given
233 //! precision. If <preci> < 0 then Precision::Confusion is used.
234 //! If Geom_Surface says that the surface is U-closed, this method
235 //! also says this. Otherwise additional analysis is performed,
236 //! comparing given precision with the following distances:
237 //! - periodic B-Splines are closed,
238 //! - polinomial B-Spline with boundary multiplicities degree+1
239 //! and Bezier - maximum distance between poles,
240 //! - rational B-Spline or one with boundary multiplicities not
241 //! degree+1 - maximum distance computed at knots and their
243 //! - surface of extrusion - distance between ends of basis
245 //! - other (RectangularTrimmed and Offset) - maximum distance
246 //! computed at 100 equi-distanted points.
247 Standard_EXPORT Standard_Boolean IsUClosed (const Standard_Real preci = -1);
249 //! Tells if the Surface is spatially closed in V with given
250 //! precision. If <preci> < 0 then Precision::Confusion is used.
251 //! If Geom_Surface says that the surface is V-closed, this method
252 //! also says this. Otherwise additional analysis is performed,
253 //! comparing given precision with the following distances:
254 //! - periodic B-Splines are closed,
255 //! - polinomial B-Spline with boundary multiplicities degree+1
256 //! and Bezier - maximum distance between poles,
257 //! - rational B-Spline or one with boundary multiplicities not
258 //! degree+1 - maximum distance computed at knots and their
260 //! - surface of revolution - distance between ends of basis
262 //! - other (RectangularTrimmed and Offset) - maximum distance
263 //! computed at 100 equi-distanted points.
264 Standard_EXPORT Standard_Boolean IsVClosed (const Standard_Real preci = -1);
266 //! Computes the parameters in the surface parametrical space of
268 //! The result is parameters of the point projected onto the
270 //! This method enhances functionality provided by the standard
271 //! tool GeomAPI_ProjectPointOnSurface by treatment of cases when
272 //! the projected point is near to the surface boundaries and
273 //! when this standard tool fails.
274 Standard_EXPORT gp_Pnt2d ValueOfUV (const gp_Pnt& P3D, const Standard_Real preci);
276 //! Projects a point P3D on the surface.
277 //! Does the same thing as ValueOfUV but tries to optimize
278 //! computations by taking into account previous point <p2dPrev>:
279 //! makes a step by UV and tries Newton algorithm.
280 //! If <maxpreci> >0. and distance between solution and
281 //! P3D is greater than <maxpreci>, that solution is considered
282 //! as bad, and ValueOfUV() is used.
283 //! If not succeded, calls ValueOfUV()
284 Standard_EXPORT gp_Pnt2d NextValueOfUV (const gp_Pnt2d& p2dPrev,
286 const Standard_Real preci,
287 const Standard_Real maxpreci = -1.0);
289 //! Tries a refinement of an already computed couple (U,V) by
290 //! using projecting 3D point on iso-lines:
291 //! 1. boundaries of the surface,
292 //! 2. iso-lines passing through (U,V)
293 //! 3. iteratively received iso-lines passing through new U and
294 //! new V (number of iterations is limited by 5 in each
296 //! Returns the best resulting distance between P3D and Value(U,V)
297 //! in the case of success. Else, returns a very great value
298 Standard_EXPORT Standard_Real UVFromIso (const gp_Pnt& P3D,
299 const Standard_Real preci,
303 //! Returns minimum value to consider the surface as U-closed
304 Standard_Real UCloseVal() const;
306 //! Returns minimum value to consider the surface as V-closed
307 Standard_Real VCloseVal() const;
309 Standard_EXPORT const Bnd_Box& GetBoxUF();
311 Standard_EXPORT const Bnd_Box& GetBoxUL();
313 Standard_EXPORT const Bnd_Box& GetBoxVF();
315 Standard_EXPORT const Bnd_Box& GetBoxVL();
320 DEFINE_STANDARD_RTTIEXT(ShapeAnalysis_Surface,Standard_Transient)
325 Handle(Geom_Surface) mySurf;
326 Handle(GeomAdaptor_HSurface) myAdSur;
327 Extrema_ExtPS myExtPS;
328 Standard_Boolean myExtOK;
329 Standard_Integer myNbDeg;
330 Standard_Real myPreci[4];
332 gp_Pnt2d myFirstP2d[4];
333 gp_Pnt2d myLastP2d[4];
334 Standard_Real myFirstPar[4];
335 Standard_Real myLastPar[4];
336 Standard_Boolean myUIsoDeg[4];
337 Standard_Boolean myIsos;
342 Handle(Geom_Curve) myIsoUF;
343 Handle(Geom_Curve) myIsoUL;
344 Handle(Geom_Curve) myIsoVF;
345 Handle(Geom_Curve) myIsoVL;
346 Standard_Boolean myIsoBoxes;
352 Standard_Real myUDelt;
353 Standard_Real myVDelt;
354 Standard_Real myUCloseVal;
355 Standard_Real myVCloseVal;
361 //! Computes singularities on the surface.
362 //! Computes the sizes of boundaries or singular ares of the
363 //! surface. Then each boundary or area is considered as
364 //! degenerated with precision not less than its size.
366 //! The singularities and corresponding precisions are the
368 //! - ConicalSurface - one degenerated point (apex of the cone),
370 //! - ToroidalSurface - two degenerated points, precision is
371 //! Max (0, majorR-minorR),
372 //! - SphericalSurface - two degenerated points (poles),
374 //! - Bounded, Surface Of Revolution, Offset - four degenerated
375 //! points, precisions are maximum distance between corners
376 //! and middle point on the boundary
377 Standard_EXPORT void ComputeSingularities();
379 Standard_EXPORT void ComputeBoxes();
381 //! @return 0, 1 or 2.
382 Standard_EXPORT Standard_Integer SurfaceNewton (const gp_Pnt2d& p2dPrev,
384 const Standard_Real preci,
387 Standard_EXPORT void SortSingularities();
394 #include <ShapeAnalysis_Surface.lxx>
400 #endif // _ShapeAnalysis_Surface_HeaderFile