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; Offset : Real)   returns mutable OffsetCurve
  81         --- Purpose : Constructs a curve offset from the basis curve C,
  82         -- where Offset is the distance between the offset
  83         -- curve and the basis curve at any point.
  84         -- A point on the offset curve is built by measuring the
  85         -- offset value along a normal vector at a point on C.
  86         -- This normal vector is obtained by rotating the
  87         -- vector tangential to C at 90 degrees in the
  88         -- anti-trigonometric sense. The side of C on which
  89         -- the offset value is measured is indicated by this
  90         -- normal vector if Offset is positive, or in the inverse
  91         -- sense if Offset is negative.
  92         --   Warnings :
  93         --  In this package the entities are not shared. The OffsetCurve is
  94         --  built with a copy of the curve C. So when C is modified the
  95         --  OffsetCurve is not modified
  96         --  Warning!  ConstructionError  raised if the basis curve C is not at least C1.
  97         --  No check is done to know if ||V^Z|| != 0.0 at any point.
  98      raises ConstructionError;
  99
 100
 101
 102   Reverse (me : mutable);
 103         --- Purpose : Changes the direction of parametrization of <me>.
 104         --     As a result:
 105         -- - the basis curve is reversed,
 106         -- - the start point of the initial curve becomes the end
 107         --   point of the reversed curve,
 108         -- - the end point of the initial curve becomes the start
 109         --   point of the reversed curve, and
 110         -- - the first and last parameters are recomputed.
 111
 112
 113   ReversedParameter(me; U : Real) returns Real;
 114         ---Purpose: Computes the parameter on the reversed curve for
 115         -- the point of parameter U on this offset curve.
 116
 117
 118   SetBasisCurve (me : mutable; C : Curve from Geom2d)
 119      raises ConstructionError;
 120         --- Purpose : Changes this offset curve by assigning C as the
 121         -- basis curve from which it is built.
 122         -- Exceptions
 123         -- Standard_ConstructionError if the curve C is not at least "C1" continuous.
 124
 125   SetOffsetValue (me : mutable; D : Real);
 126         --- Purpose :  Changes this offset curve by assigning D as the offset value.
 127
 128   BasisCurve (me) returns Curve from Geom2d;
 129         --- Purpose : Returns the basis curve of this offset curve. The basis curve can be an offset curve.
 130
 131
 132
 133   Continuity (me)  returns Shape from GeomAbs;
 134         --- Purpose :
 135         --  Continuity of the Offset curve :
 136         --  C0 : only geometric continuity,
 137         --  C1 : continuity of the first derivative all along the Curve,
 138         --  C2 : continuity of the second derivative all along the Curve,
 139         --  C3 : continuity of the third derivative all along the Curve,
 140         --  G1 : tangency continuity all along the Curve,
 141         --  G2 : curvature continuity all along the Curve,
 142         --  CN : the order of continuity is infinite.
 143         --   Warnings :
 144         --  Returns the continuity of the basis curve - 1.
 145         --  The offset curve must have a unique normal direction defined
 146         --  at any point.
 147
 148
 149
 150
 151
 152         --- Purpose  : Value and derivatives
 153         --
 154         --  Warnings :
 155         --  The exception UndefinedValue or UndefinedDerivative is
 156         --  raised if it is not possible to compute a unique offset
 157         --  direction.
 158         --  If T is the first derivative with not null length and
 159         --  Z the direction normal to the plane of the curve, the
 160         --  relation ||T(U) ^ Z|| != 0  must be satisfied to evaluate
 161         --  the offset curve.
 162         --  No check is done at the creation time and we suppose
 163         --  in this package that the offset curve is well defined.
 164
 165
 166   D0 (me; U : Real; P : out Pnt2d)
 167      raises UndefinedValue;
 168         ---Purpose:  Warning! this should not be called
 169         --          if the basis curve is not at least C1. Nevertheless
 170         --          if used on portion where the curve is C1, it is OK
 171
 172
 173
 174   D1 (me; U : Real; P : out Pnt2d; V1 : out Vec2d)
 175      raises UndefinedDerivative;
 176         ---Purpose:  Warning! this should not be called
 177         --           if the continuity of the basis curve is not C2.
 178         --           Nevertheless, it's OK to use it  on portion
 179         --           where the curve is C2
 180
 181
 182
 183   D2 (me; U : Real; P : out Pnt2d; V1, V2 : out Vec2d)
 184      raises UndefinedDerivative;
 185         ---Purpose:  Warning!  This  should  not  be called
 186         --           if the continuity of the basis curve is not C3.
 187         --           Nevertheless, it's OK to use it  on portion
 188         --           where the curve is C3
 189
 190   D3 (me; U : Real; P : out Pnt2d; V1, V2, V3 : out Vec2d)
 191      raises UndefinedDerivative;
 192
 193         ---Purpose:  Warning! This should not be called
 194         --           if the continuity of the basis curve is not C4.
 195         --           Nevertheless, it's OK to use it  on portion
 196         --           where the curve is C4
 197
 198   DN (me; U : Real; N : Integer)   returns Vec2d
 199         --- Purpose : The returned vector gives the value of the derivative
 200         --  for the order of derivation N.
 201         --  Warning! this should not be called
 202         --        raises  UndefunedDerivative   if the continuity of the basis curve is not CN+1.
 203         --           Nevertheless, it's OK to use it  on portion
 204         --           where the curve is CN+1
 205         -- raises  RangeError if N < 1.
 206         -- raises  NotImplemented if N > 3.
 207
 208      raises UndefinedDerivative,
 209
 210             RangeError,
 211             NotImplemented;
 212
 213
 214
 215         --- Purpose : The following functions compute the value and derivatives
 216         --  on the offset curve and returns the derivatives on the
 217         --  basis curve too.
 218         --  The computation of the value and derivatives on the basis
 219         --  curve are used to evaluate the offset curve
 220         --  Warnings :
 221         --  The exception UndefinedValue or UndefinedDerivative is
 222         --  raised if it is not possible to compute a unique offset direction.
 223
 224
 225   Value (me; U : Real; P, Pbasis : out Pnt2d; V1basis : out Vec2d)
 226      raises UndefinedValue;
 227
 228         ---Purpose:  Warning! this should not be called
 229         --          if the basis curve is not at least C1. Nevertheless
 230         --          if used on portion where the curve is C1, it is OK
 231
 232
 233   D1 (me; U : Real; P, Pbasis : out Pnt2d;
 234       V1, V1basis, V2basis : out Vec2d)
 235      raises UndefinedDerivative;
 236
 237         ---Purpose:  Warning! this should not be called
 238         --           if the continuity of the basis curve is not C1.
 239         --           Nevertheless, it's OK to use it  on portion
 240         --           where the curve is C1
 241
 242   D2 (me; U : Real; P, Pbasis : out Pnt2d;  V1, V2, V1basis, V2basis,
 243       V3basis : out Vec2d)
 244      raises UndefinedDerivative;
 245
 246         ---Purpose:  Warning! this should not be called
 247         --           if the continuity of the basis curve is not C3.
 248         --           Nevertheless, it's OK to use it  on portion
 249         --           where the curve is C3
 250
 251   FirstParameter (me)  returns Real;
 252
 253   LastParameter (me)   returns Real;
 254         ---Purpose: Returns the value of the first or last parameter of this
 255         -- offset curve. The first parameter corresponds to the
 256         -- start point of the curve. The last parameter
 257         -- corresponds to the end point.
 258         -- Note: the first and last parameters of this offset curve
 259         -- are also the ones of its basis curve.
 260
 261   Offset (me)          returns Real;
 262         ---Purpose: Returns the offset value of this offset curve.
 263
 264   IsClosed (me)   returns Boolean;
 265         --- Purpose :
 266         --  Returns True if the distance between the start point
 267         --  and the end point of the curve is lower or equal to
 268         --  Resolution from package gp.
 269
 270
 271   IsCN (me; N : Integer)  returns Boolean
 272         --- Purpose : Is the order of continuity of the curve N ?
 273         --   Warnings :
 274         --  This method answer True if the continuity of the basis curve
 275         --  is N + 1.  We suppose in this class that a normal direction
 276         --  to the basis curve (used to compute the offset curve) is
 277         --  defined at any point on the basis curve.
 278      raises RangeError;
 279         --- Purpose : Raised if N < 0.
 280
 281
 282   IsPeriodic (me)  returns Boolean;
 283         --- Purpose : Is the parametrization of a curve is periodic ?
 284         --  If the basis curve is a circle or an ellipse the corresponding
 285         --  OffsetCurve is periodic. If the basis curve can't be periodic
 286         --  (for example BezierCurve) the OffsetCurve can't be periodic.
 287
 288
 289   Period (me) returns Real from Standard
 290         ---Purpose: Returns the period of this offset curve, i.e. the period
 291         -- of the basis curve of this offset curve.
 292         -- Exceptions
 293         -- Standard_NoSuchObject if the basis curve is not periodic.
 294   raises  NoSuchObject from Standard
 295   is redefined;
 296
 297
 298   Transform (me : mutable; T : Trsf2d);
 299         ---Purpose : Applies the transformation T to this offset curve.
 300         -- Note: the basis curve is also modified.
 301
 302   TransformedParameter(me; U : Real; T : Trsf2d from gp) returns Real
 303         ---Purpose: Returns the  parameter on the  transformed  curve for
 304         --          the transform of the point of parameter U on <me>.
 305         --
 306         --          me->Transformed(T)->Value(me->TransformedParameter(U,T))
 307         --
 308         --          is the same point as
 309         --
 310         --          me->Value(U).Transformed(T)
 311         --
 312         --          This methods calls the basis curve method.
 313      is redefined;
 314
 315   ParametricTransformation(me; T : Trsf2d from gp) returns Real
 316         ---Purpose: Returns a  coefficient to compute the parameter on
 317         --          the transformed  curve  for  the transform  of the
 318         --          point on <me>.
 319         --
 320         --          Transformed(T)->Value(U * ParametricTransformation(T))
 321         --
 322         --          is the same point as
 323         --
 324         --          Value(U).Transformed(T)
 325         --
 326         --          This methods calls the basis curve method.
 327      is redefined;
 328
 329
 330
 331   Copy (me)  returns mutable like me;
 332         ---Purpose: Creates a new object, which is a copy of this offset curve.
 333 fields
 334
 335   basisCurve  : Curve from Geom2d;
 336   offsetValue : Real;
 337
 338 end;