path: root/src/Geom2dGcc/Geom2dGcc_Circ2d3Tan.cdl

-- File:	Circ2d3Tan.cdl
-- Created:	Tue Oct 20 16:23:14 1992
-- Author:	Remi GILET
--		<reg@sdsun1>
---Copyright:	 Matra Datavision 1992

class Circ2d3Tan from Geom2dGcc

	---Purpose: This class implements the algorithms used to 
	--          create 2d circles tangent to 3 points/lines/circles/
	--          curves with one curve or more.
	--          The arguments of all construction methods are :
	--             - The three qualifiied elements for the 
	--             tangency constrains (QualifiedCirc, QualifiedLine,
	--             Qualifiedcurv, Points).
	--             - A parameter for each QualifiedCurv.
    	--          Describes functions for building a 2D circle:
    	--          -   tangential to 3 curves, or
    	--          -   tangential to 2 curves and passing through a point, or
    	--          -   tangential to a curve and passing through 2 points, or
    	--          -   passing through 3 points.
    	--          A Circ2d3Tan object provides a framework for:
    	--          -   defining the construction of 2D circles(s),
    	--          -   implementing the construction algorithm, and
    	--          -   consulting the result(s).
        
-- inherits Entity from Standard

uses QualifiedCurve  from Geom2dGcc,
     Integer         from Standard,
     Circ2d          from gp,
     Pnt2d           from gp,
     Array1OfPnt2d   from TColgp,
     Array1OfCirc2d  from TColgp,
     Boolean         from Standard,
     Array1OfInteger from TColStd,
     Array1OfReal    from TColStd,
     Circ2d3Tan      from GccAna,
     Point           from Geom2d,
     MyC2d3Tan       from Geom2dGcc,
     Position         from GccEnt,
     Array1OfPosition from GccEnt

raises NotDone    from StdFail,
       OutOfRange from Standard

is

Create(Qualified1 : QualifiedCurve from Geom2dGcc   ;
       Qualified2 : QualifiedCurve from Geom2dGcc   ;
       Qualified3 : QualifiedCurve from Geom2dGcc   ;
       Tolerance  : Real           from Standard    ;
       Param1     : Real           from Standard    ;
       Param2     : Real           from Standard    ;
       Param3     : Real           from Standard    ) 
returns Circ2d3Tan from Geom2dGcc;
	---Purpose: Constructs one or more 2D circles
    	--   tangential to three curves Qualified1, Qualified2 and
    	--   Qualified3, where Param1, Param2 and Param3 are
    	--   used, respectively, as the initial values of the
    	--   parameters on Qualified1, Qualified2 and Qualified3
    	--   of the tangency point between these arguments and
    	--   the solution sought, if the algorithm chooses an
    	--   iterative method to find the solution (i.e. if either
    	--   Qualified1, Qualified2 or Qualified3 is more complex
    	--   than a line or a circle).

Create(Qualified1 : QualifiedCurve from Geom2dGcc   ;
       Qualified2 : QualifiedCurve from Geom2dGcc   ;
       Point      : Point          from Geom2d      ;
       Tolerance  : Real           from Standard    ;
       Param1     : Real           from Standard    ;
       Param2     : Real           from Standard    ) 
returns Circ2d3Tan from Geom2dGcc;
	---Purpose: Constructs one or more 2D circles
    	-- tangential to two curves Qualified1 and Qualified2
    	--   and passing through the point Point, where Param1
    	--   and Param2 are used, respectively, as the initial
    	--   values of the parameters on Qualified1 and
    	--   Qualified2 of the tangency point between this
    	--   argument and the solution sought, if the algorithm
    	--   chooses an iterative method to find the solution (i.e. if
    	--   either Qualified1 or Qualified2 is more complex than
    	--   a line or a circle).

Create(Qualified1 : QualifiedCurve from Geom2dGcc   ;
       Point1     : Point          from Geom2d      ;
       Point2     : Point          from Geom2d      ;
       Tolerance  : Real           from Standard    ;
       Param1     : Real           from Standard    )
returns Circ2d3Tan from Geom2dGcc;
	---Purpose: Constructs one or more 2D circles tangential to the curve Qualified1 and passing
    	--  through two points Point1 and Point2, where Param1
    	--  is used as the initial value of the parameter on
    	--  Qualified1 of the tangency point between this
    	--  argument and the solution sought, if the algorithm
    	--   chooses an iterative method to find the solution (i.e. if
    	--   Qualified1 is more complex than a line or a circle)
   

Create(Point1     : Point          from Geom2d      ;
       Point2     : Point          from Geom2d      ;
       Point3     : Point          from Geom2d      ;
       Tolerance  : Real           from Standard    )
returns Circ2d3Tan from Geom2dGcc;
	---Purpose: Constructs one or more 2D circles passing through three points Point1, Point2 and Point3.
    	-- Tolerance is a tolerance criterion used by the algorithm
    	-- to find a solution when, mathematically, the problem
    	-- posed does not have a solution, but where there is
    	-- numeric uncertainty attached to the arguments.
    	-- For example, take:
    	-- -   two circles C1 and C2, such that C2 is inside C1,
    	--   and almost tangential to C1; there is in fact no point
    	--   of intersection between C1 and C2; and
    	-- -   a circle C3 outside C1.
    	-- You now want to find a circle which is tangential to C1,
    	-- C2 and C3: a pure mathematical resolution will not find
    	-- a solution. This is where the tolerance criterion is used:
    	-- the algorithm considers that C1 and C2 are tangential if
    	-- the shortest distance between these two circles is less
    	-- than or equal to Tolerance. Thus, the algorithm finds a solution.
    	-- Warning
    	-- An iterative algorithm is used if Qualified1, Qualified2 or
    	-- Qualified3 is more complex than a line or a circle. In
    	-- such cases, the algorithm constructs only one solution.
    	-- Exceptions
    	-- GccEnt_BadQualifier if a qualifier is inconsistent with
    	-- the argument it qualifies (for example, enclosing for a line).
        
Results(me    : in out                           ;
    	Circ  :        Circ2d3Tan   from GccAna  ;
    	Rank1 :        Integer      from Standard;
    	Rank2 :        Integer      from Standard;
    	Rank3 :        Integer      from Standard)
is static;

IsDone(me) returns Boolean from Standard
is static;
    	---Purpose: Returns true if the construction algorithm does not fail (even if it finds no solution).
    	-- Note: IsDone protects against a failure arising from a
    	-- more internal intersection algorithm, which has reached its numeric limits.
        
NbSolutions(me) returns Integer from Standard
raises NotDone
is static;
    	---Purpose: This method returns the number of solutions.
    	--          NotDone is raised if the algorithm failed.

ThisSolution(me ; Index : Integer from Standard) returns Circ2d from gp
raises OutOfRange, NotDone
is static;
    	---Purpose: Returns the solution number Index and raises OutOfRange 
   	-- exception if Index is greater than the number of solutions.
    	-- Be carefull: the Index is only a way to get all the 
    	-- solutions, but is not associated to theses outside the context
    	-- of the algorithm-object.

WhichQualifier(me                                  ;
    	       Index   :     Integer  from Standard;
	       Qualif1 : out Position from GccEnt  ;
	       Qualif2 : out Position from GccEnt  ;
	       Qualif3 : out Position from GccEnt  )
raises OutOfRange, NotDone
is static;
    	---Purpose: It returns the informations about the qualifiers of the tangency 
    	--          arguments concerning the solution number Index.
    	--          It returns the real qualifiers (the qualifiers given to the 
    	--          constructor method in case of enclosed, enclosing and outside 
    	--          and the qualifiers computedin case of unqualified).

Tangency1(me                                     ;
          Index         : Integer   from Standard;
          ParSol,ParArg : out Real  from Standard;
          PntSol        : out Pnt2d from gp      )
raises NotDone
is static;
    	---Purpose: Returns informations about the tangency point between the 
    	-- result and the first argument.
    	-- ParSol is the intrinsic parameter of the point PntSol on the solution curv.
    	-- ParArg is the intrinsic parameter of the point PntSol on the argument curv.

Tangency2(me                                     ;
          Index         : Integer   from Standard;
          ParSol,ParArg : out Real  from Standard;
          PntSol        : out Pnt2d from gp      )
raises NotDone
is static;
    	---Purpose: Returns informations about the tangency point between the 
    	-- result and the second argument.
    	-- ParSol is the intrinsic parameter of the point PntSol on the solution curv.
    	-- ParArg is the intrinsic parameter of the point PntSol on the argument curv.

Tangency3(me                                     ;
          Index         : Integer   from Standard;
          ParSol,ParArg : out Real  from Standard;
          PntSol        : out Pnt2d from gp      )
raises NotDone
is static;
    	---Purpose: Returns informations about the tangency point between the 
    	-- result and the third argument.
    	-- ParSol is the intrinsic parameter of the point PntSol on the solution curv.
    	-- ParArg is the intrinsic parameter of the point PntSol on the argument curv.

IsTheSame1(me                            ;
           Index : Integer  from Standard) returns Boolean from Standard
raises NotDone
is static;
    	---Purpose: Returns True if the solution is equal to the first argument.

IsTheSame2(me                            ;
           Index : Integer  from Standard) returns Boolean from Standard
raises NotDone
is static;
    	---Purpose: Returns True if the solution is equal to the second argument.

IsTheSame3(me                            ;
           Index : Integer  from Standard) returns Boolean from Standard
raises NotDone
is static;
    	---Purpose:  Returns True if the solution is equal to the third argument.
    	-- If Rarg is the radius of the first, second or third
    	-- argument, Rsol is the radius of the solution and dist
    	-- is the distance between the two centers, we consider
    	-- the two circles to be identical if |Rarg - Rsol| and
    	-- dist are less than or equal to the tolerance criterion
    	-- given at the time of construction of this algorithm.
    	-- Exceptions
    	-- Standard_OutOfRange if Index is less than zero or
    	-- greater than the number of solutions computed by this algorithm.
    	-- StdFail_NotDone if the construction fails.
        
fields

    cirsol   : Array1OfCirc2d from TColgp;
    	---Purpose: The solution.

    NbrSol   : Real from Standard;
    	---Purpose: number of solutions.

    WellDone : Boolean from Standard;
    	---Purpose: True if the algorithm succeeded.

    qualifier1 : Array1OfPosition from GccEnt;
    	---Purpose: The qualifiers of the first argument.

    qualifier2 : Array1OfPosition from GccEnt ;
    	---Purpose: The qualifiers of the second argument.

    qualifier3 : Array1OfPosition from GccEnt;
    	---Purpose: The qualifiers of the third argument.

    TheSame1 : Array1OfInteger from TColStd;
    	---Purpose: 1 if the solution and the first argument are the same (2 circles).
    	-- if R1 is the radius of the first argument and Rsol the radius 
    	-- of the solution and dist the distance between the two centers,
    	-- we concider the two circles are identical if R1+dist-Rsol is 
    	-- less than Tolerance.
    	-- 0 in the other cases.

    TheSame2 : Array1OfInteger from TColStd;
    	---Purpose: 1 if the solution and the second argument are the same (2 circles).
    	-- if R2 is the radius of the second argument and Rsol the radius 
    	-- of the solution and dist the distance between the two centers,
    	-- we concider the two circles are identical if R2+dist-Rsol is 
    	-- less than Tolerance.
    	-- 0 in the other cases.

    TheSame3 : Array1OfInteger from TColStd;
    	---Purpose: 1 if the solution and the third argument are the same (2 circles).
    	-- if R3 is the radius of the third argument and Rsol the radius 
    	-- of the solution and dist the distance between the two centers,
    	-- we concider the two circles are identical if R3+dist-Rsol is 
    	-- less than Tolerance.
    	-- 0 in the other cases.

    pnttg1sol   : Array1OfPnt2d from TColgp;
    	---Purpose: The tangency point between the solution and the first argument.

    pnttg2sol   : Array1OfPnt2d from TColgp;
    	---Purpose: The tangency point between the solution and the second argument.

    pnttg3sol   : Array1OfPnt2d from TColgp;
    	---Purpose: The tangency point between the solution and the third argument.

    par1sol   : Array1OfReal from TColStd;
    	---Purpose: The parameter of the tangency point between the solution and the 
    	-- first argument on the solution.

    par2sol   : Array1OfReal from TColStd;
    	---Purpose: The parameter of the tangency point between the solution and the 
    	-- second argument on the solution.

    par3sol   : Array1OfReal from TColStd;
    	---Purpose: The parameter of the tangency point between the solution and the 
    	-- third argument on the solution.

    pararg1   : Array1OfReal from TColStd;
    	---Purpose: The parameter of the tangency point between the solution and the first 
    	-- argument on the first argument.

    pararg2   : Array1OfReal from TColStd;
    	---Purpose: The parameter of the tangency point between the solution and the second
    	-- argument on the second argument.

    pararg3   : Array1OfReal from TColStd;
    	---Purpose: The parameter of the tangency point between the solution and the third
    	-- argument on the second argument.


--    CircAna  : Circ2d2TanOn from GccAna;
--    CircIter : Circ2d2TanOn from GccIter;
--    TypeAna  : Boolean;

end Circ2d3Tan;