src/Geom2d/Geom2d_OffsetCurve.cdl

   1 -- Created on: 1993-03-24
   2 -- Created by: Philippe DAUTRY
   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 class OffsetCurve from Geom2d inherits Curve from Geom2d
  18
  19
  20         --- Purpose :
  21         --  This class implements the basis services for the creation,
  22         --  edition, modification and evaluation of planar offset curve.
  23         --  The offset curve is obtained by offsetting by distance along
  24         --  the normal to a basis curve defined in 2D space.
  25         --  The offset curve in this package can be a self intersecting
  26         --  curve even if the basis curve does not self-intersect.
  27         --  The self intersecting portions are not deleted at the
  28         --  construction time.
  29         --  An offset curve is a curve at constant distance (Offset) from a
  30         --  basis curve and the offset curve takes its parametrization from
  31         --  the basis curve. The Offset curve is in the direction of the
  32         --  normal to the basis curve N.
  33         --  The distance offset may be positive or negative to indicate the
  34         --  preferred side of the curve :
  35         --  . distance offset >0 => the curve is in the direction of N
  36         --  . distance offset >0 => the curve is in the direction of - N
  37         --  On the Offset curve :
  38         --  Value(u) = BasisCurve.Value(U) + (Offset * (T ^ Z)) / ||T ^ Z||
  39         --  where T is the tangent vector to the basis curve and Z the
  40         --  direction of the normal vector to the plane of the curve,
  41         --  N = T ^ Z defines the offset direction and should not have
  42         --  null length.
  43         --
  44         --  Warnings :
  45         --  In this package we suppose that the continuity of the offset
  46         --  curve is one degree less than the continuity of the
  47         --  basis curve and we don't check that at any point ||T^Z|| != 0.0
  48         --
  49         --  So to evaluate the curve it is better to check that the offset
  50         --  curve is well defined at any point because an exception could
  51         --  be raised. The check is not done in this package at the creation
  52         --  of the offset curve because the control needs the use of an
  53         --  algorithm which cannot be implemented in this package.
  54         --  The OffsetCurve is closed if the first point and the last point
  55         --  are the same (The distance between these two points is lower or
  56         --  equal to the Resolution sea package gp) . The OffsetCurve can be
  57         --  closed even if the basis curve is not closed.
  58
  59 uses Dir2d    from gp,
  60      Pnt2d    from gp,
  61      Trsf2d   from gp,
  62      Vec2d    from gp,
  63      Curve    from Geom2d,
  64      Geometry from Geom2d,
  65      Shape    from GeomAbs
  66
  67
  68 raises ConstructionError   from Standard,
  69        RangeError          from Standard,
  70        NoSuchObject        from Standard,
  71        UndefinedDerivative from Geom2d,
  72        UndefinedValue      from Geom2d,
  73        NotImplemented      from Standard
  74
  75
  76
  77 is
  78
  79
  80   Create (C : Curve from Geom2d;
  81           Offset : Real;
  82           isNotCheckC0 : Boolean = Standard_False)
  83
  84   returns OffsetCurve
  85         --- Purpose : Constructs a curve offset from the basis curve C,
  86         -- where Offset is the distance between the offset
  87         -- curve and the basis curve at any point.
  88         -- A point on the offset curve is built by measuring the
  89         -- offset value along a normal vector at a point on C.
  90         -- This normal vector is obtained by rotating the
  91         -- vector tangential to C at 90 degrees in the
  92         -- anti-trigonometric sense. The side of C on which
  93         -- the offset value is measured is indicated by this
  94         -- normal vector if Offset is positive, or in the inverse
  95         -- sense if Offset is negative.
  96       -- If isNotCheckC0 = TRUE checking if basis curve has C0-continuity
  97       -- is not made.
  98         --   Warnings :
  99         --  In this package the entities are not shared. The OffsetCurve is
 100         --  built with a copy of the curve C. So when C is modified the
 101         --  OffsetCurve is not modified
 102         --  Warning!  if isNotCheckC0 = false,
 103             -- ConstructionError  raised if the basis curve C is not at least C1.
 104         --  No check is done to know if ||V^Z|| != 0.0 at any point.
 105      raises ConstructionError;
 106
 107
 108
 109   Reverse (me : mutable);
 110         --- Purpose : Changes the direction of parametrization of <me>.
 111         --     As a result:
 112         -- - the basis curve is reversed,
 113         -- - the start point of the initial curve becomes the end
 114         --   point of the reversed curve,
 115         -- - the end point of the initial curve becomes the start
 116         --   point of the reversed curve, and
 117         -- - the first and last parameters are recomputed.
 118
 119
 120   ReversedParameter(me; U : Real) returns Real;
 121         ---Purpose: Computes the parameter on the reversed curve for
 122         -- the point of parameter U on this offset curve.
 123
 124
 125   SetBasisCurve ( me : mutable;
 126                   C : Curve from Geom2d;
 127                   isNotCheckC0 : Boolean = Standard_False)
 128      raises ConstructionError;
 129         --- Purpose : Changes this offset curve by assigning C as the
 130         -- basis curve from which it is built.
 131       -- If isNotCheckC0 = TRUE checking if basis curve has C0-continuity
 132       -- is not made.
 133         -- Exceptions
 134                 -- if isNotCheckC0 = false,
 135         -- Standard_ConstructionError if the curve C is not at least "C1" continuous.
 136
 137   SetOffsetValue (me : mutable; D : Real);
 138         --- Purpose :  Changes this offset curve by assigning D as the offset value.
 139
 140   BasisCurve (me) returns Curve from Geom2d;
 141         --- Purpose : Returns the basis curve of this offset curve. The basis curve can be an offset curve.
 142
 143
 144
 145   Continuity (me)  returns Shape from GeomAbs;
 146         --- Purpose :
 147         --  Continuity of the Offset curve :
 148         --  C0 : only geometric continuity,
 149         --  C1 : continuity of the first derivative all along the Curve,
 150         --  C2 : continuity of the second derivative all along the Curve,
 151         --  C3 : continuity of the third derivative all along the Curve,
 152         --  G1 : tangency continuity all along the Curve,
 153         --  G2 : curvature continuity all along the Curve,
 154         --  CN : the order of continuity is infinite.
 155         --   Warnings :
 156         --  Returns the continuity of the basis curve - 1.
 157         --  The offset curve must have a unique normal direction defined
 158         --  at any point.
 159
 160
 161
 162
 163
 164         --- Purpose  : Value and derivatives
 165         --
 166         --  Warnings :
 167         --  The exception UndefinedValue or UndefinedDerivative is
 168         --  raised if it is not possible to compute a unique offset
 169         --  direction.
 170         --  If T is the first derivative with not null length and
 171         --  Z the direction normal to the plane of the curve, the
 172         --  relation ||T(U) ^ Z|| != 0  must be satisfied to evaluate
 173         --  the offset curve.
 174         --  No check is done at the creation time and we suppose
 175         --  in this package that the offset curve is well defined.
 176
 177
 178   D0 (me; U : Real; P : out Pnt2d)
 179      raises UndefinedValue;
 180         ---Purpose:  Warning! this should not be called
 181         --          if the basis curve is not at least C1. Nevertheless
 182         --          if used on portion where the curve is C1, it is OK
 183
 184
 185
 186   D1 (me; U : Real; P : out Pnt2d; V1 : out Vec2d)
 187      raises UndefinedDerivative;
 188         ---Purpose:  Warning! this should not be called
 189         --           if the continuity of the basis curve is not C2.
 190         --           Nevertheless, it's OK to use it  on portion
 191         --           where the curve is C2
 192
 193
 194
 195   D2 (me; U : Real; P : out Pnt2d; V1, V2 : out Vec2d)
 196      raises UndefinedDerivative;
 197         ---Purpose:  Warning!  This  should  not  be called
 198         --           if the continuity of the basis curve is not C3.
 199         --           Nevertheless, it's OK to use it  on portion
 200         --           where the curve is C3
 201
 202   D3 (me; U : Real; P : out Pnt2d; V1, V2, V3 : out Vec2d)
 203      raises UndefinedDerivative;
 204
 205         ---Purpose:  Warning! This should not be called
 206         --           if the continuity of the basis curve is not C4.
 207         --           Nevertheless, it's OK to use it  on portion
 208         --           where the curve is C4
 209
 210   DN (me; U : Real; N : Integer)   returns Vec2d
 211         --- Purpose : The returned vector gives the value of the derivative
 212         --  for the order of derivation N.
 213         --  Warning! this should not be called
 214         --        raises  UndefunedDerivative   if the continuity of the basis curve is not CN+1.
 215         --           Nevertheless, it's OK to use it  on portion
 216         --           where the curve is CN+1
 217         -- raises  RangeError if N < 1.
 218         -- raises  NotImplemented if N > 3.
 219
 220      raises UndefinedDerivative,
 221
 222             RangeError,
 223             NotImplemented;
 224
 225
 226
 227         --- Purpose : The following functions compute the value and derivatives
 228         --  on the offset curve and returns the derivatives on the
 229         --  basis curve too.
 230         --  The computation of the value and derivatives on the basis
 231         --  curve are used to evaluate the offset curve
 232         --  Warnings :
 233         --  The exception UndefinedValue or UndefinedDerivative is
 234         --  raised if it is not possible to compute a unique offset direction.
 235
 236
 237   Value (me; U : Real; P, Pbasis : out Pnt2d; V1basis : out Vec2d)
 238      raises UndefinedValue;
 239
 240         ---Purpose:  Warning! this should not be called
 241         --          if the basis curve is not at least C1. Nevertheless
 242         --          if used on portion where the curve is C1, it is OK
 243
 244
 245   D1 (me; U : Real; P, Pbasis : out Pnt2d;
 246       V1, V1basis, V2basis : out Vec2d)
 247      raises UndefinedDerivative;
 248
 249         ---Purpose:  Warning! this should not be called
 250         --           if the continuity of the basis curve is not C1.
 251         --           Nevertheless, it's OK to use it  on portion
 252         --           where the curve is C1
 253
 254   D2 (me; U : Real; P, Pbasis : out Pnt2d;  V1, V2, V1basis, V2basis,
 255       V3basis : out Vec2d)
 256      raises UndefinedDerivative;
 257
 258         ---Purpose:  Warning! this should not be called
 259         --           if the continuity of the basis curve is not C3.
 260         --           Nevertheless, it's OK to use it  on portion
 261         --           where the curve is C3
 262
 263   FirstParameter (me)  returns Real;
 264
 265   LastParameter (me)   returns Real;
 266         ---Purpose: Returns the value of the first or last parameter of this
 267         -- offset curve. The first parameter corresponds to the
 268         -- start point of the curve. The last parameter
 269         -- corresponds to the end point.
 270         -- Note: the first and last parameters of this offset curve
 271         -- are also the ones of its basis curve.
 272
 273   Offset (me)          returns Real;
 274         ---Purpose: Returns the offset value of this offset curve.
 275
 276   IsClosed (me)   returns Boolean;
 277         --- Purpose :
 278         --  Returns True if the distance between the start point
 279         --  and the end point of the curve is lower or equal to
 280         --  Resolution from package gp.
 281
 282
 283   IsCN (me; N : Integer)  returns Boolean
 284         --- Purpose : Is the order of continuity of the curve N ?
 285         --   Warnings :
 286         --  This method answer True if the continuity of the basis curve
 287         --  is N + 1.  We suppose in this class that a normal direction
 288         --  to the basis curve (used to compute the offset curve) is
 289         --  defined at any point on the basis curve.
 290      raises RangeError;
 291         --- Purpose : Raised if N < 0.
 292
 293
 294   IsPeriodic (me)  returns Boolean;
 295         --- Purpose : Is the parametrization of a curve is periodic ?
 296         --  If the basis curve is a circle or an ellipse the corresponding
 297         --  OffsetCurve is periodic. If the basis curve can't be periodic
 298         --  (for example BezierCurve) the OffsetCurve can't be periodic.
 299
 300
 301   Period (me) returns Real from Standard
 302         ---Purpose: Returns the period of this offset curve, i.e. the period
 303         -- of the basis curve of this offset curve.
 304         -- Exceptions
 305         -- Standard_NoSuchObject if the basis curve is not periodic.
 306   raises  NoSuchObject from Standard
 307   is redefined;
 308
 309
 310   Transform (me : mutable; T : Trsf2d);
 311         ---Purpose : Applies the transformation T to this offset curve.
 312         -- Note: the basis curve is also modified.
 313
 314   TransformedParameter(me; U : Real; T : Trsf2d from gp) returns Real
 315         ---Purpose: Returns the  parameter on the  transformed  curve for
 316         --          the transform of the point of parameter U on <me>.
 317         --
 318         --          me->Transformed(T)->Value(me->TransformedParameter(U,T))
 319         --
 320         --          is the same point as
 321         --
 322         --          me->Value(U).Transformed(T)
 323         --
 324         --          This methods calls the basis curve method.
 325      is redefined;
 326
 327   ParametricTransformation(me; T : Trsf2d from gp) returns Real
 328         ---Purpose: Returns a  coefficient to compute the parameter on
 329         --          the transformed  curve  for  the transform  of the
 330         --          point on <me>.
 331         --
 332         --          Transformed(T)->Value(U * ParametricTransformation(T))
 333         --
 334         --          is the same point as
 335         --
 336         --          Value(U).Transformed(T)
 337         --
 338         --          This methods calls the basis curve method.
 339      is redefined;
 340
 341
 342
 343   Copy (me)  returns like me;
 344         ---Purpose: Creates a new object, which is a copy of this offset curve.
 345
 346   GetBasisCurveContinuity(me)
 347     returns Shape from GeomAbs;
 348         ---Purpose: Returns continuity of the basis curve.
 349
 350
 351 fields
 352
 353   basisCurve  : Curve from Geom2d;
 354   offsetValue : Real;
 355   myBasisCurveContinuity : Shape from GeomAbs;
 356
 357 end;