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