0024411: SplitShape produces shape with incorrectly parameterized periodic 3D curve
[occt.git] / src / Geom / Geom_TrimmedCurve.cdl
1 -- Created on: 1993-03-10
2 -- Created by: JCV
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 TrimmedCurve from Geom inherits BoundedCurve from Geom
18
19
20         ---Purpose : Describes a portion of a curve (termed the "basis
21         -- curve") limited by two parameter values inside the
22         -- parametric domain of the basis curve.
23         -- The trimmed curve is defined by:
24         -- - the basis curve, and
25         -- - the two parameter values which limit it.
26         -- The trimmed curve can either have the same
27         -- orientation as the basis curve or the opposite orientation.
28
29 uses Ax1      from gp,
30      Ax2      from gp,
31      Pnt      from gp, 
32      Trsf     from gp,
33      Vec      from gp,
34      Curve    from Geom,
35      Geometry from Geom,
36      Shape    from GeomAbs
37
38
39 raises ConstructionError   from Standard,
40        RangeError          from Standard,
41        NoSuchObject        from Standard,
42        UndefinedDerivative from Geom,
43        UndefinedValue      from Geom
44
45
46 is
47
48
49   Create (C : Curve; U1, U2 : Real; Sense : Boolean = Standard_True;
50           theAdjustPeriodic : Boolean = Standard_True)
51      returns TrimmedCurve
52         ---Purpose : Constructs a trimmed curve from the basis curve C
53         -- which is limited between parameter values U1 and U2.
54         -- Note: - U1 can be greater or less than U2; in both cases,
55         --   the returned curve is oriented from U1 to U2.
56         -- - If the basis curve C is periodic, there is an
57         --   ambiguity because two parts are available. In this
58         --   case, the trimmed curve has the same orientation
59         --   as the basis curve if Sense is true (default value)
60         --   or the opposite orientation if Sense is false.
61         -- - If the curve is closed but not periodic, it is not
62         --   possible to keep the part of the curve which
63         --   includes the junction point (except if the junction
64         --   point is at the beginning or at the end of the
65         --   trimmed curve). If you tried to do this, you could
66         --   alter the fundamental characteristics of the basis
67         --   curve, which are used, for example, to compute
68         --   the derivatives of the trimmed curve. The rules
69         --   for a closed curve are therefore the same as
70         --   those for an open curve.
71         -- Warning: The trimmed curve is built from a copy of curve C.
72         --   Therefore, when C is modified, the trimmed curve
73         --   is not modified.
74         -- - If the basis curve is periodic and theAdjustPeriodic is True, 
75         --   the bounds of the trimmed curve may be different from U1 and U2
76         --   if the parametric origin of the basis curve is within
77         --   the arc of the trimmed curve. In this case, the
78         --   modified parameter will be equal to U1 or U2
79         --   plus or minus the period.
80         --   When theAdjustPeriodic is False, parameters U1 and U2 will be 
81         --   the same, without adjustment into the first period.
82         --   Exceptions
83         -- Standard_ConstructionError if:
84         -- - C is not periodic and U1 or U2 is outside the
85         --   bounds of C, or
86         -- - U1 is equal to U2.
87      raises ConstructionError;
88     
89
90
91
92   Reverse (me : mutable);
93         ---Purpose : Changes the orientation of this trimmed curve.
94         -- As a result:
95         -- - the basis curve is reversed,
96         -- - the start point of the initial curve becomes the
97         --   end point of the reversed curve,
98         -- - the end point of the initial curve becomes the
99         --   start point of the reversed curve,
100         -- - the first and last parameters are recomputed.
101         --   If the trimmed curve was defined by:
102         -- - a basis curve whose parameter range is [ 0., 1. ],
103         -- - the two trim values U1 (first parameter) and U2 (last parameter),
104         --   the reversed trimmed curve is defined by:
105         -- - the reversed basis curve, whose parameter range is still [ 0., 1. ],
106         -- - the two trim values 1. - U2 (first parameter) and 1. - U1 (last parameter).
107      
108
109
110   ReversedParameter(me; U : Real) returns Real;
111         ---Purpose: Computes the parameter on the reversed curve for
112         -- the point of parameter U on this trimmed curve.
113
114
115   SetTrim (me : mutable; U1, U2 : Real; Sense : Boolean = Standard_True;
116            theAdjustPeriodic : Boolean = Standard_True)
117         ---Purpose :  Changes this trimmed curve, by redefining the
118         -- parameter values U1 and U2 which limit its basis curve.
119         -- Note: If the basis curve is periodic, the trimmed curve
120         -- has the same orientation as the basis curve if Sense
121         -- is true (default value) or the opposite orientation if Sense is false.
122         -- Warning
123         -- If the basis curve is periodic and theAdjustPeriodic is True, 
124         -- the bounds of the trimmed curve may be different from U1 and U2 if the
125         -- parametric origin of the basis curve is within the arc of
126         -- the trimmed curve. In this case, the modified
127         -- parameter will be equal to U1 or U2 plus or minus the period.
128         -- When theAdjustPeriodic is False, parameters U1 and U2 will be 
129         -- the same, without adjustment into the first period.
130         -- Exceptions
131         -- Standard_ConstructionError if:
132         -- - the basis curve is not periodic, and either U1 or U2
133         --   are outside the bounds of the basis curve, or
134         -- - U1 is equal to U2.
135      raises ConstructionError;
136       
137
138
139   BasisCurve (me)    returns Curve;
140         ---Purpose : Returns the basis curve. 
141         --   Warning
142         -- This function does not return a constant reference.
143         -- Consequently, any modification of the returned value
144         -- directly modifies the trimmed curve.
145
146
147   Continuity (me)  returns Shape from GeomAbs;
148         ---Purpose :
149         --  Returns the continuity of the curve :
150         -- C0 : only geometric continuity,
151         -- C1 : continuity of the first derivative all along the Curve,
152         -- C2 : continuity of the second derivative all along the Curve,
153         -- C3 : continuity of the third derivative all along the Curve,
154         -- CN : the order of continuity is infinite.
155
156
157   IsCN (me; N : Integer)   returns Boolean
158         ---Purpose : Returns true if the degree of continuity of the basis
159         -- curve of this trimmed curve is at least N. A trimmed
160         -- curve is at least "C0" continuous.
161         --  Warnings :
162         --  The continuity of the trimmed curve can be greater than
163         --  the continuity of the basis curve because you consider
164         --  only a part of the basis curve.
165      raises RangeError;
166         ---Purpose : Raised if N < 0.
167
168
169   EndPoint (me)   returns Pnt;
170         ---Purpose :
171         --  Returns the end point of <me>. This point is the
172         --  evaluation of the curve for the "LastParameter".
173
174
175   FirstParameter (me)   returns Real;
176         ---Purpose :
177         --  Returns the value of the first parameter of <me>. 
178         --  The first parameter is the parameter of the "StartPoint"
179         --  of the trimmed curve.
180
181
182   IsClosed (me)  returns Boolean;
183         ---Purpose :
184         --  Returns True if the distance between the StartPoint and
185         --  the EndPoint is lower or equal to Resolution from package gp.
186
187
188   IsPeriodic (me)   returns Boolean;
189         ---Purpose : Returns true if the basis curve of this trimmed curve is periodic.
190
191
192   Period (me) returns Real from Standard 
193         ---Purpose: Returns the period of the basis curve of this trimmed curve.
194         -- Exceptions
195         -- Standard_NoSuchObject if the basis curve is not periodic.
196   raises
197         NoSuchObject from Standard
198   is redefined;
199
200
201   LastParameter (me)  returns Real;
202         ---Purpose :
203         --  Returns the value of the last parameter of <me>.
204         --  The last parameter is the parameter of the "EndPoint" of the
205         --  trimmed curve.
206
207
208   StartPoint (me)  returns Pnt;
209         ---Purpose :
210         --  Returns the start point of <me>.
211         --  This point is the evaluation of the curve from the 
212         --  "FirstParameter".
213
214
215
216
217
218
219         ---Purpose  : value and derivatives
220         --- Warnings :
221         --  The returned derivatives have the same orientation as the
222         --  derivatives of the basis curve even if the trimmed curve 
223         --  has not the same orientation as the basis curve.
224
225
226   D0(me; U : Real; P : out Pnt);
227         ---Purpose: Returns in P the point of parameter U.
228         --          
229         --  If the basis curve is an OffsetCurve sometimes it is not 
230         --  possible to do the evaluation of the curve at the parameter
231         --  U (see class OffsetCurve).
232
233
234   D1 (me; U : Real; P : out Pnt; V1 : out Vec)
235      raises UndefinedDerivative;
236         ---Purpose : Raised if the continuity of the curve is not C1.
237
238
239   D2 (me; U : Real; P : out Pnt; V1, V2 : out Vec)
240      raises UndefinedDerivative;
241         ---Purpose : Raised if the continuity of the curve is not C2.
242
243
244   D3 (me; U : Real; P : out Pnt; V1, V2, V3 : out Vec)
245      raises UndefinedDerivative;
246         ---Purpose : Raised if the continuity of the curve is not C3.
247         
248
249   DN (me; U : Real; N : Integer)  returns Vec
250         ---Purpose  : N is the order of derivation.
251      raises  UndefinedDerivative,
252         ---Purpose : Raised if the continuity of the curve is not CN.
253              RangeError;
254         ---Purpose : Raised if N < 1.            
255
256
257
258
259
260         ---Purpose : geometric transformations
261
262   Transform (me : mutable; T : Trsf);
263         --- Purpose: Applies the transformation T to this trimmed curve.
264         -- Warning The basis curve is also modified.
265
266   TransformedParameter(me; U : Real; T : Trsf from gp) returns Real
267         ---Purpose: Returns the  parameter on the  transformed  curve for
268         --          the transform of the point of parameter U on <me>.
269         --          
270         --          me->Transformed(T)->Value(me->TransformedParameter(U,T))
271         --          
272         --          is the same point as
273         --          
274         --          me->Value(U).Transformed(T)
275         --          
276         --          This methods calls the basis curve method.
277      is redefined;  
278
279   ParametricTransformation(me; T : Trsf from gp) returns Real
280         ---Purpose: Returns a  coefficient to compute the parameter on
281         --          the transformed  curve  for  the transform  of the
282         --          point on <me>.
283         --          
284         --          Transformed(T)->Value(U * ParametricTransformation(T))
285         --          
286         --          is the same point as
287         --          
288         --          Value(U).Transformed(T)
289         --          
290         --          This methods calls the basis curve method.
291      is redefined;  
292
293   Copy (me)  returns like me;
294         ---Purpose: Creates a new object which is a copy of this trimmed curve.
295     
296 fields
297
298     basisCurve : Curve;
299     uTrim1     : Real;
300     uTrim2     : Real;
301
302 end;
303
304
305
306
307