src/Geom/Geom_OffsetSurface.cdl

   1 -- Created on: 1993-03-10
   2 -- Created by: JCV
   3 -- Copyright (c) 1993-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 -- Modified: 18/11/96 : JPI : ajout methode Surface
  18
  19 class OffsetSurface from Geom inherits Surface from Geom
  20
  21         ---Purpose : Describes an offset surface in 3D space.
  22         -- An offset surface is defined by:
  23         -- - the basis surface to which it is parallel, and
  24         -- - the distance between the offset surface and its basis surface.
  25         --   A point on the offset surface is built by measuring the
  26         -- offset value along the normal vector at a point on the
  27         -- basis surface. This normal vector is given by the cross
  28         -- product D1u^D1v, where D1u and D1v are the
  29         -- vectors tangential to the basis surface in the u and v
  30         -- parametric directions at this point. The side of the
  31         -- basis surface on which the offset is measured
  32         -- depends on the sign of the offset value.
  33         -- A Geom_OffsetSurface surface can be
  34         -- self-intersecting, even if the basis surface does not
  35         -- self-intersect. The self-intersecting portions are not
  36         -- deleted at the time of construction.
  37         -- Warning
  38         -- There must be only one normal vector defined at any
  39         -- point on the basis surface. This must be verified by the
  40         -- user as no check is made at the time of construction
  41         -- to detect points with multiple possible normal
  42         -- directions (for example, the top of a conical surface).
  43
  44
  45
  46 uses Pnt              from gp,
  47      Trsf             from gp,
  48      GTrsf2d          from gp,
  49      Vec              from gp,
  50      Curve            from Geom,
  51      Geometry         from Geom,
  52      BSplineSurface   from Geom,
  53      Shape            from GeomAbs,
  54      Surface          from Geom,
  55      SequenceOfBSplineSurface  from Geom,
  56      OsculatingSurface from Geom
  57
  58 --     Array1OfBoolean from TColStd
  59
  60 raises ConstructionError   from Standard,
  61        RangeError          from Standard,
  62        NoSuchObject        from Standard,
  63        UndefinedDerivative from Geom,
  64        UndefinedValue      from Geom
  65
  66
  67 is
  68
  69
  70
  71   Create (S : Surface from Geom; Offset : Real)   returns OffsetSurface
  72         ---Purpose : Constructs a surface offset from the basis surface
  73         -- S, where Offset is the distance between the offset
  74         -- surface and the basis surface at any point.
  75         -- A point on the offset surface is built by measuring
  76         -- the offset value along a normal vector at a point on
  77         -- S. This normal vector is given by the cross product
  78         -- D1u^D1v, where D1u and D1v are the vectors
  79         -- tangential to the basis surface in the u and v
  80         -- parametric directions at this point. The side of S on
  81         -- which the offset value is measured is indicated by
  82         -- this normal vector if Offset is positive, or is the
  83         -- inverse sense if Offset is negative.
  84         --  Warnings :
  85         -- - The offset surface is built with a copy of the
  86         --   surface S. Therefore, when S is modified the
  87         --   offset surface is not modified.
  88         -- - No check is made at the time of construction to
  89         --   detect points on S with multiple possible normal directions.
  90      raises ConstructionError;
  91         ---Purpose : Raised if S is not at least C1.
  92         --  Warnings :
  93         --  No check is done to verify that a unique normal direction is
  94         --  defined at any point of the basis surface S.
  95
  96
  97
  98   SetBasisSurface (me : mutable; S : Surface from Geom)
  99      raises ConstructionError;
 100         ---Purpose : Raised if S is not at least C1.
 101         --  Warnings :
 102         --  No check is done to verify that a unique normal direction is
 103         --  defined at any point of the basis surface S.
 104         -- Exceptions
 105         -- Standard_ConstructionError if the surface S is not
 106         -- at least "C1" continuous.
 107
 108   SetOffsetValue (me : mutable; D : Real);
 109         ---Purpose: Changes this offset surface by assigning D as the offset value.
 110
 111   Offset (me)   returns Real;
 112
 113         ---Purpose: Returns the offset value of this offset surface.
 114
 115   BasisSurface (me)  returns Surface from Geom;
 116
 117         --- Purpose: Returns the basis surface of this offset surface.
 118         --  Note: The basis surface can be an offset surface.
 119
 120   UReverse (me : mutable);
 121         ---Purpose : Changes the orientation of this offset surface in the u
 122         -- parametric direction. The bounds of the surface
 123         -- are not changed but the given parametric direction is reversed.
 124
 125   UReversedParameter (me; U : Real) returns Real;
 126         ---Purpose: Computes the u  parameter on the modified
 127         -- surface, produced by reversing the u
 128         -- parametric direction of this offset surface, for any
 129         -- point of u parameter U  on this offset surface.
 130
 131
 132   VReverse (me : mutable);
 133         ---Purpose :  Changes the orientation of this offset surface in the v parametric direction. The bounds of the surface
 134         -- are not changed but the given parametric direction is reversed.
 135
 136   VReversedParameter (me; V : Real) returns Real;
 137         ---Purpose: Computes the  v parameter on the modified
 138         -- surface, produced by reversing the or v
 139         -- parametric direction of this offset surface, for any
 140         -- point of  v parameter V on this offset surface.
 141
 142
 143   Bounds (me; U1, U2, V1, V2 : out Real);
 144         ---Purpose : Returns the parametric bounds U1, U2, V1 and V2 of
 145         -- this offset surface.
 146         -- If the surface is infinite, this function can return:
 147         -- - Standard_Real::RealFirst(), or
 148         -- - Standard_Real::RealLast().
 149
 150   Continuity (me)   returns Shape from GeomAbs;
 151         ---Purpose :
 152         --  This method returns the continuity of the basis surface - 1.
 153         --  Continuity of the Offset surface :
 154         --  C0 : only geometric continuity,
 155         --  C1 : continuity of the first derivative all along the Surface,
 156         --  C2 : continuity of the second derivative all along the Surface,
 157         --  C3 : continuity of the third derivative all along the Surface,
 158         --  CN : the order of continuity is infinite.
 159         -- Example :
 160         --  If the basis surface is C2 in the V direction and C3 in the U
 161         --  direction Shape = C1.
 162         -- Warnings :
 163         --  If the basis surface has a unique normal direction defined at
 164         --  any point this method gives the continuity of the offset
 165         --  surface otherwise the effective continuity can be lower than
 166         --  the continuity of the basis surface - 1.
 167
 168
 169   IsCNu(me; N : Integer)   returns Boolean
 170         ---Purpose :
 171         --  This method answer True if the continuity of the basis surface
 172         --  is N + 1 in the U parametric direction. We suppose in this
 173         --  class that a unique normal is defined at any point on the basis
 174         --  surface.
 175      raises RangeError;
 176         ---Purpose : Raised if N <0.
 177
 178
 179   IsCNv (me; N : Integer)   returns Boolean
 180         ---Purpose :
 181         --  This method answer True if the continuity of the basis surface
 182         --  is N + 1 in the V parametric direction. We suppose in this
 183         --  class that a unique normal is defined at any point on the basis
 184         --  surface.
 185      raises RangeError;
 186         ---Purpose : Raised if N <0.
 187
 188   IsUClosed (me)     returns Boolean;
 189         ---Purpose: Checks whether this offset surface is closed in the u
 190         --  parametric direction.
 191         -- Returns true if, taking uFirst and uLast as
 192         --   the parametric bounds in the u parametric direction,
 193         --   the distance between the points P(uFirst,v)
 194         --   and P(uLast,v) is less than or equal to
 195         --   gp::Resolution() for each value of the   parameter v.
 196
 197   IsVClosed (me)     returns Boolean;
 198         ---Purpose: Checks whether this offset surface is closed in the u
 199         -- or v parametric direction. Returns true if taking vFirst and vLast as the
 200         --   parametric bounds in the v parametric direction, the
 201         --   distance between the points P(u,vFirst) and
 202         --   P(u,vLast) is less than or equal to
 203         --   gp::Resolution() for each value of the parameter u.
 204
 205   IsUPeriodic (me)   returns Boolean;
 206         ---Purpose:
 207         -- Returns true if this offset surface is periodic in the u
 208         -- parametric direction, i.e. if the basis
 209         -- surface of this offset surface is periodic in this direction.
 210
 211   UPeriod (me)    returns Real from Standard
 212         ---Purpose: Returns the period of this offset surface in the u
 213         -- parametric direction respectively, i.e. the period of the
 214         -- basis surface of this offset surface in this parametric direction.
 215   raises
 216         NoSuchObject from Standard
 217         ---Purpose: raises if the surface is not uperiodic.
 218   is redefined;
 219
 220   IsVPeriodic (me)   returns Boolean;
 221         ---Purpose:
 222         -- Returns true if this offset surface is periodic in the v
 223         -- parametric direction, i.e. if the basis
 224         -- surface of this offset surface is periodic in this direction.
 225
 226   VPeriod (me)    returns Real from Standard
 227         ---Purpose: Returns the period of this offset surface in the v
 228         -- parametric direction respectively, i.e. the period of the
 229         -- basis surface of this offset surface in this parametric direction.
 230   raises
 231         NoSuchObject from Standard
 232         ---Purpose: raises if the surface is not vperiodic.
 233   is redefined;
 234
 235   UIso (me; U : Real)  returns Curve;
 236         ---Purpose : Computes the U isoparametric curve.
 237
 238   VIso (me; V : Real)  returns Curve;
 239         ---Purpose : Computes the V isoparametric curve.
 240
 241
 242
 243
 244         ---Purpose :
 245         --  Te followings methods compute value and derivatives.
 246         --
 247         --- Warnings
 248         --  An exception is raised if a unique normal vector is
 249         --  not defined on the basis surface for the parametric
 250         --  value (U,V).
 251         --  No check is done at the creation time and we suppose
 252         --  in this package that the offset surface can be defined
 253         --  at any point.
 254
 255
 256   D0 (me; U, V : Real; P : out Pnt)
 257         ---Purpose :
 258         --  P (U, V) = Pbasis + Offset * Ndir   where
 259         --  Ndir = D1Ubasis ^ D1Vbasis / ||D1Ubasis ^ D1Vbasis|| is the
 260         --  normal direction of the basis surface. Pbasis, D1Ubasis,
 261         --  D1Vbasis are the point and the first derivatives on the basis
 262         --  surface.
 263         --  If Ndir is undefined this method computes an approched normal
 264         --  direction using the following limited development :
 265         --  Ndir = N0 + DNdir/DU + DNdir/DV + Eps with Eps->0 which
 266         --  requires to compute the second derivatives on the basis surface.
 267         --  If the normal direction cannot be approximate for this order
 268         --  of derivation the exception UndefinedValue is raised.
 269      raises UndefinedValue;
 270         ---Purpose :
 271         --  Raised if the continuity of the basis surface is not C1.
 272         --  Raised if the order of derivation required to compute the
 273         --  normal direction is greater than the second order.
 274
 275
 276   D1 (me; U, V : Real; P : out Pnt; D1U, D1V : out Vec)
 277      raises UndefinedDerivative;
 278         ---Purpose :
 279         --  Raised if the continuity of the basis surface is not C2.
 280
 281
 282   D2 (me; U, V : Real; P : out Pnt; D1U, D1V, D2U, D2V, D2UV : out Vec)
 283      raises UndefinedDerivative;
 284         ---Purpose ;
 285         --  Raised if the continuity of the basis surface is not C3.
 286
 287
 288   D3 (me; U, V : Real;  P : out Pnt;
 289       D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV : out Vec)
 290      raises UndefinedDerivative;
 291         ---Purpose :
 292         --  Raised if the continuity of the basis surface is not C4.
 293
 294
 295   DN (me; U, V : Real; Nu, Nv : Integer)   returns Vec
 296         ---Purpose :
 297         --  Computes the derivative of order Nu in the direction u and Nv
 298         --  in the direction v.
 299      raises UndefinedDerivative,
 300         ---Purpose ;
 301         --  Raised if the continuity of the basis surface is not CNu + 1
 302         --  in the U direction and CNv + 1 in the V direction.
 303             RangeError;
 304         ---Purpose : Raised if Nu + Nv < 1 or Nu < 0 or Nv < 0.
 305
 306
 307
 308
 309
 310         ---Purpose  :
 311         --  The following methods compute the value and derivatives
 312         --  on the offset surface and returns the derivatives on the
 313         --  basis surface too.
 314         --  The computation of the value and derivatives on the basis
 315         --  surface are used to evaluate the offset surface.
 316         --
 317         --  Warnings :
 318         --  The exception UndefinedValue or UndefinedDerivative is
 319         --  raised if it is not possible to compute a unique offset
 320         --  direction.
 321
 322
 323
 324   Value(me; U, V : Real; P, Pbasis : out Pnt; D1Ubasis, D1Vbasis : out Vec)
 325         ---Purpose :
 326         --  P (U, V) = Pbasis + Offset * Ndir   where
 327         --  Ndir = D1Ubasis ^ D1Vbasis / ||D1Ubasis ^ D1Vbasis|| is
 328         --  the normal direction of the surface.
 329         --  If Ndir is undefined this method computes an approched normal
 330         --  direction using the following limited development :
 331         --  Ndir = N0 + DNdir/DU + DNdir/DV + Eps with Eps->0 which
 332         --  requires to compute the second derivatives on the basis surface.
 333         --  If the normal direction cannot be approximate for this order
 334         --  of derivation the exception UndefinedValue is raised.
 335      raises UndefinedValue;
 336         ---Purpose :
 337         --  Raised if the continuity of the basis surface is not C1.
 338         --  Raised if the order of derivation required to compute the normal
 339         --  direction is greater than the second order.
 340
 341
 342   D1 (me; U, V : Real; P, Pbasis : out Pnt; D1U, D1V, D1Ubasis, D1Vbasis,
 343       D2Ubasis, D2Vbasis, D2UVbasis : out Vec)
 344      raises UndefinedDerivative;
 345         ---Purpose :
 346         --  Raised if the continuity of the basis surface is not C2.
 347
 348
 349   D2 (me; U, V : Real; P, Pbasis : out Pnt; D1U, D1V, D2U, D2V, D2UV,
 350       D1Ubasis, D1Vbasis, D2Ubasis, D2Vbasis, D2UVbasis, D3Ubasis, D3Vbasis,
 351       D3UUVbasis, D3UVVbasis : out Vec)
 352      raises UndefinedDerivative;
 353         ---Purpose :
 354         --  Raised if the continuity of the basis surface is not C3.
 355
 356
 357
 358
 359         ---Purpose :  The  following  private  methods
 360                   --  includes common part of local  and  global methods
 361                   --  of  derivative  evaluations.
 362
 363   SetD0 (me; U, V : Real; P : out Pnt; D1U, D1V : Vec)
 364                    raises UndefinedDerivative
 365                    is  private;
 366   SetD1 (me; U, V : Real; P : out Pnt; D1U, D1V : out Vec;
 367           d2u,d2v,d2uv : Vec)
 368                    raises UndefinedDerivative
 369                    is  private;
 370   SetD2 (me; U, V : Real; P : out Pnt;
 371              D1U, D1V, D2U, D2V, D2UV : out Vec;
 372              d3u,d3v,d3uuv,d3uvv :  Vec )
 373                    raises UndefinedDerivative
 374                    is  private;
 375   SetD3 (me; U, V : Real;  P : out Pnt;
 376              D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV : out Vec)
 377                    raises UndefinedDerivative
 378                    is  private;
 379
 380   SetDN(me;  U, V : Real;  Nu,  Nv  :  Integer;
 381              D1U, D1V  : Vec)
 382         returns  Vec
 383         is  private;
 384
 385         ---Purpose : The following  functions  evaluates the  local
 386         -- derivatives on surface. Useful to manage discontinuities
 387         -- on the surface.
 388         --           if    Side  =  1  ->  P  =  S( U+,V )
 389         --           if    Side  = -1  ->  P  =  S( U-,V )
 390         --           else  P  is betveen discontinuities
 391         --           can be evaluated using methods  of
 392         --           global evaluations    P  =  S( U ,V )
 393
 394   LocalD0 (me; U, V : Real; USide, VSide : Integer;
 395                P : out Pnt);
 396
 397   LocalD1 (me; U, V : Real;  USide, VSide : Integer;
 398           P : out Pnt; D1U, D1V : out Vec);
 399
 400   LocalD2 (me; U, V : Real; USide, VSide : Integer;
 401            P : out Pnt; D1U, D1V, D2U, D2V, D2UV : out Vec);
 402
 403   LocalD3 (me; U, V : Real; USide, VSide : Integer;
 404            P : out Pnt; D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV :
 405            out Vec);
 406
 407   LocalDN (me; U, V : Real; USide, VSide : Integer;
 408            Nu, Nv : Integer)
 409      returns Vec;
 410
 411    LocateSides(me ;  U,V  :  Real; USide,  VSide :  Integer ;
 412                 BSplS  :  BSplineSurface  from  Geom;
 413                 NDir  :  Integer  ;  P  :  out  Pnt ;
 414                 D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV :  out  Vec )
 415         ---Purpose: This  method locates U,V parameters on basis BSpline surface
 416              -- and calls LocalDi or Di methods corresponding an order
 417              -- of derivative and  position
 418              -- of UV-point relatively the surface discontinuities.
 419     is  private  ;
 420
 421    Transform (me : mutable; T : Trsf);
 422         --- Purpose:
 423         -- Applies the transformation T to this offset surface.
 424         -- Note: the basis surface is also modified.
 425
 426   TransformParameters(me; U,V : in out Real; T : Trsf from gp)
 427         ---Purpose: Computes the  parameters on the  transformed  surface for
 428         --          the transform of the point of parameters U,V on <me>.
 429         --
 430         --          me->Transformed(T)->Value(U',V')
 431         --
 432         --          is the same point as
 433         --
 434         --          me->Value(U,V).Transformed(T)
 435         --
 436         --          Where U',V' are the new values of U,V after calling
 437         --
 438         --          me->TranformParameters(U,V,T)
 439         --          This methods calls the basis surface method.
 440      is redefined;
 441
 442   ParametricTransformation(me; T : Trsf from gp) returns GTrsf2d from gp
 443         ---Purpose: Returns a 2d transformation  used to find the  new
 444         --          parameters of a point on the transformed surface.
 445         --
 446         --          me->Transformed(T)->Value(U',V')
 447         --
 448         --          is the same point as
 449         --
 450         --          me->Value(U,V).Transformed(T)
 451         --
 452         --          Where U',V' are  obtained by transforming U,V with
 453         --          th 2d transformation returned by
 454         --
 455         --          me->ParametricTransformation(T)
 456         --
 457         --          This methods calls the basis surface method.
 458      is redefined;
 459
 460   Copy (me)  returns like me;
 461         ---Purpose: Creates a new object which is a copy of this offset surface.
 462
 463   Surface (me) returns Surface from Geom;
 464         ---Purpose: returns an  equivalent surface of the offset surface
 465         --          when  the basis surface   is a canonic  surface or a
 466         --          rectangular  limited surface on canonic surface or if
 467         --          the offset is null.
 468
 469   UOsculatingSurface (me ; U,V : Real ; IsOpposite : out Boolean from Standard
 470                                       ; UOsculSurf : out BSplineSurface from Geom)
 471         ---Purpose: if Standard_True, L is  the local osculating surface
 472         --          along U at  the point U,V.   It means that  DL/DU is
 473         --          collinear to DS/DU .  If IsOpposite == Standard_True
 474         --          these vectors have opposite direction.
 475         --
 476       returns Boolean from Standard;
 477
 478   VOsculatingSurface (me ; U,V : Real ; IsOpposite : out Boolean from Standard
 479                                       ; VOsculSurf : out BSplineSurface from Geom)
 480         ---Purpose: if Standard_True, L is the local osculating surface
 481         --          along V at the point U,V.
 482         --          It means that  DL/DV is
 483         --          collinear to DS/DV .  If IsOpposite == Standard_True
 484         --          these vectors have opposite direction.
 485      returns Boolean from Standard;
 486
 487
 488 fields
 489
 490   basisSurf   : Surface from Geom;
 491   equivSurf   : Surface from Geom;
 492   offsetValue : Real;
 493   myOscSurf   : OsculatingSurface from Geom;
 494 end;