0024062: A mistake in Geom_OffsetCurve.cdl about direction of offset
[occt.git] / src / Geom / Geom_OffsetCurve.cdl
CommitLineData
b311480e 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
7fd59977 21
22
23class 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.
9733d9b3 35 -- The Offset curve is in the direction of the normal N
36 -- defined with the cross product T^V, where the vector T
7fd59977 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
9733d9b3 42 -- . distance offset <0 => the curve is in the direction of - N
7fd59977 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
70uses 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
79raises ConstructionError from Standard,
80 RangeError from Standard,
81 NoSuchObject from Standard,
82 UndefinedDerivative from Geom,
83 UndefinedValue from Geom
84
85
86
87
88is
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
357fields
358
359 basisCurve : Curve from Geom;
360 direction : Dir;
361 offsetValue : Real;
362
363end;