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