0025124: [Feature request] Removal of continuity checks for offset geometries
[occt.git] / src / Geom2d / Geom2d_OffsetCurve.cdl
1 -- Created on: 1993-03-24
2 -- Created by: Philippe DAUTRY
3 -- Copyright (c) 1993-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 OffsetCurve from Geom2d inherits Curve from Geom2d
18
19  
20         --- Purpose :  
21         --  This class implements the basis services for the creation,
22         --  edition, modification and evaluation of planar offset curve.
23         --  The offset curve is obtained by offsetting by distance along 
24         --  the normal to a basis curve defined in 2D space.
25         --  The offset curve in this package can be a self intersecting
26         --  curve even if the basis curve does not self-intersect.
27         --  The self intersecting portions are not deleted at the
28         --  construction time.
29         --  An offset curve is a curve at constant distance (Offset) from a
30         --  basis curve and the offset curve takes its parametrization from
31         --  the basis curve. The Offset curve is in the direction of the
32         --  normal to the basis curve N.
33         --  The distance offset may be positive or negative to indicate the
34         --  preferred side of the curve :
35         --  . distance offset >0 => the curve is in the direction of N
36         --  . distance offset >0 => the curve is in the direction of - N
37         --  On the Offset curve :
38         --  Value(u) = BasisCurve.Value(U) + (Offset * (T ^ Z)) / ||T ^ Z||
39         --  where T is the tangent vector to the basis curve and Z the 
40         --  direction of the normal vector to the plane of the curve,
41         --  N = T ^ Z defines the offset direction and should not have 
42         --  null length. 
43         --  
44         --  Warnings :
45         --  In this package we suppose that the continuity of the offset
46         --  curve is one degree less than the continuity of the
47         --  basis curve and we don't check that at any point ||T^Z|| != 0.0
48         --  
49         --  So to evaluate the curve it is better to check that the offset
50         --  curve is well defined at any point because an exception could 
51         --  be raised. The check is not done in this package at the creation
52         --  of the offset curve because the control needs the use of an
53         --  algorithm which cannot be implemented in this package.
54         --  The OffsetCurve is closed if the first point and the last point
55         --  are the same (The distance between these two points is lower or
56         --  equal to the Resolution sea package gp) . The OffsetCurve can be
57         --  closed even if the basis curve is not closed. 
58
59 uses Dir2d    from gp,
60      Pnt2d    from gp,
61      Trsf2d   from gp,
62      Vec2d    from gp,
63      Curve    from Geom2d,
64      Geometry from Geom2d,
65      Shape    from GeomAbs
66
67
68 raises ConstructionError   from Standard,
69        RangeError          from Standard,
70        NoSuchObject        from Standard,
71        UndefinedDerivative from Geom2d,
72        UndefinedValue      from Geom2d,
73        NotImplemented      from Standard
74
75
76
77 is
78
79
80   Create (C : Curve from Geom2d;
81           Offset : Real;
82           isNotCheckC0 : Boolean = Standard_False)
83
84   returns OffsetCurve
85         --- Purpose : Constructs a curve offset from the basis curve C,
86         -- where Offset is the distance between the offset
87         -- curve and the basis curve at any point.
88         -- A point on the offset curve is built by measuring the
89         -- offset value along a normal vector at a point on C.
90         -- This normal vector is obtained by rotating the
91         -- vector tangential to C at 90 degrees in the
92         -- anti-trigonometric sense. The side of C on which
93         -- the offset value is measured is indicated by this
94         -- normal vector if Offset is positive, or in the inverse
95         -- sense if Offset is negative.
96       -- If isNotCheckC0 = TRUE checking if basis curve has C0-continuity
97       -- is not made.
98         --   Warnings :
99         --  In this package the entities are not shared. The OffsetCurve is
100         --  built with a copy of the curve C. So when C is modified the
101         --  OffsetCurve is not modified 
102         --  Warning!  if isNotCheckC0 = false, 
103             -- ConstructionError  raised if the basis curve C is not at least C1.
104         --  No check is done to know if ||V^Z|| != 0.0 at any point.
105      raises ConstructionError;
106
107         
108
109   Reverse (me : mutable);
110         --- Purpose : Changes the direction of parametrization of <me>.
111         --     As a result:
112         -- - the basis curve is reversed,
113         -- - the start point of the initial curve becomes the end
114         --   point of the reversed curve,
115         -- - the end point of the initial curve becomes the start
116         --   point of the reversed curve, and
117         -- - the first and last parameters are recomputed.
118
119
120   ReversedParameter(me; U : Real) returns Real;
121         ---Purpose: Computes the parameter on the reversed curve for
122         -- the point of parameter U on this offset curve.
123
124
125   SetBasisCurve ( me : mutable;
126                   C : Curve from Geom2d;
127                   isNotCheckC0 : Boolean = Standard_False)
128      raises ConstructionError;
129         --- Purpose : Changes this offset curve by assigning C as the
130         -- basis curve from which it is built.
131       -- If isNotCheckC0 = TRUE checking if basis curve has C0-continuity
132       -- is not made.
133         -- Exceptions
134                 -- if isNotCheckC0 = false, 
135         -- Standard_ConstructionError if the curve C is not at least "C1" continuous.
136
137   SetOffsetValue (me : mutable; D : Real);
138         --- Purpose :  Changes this offset curve by assigning D as the offset value.
139         
140   BasisCurve (me) returns Curve from Geom2d;
141         --- Purpose : Returns the basis curve of this offset curve. The basis curve can be an offset curve.
142         
143
144
145   Continuity (me)  returns Shape from GeomAbs;
146         --- Purpose :
147         --  Continuity of the Offset curve :
148         --  C0 : only geometric continuity,
149         --  C1 : continuity of the first derivative all along the Curve,
150         --  C2 : continuity of the second derivative all along the Curve,
151         --  C3 : continuity of the third derivative all along the Curve,
152         --  G1 : tangency continuity all along the Curve,
153         --  G2 : curvature continuity all along the Curve,
154         --  CN : the order of continuity is infinite.
155         --   Warnings :
156         --  Returns the continuity of the basis curve - 1. 
157         --  The offset curve must have a unique normal direction defined
158         --  at any point.
159
160
161
162
163
164         --- Purpose  : Value and derivatives
165         --  
166         --  Warnings :
167         --  The exception UndefinedValue or UndefinedDerivative is 
168         --  raised if it is not possible to compute a unique offset
169         --  direction.
170         --  If T is the first derivative with not null length and
171         --  Z the direction normal to the plane of the curve, the
172         --  relation ||T(U) ^ Z|| != 0  must be satisfied to evaluate
173         --  the offset curve.
174         --  No check is done at the creation time and we suppose
175         --  in this package that the offset curve is well defined.
176
177
178   D0 (me; U : Real; P : out Pnt2d)
179      raises UndefinedValue;
180         ---Purpose:  Warning! this should not be called 
181         --          if the basis curve is not at least C1. Nevertheless
182         --          if used on portion where the curve is C1, it is OK
183  
184
185
186   D1 (me; U : Real; P : out Pnt2d; V1 : out Vec2d)
187      raises UndefinedDerivative;
188         ---Purpose:  Warning! this should not be called 
189         --           if the continuity of the basis curve is not C2.
190         --           Nevertheless, it's OK to use it  on portion 
191         --           where the curve is C2
192
193
194
195   D2 (me; U : Real; P : out Pnt2d; V1, V2 : out Vec2d)
196      raises UndefinedDerivative;
197         ---Purpose:  Warning!  This  should  not  be called 
198         --           if the continuity of the basis curve is not C3.
199         --           Nevertheless, it's OK to use it  on portion 
200         --           where the curve is C3  
201
202   D3 (me; U : Real; P : out Pnt2d; V1, V2, V3 : out Vec2d)
203      raises UndefinedDerivative;
204
205         ---Purpose:  Warning! This should not be called 
206         --           if the continuity of the basis curve is not C4.
207         --           Nevertheless, it's OK to use it  on portion 
208         --           where the curve is C4          
209
210   DN (me; U : Real; N : Integer)   returns Vec2d
211         --- Purpose : The returned vector gives the value of the derivative
212         --  for the order of derivation N.      
213         --  Warning! this should not be called 
214         --        raises  UndefunedDerivative   if the continuity of the basis curve is not CN+1.
215         --           Nevertheless, it's OK to use it  on portion 
216         --           where the curve is CN+1  
217         -- raises  RangeError if N < 1. 
218         -- raises  NotImplemented if N > 3. 
219     
220      raises UndefinedDerivative,
221
222             RangeError,
223             NotImplemented; 
224
225
226
227         --- Purpose : The following functions compute the value and derivatives
228         --  on the offset curve and returns the derivatives on the
229         --  basis curve too.  
230         --  The computation of the value and derivatives on the basis
231         --  curve are used to evaluate the offset curve
232         --  Warnings :
233         --  The exception UndefinedValue or UndefinedDerivative is 
234         --  raised if it is not possible to compute a unique offset direction.
235
236
237   Value (me; U : Real; P, Pbasis : out Pnt2d; V1basis : out Vec2d)
238      raises UndefinedValue;
239
240         ---Purpose:  Warning! this should not be called 
241         --          if the basis curve is not at least C1. Nevertheless
242         --          if used on portion where the curve is C1, it is OK 
243   
244
245   D1 (me; U : Real; P, Pbasis : out Pnt2d;
246       V1, V1basis, V2basis : out Vec2d)
247      raises UndefinedDerivative;
248
249         ---Purpose:  Warning! this should not be called 
250         --           if the continuity of the basis curve is not C1.
251         --           Nevertheless, it's OK to use it  on portion 
252         --           where the curve is C1
253
254   D2 (me; U : Real; P, Pbasis : out Pnt2d;  V1, V2, V1basis, V2basis, 
255       V3basis : out Vec2d)
256      raises UndefinedDerivative;
257
258         ---Purpose:  Warning! this should not be called 
259         --           if the continuity of the basis curve is not C3.
260         --           Nevertheless, it's OK to use it  on portion 
261         --           where the curve is C3 
262
263   FirstParameter (me)  returns Real;
264
265   LastParameter (me)   returns Real;
266         ---Purpose: Returns the value of the first or last parameter of this
267         -- offset curve. The first parameter corresponds to the
268         -- start point of the curve. The last parameter
269         -- corresponds to the end point.
270         -- Note: the first and last parameters of this offset curve
271         -- are also the ones of its basis curve.
272         
273   Offset (me)          returns Real;
274         ---Purpose: Returns the offset value of this offset curve.
275
276   IsClosed (me)   returns Boolean;
277         --- Purpose :
278         --  Returns True if the distance between the start point 
279         --  and the end point of the curve is lower or equal to 
280         --  Resolution from package gp.
281
282
283   IsCN (me; N : Integer)  returns Boolean
284         --- Purpose : Is the order of continuity of the curve N ?
285         --   Warnings :
286         --  This method answer True if the continuity of the basis curve 
287         --  is N + 1.  We suppose in this class that a normal direction
288         --  to the basis curve (used to compute the offset curve) is 
289         --  defined at any point on the basis curve.
290      raises RangeError;
291         --- Purpose : Raised if N < 0.
292
293
294   IsPeriodic (me)  returns Boolean;
295         --- Purpose : Is the parametrization of a curve is periodic ?
296         --  If the basis curve is a circle or an ellipse the corresponding
297         --  OffsetCurve is periodic. If the basis curve can't be periodic 
298         --  (for example BezierCurve) the OffsetCurve can't be periodic.
299
300
301   Period (me) returns Real from Standard
302         ---Purpose: Returns the period of this offset curve, i.e. the period
303         -- of the basis curve of this offset curve.
304         -- Exceptions
305         -- Standard_NoSuchObject if the basis curve is not periodic.
306   raises  NoSuchObject from Standard
307   is redefined;
308
309
310   Transform (me : mutable; T : Trsf2d);
311         ---Purpose : Applies the transformation T to this offset curve.
312         -- Note: the basis curve is also modified.
313
314   TransformedParameter(me; U : Real; T : Trsf2d from gp) returns Real
315         ---Purpose: Returns the  parameter on the  transformed  curve for
316         --          the transform of the point of parameter U on <me>.
317         --          
318         --          me->Transformed(T)->Value(me->TransformedParameter(U,T))
319         --          
320         --          is the same point as
321         --          
322         --          me->Value(U).Transformed(T)
323         --          
324         --          This methods calls the basis curve method.
325      is redefined;  
326
327   ParametricTransformation(me; T : Trsf2d from gp) returns Real
328         ---Purpose: Returns a  coefficient to compute the parameter on
329         --          the transformed  curve  for  the transform  of the
330         --          point on <me>.
331         --          
332         --          Transformed(T)->Value(U * ParametricTransformation(T))
333         --          
334         --          is the same point as
335         --          
336         --          Value(U).Transformed(T)
337         --          
338         --          This methods calls the basis curve method.
339      is redefined;  
340
341
342
343   Copy (me)  returns like me;
344         ---Purpose: Creates a new object, which is a copy of this offset curve.   
345
346   GetBasisCurveContinuity(me)
347     returns Shape from GeomAbs;
348         ---Purpose: Returns continuity of the basis curve.   
349     
350       
351 fields
352
353   basisCurve  : Curve from Geom2d;
354   offsetValue : Real;
355   myBasisCurveContinuity : Shape from GeomAbs;
356
357 end;