src/PLib/PLib.cdl

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