[occt.git] / src / GeomAPI / GeomAPI_ExtremaCurveCurve.cdl

-- Created on: 1994-03-18
-- Created by: Bruno DUMORTIER
-- Copyright (c) 1994-1999 Matra Datavision
-- Copyright (c) 1999-2014 OPEN CASCADE SAS
--
-- This file is part of Open CASCADE Technology software library.
--
-- This library is free software; you can redistribute it and / or modify it
-- under the terms of the GNU Lesser General Public version 2.1 as published
-- by the Free Software Foundation, with special exception defined in the file
-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
-- distribution for complete text of the license and disclaimer of any warranty.
--
-- Alternatively, this file may be used under the terms of Open CASCADE
-- commercial license or contractual agreement.

class ExtremaCurveCurve from GeomAPI
    	---Purpose: Describes functions for computing all the extrema
    	-- between two 3D curves.
    	-- An ExtremaCurveCurve algorithm minimizes or
    	-- maximizes the distance between a point on the first
    	-- curve and a point on the second curve. Thus, it
    	-- computes start and end points of perpendiculars
    	-- common to the two curves (an intersection point is
    	-- not an extremum unless the two curves are tangential at this point).
    	-- Solutions consist of pairs of points, and an extremum
    	-- is considered to be a segment joining the two points of a solution.
    	-- An ExtremaCurveCurve object provides a framework for:
    	-- -   defining the construction of the extrema,
    	-- -   implementing the construction algorithm, and
    	-- -   consulting the results.
    	-- Warning
    	-- In some cases, the nearest points between two
    	-- curves do not correspond to one of the computed
    	-- extrema. Instead, they may be given by:
    	-- -   a limit point of one curve and one of the following:
    	--   -   its orthogonal projection on the other curve,
    	--   -   a limit point of the other curve; or
    	--   -   an intersection point between the two curves.

uses
    Curve     from Geom,
    Curve     from GeomAdaptor,
    ExtCC     from Extrema,
    Pnt       from gp,
    Length    from Quantity,
    Parameter from Quantity
    
    
raises
    OutOfRange from Standard,
    NotDone    from StdFail
    
    
is

    Create
	---Purpose: Constructs an empty algorithm for computing
    	-- extrema between two curves. Use an Init function
    	-- to define the curves on which it is going to work.
    returns ExtremaCurveCurve from GeomAPI;
    
    
    Create(C1   , C2    : Curve from Geom)
	---Purpose: Computes the extrema between the curves C1 and C2.   
    returns ExtremaCurveCurve from GeomAPI;


    Create(C1   , C2    : Curve    from Geom;
    	   U1min, U1max : Parameter from Quantity;
    	   U2min, U2max : Parameter from Quantity)
	---Purpose: Computes   the portion of the curve C1 limited by the two
    	--    points of parameter (U1min,U1max), and
    	--  -   the portion of the curve C2 limited by the two
    	--   points of parameter (U2min,U2max).
    	--        Warning
    	-- Use the function NbExtrema to obtain the number
    	-- of solutions. If this algorithm fails, NbExtrema returns 0.
    returns ExtremaCurveCurve from GeomAPI;


    Init(me : in out;
    	 C1   , C2    : Curve from Geom)
	---Purpose: Initializes this algorithm with the given arguments
    	-- and computes the extrema between the curves C1 and C2          
    is static;


    Init(me : in out;
    	 C1   , C2    : Curve from Geom;
    	 U1min, U1max : Parameter from Quantity;
    	 U2min, U2max : Parameter from Quantity)
	---Purpose: Initializes this algorithm with the given arguments
    	-- and computes the extrema between :
    	--   -   the portion of the curve C1 limited by the two
    	--    points of parameter (U1min,U1max), and
    	--   -   the portion of the curve C2 limited by the two
    	--    points of parameter (U2min,U2max).
    	--        Warning
    	-- Use the function NbExtrema to obtain the number
    	-- of solutions. If this algorithm fails, NbExtrema returns 0.
           is static;


    NbExtrema(me)
	---Purpose: Returns the number of extrema computed by this algorithm.
    	-- Note: if this algorithm fails, NbExtrema returns 0.
    returns Integer from Standard
	---C++: alias "Standard_EXPORT operator Standard_Integer() const;"
    is static;
    
    
    Points(me; Index  :     Integer from Standard;
    	       P1, P2 : out Pnt     from gp )
        ---Purpose: Returns the points P1 on the first curve and P2 on
    	-- the second curve, which are the ends of the
    	-- extremum of index Index computed by this algorithm.
    	-- Exceptions
    	-- Standard_OutOfRange if Index is not in the range [
    	-- 1,NbExtrema ], where NbExtrema is the
    	-- number of extrema computed by this algorithm.
    raises
    	OutOfRange from Standard
	    is static;	       


    Parameters(me; Index  :     Integer   from Standard;
    	     	   U1, U2 : out Parameter from Quantity)
       	---Purpose: Returns the parameters U1 of the point on the first
    	-- curve and U2 of the point on the second curve, which
    	-- are the ends of the extremum of index Index computed by this algorithm.
    	-- Exceptions
    	-- Standard_OutOfRange if Index is not in the range [
    	-- 1,NbExtrema ], where NbExtrema is the
    	-- number of extrema computed by this algorithm.
    raises
    	OutOfRange from Standard
	    is static;		    
		    
    
    Distance(me; Index : Integer from Standard)
    returns Length from Quantity
	---Purpose: Computes the distance between the end points of the
    	-- extremum of index Index computed by this algorithm.
    	-- Exceptions
    	-- Standard_OutOfRange if Index is not in the range [
    	-- 1,NbExtrema ], where NbExtrema is the
    	-- number of extrema computed by this algorithm.
    raises
    	OutOfRange from Standard
	    is static;		    
		    
    
    NearestPoints(me; P1, P2 : out Pnt from gp)
	---Purpose: Returns the points P1 on the first curve and P2 on
    	-- the second curve, which are the ends of the shortest
    	-- extremum computed by this algorithm.
    	-- Exceptions StdFail_NotDone if this algorithm fails.
    raises
    	NotDone from StdFail
    is static;
    
    
    LowerDistanceParameters(me;  U1, U2 : out Parameter from Quantity)
	---Purpose: Returns the parameters U1 of the point on the first
    	-- curve and U2 of the point on the second curve, which
    	-- are the ends of the shortest extremum computed by this algorithm.
    	-- Exceptions StdFail_NotDone if this algorithm fails.
    raises
    	NotDone from StdFail
    is static;
    
    
    LowerDistance(me)
	---Purpose: Computes the distance between the end points of the
    	-- shortest extremum computed by this algorithm.
    	-- Exceptions StdFail_NotDone if this algorithm fails.
    	---C++: alias "Standard_EXPORT operator Standard_Real() const;"
  returns Length from Quantity
    raises
    	NotDone from StdFail
    is static;
    
    
    Extrema(me)
	---Purpose: return the algorithmic object from Extrema
	---Level: Advanced
	---C++: return const&
	---C++: inline      
    returns ExtCC from Extrema
    is static;
    	
    TotalNearestPoints(me  :  in  out; P1, P2 : out Pnt from gp )
	---Purpose: set  in  <P1>  and <P2> the couple solution points
	--          such a the distance [P1,P2] is the minimum. taking  in  account 
	--          extremity  points  of  curves.
	---Level: Public          
    returns  Boolean  from  Standard 
        --  returns  "true"  if  it  is  possible  to  compute  points  and  "false" 
	--  if  such  points  do  not  exist, for  ex. - infinite parallel lines
    is static;
 
    TotalLowerDistanceParameters(me  :  in  out;  U1, U2 : out Parameter from Quantity)
	---Purpose: set  in <U1> and <U2> the parameters of the couple
	--          solution   points  which  represents  the  total  nearest
	--          solution.
	---Level: Public          
    returns  Boolean  from  Standard 
        --  returns  "true"  if  it  is  possible  to  compute  points  and  "false" 
	--  if  such  points  do  not  exist, for  ex. - infinite parallel lines
    is static;
    
    TotalLowerDistance(me  :  in  out)
	---Purpose: return the distance of the total  nearest couple solution
	--          point. 
	---Level: Public          
    returns Length from Quantity
    raises
    	NotDone from StdFail
	---Purpose: if <myExtCC> is not done
    is static;
    
    TotalPerform(me  :  in  out) 
    is static  private;
     
	 
fields

    myIsDone: Boolean from Standard;
    myIndex : Integer from Standard;    -- index of the nearest solution
    myExtCC : ExtCC   from Extrema;
    myC1    : Curve   from GeomAdaptor;
    myC2    : Curve   from GeomAdaptor;  
    
    --  Fields  to  compute  total  min.  dist  with  extremities of  curves
    myTotalExt  :  Boolean from Standard;  --  indicate  that  total  extr. 
    	    	    	    	    	   --  has  been  computed  
    myIsInfinite  : Boolean from Standard;  --  infinite  extremity  points 					   
    myTotalDist  :  Real  from  Standard;  --  total  min.  dist 
    myTotalPoints  :  Pnt[2]; 
    myTotalPars  :  Real[2]; 
     
end ExtremaCurveCurve;
Commit	Line	Data
b311480e	1	-- Created on: 1994-03-18
	2	-- Created by: Bruno DUMORTIER
	3	-- Copyright (c) 1994-1999 Matra Datavision
973c2be1	4	-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e	5	--
973c2be1	6	-- This file is part of Open CASCADE Technology software library.
b311480e	7	--
973c2be1	8	-- This library is free software; you can redistribute it and / or modify it
	9	-- under the terms of the GNU Lesser General Public 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.
b311480e	13	--
973c2be1	14	-- Alternatively, this file may be used under the terms of Open CASCADE
973c2be1	15	-- commercial license or contractual agreement.
7fd59977	16
	17	class ExtremaCurveCurve from GeomAPI
	18	---Purpose: Describes functions for computing all the extrema
	19	-- between two 3D curves.
	20	-- An ExtremaCurveCurve algorithm minimizes or
	21	-- maximizes the distance between a point on the first
	22	-- curve and a point on the second curve. Thus, it
	23	-- computes start and end points of perpendiculars
	24	-- common to the two curves (an intersection point is
	25	-- not an extremum unless the two curves are tangential at this point).
	26	-- Solutions consist of pairs of points, and an extremum
	27	-- is considered to be a segment joining the two points of a solution.
	28	-- An ExtremaCurveCurve object provides a framework for:
	29	-- - defining the construction of the extrema,
	30	-- - implementing the construction algorithm, and
	31	-- - consulting the results.
	32	-- Warning
	33	-- In some cases, the nearest points between two
	34	-- curves do not correspond to one of the computed
	35	-- extrema. Instead, they may be given by:
	36	-- - a limit point of one curve and one of the following:
	37	-- - its orthogonal projection on the other curve,
	38	-- - a limit point of the other curve; or
	39	-- - an intersection point between the two curves.
	40
	41	uses
	42	Curve from Geom,
	43	Curve from GeomAdaptor,
	44	ExtCC from Extrema,
	45	Pnt from gp,
	46	Length from Quantity,
	47	Parameter from Quantity
	48
	49
	50	raises
	51	OutOfRange from Standard,
	52	NotDone from StdFail
	53
	54
	55	is
	56
	57	Create
	58	---Purpose: Constructs an empty algorithm for computing
	59	-- extrema between two curves. Use an Init function
	60	-- to define the curves on which it is going to work.
	61	returns ExtremaCurveCurve from GeomAPI;
	62
	63
	64	Create(C1 , C2 : Curve from Geom)
	65	---Purpose: Computes the extrema between the curves C1 and C2.
	66	returns ExtremaCurveCurve from GeomAPI;
	67
	68
	69	Create(C1 , C2 : Curve from Geom;
	70	U1min, U1max : Parameter from Quantity;
	71	U2min, U2max : Parameter from Quantity)
	72	---Purpose: Computes the portion of the curve C1 limited by the two
	73	-- points of parameter (U1min,U1max), and
	74	-- - the portion of the curve C2 limited by the two
	75	-- points of parameter (U2min,U2max).
	76	-- Warning
	77	-- Use the function NbExtrema to obtain the number
	78	-- of solutions. If this algorithm fails, NbExtrema returns 0.
	79	returns ExtremaCurveCurve from GeomAPI;
80
81
82	Init(me : in out;
83	C1 , C2 : Curve from Geom)
84	---Purpose: Initializes this algorithm with the given arguments
85	-- and computes the extrema between the curves C1 and C2
86	is static;
87
88
89	Init(me : in out;
90	C1 , C2 : Curve from Geom;
91	U1min, U1max : Parameter from Quantity;
92	U2min, U2max : Parameter from Quantity)
93	---Purpose: Initializes this algorithm with the given arguments
94	-- and computes the extrema between :
95	-- - the portion of the curve C1 limited by the two
96	-- points of parameter (U1min,U1max), and
97	-- - the portion of the curve C2 limited by the two
98	-- points of parameter (U2min,U2max).
99	-- Warning
100	-- Use the function NbExtrema to obtain the number
101	-- of solutions. If this algorithm fails, NbExtrema returns 0.
102	is static;
103
104
105	NbExtrema(me)
106	---Purpose: Returns the number of extrema computed by this algorithm.
107	-- Note: if this algorithm fails, NbExtrema returns 0.
108	returns Integer from Standard
109	---C++: alias "Standard_EXPORT operator Standard_Integer() const;"
110	is static;
111
112
113	Points(me; Index : Integer from Standard;
114	P1, P2 : out Pnt from gp )
115	---Purpose: Returns the points P1 on the first curve and P2 on
116	-- the second curve, which are the ends of the
117	-- extremum of index Index computed by this algorithm.
118	-- Exceptions
119	-- Standard_OutOfRange if Index is not in the range [
120	-- 1,NbExtrema ], where NbExtrema is the
121	-- number of extrema computed by this algorithm.
122	raises
123	OutOfRange from Standard
124	is static;
125
126
127	Parameters(me; Index : Integer from Standard;
128	U1, U2 : out Parameter from Quantity)
129	---Purpose: Returns the parameters U1 of the point on the first
130	-- curve and U2 of the point on the second curve, which
131	-- are the ends of the extremum of index Index computed by this algorithm.
132	-- Exceptions
133	-- Standard_OutOfRange if Index is not in the range [
134	-- 1,NbExtrema ], where NbExtrema is the
135	-- number of extrema computed by this algorithm.
136	raises
137	OutOfRange from Standard
138	is static;
139
140
141	Distance(me; Index : Integer from Standard)
142	returns Length from Quantity
143	---Purpose: Computes the distance between the end points of the
144	-- extremum of index Index computed by this algorithm.
145	-- Exceptions
146	-- Standard_OutOfRange if Index is not in the range [
147	-- 1,NbExtrema ], where NbExtrema is the
148	-- number of extrema computed by this algorithm.
149	raises
150	OutOfRange from Standard
151	is static;
152
153
154	NearestPoints(me; P1, P2 : out Pnt from gp)
155	---Purpose: Returns the points P1 on the first curve and P2 on
156	-- the second curve, which are the ends of the shortest
157	-- extremum computed by this algorithm.
158	-- Exceptions StdFail_NotDone if this algorithm fails.
159	raises
160	NotDone from StdFail
161	is static;
162
163
164	LowerDistanceParameters(me; U1, U2 : out Parameter from Quantity)
165	---Purpose: Returns the parameters U1 of the point on the first
166	-- curve and U2 of the point on the second curve, which
167	-- are the ends of the shortest extremum computed by this algorithm.
168	-- Exceptions StdFail_NotDone if this algorithm fails.
169	raises
170	NotDone from StdFail
171	is static;
172
173
174	LowerDistance(me)
175	---Purpose: Computes the distance between the end points of the
176	-- shortest extremum computed by this algorithm.
177	-- Exceptions StdFail_NotDone if this algorithm fails.
178	---C++: alias "Standard_EXPORT operator Standard_Real() const;"
179	returns Length from Quantity
180	raises
181	NotDone from StdFail
182	is static;
183
184
185	Extrema(me)
186	---Purpose: return the algorithmic object from Extrema
187	---Level: Advanced
188	---C++: return const&
189	---C++: inline
190	returns ExtCC from Extrema
191	is static;
192
193	TotalNearestPoints(me : in out; P1, P2 : out Pnt from gp )
194	---Purpose: set in <P1> and <P2> the couple solution points
195	-- such a the distance [P1,P2] is the minimum. taking in account
196	-- extremity points of curves.
197	---Level: Public
198	returns Boolean from Standard
199	-- returns "true" if it is possible to compute points and "false"
200	-- if such points do not exist, for ex. - infinite parallel lines
201	is static;
202
203	TotalLowerDistanceParameters(me : in out; U1, U2 : out Parameter from Quantity)
204	---Purpose: set in <U1> and <U2> the parameters of the couple
205	-- solution points which represents the total nearest
206	-- solution.
207	---Level: Public
208	returns Boolean from Standard
209	-- returns "true" if it is possible to compute points and "false"
210	-- if such points do not exist, for ex. - infinite parallel lines
211	is static;
212
213	TotalLowerDistance(me : in out)
214	---Purpose: return the distance of the total nearest couple solution
215	-- point.
216	---Level: Public
217	returns Length from Quantity
218	raises
219	NotDone from StdFail
220	---Purpose: if <myExtCC> is not done
221	is static;
222
223	TotalPerform(me : in out)
224	is static private;
225
226
227	fields
228
229	myIsDone: Boolean from Standard;
230	myIndex : Integer from Standard; -- index of the nearest solution
231	myExtCC : ExtCC from Extrema;
232	myC1 : Curve from GeomAdaptor;
233	myC2 : Curve from GeomAdaptor;
234
235	-- Fields to compute total min. dist with extremities of curves
236	myTotalExt : Boolean from Standard; -- indicate that total extr.
237	-- has been computed
238	myIsInfinite : Boolean from Standard; -- infinite extremity points
239	myTotalDist : Real from Standard; -- total min. dist
240	myTotalPoints : Pnt[2];
241	myTotalPars : Real[2];
242
243	end ExtremaCurveCurve;