src/GeomAPI/GeomAPI_ExtremaCurveCurve.cdl

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