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