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