src/Geom2d/Geom2d_BezierCurve.cdl

   1 -- Created on: 1993-03-24
   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 class BezierCurve from Geom2d inherits BoundedCurve from Geom2d
  18
  19         --- Purpose : Describes a rational or non-rational Bezier curve
  20         -- - a non-rational Bezier curve is defined by a table
  21         --   of poles (also called control points),
  22         -- - a rational Bezier curve is defined by a table of
  23         --   poles with varying weights.
  24         -- These data are manipulated by two parallel arrays:
  25         -- - the poles table, which is an array of gp_Pnt2d points, and
  26         -- - the weights table, which is an array of reals.
  27         -- The bounds of these arrays are 1 and "the number of poles" of the curve.
  28         -- The poles of the curve are "control points" used to deform the curve.
  29         -- The first pole is the start point of the curve, and the
  30         -- last pole is the end point of the curve. The segment
  31         -- which joins the first pole to the second pole is the
  32         -- tangent to the curve at its start point, and the
  33         -- segment which joins the last pole to the
  34         -- second-from-last pole is the tangent to the curve
  35         -- at its end point.
  36         -- It is more difficult to give a geometric signification
  37         -- to the weights but they are useful for providing
  38         -- exact representations of the arcs of a circle or
  39         -- ellipse. Moreover, if the weights of all the poles are
  40         -- equal, the curve is polynomial; it is therefore a
  41         -- non-rational curve. The non-rational curve is a
  42         -- special and frequently used case. The weights are
  43         -- defined and used only in case of a rational curve.
  44         -- The degree of a Bezier curve is equal to the
  45         -- number of poles, minus 1. It must be greater than or
  46         -- equal to 1. However, the degree of a
  47         -- Geom2d_BezierCurve curve is limited to a value
  48         -- (25) which is defined and controlled by the system.
  49         -- This value is returned by the function MaxDegree.
  50         -- The parameter range for a Bezier curve is [ 0, 1 ].
  51         -- If the first and last control points of the Bezier
  52         -- curve are the same point then the curve is closed.
  53         -- For example, to create a closed Bezier curve with
  54         -- four control points, you have to give a set of control
  55         -- points P1, P2, P3 and P1.
  56         -- The continuity of a Bezier curve is infinite.
  57         -- It is not possible to build a Bezier curve with
  58         -- negative weights. We consider that a weight value
  59         -- is zero if it is less than or equal to
  60         -- gp::Resolution(). We also consider that
  61         -- two weight values W1 and W2 are equal if:
  62         -- |W2 - W1| <= gp::Resolution().
  63         --  Warning
  64         -- - When considering the continuity of a closed
  65         --   Bezier curve at the junction point, remember that
  66         --   a curve of this type is never periodic. This means
  67         --   that the derivatives for the parameter u = 0
  68         --   have no reason to be the same as the
  69         --   derivatives for the parameter u = 1 even if the curve is closed.
  70         -- - The length of a Bezier curve can be null.
  71
  72
  73 uses  Array1OfReal        from TColStd,
  74       HArray1OfReal       from TColStd,
  75       Array1OfPnt2d       from TColgp,
  76       Ax2d                from gp,
  77       Pnt2d               from gp,
  78       HArray1OfPnt2d      from TColgp,
  79       Vec2d               from gp,
  80       Trsf2d              from gp,
  81       Geometry            from Geom2d,
  82       Shape               from GeomAbs
  83
  84
  85 raises ConstructionError from Standard,
  86        DimensionError    from Standard,
  87        RangeError        from Standard,
  88        OutOfRange        from Standard
  89
  90
  91 is
  92
  93
  94
  95
  96   Create (CurvePoles : Array1OfPnt2d from TColgp) returns BezierCurve
  97         --- Purpose :
  98         --  Creates a non rational Bezier curve with a set of poles :
  99         --  CurvePoles.  The weights are defaulted to all being 1.
 100         --    Raises ConstructionError if the number of poles is greater than MaxDegree + 1
 101         --  or lower than 2.
 102      raises ConstructionError;
 103
 104
 105   Create (CurvePoles  : Array1OfPnt2d from TColgp;
 106           PoleWeights : Array1OfReal from TColStd)
 107      returns BezierCurve
 108         --- Purpose :
 109         --  Creates a rational Bezier curve with the set of poles
 110         --  CurvePoles and the set of weights  PoleWeights .
 111         --  If all the weights are identical the curve is considered
 112         --  as non rational.  Raises ConstructionError if
 113         --  the number of poles is greater than  MaxDegree + 1 or lower
 114         --  than 2 or CurvePoles and CurveWeights have not the same length
 115         --  or one weight value is lower or equal to Resolution from
 116         --  package gp.
 117      raises ConstructionError;
 118
 119
 120   Increase (me : mutable; Degree : Integer)
 121         --- Purpose :
 122         --  Increases the degree of a bezier curve. Degree is the new
 123         --  degree of <me>.
 124         --    raises ConstructionError if Degree is greater than MaxDegree or lower than 2
 125         --  or lower than the initial degree of <me>.
 126
 127      raises ConstructionError;
 128
 129
 130
 131   InsertPoleAfter (me : mutable; Index : Integer; P : Pnt2d;
 132                    Weight : Real = 1.0)
 133         --- Purpose :
 134         --  Inserts a pole with its weight in the set of poles after the
 135         --  pole of range Index. If the curve was non rational it can
 136         --  become rational if all the weights are not identical.
 137      raises OutOfRange,
 138         --- Purpose : Raised if Index is not in the range [0, NbPoles]
 139             ConstructionError;
 140         --- Purpose :
 141         --  Raised if the resulting number of poles is greater than
 142         --  MaxDegree + 1.
 143
 144
 145   InsertPoleBefore (me : mutable; Index : Integer; P : Pnt2d;
 146                     Weight : Real = 1.0)
 147         --- Purpose :
 148         --  Inserts a pole with its weight in the set of poles after
 149         --  the pole of range Index. If the curve was non rational it
 150         --  can become rational if all the weights are not identical.
 151      raises OutOfRange,
 152         --- Purpose : Raised if Index is not in the range [1, NbPoles+1]
 153             ConstructionError;
 154         --- Purpose :
 155         --  Raised if the resulting number of poles is greater than
 156         --  MaxDegree + 1.
 157
 158
 159   RemovePole (me : mutable; Index : Integer)
 160         --- Purpose : Removes the pole of range Index.
 161         --  If the curve was rational it can become non rational.
 162      raises OutOfRange,
 163         --- Purpose : Raised if Index is not in the range [1, NbPoles]
 164             ConstructionError;
 165          -- Purpose : Raised if Degree is lower than 2.
 166
 167
 168   Reverse (me : mutable);
 169         --- Purpose :
 170         --  Reverses the direction of parametrization of <me>
 171         --  Value (NewU) =  Value (1 - OldU)
 172
 173
 174   ReversedParameter(me; U : Real) returns Real;
 175         ---Purpose: Returns the  parameter on the  reversed  curve for
 176         --          the point of parameter U on <me>.
 177         --
 178         --          returns 1-U
 179
 180
 181   Segment (me : mutable; U1, U2 : Real);
 182         --- Purpose :
 183         --  Segments the curve between U1 and U2 which can be out
 184         --  of the bounds of the curve. The curve is oriented from U1
 185         --  to U2.
 186         --  The control points are modified, the first and the last point
 187         --  are not the same but the parametrization range is [0, 1]
 188         --  else it could not be a Bezier curve.
 189         -- Warnings :
 190         --  Even if <me> is not closed it can become closed after the
 191         --  segmentation for example if U1 or U2 are out of the bounds
 192         --  of the curve <me> or if the curve makes loop.
 193         --  After the segmentation the length of a curve can be null.
 194
 195
 196   SetPole (me : mutable; Index : Integer; P : Pnt2d)
 197         --- Purpose :
 198         --  Substitutes the pole of range index with P.
 199         --  If the curve <me> is rational the weight of range Index
 200         --  is not modified.
 201      raises OutOfRange;
 202         --- Purpose : raiseD if Index is not in the range [1, NbPoles]
 203
 204
 205   SetPole (me : mutable; Index : Integer; P : Pnt2d; Weight : Real)
 206         --- Purpose :
 207         --  Substitutes the pole and the weights of range Index.
 208         --  If the curve <me> is not rational it can become rational
 209         --  if all the weights are not identical.
 210         --  If the curve was rational it can become non rational if
 211         --  all the weights are identical.
 212      raises OutOfRange,
 213         --- Purpose : Raised if Index is not in the range [1, NbPoles]
 214             ConstructionError;
 215         --- Purpose : Raised if Weight <= Resolution from package gp
 216
 217
 218   SetWeight (me : mutable; Index : Integer; Weight : Real)
 219         --- Purpose :
 220         --  Changes the weight of the pole of range Index.
 221         --  If the curve <me> is not rational it can become rational
 222         --  if all the weights are not identical.
 223         --  If the curve was rational it can become non rational if
 224         --  all the weights are identical.
 225      raises OutOfRange,
 226         --- Purpose : Raised if Index is not in the range [1, NbPoles]
 227             ConstructionError;
 228         --- Purpose : Raised if Weight <= Resolution from package gp
 229
 230
 231
 232   IsClosed (me)   returns Boolean;
 233         --- Purpose :
 234         --  Returns True if the distance between the first point
 235         --  and the last point of the curve is lower or equal to
 236         --  the Resolution from package gp.
 237
 238
 239   IsCN (me; N : Integer)   returns Boolean;
 240         --- Purpose : Continuity of the curve, returns True.
 241
 242
 243   IsPeriodic (me)   returns Boolean;
 244         --- Purpose :
 245         --  Returns False. A BezierCurve cannot be periodic in this
 246         --  package
 247
 248
 249   IsRational (me)   returns Boolean;
 250         --- Purpose :
 251         --  Returns false if all the weights are identical. The tolerance
 252         --  criterion is Resolution from package gp.
 253
 254
 255   Continuity (me)   returns Shape from GeomAbs;
 256         --- Purpose :  Returns GeomAbs_CN, which is the continuity of any Bezier curve.
 257
 258
 259   Degree (me)   returns Integer;
 260         --- Purpose :
 261         --  Returns the polynomial degree of the curve. It is the number
 262         --  of poles less one.  In this package the Degree of a Bezier
 263         --  curve cannot be greater than "MaxDegree".
 264
 265
 266
 267
 268
 269
 270   D0 (me; U : Real; P : out Pnt2d);
 271
 272   D1 (me; U : Real; P : out Pnt2d; V1 : out Vec2d);
 273
 274   D2 (me; U : Real; P : out Pnt2d; V1, V2 : out Vec2d);
 275
 276   D3 (me; U : Real; P : out Pnt2d; V1, V2, V3 : out Vec2d);
 277
 278   DN (me; U : Real; N : Integer)  returns Vec2d
 279         --- Purpose :  For this Bezier curve, computes
 280         -- - the point P of parameter U, or
 281         -- - the point P and one or more of the following values:
 282         --   - V1, the first derivative vector,
 283         --   - V2, the second derivative vector,
 284         --   - V3, the third derivative vector.
 285         -- Note: the parameter U can be outside the bounds of the curve.
 286         --     Raises RangeError if N < 1.
 287      raises RangeError;
 288
 289   EndPoint (me) returns Pnt2d;
 290         --- Purpose :    Returns the end point or start point of this Bezier curve.
 291
 292
 293   FirstParameter (me) returns Real;
 294         --- Purpose : Returns the value of the first  parameter of this
 295         -- Bezier curve. This is  0.0, which gives the start point of this Bezier curve.
 296
 297
 298   LastParameter (me) returns Real;
 299         --- Purpose : Returns the value of the last  parameter of this
 300         -- Bezier curve. This is  1.0, which gives the end point of this Bezier curve.
 301
 302
 303   NbPoles (me)  returns Integer;
 304
 305         ---Purpose: Returns the number of poles for this Bezier curve.
 306
 307   Pole (me; Index : Integer) returns Pnt2d
 308         --- Purpose : Returns the pole of range Index.
 309      raises OutOfRange;
 310         --- Purpose : Raised if Index is not in the range [1, NbPoles]
 311
 312
 313   Poles (me; P : out Array1OfPnt2d from TColgp)
 314         --- Purpose : Returns all the poles of the curve.
 315      raises DimensionError;
 316         --- Purpose :
 317         --  Raised if the length of P is not equal to the number of poles.
 318
 319
 320   StartPoint (me)  returns Pnt2d;
 321         --- Purpose :
 322         --  Returns Value (U=1), it is the first control point
 323         --  of the curve.
 324
 325
 326   Weight (me; Index : Integer)   returns Real
 327         --- Purpose : Returns the weight of range Index.
 328      raises OutOfRange;
 329         --- Purpose : Raised if Index is not in the range [1, NbPoles]
 330
 331
 332   Weights (me; W : out Array1OfReal from TColStd)
 333         --- Purpose : Returns all the weights of the curve.
 334      raises DimensionError;
 335         --- Purpose :
 336         --  Raised if the length of W is not equal to the number of poles.
 337
 338
 339
 340
 341   Transform (me : mutable; T : Trsf2d);
 342
 343         ---Purpose: Applies the transformation T to this Bezier curve.
 344
 345
 346   MaxDegree (myclass)   returns Integer;
 347         --- Purpose:
 348         --  Returns the value of the maximum polynomial degree of a
 349         --  BezierCurve. This value is 25.
 350
 351
 352
 353   Resolution(me          : mutable;
 354              ToleranceUV : Real;
 355              UTolerance  : out Real);
 356         ---Purpose:  Computes for this Bezier curve the parametric
 357         -- tolerance UTolerance for a given tolerance
 358         -- Tolerance3D (relative to dimensions in the plane).
 359         -- If f(t) is the equation of this Bezier curve,
 360         -- UTolerance ensures that
 361         --           | t1 - t0| < Utolerance ===>
 362         --           |f(t1) - f(t0)| < ToleranceUV
 363
 364   Copy (me)  returns like me;
 365         ---Purpose: Creates a new object which is a copy of this Bezier curve.
 366
 367   Init (me : mutable; Poles   :  HArray1OfPnt2d  from TColgp;
 368                       Weights : HArray1OfReal    from TColStd)
 369
 370         ---Purpose : Set  poles  to  Poles,  weights to  Weights  (not
 371         --         copied). If Weights is   null  the  curve is    non
 372         --         rational. Create the arrays of coefficients.  Poles
 373         --         and    Weights  are   assumed   to  have the  first
 374         --         coefficient 1.
 375         --
 376         --         Update rational and closed.
 377         --
 378   raises ConstructionError -- if nbpoles < 2 or nbboles > MaDegree + 1
 379
 380   is static private;
 381
 382   CoefficientsOK(me; U : Real) returns Boolean
 383
 384         ---Purpose : returns true if the coefficients have been
 385         --           computed with the right value of cacheparameter
 386         --           for the given U value.
 387         --
 388         is static private;
 389
 390   UpdateCoefficients(me : mutable; U : Real from Standard = 0.0)
 391         ---Purpose: Recompute the coeficients.
 392   is static private;
 393
 394
 395
 396 fields
 397
 398    rational : Boolean;
 399    closed   : Boolean;
 400    poles    : HArray1OfPnt2d from TColgp;
 401    weights  : HArray1OfReal from TColStd;
 402
 403    coeffs   : HArray1OfPnt2d from TColgp;
 404    wcoeffs  : HArray1OfReal from TColStd;
 405
 406    validcache      : Integer;
 407    -- = 1 the cache is valid
 408    -- = 0 the cache is invalid
 409    parametercache    : Real;
 410    -- Parameter at which the Taylor expension is stored in
 411    -- the cache, often 0., sometimes 1..
 412    spanlenghtcache   : Real;
 413    -- always 1. for the moment.
 414
 415    -- usefull to evaluate the parametric resolution
 416    maxderivinv   : Real from Standard;
 417    maxderivinvok : Boolean from Standard;
 418
 419 end;