src/PLib/PLib.cdl

   1 -- Created on: 1995-08-28
   2 -- Created by: Laurent BOURESCHE
   3 -- Copyright (c) 1995-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 -- Modified: 28/02/1996 by PMN :  HermiteCoefficients added
  22 -- Modified: 19/02/1997 by JCT :  EvalPoly2Var added
  23
  24 --   Modified:  05/09/97 by   JPI for    SSV   : JacobiPolynomial   --
  25 --  DoubleJacobiPolynomial, HermiteInterpolate, JacobiParameters
  26
  27
  28 package PLib
  29
  30         ---Purpose: PLib means Polynomial  functions library.  This pk
  31         --          provides  basic       computation    functions for
  32         --          polynomial functions.
  33         --
  34
  35 uses Standard, math, TColStd, gp, TColgp,  GeomAbs
  36
  37 is
  38       deferred class Base from PLib;
  39       class JacobiPolynomial  from  PLib;
  40       class HermitJacobi from PLib;
  41       class DoubleJacobiPolynomial  from  PLib;
  42
  43      NoWeights returns Array1OfReal from TColStd;
  44         ---Purpose: Used as argument for a non rational functions
  45         --
  46         ---C++: return &
  47         ---C++: inline
  48
  49      NoWeights2 returns Array2OfReal from TColStd;
  50         ---Purpose: Used as argument for a non rational functions
  51         --
  52         ---C++: return &
  53         ---C++: inline
  54
  55      SetPoles(Poles : Array1OfPnt      from TColgp;
  56               FP    : out Array1OfReal from TColStd);
  57       ---Purpose: Copy in FP the coordinates of the poles.
  58
  59      SetPoles(Poles   : Array1OfPnt      from TColgp;
  60               Weights : Array1OfReal     from TColStd;
  61               FP      : out Array1OfReal from TColStd);
  62       ---Purpose: Copy in FP the coordinates of the poles.
  63
  64      GetPoles(FP    : Array1OfReal    from TColStd;
  65               Poles : out Array1OfPnt from TColgp);
  66       ---Purpose: Get from FP the coordinates of the poles.
  67
  68      GetPoles(FP      : Array1OfReal     from TColStd;
  69               Poles   : out Array1OfPnt  from TColgp;
  70               Weights : out Array1OfReal from TColStd);
  71       ---Purpose: Get from FP the coordinates of the poles.
  72
  73      SetPoles(Poles : Array1OfPnt2d    from TColgp;
  74               FP    : out Array1OfReal from TColStd);
  75       ---Purpose: Copy in FP the coordinates of the poles.
  76
  77      SetPoles(Poles   : Array1OfPnt2d    from TColgp;
  78               Weights : Array1OfReal     from TColStd;
  79               FP      : out Array1OfReal from TColStd);
  80       ---Purpose: Copy in FP the coordinates of the poles.
  81
  82      GetPoles(FP    : Array1OfReal      from TColStd;
  83               Poles : out Array1OfPnt2d from TColgp);
  84       ---Purpose: Get from FP the coordinates of the poles.
  85
  86      GetPoles(FP      : Array1OfReal      from TColStd;
  87               Poles   : out Array1OfPnt2d from TColgp;
  88               Weights : out Array1OfReal  from TColStd);
  89       ---Purpose: Get from FP the coordinates of the poles.
  90
  91      Bin(N,P : Integer) returns Real;
  92       ---Purpose: Returns the Binomial Cnp. N should be <= BSplCLib::MaxDegree().
  93
  94      RationalDerivative(Degree    : Integer;
  95                         N         : Integer;
  96                         Dimension : Integer;
  97                         Ders      : in out Real;
  98                         RDers     : in out Real;
  99                         All       : Boolean = Standard_True);
 100       ---Purpose: Computes the derivatives of a ratio at order
 101       --          <N> in dimension <Dimension>.
 102       --
 103       --          <Ders> is an  array containing the  values  of the
 104       --          input   derivatives from  0 to  Min(<N>,<Degree>).
 105       --          For   orders   higher  than <Degree>    the  inputcd /s2d1/BMDL/
 106       --          derivatives   are assumed to be  0.
 107       --
 108       --          Content of <Ders> :
 109       --
 110       --          x(1),x(2),...,x(Dimension),w
 111       --          x'(1),x'(2),...,x'(Dimension),w'
 112       --          x''(1),x''(2),...,x''(Dimension),w''
 113       --
 114       --          If  <All> is false, only the   derivative at order
 115       --          <N> is computed.  <RDers>  is an array   of length
 116       --          Dimension which will contain the result :
 117       --
 118       --          x(1)/w , x(2)/w ,  ... derivated <N> times
 119       --
 120       --          If <All> is  true all the  derivatives up to order
 121       --          <N> are computed.   <RDers> is an array of  length
 122       --          Dimension * (N+1) which will contains :
 123       --
 124       --          x(1)/w , x(2)/w ,  ...
 125       --          x(1)/w , x(2)/w ,  ... derivated <1> times
 126       --          x(1)/w , x(2)/w ,  ... derivated <2> times
 127       --          ...
 128       --          x(1)/w , x(2)/w ,  ... derivated <N> times
 129       --
 130       --  Warning: <RDers> must be dimensionned properly.
 131
 132
 133      RationalDerivatives(DerivativesRequest         : Integer;
 134                          Dimension                  : Integer;
 135                          PolesDerivatives           : in out Real;
 136                          WeightsDerivatives         : in out Real;
 137                          RationalDerivates          : in out Real) ;
 138
 139       ---Purpose: Computes DerivativesRequest derivatives of a ratio at
 140       --          of a BSpline function of degree <Degree>
 141       --          dimension <Dimension>.
 142       --
 143       --          <PolesDerivatives> is an  array containing the  values
 144       --          of the input   derivatives from  0 to  <DerivativeRequest>
 145       --          For   orders   higher  than <Degree>    the  input
 146       --          derivatives   are assumed to be  0.
 147       --
 148       --          Content of <PoleasDerivatives> :
 149       --
 150       --          x(1),x(2),...,x(Dimension)
 151       --          x'(1),x'(2),...,x'(Dimension)
 152       --          x''(1),x''(2),...,x''(Dimension)
 153       --
 154       --
 155       --          WeightsDerivatives is an array that contains derivatives
 156       --          from 0 to  <DerivativeRequest>
 157       --          After returning from the routine the array
 158       --          RationalDerivatives contains the following
 159       --          x(1)/w , x(2)/w ,  ...
 160       --          x(1)/w , x(2)/w ,  ...   derivated once
 161       --          x(1)/w , x(2)/w ,  ...   twice
 162       --          x(1)/w , x(2)/w ,  ... derivated <DerivativeRequest> times
 163       --
 164       --          The array RationalDerivatives and PolesDerivatives
 165       --          can be same since the overwrite is non destructive within
 166       --          the algorithm
 167       --
 168       --  Warning: <RationalDerivates> must be dimensionned properly.
 169
 170
 171      EvalPolynomial(U                 : Real;
 172                     DerivativeOrder   : Integer ;
 173                     Degree            : Integer ;
 174                     Dimension         : Integer ;
 175                     PolynomialCoeff   : in out Real ;
 176                     Results           : in out Real) ;
 177
 178       ---Purpose: Performs Horner method with synthethic division
 179       --          for derivatives
 180       --          parameter <U>, with <Degree> and <Dimension>.
 181       --          PolynomialCoeff are stored in the following fashion
 182       --          c0(1)      c0(2) ....       c0(Dimension)
 183       --          c1(1)      c1(2) ....       c1(Dimension)
 184       --
 185       --
 186       --          cDegree(1) cDegree(2) ....  cDegree(Dimension)
 187       --          where the polynomial is defined as :
 188       --
 189       --                          2                     Degree
 190       --          c0 + c1 X + c2 X  +  ....   cDegree X
 191       --
 192       --          Results stores the result in the following format
 193       --
 194       --          f(1)             f(2)  ....     f(Dimension)
 195       --           (1)           (1)              (1)
 196       --          f  (1)        f   (2) ....     f   (Dimension)
 197       --
 198       --           (DerivativeRequest)            (DerivativeRequest)
 199       --          f  (1)                         f   (Dimension)
 200       --
 201       --          this just evaluates the point at parameter U
 202       --
 203       --  Warning: <Results> and <PolynomialCoeff> must be dimensioned properly
 204       --
 205       --
 206
 207      NoDerivativeEvalPolynomial(U                 : Real;
 208                                 Degree            : Integer ;
 209                                 Dimension         : Integer ;
 210                                 DegreeDimension   : Integer ;
 211                                 PolynomialCoeff   : in out Real ;
 212                                 Results           : in out Real) ;
 213       ---Purpose: Same as above with DerivativeOrder = 0;
 214
 215      EvalPoly2Var(U,V                                 : Real;
 216                   UDerivativeOrder,VDerivativeOrder   : Integer ;
 217                   UDegree,VDegree,Dimension           : Integer ;
 218                   PolynomialCoeff                     : in out Real;
 219                   Results                             : in out Real) ;
 220
 221       ---Purpose: Applies EvalPolynomial twice to evaluate the derivative
 222       --          of orders UDerivativeOrder in U, VDerivativeOrder in V
 223       --          at parameters U,V
 224       --
 225       --
 226       --          PolynomialCoeff are stored in the following fashion
 227       --          c00(1)  ....       c00(Dimension)
 228       --          c10(1)  ....       c10(Dimension)
 229       --          ....
 230       --          cm0(1)  ....       cm0(Dimension)
 231       --          ....
 232       --          c01(1)  ....       c01(Dimension)
 233       --          c11(1)  ....       c11(Dimension)
 234       --          ....
 235       --          cm1(1)  ....       cm1(Dimension)
 236       --          ....
 237       --          c0n(1)  ....       c0n(Dimension)
 238       --          c1n(1)  ....       c1n(Dimension)
 239       --          ....
 240       --          cmn(1)  ....       cmn(Dimension)
 241       --
 242       --
 243       --          where the polynomial is defined as :
 244       --                             2                 m
 245       --          c00 + c10 U + c20 U  +  ....  + cm0 U
 246       --                                  2                   m
 247       --          + c01 V + c11 UV + c21 U V  +  ....  + cm1 U  V
 248       --                         n               m n
 249       --          + .... + c0n V +  ....  + cmn U V
 250       --
 251       --          with m = UDegree and n = VDegree
 252       --
 253       --          Results stores the result in the following format
 254       --
 255       --          f(1)             f(2)  ....     f(Dimension)
 256       --
 257       --  Warning: <Results> and <PolynomialCoeff> must be dimensioned properly
 258       --
 259       --
 260
 261
 262      EvalLagrange(U                 : Real    ;
 263                   DerivativeOrder   : Integer ;
 264                   Degree            : Integer ;
 265                   Dimension         : Integer ;
 266                   ValueArray        : in out Real;
 267                   ParameterArray    : in out Real;
 268                   Results           : in out Real) returns Integer ;
 269
 270       ---Purpose: Performs the Lagrange Interpolation of
 271       --          given series of points with given parameters
 272       --          with the requested derivative order
 273       --          Results will store things in the following format
 274       --          with d = DerivativeOrder
 275       --
 276       -- [0],             [Dimension-1]              : value
 277       -- [Dimension],     [Dimension  + Dimension-1] : first derivative
 278       --
 279       -- [d *Dimension],  [d*Dimension + Dimension-1]: dth   derivative
 280
 281      EvalCubicHermite(U                 : Real    ;
 282                       DerivativeOrder   : Integer ;
 283                       Dimension         : Integer ;
 284                       ValueArray        : in out Real;
 285                       DerivativeArray   : in out Real;
 286                       ParameterArray    : in out Real;
 287                       Results           : in out Real) returns Integer ;
 288
 289       ---Purpose: Performs the Cubic Hermite Interpolation of
 290       --          given series of points with given parameters
 291       --          with the requested derivative order.
 292       --          ValueArray stores the value at the first and
 293       --          last parameter. It has the following format :
 294       -- [0],             [Dimension-1]              : value at first param
 295       -- [Dimension],     [Dimension  + Dimension-1] : value at last param
 296       --           Derivative array stores the value of the derivatives
 297       --           at the first parameter and at the last parameter
 298       --           in the following format
 299       -- [0],             [Dimension-1]              : derivative at
 300       --                                               first param
 301       -- [Dimension],     [Dimension  + Dimension-1] : derivative at
 302       --                                               last param
 303       --
 304       --          ParameterArray  stores the first and last parameter
 305       --          in the following format :
 306       --          [0] : first parameter
 307       --          [1] : last  parameter
 308       --
 309       --          Results will store things in the following format
 310       --          with d = DerivativeOrder
 311       --
 312       -- [0],             [Dimension-1]              : value
 313       -- [Dimension],     [Dimension  + Dimension-1] : first derivative
 314       --
 315       -- [d *Dimension],  [d*Dimension + Dimension-1]: dth   derivative
 316
 317   HermiteCoefficients(FirstParameter : in Real;
 318                       LastParameter  : in Real;
 319                       FirstOrder     : in Integer;
 320                       LastOrder      : in Integer;
 321                       MatrixCoefs    : in out Matrix from math)
 322
 323       ---Purpose: This build the coefficient of Hermite's polynomes on
 324       --          [FirstParameter, LastParameter]
 325       --
 326       --          if j <= FirstOrder+1 then
 327       --
 328       --          MatrixCoefs[i, j] = ith coefficient of the polynome H0,j-1
 329       --
 330       --          else
 331       --
 332       --          MatrixCoefs[i, j] = ith coefficient of the polynome H1,k
 333       --            with k = j - FirstOrder - 2
 334       --
 335       --          return false if
 336       --          - |FirstParameter| > 100
 337       --          - |LastParameter| > 100
 338       --          - |FirstParameter| +|LastParameter| < 1/100
 339       --          -   |LastParameter - FirstParameter|
 340       --            / (|FirstParameter| +|LastParameter|)  < 1/100
 341   returns Boolean;
 342
 343 ----------------------------------------------------------------
 344 --  The following functions computes poles corresponding to   --
 345 --  given coefficients.                                       --
 346 --  PLib::NoWeights() must be given for non rational functions--
 347 ----------------------------------------------------------------
 348
 349   CoefficientsPoles(Coefs  : in Array1OfPnt from TColgp;
 350                     WCoefs : in Array1OfReal from TColStd;
 351                     Poles  : in out Array1OfPnt from TColgp;
 352                     WPoles : in out Array1OfReal from TColStd);
 353
 354   CoefficientsPoles(Coefs  : in Array1OfPnt2d from TColgp;
 355                     WCoefs : in Array1OfReal from TColStd;
 356                     Poles  : in out Array1OfPnt2d from TColgp;
 357                     WPoles : in out Array1OfReal from TColStd);
 358
 359   CoefficientsPoles(Coefs  : in Array1OfReal from TColStd;
 360                     WCoefs : in Array1OfReal from TColStd;
 361                     Poles  : in out Array1OfReal from TColStd;
 362                     WPoles : in out Array1OfReal from TColStd);
 363
 364   CoefficientsPoles(dim    : in Integer from Standard;
 365                     Coefs  : in Array1OfReal from TColStd;
 366                     WCoefs : in Array1OfReal from TColStd;
 367                     Poles  : in out Array1OfReal from TColStd;
 368                     WPoles : in out Array1OfReal from TColStd);
 369
 370
 371 ----------------------------------------------------------------
 372 --  The following functions trim the Bezier curve between two --
 373 --  parametric values U1, U2.                                 --
 374 --  Can be used to extend the curve :                         --
 375 --  Parameters  U1<0. or U2>1. can be given.                  --
 376 --  PLib::NoWeights() must be given for non rational functions--
 377 ----------------------------------------------------------------
 378
 379
 380   Trimming (U1, U2  : in  Real;
 381             Coeffs  : in  out Array1OfPnt from TColgp;
 382             WCoeffs : in  out Array1OfReal from TColStd);
 383
 384
 385   Trimming (U1, U2  : in  Real;
 386             Coeffs  : in  out Array1OfPnt2d from TColgp;
 387             WCoeffs : in  out Array1OfReal from TColStd);
 388
 389
 390   Trimming (U1, U2  : in  Real;
 391             Coeffs  : in  out Array1OfReal from TColStd;
 392             WCoeffs : in  out Array1OfReal from TColStd);
 393
 394
 395   Trimming (U1, U2  : in  Real;
 396             dim     : in  Integer;
 397             Coeffs  : in  out Array1OfReal from TColStd;
 398             WCoeffs : in  out Array1OfReal from TColStd);
 399
 400
 401
 402
 403 ----------------------------------------------------------------
 404 --  The following functions computes poles corresponding to   --
 405 --  given coefficients.                                       --
 406 --  PLib::NoWeights2() must be given for non rational         --
 407 --  functions.                                                --
 408 ----------------------------------------------------------------
 409
 410   CoefficientsPoles(Coefs  : in Array2OfPnt from TColgp;
 411                     WCoefs : in Array2OfReal from TColStd;
 412                     Poles  : in out Array2OfPnt from TColgp;
 413                     WPoles : in out Array2OfReal from TColStd);
 414
 415
 416 ----------------------------------------------------------------
 417 --  The following functions trim the Bezier surface between   --
 418 --  two parametric values.                                    --
 419 --  Can be used to extend the surface :                       --
 420 --  Parameters  U1(V1)<0. or U2(V2)>1. can be given.          --
 421 --  PLib::NoWeights2() must be given for non rational         --
 422 --  functions.                                                --
 423 ----------------------------------------------------------------
 424
 425
 426   UTrimming (U1, U2  : in  Real;
 427              Coeffs  : in  out Array2OfPnt  from TColgp;
 428              WCoeffs : in  out Array2OfReal from TColStd);
 429
 430
 431   VTrimming (V1, V2  : in  Real;
 432              Coeffs  : in  out Array2OfPnt  from TColgp;
 433              WCoeffs : in  out Array2OfReal from TColStd);
 434
 435
 436   HermiteInterpolate(Dimension : in Integer;
 437                      FirstParameter,LastParameter : in Real;
 438                      FirstOrder,LastOrder : in Integer;
 439                      FirstConstr,LastConstr : Array2OfReal from TColStd;
 440                      Coefficients : out Array1OfReal from TColStd)
 441                      returns Boolean from Standard;
 442   ---Purpose : Compute the coefficients in the canonical base of the
 443   --         polynomial satisfying the given constraints
 444   --         at the given parameters
 445   --         The array FirstContr(i,j) i=1,Dimension j=0,FirstOrder
 446   --         contains the values of the constraint at parameter FirstParameter
 447   --         idem for LastConstr
 448
 449   JacobiParameters (ConstraintOrder: Shape from GeomAbs;
 450                   MaxDegree, Code: in Integer;
 451                   NbGaussPoints: out Integer;
 452                   WorkDegree: out Integer)
 453 ---Purpose : Compute the number of points used for integral
 454 --         computations (NbGaussPoints) and the degree of Jacobi
 455 --         Polynomial (WorkDegree).
 456 --         ConstraintOrder has to be GeomAbs_C0, GeomAbs_C1 or GeomAbs_C2
 457 --         Code: Code d' init. des parametres de discretisation.
 458 --            = -5
 459 --            = -4
 460 --            = -3
 461 --            = -2
 462 --            = -1
 463 --            =  1 calcul rapide avec precision moyenne.
 464 --            =  2 calcul rapide avec meilleure precision.
 465 --            =  3 calcul un peu plus lent avec bonne precision.
 466 --            =  4 calcul lent avec la meilleure precision possible.
 467
 468     raises ConstructionError from Standard;
 469 -- if ConstraintOrder or Code is not valid
 470 --    MaxDegree < 2*NivConstr+2 or MaxDegree > 50
 471 --
 472 ----------  new
 473     NivConstr(ConstraintOrder : Shape from GeomAbs)
 474     ---Purpose: translates from GeomAbs_Shape to Integer
 475     returns Integer
 476     raises ConstructionError from Standard;
 477
 478     ConstraintOrder(NivConstr : Integer)
 479     ---Purpose: translates from Integer to GeomAbs_Shape
 480     returns Shape from GeomAbs
 481     raises ConstructionError from Standard;
 482
 483
 484     EvalLength(Degree : Integer;
 485                Dimension : Integer;
 486                PolynomialCoeff : in out Real;
 487                U1, U2 : Real;
 488                Length : out Real);
 489
 490     EvalLength(Degree : Integer;
 491                Dimension : Integer;
 492                PolynomialCoeff : in out Real;
 493                U1, U2 : Real;
 494                Tol : Real;
 495                Length : out Real;
 496                Error : out Real);
 497
 498 end PLib;