src/Geom2dGcc/Geom2dGcc_Circ2d3Tan.cdl

   1 -- Created on: 1992-10-20
   2 -- Created by: Remi GILET
   3 -- Copyright (c) 1992-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 Circ2d3Tan from Geom2dGcc
  18
  19         ---Purpose: This class implements the algorithms used to
  20         --          create 2d circles tangent to 3 points/lines/circles/
  21         --          curves with one curve or more.
  22         --          The arguments of all construction methods are :
  23         --             - The three qualifiied elements for the
  24         --             tangency constrains (QualifiedCirc, QualifiedLine,
  25         --             Qualifiedcurv, Points).
  26         --             - A parameter for each QualifiedCurv.
  27         --          Describes functions for building a 2D circle:
  28         --          -   tangential to 3 curves, or
  29         --          -   tangential to 2 curves and passing through a point, or
  30         --          -   tangential to a curve and passing through 2 points, or
  31         --          -   passing through 3 points.
  32         --          A Circ2d3Tan object provides a framework for:
  33         --          -   defining the construction of 2D circles(s),
  34         --          -   implementing the construction algorithm, and
  35         --          -   consulting the result(s).
  36
  37 -- inherits Entity from Standard
  38
  39 uses QualifiedCurve  from Geom2dGcc,
  40      Integer         from Standard,
  41      Circ2d          from gp,
  42      Pnt2d           from gp,
  43      Array1OfPnt2d   from TColgp,
  44      Array1OfCirc2d  from TColgp,
  45      Boolean         from Standard,
  46      Array1OfInteger from TColStd,
  47      Array1OfReal    from TColStd,
  48      Circ2d3Tan      from GccAna,
  49      Point           from Geom2d,
  50      Circ2d3TanIter   from Geom2dGcc,
  51      Position         from GccEnt,
  52      Array1OfPosition from GccEnt
  53
  54 raises NotDone    from StdFail,
  55        OutOfRange from Standard
  56
  57 is
  58
  59 Create(Qualified1 : QualifiedCurve from Geom2dGcc   ;
  60        Qualified2 : QualifiedCurve from Geom2dGcc   ;
  61        Qualified3 : QualifiedCurve from Geom2dGcc   ;
  62        Tolerance  : Real           from Standard    ;
  63        Param1     : Real           from Standard    ;
  64        Param2     : Real           from Standard    ;
  65        Param3     : Real           from Standard    )
  66 returns Circ2d3Tan from Geom2dGcc;
  67         ---Purpose: Constructs one or more 2D circles
  68         --   tangential to three curves Qualified1, Qualified2 and
  69         --   Qualified3, where Param1, Param2 and Param3 are
  70         --   used, respectively, as the initial values of the
  71         --   parameters on Qualified1, Qualified2 and Qualified3
  72         --   of the tangency point between these arguments and
  73         --   the solution sought, if the algorithm chooses an
  74         --   iterative method to find the solution (i.e. if either
  75         --   Qualified1, Qualified2 or Qualified3 is more complex
  76         --   than a line or a circle).
  77
  78 Create(Qualified1 : QualifiedCurve from Geom2dGcc   ;
  79        Qualified2 : QualifiedCurve from Geom2dGcc   ;
  80        Point      : Point          from Geom2d      ;
  81        Tolerance  : Real           from Standard    ;
  82        Param1     : Real           from Standard    ;
  83        Param2     : Real           from Standard    )
  84 returns Circ2d3Tan from Geom2dGcc;
  85         ---Purpose: Constructs one or more 2D circles
  86         -- tangential to two curves Qualified1 and Qualified2
  87         --   and passing through the point Point, where Param1
  88         --   and Param2 are used, respectively, as the initial
  89         --   values of the parameters on Qualified1 and
  90         --   Qualified2 of the tangency point between this
  91         --   argument and the solution sought, if the algorithm
  92         --   chooses an iterative method to find the solution (i.e. if
  93         --   either Qualified1 or Qualified2 is more complex than
  94         --   a line or a circle).
  95
  96 Create(Qualified1 : QualifiedCurve from Geom2dGcc   ;
  97        Point1     : Point          from Geom2d      ;
  98        Point2     : Point          from Geom2d      ;
  99        Tolerance  : Real           from Standard    ;
 100        Param1     : Real           from Standard    )
 101 returns Circ2d3Tan from Geom2dGcc;
 102         ---Purpose: Constructs one or more 2D circles tangential to the curve Qualified1 and passing
 103         --  through two points Point1 and Point2, where Param1
 104         --  is used as the initial value of the parameter on
 105         --  Qualified1 of the tangency point between this
 106         --  argument and the solution sought, if the algorithm
 107         --   chooses an iterative method to find the solution (i.e. if
 108         --   Qualified1 is more complex than a line or a circle)
 109
 110
 111 Create(Point1     : Point          from Geom2d      ;
 112        Point2     : Point          from Geom2d      ;
 113        Point3     : Point          from Geom2d      ;
 114        Tolerance  : Real           from Standard    )
 115 returns Circ2d3Tan from Geom2dGcc;
 116         ---Purpose: Constructs one or more 2D circles passing through three points Point1, Point2 and Point3.
 117         -- Tolerance is a tolerance criterion used by the algorithm
 118         -- to find a solution when, mathematically, the problem
 119         -- posed does not have a solution, but where there is
 120         -- numeric uncertainty attached to the arguments.
 121         -- For example, take:
 122         -- -   two circles C1 and C2, such that C2 is inside C1,
 123         --   and almost tangential to C1; there is in fact no point
 124         --   of intersection between C1 and C2; and
 125         -- -   a circle C3 outside C1.
 126         -- You now want to find a circle which is tangential to C1,
 127         -- C2 and C3: a pure mathematical resolution will not find
 128         -- a solution. This is where the tolerance criterion is used:
 129         -- the algorithm considers that C1 and C2 are tangential if
 130         -- the shortest distance between these two circles is less
 131         -- than or equal to Tolerance. Thus, the algorithm finds a solution.
 132         -- Warning
 133         -- An iterative algorithm is used if Qualified1, Qualified2 or
 134         -- Qualified3 is more complex than a line or a circle. In
 135         -- such cases, the algorithm constructs only one solution.
 136         -- Exceptions
 137         -- GccEnt_BadQualifier if a qualifier is inconsistent with
 138         -- the argument it qualifies (for example, enclosing for a line).
 139
 140 Results(me    : in out                           ;
 141         Circ  :        Circ2d3Tan   from GccAna  ;
 142         Rank1 :        Integer      from Standard;
 143         Rank2 :        Integer      from Standard;
 144         Rank3 :        Integer      from Standard)
 145 is static;
 146
 147 IsDone(me) returns Boolean from Standard
 148 is static;
 149         ---Purpose: Returns true if the construction algorithm does not fail (even if it finds no solution).
 150         -- Note: IsDone protects against a failure arising from a
 151         -- more internal intersection algorithm, which has reached its numeric limits.
 152
 153 NbSolutions(me) returns Integer from Standard
 154 raises NotDone
 155 is static;
 156         ---Purpose: This method returns the number of solutions.
 157         --          NotDone is raised if the algorithm failed.
 158
 159 ThisSolution(me ; Index : Integer from Standard) returns Circ2d from gp
 160 raises OutOfRange, NotDone
 161 is static;
 162         ---Purpose: Returns the solution number Index and raises OutOfRange
 163         -- exception if Index is greater than the number of solutions.
 164         -- Be carefull: the Index is only a way to get all the
 165         -- solutions, but is not associated to theses outside the context
 166         -- of the algorithm-object.
 167
 168 WhichQualifier(me                                  ;
 169                Index   :     Integer  from Standard;
 170                Qualif1 : out Position from GccEnt  ;
 171                Qualif2 : out Position from GccEnt  ;
 172                Qualif3 : out Position from GccEnt  )
 173 raises OutOfRange, NotDone
 174 is static;
 175         ---Purpose: It returns the informations about the qualifiers of the tangency
 176         --          arguments concerning the solution number Index.
 177         --          It returns the real qualifiers (the qualifiers given to the
 178         --          constructor method in case of enclosed, enclosing and outside
 179         --          and the qualifiers computedin case of unqualified).
 180
 181 Tangency1(me                                     ;
 182           Index         : Integer   from Standard;
 183           ParSol,ParArg : out Real  from Standard;
 184           PntSol        : out Pnt2d from gp      )
 185 raises NotDone
 186 is static;
 187         ---Purpose: Returns informations about the tangency point between the
 188         -- result and the first argument.
 189         -- ParSol is the intrinsic parameter of the point PntSol on the solution curv.
 190         -- ParArg is the intrinsic parameter of the point PntSol on the argument curv.
 191
 192 Tangency2(me                                     ;
 193           Index         : Integer   from Standard;
 194           ParSol,ParArg : out Real  from Standard;
 195           PntSol        : out Pnt2d from gp      )
 196 raises NotDone
 197 is static;
 198         ---Purpose: Returns informations about the tangency point between the
 199         -- result and the second argument.
 200         -- ParSol is the intrinsic parameter of the point PntSol on the solution curv.
 201         -- ParArg is the intrinsic parameter of the point PntSol on the argument curv.
 202
 203 Tangency3(me                                     ;
 204           Index         : Integer   from Standard;
 205           ParSol,ParArg : out Real  from Standard;
 206           PntSol        : out Pnt2d from gp      )
 207 raises NotDone
 208 is static;
 209         ---Purpose: Returns informations about the tangency point between the
 210         -- result and the third argument.
 211         -- ParSol is the intrinsic parameter of the point PntSol on the solution curv.
 212         -- ParArg is the intrinsic parameter of the point PntSol on the argument curv.
 213
 214 IsTheSame1(me                            ;
 215            Index : Integer  from Standard) returns Boolean from Standard
 216 raises NotDone
 217 is static;
 218         ---Purpose: Returns True if the solution is equal to the first argument.
 219
 220 IsTheSame2(me                            ;
 221            Index : Integer  from Standard) returns Boolean from Standard
 222 raises NotDone
 223 is static;
 224         ---Purpose: Returns True if the solution is equal to the second argument.
 225
 226 IsTheSame3(me                            ;
 227            Index : Integer  from Standard) returns Boolean from Standard
 228 raises NotDone
 229 is static;
 230         ---Purpose:  Returns True if the solution is equal to the third argument.
 231         -- If Rarg is the radius of the first, second or third
 232         -- argument, Rsol is the radius of the solution and dist
 233         -- is the distance between the two centers, we consider
 234         -- the two circles to be identical if |Rarg - Rsol| and
 235         -- dist are less than or equal to the tolerance criterion
 236         -- given at the time of construction of this algorithm.
 237         -- Exceptions
 238         -- Standard_OutOfRange if Index is less than zero or
 239         -- greater than the number of solutions computed by this algorithm.
 240         -- StdFail_NotDone if the construction fails.
 241
 242 fields
 243
 244     cirsol   : Array1OfCirc2d from TColgp;
 245         ---Purpose: The solution.
 246
 247     NbrSol   : Real from Standard;
 248         ---Purpose: number of solutions.
 249
 250     WellDone : Boolean from Standard;
 251         ---Purpose: True if the algorithm succeeded.
 252
 253     qualifier1 : Array1OfPosition from GccEnt;
 254         ---Purpose: The qualifiers of the first argument.
 255
 256     qualifier2 : Array1OfPosition from GccEnt ;
 257         ---Purpose: The qualifiers of the second argument.
 258
 259     qualifier3 : Array1OfPosition from GccEnt;
 260         ---Purpose: The qualifiers of the third argument.
 261
 262     TheSame1 : Array1OfInteger from TColStd;
 263         ---Purpose: 1 if the solution and the first argument are the same (2 circles).
 264         -- if R1 is the radius of the first argument and Rsol the radius
 265         -- of the solution and dist the distance between the two centers,
 266         -- we concider the two circles are identical if R1+dist-Rsol is
 267         -- less than Tolerance.
 268         -- 0 in the other cases.
 269
 270     TheSame2 : Array1OfInteger from TColStd;
 271         ---Purpose: 1 if the solution and the second argument are the same (2 circles).
 272         -- if R2 is the radius of the second argument and Rsol the radius
 273         -- of the solution and dist the distance between the two centers,
 274         -- we concider the two circles are identical if R2+dist-Rsol is
 275         -- less than Tolerance.
 276         -- 0 in the other cases.
 277
 278     TheSame3 : Array1OfInteger from TColStd;
 279         ---Purpose: 1 if the solution and the third argument are the same (2 circles).
 280         -- if R3 is the radius of the third argument and Rsol the radius
 281         -- of the solution and dist the distance between the two centers,
 282         -- we concider the two circles are identical if R3+dist-Rsol is
 283         -- less than Tolerance.
 284         -- 0 in the other cases.
 285
 286     pnttg1sol   : Array1OfPnt2d from TColgp;
 287         ---Purpose: The tangency point between the solution and the first argument.
 288
 289     pnttg2sol   : Array1OfPnt2d from TColgp;
 290         ---Purpose: The tangency point between the solution and the second argument.
 291
 292     pnttg3sol   : Array1OfPnt2d from TColgp;
 293         ---Purpose: The tangency point between the solution and the third argument.
 294
 295     par1sol   : Array1OfReal from TColStd;
 296         ---Purpose: The parameter of the tangency point between the solution and the
 297         -- first argument on the solution.
 298
 299     par2sol   : Array1OfReal from TColStd;
 300         ---Purpose: The parameter of the tangency point between the solution and the
 301         -- second argument on the solution.
 302
 303     par3sol   : Array1OfReal from TColStd;
 304         ---Purpose: The parameter of the tangency point between the solution and the
 305         -- third argument on the solution.
 306
 307     pararg1   : Array1OfReal from TColStd;
 308         ---Purpose: The parameter of the tangency point between the solution and the first
 309         -- argument on the first argument.
 310
 311     pararg2   : Array1OfReal from TColStd;
 312         ---Purpose: The parameter of the tangency point between the solution and the second
 313         -- argument on the second argument.
 314
 315     pararg3   : Array1OfReal from TColStd;
 316         ---Purpose: The parameter of the tangency point between the solution and the third
 317         -- argument on the second argument.
 318
 319 end Circ2d3Tan;