src/ShapeAnalysis/ShapeAnalysis_Surface.cdl

   1 -- Created on: 1998-06-03
   2 -- Created by: data exchange team
   3 -- Copyright (c) 1998-1999 Matra Datavision
   4 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
   5 --
   6 -- The content of this file is subject to the Open CASCADE Technology Public
   7 -- License Version 6.5 (the "License"). You may not use the content of this file
   8 -- except in compliance with the License. Please obtain a copy of the License
   9 -- at http://www.opencascade.org and read it completely before using this file.
  10 --
  11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
  12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
  13 --
  14 -- The Original Code and all software distributed under the License is
  15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
  16 -- Initial Developer hereby disclaims all such warranties, including without
  17 -- limitation, any warranties of merchantability, fitness for a particular
  18 -- purpose or non-infringement. Please see the License for the specific terms
  19 -- and conditions governing the rights and limitations under the License.
  20
  21
  22
  23 class Surface from ShapeAnalysis inherits TShared from MMgt
  24
  25     ---Purpose: Complements standard tool Geom_Surface by providing additional
  26     --          functionality for detection surface singularities, checking
  27     --          spatial surface closure and computing projections of 3D points
  28     --          onto a surface.
  29     --
  30     --          * The singularities
  31     --          Each singularity stores the precision with which corresponding
  32     --          surface iso-line is considered as degenerated.
  33     --          The number of singularities is determined by specifying precision
  34     --          and always not greater than 4.
  35     --
  36     --          * The spatial closure
  37     --          The check for spatial closure is performed with given precision
  38     --          (default value is Precision::Confusion).
  39     --          If Geom_Surface says that the surface is closed, this class
  40     --          also says this. Otherwise additional analysis is performed.
  41     --
  42     --          * The parameters of 3D point on the surface
  43     --          The projection of the point is performed with given precision.
  44     --          This class tries to find a solution taking into account possible
  45     --          singularities.
  46     --          Additional method for searching the solution from already built
  47     --          one is also provided.
  48     --
  49     --          This tool is optimised: computes most information only once
  50
  51 uses
  52     Pnt   from gp,
  53     Pnt2d from gp,
  54     Box from Bnd,
  55     Curve   from Geom,
  56     Surface from Geom,
  57     Surface  from GeomAdaptor,
  58     HSurface from GeomAdaptor,
  59     ExtPS from Extrema,
  60     Array1OfPnt from TColgp,
  61     Array1OfPnt2d from TColgp
  62
  63 is
  64     Create (S : Surface from Geom) returns mutable Surface from ShapeAnalysis;
  65         ---Purpose: Creates an analyzer object on the basis of existing surface
  66
  67     Init (me : mutable; S: Surface from Geom);
  68         ---Purpose: Loads existing surface
  69
  70     Init (me : mutable; other: Surface from ShapeAnalysis);
  71         ---Purpose: Reads all the data from another Surface, without recomputing
  72
  73     SetDomain(me : mutable; U1, U2, V1, V2 : Real);
  74
  75     Surface (me) returns Surface from Geom;
  76         ---C++: return const &
  77         ---C++: inline
  78         ---Purpose: Returns a surface being analyzed
  79
  80     Adaptor3d (me : mutable) returns HSurface from GeomAdaptor;
  81         ---C++: return const &
  82         ---Purpose: Returns the Adaptor.
  83         --          Creates it if not yet done.
  84
  85     TrueAdaptor3d (me) returns HSurface from GeomAdaptor;
  86         ---C++: return const &
  87         ---C++: inline
  88         ---Purpose: Returns the Adaptor (may be Null if method Adaptor() was not called)
  89
  90     Gap (me) returns Real;
  91         ---C++: inline
  92         ---Purpose: Returns 3D distance found by one of the following methods.
  93         --          IsDegenerated, DegeneratedValues, ProjectDegenerated
  94         --          (distance between 3D point and found or last (if not found)
  95         --          singularity),
  96         --          IsUClosed, IsVClosed (minimum value of precision to consider
  97         --          the surface to be closed),
  98         --          ValueOfUV (distance between 3D point and found solution).
  99
 100     Value (me : mutable; u,v : Real) returns Pnt from gp;
 101         ---C++: inline
 102         ---Purpose: Returns a 3D point specified by parameters in surface
 103         --          parametrical space
 104
 105     Value (me : mutable; p2d : Pnt2d from gp) returns Pnt from gp;
 106         ---C++: inline
 107         ---Purpose: Returns a 3d point specified by a point in surface
 108         --          parametrical space
 109
 110     ComputeSingularities (me: mutable) is private;
 111         ---Purpose: Computes singularities on the surface.
 112         --          Computes the sizes of boundaries or singular ares of the
 113         --          surface. Then each boundary or area is considered as
 114         --          degenerated with precision not less than its size.
 115         --
 116         --          The singularities and corresponding precisions are the
 117         --          following:
 118         --          - ConicalSurface -  one degenerated point (apex of the cone),
 119         --              precision is 0.,
 120         --          - ToroidalSurface - two degenerated points, precision is
 121         --              Max (0, majorR-minorR),
 122         --          - SphericalSurface - two degenerated points (poles),
 123         --              precision is 0.
 124         --          - Bounded, Surface Of Revolution, Offset - four degenerated
 125         --              points, precisions are maximum distance between corners
 126         --              and middle point on the boundary
 127         --
 128         ---Remark:  Considers only boundaries of the surface (i.e. does not detect
 129         --          singularity if it is inside parametrical space)
 130
 131     HasSingularities (me: mutable; preci: Real) returns Boolean;
 132         ---Purpose: Returns True if the surface has singularities for the given
 133         --          precision (i.e. if there are surface singularities with sizes
 134         --          not greater than precision).
 135
 136     NbSingularities (me: mutable; preci: Real) returns Integer;
 137         ---Purpose: Returns the number of singularities for the given precision
 138         --          (i.e. number of surface singularities with sizes not greater
 139         --          than precision).
 140
 141     Singularity (me: mutable; num              : Integer;
 142                               preci            : out Real;
 143                               P3d              : out Pnt from gp;
 144                               firstP2d, lastP2d: out Pnt2d from gp;
 145                               firstpar, lastpar: out Real;
 146                               uisodeg          : out Boolean)
 147     returns Boolean;
 148         ---Purpose: Returns the characteristics of the singularity specified by
 149         --          its rank number <num>.
 150         --          That means, that it is not neccessary for <num> to be in the
 151         --          range [1, NbSingularities] but must be not greater than
 152         --          possible (see ComputeSingularities).
 153         --          The returned characteristics are:
 154         --          preci: the smallest precision with which the iso-line is
 155         --                 considered as degenerated,
 156         --          P3d: 3D point of singularity (middle point of the surface
 157         --               iso-line),
 158         --          firstP2d and lastP2d: first and last 2D points of the
 159         --                                iso-line in parametrical surface,
 160         --          firstpar and lastpar: first and last parameters of the
 161         --                                iso-line in parametrical surface,
 162         --          uisodeg: if the degenerated iso-line is U-iso (True) or
 163         --          V-iso (False).
 164         --          Returns False if <num> is out of range, else returns True.
 165         ---Remarks  - all the singularities are sorted in ascending order by
 166         --            precision
 167         --          - firstP2d and lastP2d are such to define left-hand passing of
 168         --            parametrical space
 169
 170     IsDegenerated (me: mutable; P3d  : Pnt from gp;
 171                                 preci: Real)
 172     returns Boolean;
 173         ---Purpose: Returns True if there is at least one surface boundary which
 174         --          is considered as degenerated with <preci> and distance
 175         --          between P3d and corresponding singular point is less than
 176         --          <preci>
 177
 178     DegeneratedValues (me: mutable; P3d              : Pnt from gp;
 179                                     preci            : Real;
 180                                     firstP2d, lastP2d: out Pnt2d from gp;
 181                                     firstpar, lastpar: out Real;
 182                                     forward          : Boolean = Standard_True)
 183     returns Boolean;
 184         ---Purpose: Returns True if there is at least one surface iso-line which
 185         --          is considered as degenerated with <preci> and distance
 186         --          between P3d and corresponding singular point is less than
 187         --          <preci> (like IsDegenerated).
 188         --          Returns characteristics of the first found boundary matching
 189         --          those criteria.
 190         ---Remark : <forward> is not used
 191
 192     ProjectDegenerated (me: mutable; P3d      : Pnt from gp;
 193                                      preci    : Real;
 194                                      neighbour: Pnt2d from gp;
 195                                      result   : in out Pnt2d from gp)
 196     returns Boolean;
 197         ---Purpose: Projects a point <P3d> on a singularity by computing
 198         --          one of the coordinates of preliminary computed <result>.
 199         --
 200         --          Finds the iso-line which is considered as degenerated with
 201         --          <preci> and
 202         --          a. distance between P3d and corresponding singular point is
 203         --             less than <preci> (like IsDegenerated) or
 204         --          b. difference between already computed <result>'s coordinate
 205         --             and iso-coordinate of the boundary is less than 2D
 206         --             resolution (computed from <preci> by Geom_Adaptor).
 207         --          Then sets not yet computed <result>'s coordinate taking it
 208         --          from <neighbour> and returns True.
 209         ---Example: U-iso at Ufirst=0 is degenerated with 1e-03,
 210         --          <neighbour> = (0, 0.5),
 211         --          <result> = (1e-06, ?); (1e-06 - already computed, ? - not yet)
 212         --          After, <result> will be (1e-06, 0.5): 0.5 is taken from <neighbour>
 213         --
 214         ---Remark : This is only one method to compute the coordinate taking it
 215         --          from neighbour point. Other methods are also possible (by
 216         --          using tangent or C2, etc).
 217         --
 218         --          If the P3d is not on a singularity, no computation is done,
 219         --          returns False and <result> remains unchanged
 220
 221     ProjectDegenerated (me: mutable; nbrPnt: Integer;
 222                                      points: Array1OfPnt from TColgp;
 223                                      pnt2d : in out Array1OfPnt2d from TColgp;
 224                                      preci : Real;
 225                                      direct: Boolean)
 226     returns Boolean;
 227         ---Purpose: Checks points at the beginning (direct is True) or end
 228         --          (direct is False) of array <points> to lie in singularity of
 229         --          surface, and if yes, adjusts the indeterminate 2d coordinate
 230         --          of these points by nearest point which is not in singularity.
 231         --          Returns True if some points were adjusted.
 232
 233     IsDegenerated (me: mutable; p2d1, p2d2: Pnt2d from gp; tol, ratio: Real)
 234     returns Boolean;
 235         ---Purpose: Returns True if straight pcurve going from point p2d1 to p2d2
 236         --          is degenerate, i.e. lies in the singularity of the surface.
 237         --          NOTE: it uses another method of detecting singularity than
 238         --                used by ComputeSingularities() et al.!
 239         --          For that, maximums of distances between points p2d1, p2d2
 240         --          and 0.5*(p2d1+p2d2) and between corresponding 3d points are
 241         --          computed.
 242         --          The pcurve (p2d1, p2d2) is considered as degenerate if:
 243         --          - max distance in 3d is less than <tol>
 244         --          - max distance in 2d is at least <ratio> times greather than
 245         --            the Resolution computed from max distance in 3d
 246         --            (max3d < tol && max2d > ratio * Resolution(max3d))
 247         --          NOTE: <ratio> should be >1 (e.g. 10)
 248
 249     Bounds (me; ufirst, ulast, vfirst, vlast: out Real);
 250         ---C++: inline
 251         ---Purpose: Returns the bounds of the surface
 252         --          (from Bounds from Surface, but buffered)
 253
 254     ComputeBoundIsos(me : mutable);
 255         ---Purpose: Computes bound isos (protected against exceptions)
 256
 257     UIso (me: mutable; U: Real) returns Curve from Geom;
 258         ---Purpose: Returns a U-Iso. Null if not possible or failed
 259         --          Remark : bound isos are buffered
 260
 261     VIso (me: mutable; V: Real) returns Curve from Geom;
 262         ---Purpose: Returns a V-Iso. Null if not possible or failed
 263         --          Remark : bound isos are buffered
 264
 265     IsUClosed (me: mutable; preci: Real = -1) returns Boolean;
 266         ---Purpose: Tells if the Surface is spatially closed in U with given
 267         --          precision. If <preci> < 0 then Precision::Confusion is used.
 268         --          If Geom_Surface says that the surface is U-closed, this method
 269         --          also says this. Otherwise additional analysis is performed,
 270         --          comparing given precision with the following distances:
 271         --          - periodic B-Splines are closed,
 272         --          - polinomial B-Spline with boundary multiplicities degree+1
 273         --            and Bezier - maximum distance between poles,
 274         --          - rational B-Spline or one with boundary multiplicities not
 275         --            degree+1 - maximum distance computed at knots and their
 276         --            middles,
 277         --          - surface of extrusion - distance between ends of basis
 278         --            curve,
 279         --          - other (RectangularTrimmed and Offset) - maximum distance
 280         --            computed at 100 equi-distanted points.
 281
 282     IsVClosed (me: mutable; preci: Real = -1) returns Boolean;
 283         ---Purpose: Tells if the Surface is spatially closed in V with given
 284         --          precision. If <preci> < 0 then Precision::Confusion is used.
 285         --          If Geom_Surface says that the surface is V-closed, this method
 286         --          also says this. Otherwise additional analysis is performed,
 287         --          comparing given precision with the following distances:
 288         --          - periodic B-Splines are closed,
 289         --          - polinomial B-Spline with boundary multiplicities degree+1
 290         --            and Bezier - maximum distance between poles,
 291         --          - rational B-Spline or one with boundary multiplicities not
 292         --            degree+1 - maximum distance computed at knots and their
 293         --            middles,
 294         --          - surface of revolution - distance between ends of basis
 295         --            curve,
 296         --          - other (RectangularTrimmed and Offset) - maximum distance
 297         --            computed at 100 equi-distanted points.
 298
 299     ValueOfUV (me: mutable; P3D: Pnt from gp;
 300                             preci : Real)
 301     returns Pnt2d from gp;
 302         ---Purpose: Computes the parameters in the surface parametrical space of
 303         --          3D point.
 304         --          The result is parameters of the point projected onto the
 305         --          surface.
 306         --          This method enhances functionality provided by the standard
 307         --          tool GeomAPI_ProjectPointOnSurface by treatment of cases when
 308         --          the projected point is near to the surface boundaries and
 309         --          when this standard tool fails.
 310
 311     NextValueOfUV (me: mutable; p2dPrev: Pnt2d from gp;
 312                                 P3D    : Pnt from gp;
 313                                 preci  : Real;
 314                                 maxpreci:Real = -1.0)
 315     returns Pnt2d from gp;
 316         ---Purpose: Projects a point P3D on the surface.
 317         --          Does the same thing as ValueOfUV but tries to optimize
 318         --          computations by taking into account previous point <p2dPrev>:
 319         --          makes a step by UV and tries Newton algorithm.
 320         --          If <maxpreci> >0. and distance between solution and
 321         --          P3D is greater than <maxpreci>, that solution is considered
 322         --          as bad, and ValueOfUV() is used.
 323         --          If not succeded, calls ValueOfUV()
 324
 325     UVFromIso (me: mutable; P3D  : Pnt from gp;
 326                            preci : Real;
 327                            U, V  : in out Real)
 328     returns Real;
 329         ---Purpose: Tries a refinement of an already computed couple (U,V) by
 330         --          using projecting 3D point on iso-lines:
 331         --          1. boundaries of the surface,
 332         --          2. iso-lines passing through (U,V)
 333         --          3. iteratively received iso-lines passing through new U and
 334         --             new V (number of iterations is limited by 5 in each
 335         --             direction)
 336         --          Returns the best resulting distance between P3D and Value(U,V)
 337         --          in the case of success. Else, returns a very great value
 338
 339     UCloseVal (me) returns Real;
 340         ---C++: inline
 341         ---Purpose: Returns minimum value to consider the surface as U-closed
 342
 343     VCloseVal (me) returns Real;
 344         ---C++: inline
 345         ---Purpose: Returns minimum value to consider the surface as V-closed
 346
 347     GetBoxUF(me: mutable) returns Box from Bnd;
 348         ---C++: return const&
 349
 350     GetBoxUL(me: mutable) returns Box from Bnd;
 351         ---C++: return const&
 352
 353     GetBoxVF(me: mutable) returns Box from Bnd;
 354         ---C++: return const&
 355
 356     GetBoxVL(me: mutable) returns Box from Bnd;
 357         ---C++: return const&
 358
 359     ComputeBoxes(me: mutable) is private;
 360
 361     SurfaceNewton (me: mutable; p2dPrev: Pnt2d from gp;
 362                                 P3D    : Pnt from gp;
 363                                 preci  : Real;
 364                                 sol    :in out Pnt2d from gp)
 365     returns Boolean is private;
 366
 367     SortSingularities (me: mutable) is private;
 368
 369 fields
 370
 371     mySurf     : Surface  from Geom is protected;
 372     myAdSur    : HSurface from GeomAdaptor is protected;
 373
 374     myExtPS    : ExtPS from Extrema is protected;        -- speed optimization
 375     myExtSrf   : Surface from GeomAdaptor is protected;  -- for extrema
 376     myExtOK    : Boolean is protected;                   -- is theExtPS initialized?
 377
 378     myNbDeg    : Integer is protected; --  < 0 means not yet computed
 379     myPreci    : Real          [4] is protected;
 380     myP3d      : Pnt   from gp [4] is protected;
 381     myFirstP2d : Pnt2d from gp [4] is protected;
 382     myLastP2d  : Pnt2d from gp [4] is protected;
 383     myFirstPar : Real          [4] is protected;
 384     myLastPar  : Real          [4] is protected;
 385     myUIsoDeg  : Boolean       [4] is protected; -- True if U-iso is degenerated, False if V-iso
 386
 387     myIsos     : Boolean is protected;  -- are bound isos computed
 388     myUF       : Real is protected;
 389     myUL       : Real is protected;
 390     myVF       : Real is protected;
 391     myVL       : Real is protected;
 392     myIsoUF    : Curve from Geom is protected;
 393     myIsoUL    : Curve from Geom is protected;
 394     myIsoVF    : Curve from Geom is protected;
 395     myIsoVL    : Curve from Geom is protected;
 396     myIsoBoxes : Boolean is protected;  -- are boxes for bound isos computed
 397     myBndUF    : Box from Bnd is protected;
 398     myBndUL    : Box from Bnd is protected;
 399     myBndVF    : Box from Bnd is protected;
 400     myBndVL    : Box from Bnd is protected;
 401
 402     myGap      : Real is protected;
 403     myUDelt    : Real is protected; -- what overparametrisation to have good ValueOfUV
 404     myVDelt    : Real is protected;
 405
 406     myUCloseVal: Real is protected; -- minimum value to consider the surface as U-closed
 407     myVCloseVal: Real is protected; -- minimum value to consider the surface as V-closed
 408
 409 end Surface;