0025124: [Feature request] Removal of continuity checks for offset geometries
[occt.git] / src / Geom / Geom_OffsetSurface.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 -- Modified: 18/11/96 : JPI : ajout methode Surface
18
19 class OffsetSurface from Geom inherits Surface from Geom
20
21         ---Purpose : Describes an offset surface in 3D space.
22         -- An offset surface is defined by:
23         -- - the basis surface to which it is parallel, and
24         -- - the distance between the offset surface and its basis surface.
25         --   A point on the offset surface is built by measuring the
26         -- offset value along the normal vector at a point on the
27         -- basis surface. This normal vector is given by the cross
28         -- product D1u^D1v, where D1u and D1v are the
29         -- vectors tangential to the basis surface in the u and v
30         -- parametric directions at this point. The side of the
31         -- basis surface on which the offset is measured
32         -- depends on the sign of the offset value.
33         -- A Geom_OffsetSurface surface can be
34         -- self-intersecting, even if the basis surface does not
35         -- self-intersect. The self-intersecting portions are not
36         -- deleted at the time of construction.
37         -- Warning
38         -- There must be only one normal vector defined at any
39         -- point on the basis surface. This must be verified by the
40         -- user as no check is made at the time of construction
41         -- to detect points with multiple possible normal
42         -- directions (for example, the top of a conical surface).
43        
44
45
46 uses Pnt              from gp, 
47      Trsf             from gp,
48      GTrsf2d          from gp,
49      Vec              from gp,
50      Curve            from Geom,
51      Geometry         from Geom,
52      BSplineSurface   from Geom,
53      Shape            from GeomAbs, 
54      Surface          from Geom,
55      SequenceOfBSplineSurface  from Geom,
56      OsculatingSurface from Geom 
57      
58 --     Array1OfBoolean from TColStd
59      
60 raises ConstructionError   from Standard, 
61        RangeError          from Standard,
62        NoSuchObject        from Standard,
63        UndefinedDerivative from Geom, 
64        UndefinedValue      from Geom
65
66
67 is
68
69
70
71   Create (S : Surface from Geom;
72           Offset : Real;
73           isNotCheckC0 : Boolean = Standard_False)
74     returns OffsetSurface
75         ---Purpose : Constructs a surface offset from the basis surface
76         -- S, where Offset is the distance between the offset
77         -- surface and the basis surface at any point.
78         -- A point on the offset surface is built by measuring
79         -- the offset value along a normal vector at a point on
80         -- S. This normal vector is given by the cross product
81         -- D1u^D1v, where D1u and D1v are the vectors
82         -- tangential to the basis surface in the u and v
83         -- parametric directions at this point. The side of S on
84         -- which the offset value is measured is indicated by
85         -- this normal vector if Offset is positive, or is the
86         -- inverse sense if Offset is negative.
87       -- If isNotCheckC0 = TRUE checking if basis surface has C0-continuity
88       -- is not made.
89         --  Warnings :
90         -- - The offset surface is built with a copy of the
91         --   surface S. Therefore, when S is modified the
92         --   offset surface is not modified.
93         -- - No check is made at the time of construction to
94         --   detect points on S with multiple possible normal directions.
95      raises ConstructionError;
96         ---Purpose : Raised if S is not at least C1.
97         --  Warnings :
98         --  No check is done to verify that a unique normal direction is
99         --  defined at any point of the basis surface S.
100
101
102
103   SetBasisSurface ( me : mutable;
104                     S : Surface from Geom;
105                     isNotCheckC0 : Boolean = Standard_False)
106      raises ConstructionError;
107         ---Purpose : Raised if S is not at least C1.
108         --  Warnings :
109         --  No check is done to verify that a unique normal direction is
110         --  defined at any point of the basis surface S.
111         --  If isNotCheckC0 = TRUE checking if basis surface has C0-continuity
112         --  is not made.
113         -- Exceptions
114         -- Standard_ConstructionError if the surface S is not
115         -- at least "C1" continuous.
116
117   SetOffsetValue (me : mutable; D : Real);
118         ---Purpose: Changes this offset surface by assigning D as the offset value.
119
120   Offset (me)   returns Real;
121
122         ---Purpose: Returns the offset value of this offset surface.
123
124   BasisSurface (me)  returns Surface from Geom;
125
126         --- Purpose: Returns the basis surface of this offset surface.
127         --  Note: The basis surface can be an offset surface.
128         
129   UReverse (me : mutable);
130         ---Purpose : Changes the orientation of this offset surface in the u
131         -- parametric direction. The bounds of the surface
132         -- are not changed but the given parametric direction is reversed. 
133
134   UReversedParameter (me; U : Real) returns Real;
135         ---Purpose: Computes the u  parameter on the modified
136         -- surface, produced by reversing the u 
137         -- parametric direction of this offset surface, for any
138         -- point of u parameter U  on this offset surface.
139   
140   
141   VReverse (me : mutable);
142         ---Purpose :  Changes the orientation of this offset surface in the v parametric direction. The bounds of the surface
143         -- are not changed but the given parametric direction is reversed.
144
145   VReversedParameter (me; V : Real) returns Real;
146         ---Purpose: Computes the  v parameter on the modified
147         -- surface, produced by reversing the or v
148         -- parametric direction of this offset surface, for any
149         -- point of  v parameter V on this offset surface.
150   
151   
152   Bounds (me; U1, U2, V1, V2 : out Real);
153         ---Purpose : Returns the parametric bounds U1, U2, V1 and V2 of
154         -- this offset surface.
155         -- If the surface is infinite, this function can return:
156         -- - Standard_Real::RealFirst(), or
157         -- - Standard_Real::RealLast().
158
159   Continuity (me)   returns Shape from GeomAbs;
160         ---Purpose :
161         --  This method returns the continuity of the basis surface - 1.
162         --  Continuity of the Offset surface : 
163         --  C0 : only geometric continuity,
164         --  C1 : continuity of the first derivative all along the Surface,
165         --  C2 : continuity of the second derivative all along the Surface,
166         --  C3 : continuity of the third derivative all along the Surface,
167         --  CN : the order of continuity is infinite.
168         -- Example : 
169         --  If the basis surface is C2 in the V direction and C3 in the U 
170         --  direction Shape = C1.
171         -- Warnings :
172         --  If the basis surface has a unique normal direction defined at 
173         --  any point this method gives the continuity of the offset 
174         --  surface otherwise the effective continuity can be lower than
175         --  the continuity of the basis surface - 1. 
176
177
178   IsCNu(me; N : Integer)   returns Boolean
179         ---Purpose :
180         --  This method answer True if the continuity of the basis surface 
181         --  is N + 1 in the U parametric direction. We suppose in this
182         --  class that a unique normal is defined at any point on the basis
183         --  surface.
184      raises RangeError;
185         ---Purpose : Raised if N <0.
186
187
188   IsCNv (me; N : Integer)   returns Boolean
189         ---Purpose :
190         --  This method answer True if the continuity of the basis surface 
191         --  is N + 1 in the V parametric direction. We suppose in this
192         --  class that a unique normal is defined at any point on the basis
193         --  surface.
194      raises RangeError;
195         ---Purpose : Raised if N <0.
196
197   IsUClosed (me)     returns Boolean;
198         ---Purpose: Checks whether this offset surface is closed in the u
199         --  parametric direction.
200         -- Returns true if, taking uFirst and uLast as
201         --   the parametric bounds in the u parametric direction,
202         --   the distance between the points P(uFirst,v)
203         --   and P(uLast,v) is less than or equal to
204         --   gp::Resolution() for each value of the   parameter v.
205         
206   IsVClosed (me)     returns Boolean;
207         ---Purpose: Checks whether this offset surface is closed in the u
208         -- or v parametric direction. Returns true if taking vFirst and vLast as the
209         --   parametric bounds in the v parametric direction, the
210         --   distance between the points P(u,vFirst) and
211         --   P(u,vLast) is less than or equal to
212         --   gp::Resolution() for each value of the parameter u.
213         
214   IsUPeriodic (me)   returns Boolean;
215         ---Purpose:
216         -- Returns true if this offset surface is periodic in the u
217         -- parametric direction, i.e. if the basis
218         -- surface of this offset surface is periodic in this direction.
219     
220   UPeriod (me)    returns Real from Standard
221         ---Purpose: Returns the period of this offset surface in the u 
222         -- parametric direction respectively, i.e. the period of the
223         -- basis surface of this offset surface in this parametric direction.
224   raises
225         NoSuchObject from Standard
226         ---Purpose: raises if the surface is not uperiodic.
227   is redefined;
228
229   IsVPeriodic (me)   returns Boolean;
230         ---Purpose:
231         -- Returns true if this offset surface is periodic in the v
232         -- parametric direction, i.e. if the basis
233         -- surface of this offset surface is periodic in this direction.
234     
235   VPeriod (me)    returns Real from Standard
236         ---Purpose: Returns the period of this offset surface in the v 
237         -- parametric direction respectively, i.e. the period of the
238         -- basis surface of this offset surface in this parametric direction.
239   raises
240         NoSuchObject from Standard
241         ---Purpose: raises if the surface is not vperiodic.
242   is redefined;
243
244   UIso (me; U : Real)  returns Curve;
245         ---Purpose : Computes the U isoparametric curve.
246
247   VIso (me; V : Real)  returns Curve;
248         ---Purpose : Computes the V isoparametric curve.
249
250
251
252
253         ---Purpose : 
254         --  Te followings methods compute value and derivatives.
255         --  
256         --- Warnings
257         --  An exception is raised if a unique normal vector is 
258         --  not defined on the basis surface for the parametric 
259         --  value (U,V).
260         --  No check is done at the creation time and we suppose
261         --  in this package that the offset surface can be defined
262         --  at any point.
263
264
265   D0 (me; U, V : Real; P : out Pnt)
266         ---Purpose :
267         --  P (U, V) = Pbasis + Offset * Ndir   where
268         --  Ndir = D1Ubasis ^ D1Vbasis / ||D1Ubasis ^ D1Vbasis|| is the 
269         --  normal direction of the basis surface. Pbasis, D1Ubasis, 
270         --  D1Vbasis are the point and the first derivatives on the basis
271         --  surface.
272         --  If Ndir is undefined this method computes an approched normal
273         --  direction using the following limited development :
274         --  Ndir = N0 + DNdir/DU + DNdir/DV + Eps with Eps->0 which
275         --  requires to compute the second derivatives on the basis surface. 
276         --  If the normal direction cannot be approximate for this order
277         --  of derivation the exception UndefinedValue is raised.
278      raises UndefinedValue;
279         ---Purpose :
280         --  Raised if the continuity of the basis surface is not C1.
281         --  Raised if the order of derivation required to compute the 
282         --  normal direction is greater than the second order.
283
284
285   D1 (me; U, V : Real; P : out Pnt; D1U, D1V : out Vec)
286      raises UndefinedDerivative;
287         ---Purpose : 
288         --  Raised if the continuity of the basis surface is not C2.
289
290
291   D2 (me; U, V : Real; P : out Pnt; D1U, D1V, D2U, D2V, D2UV : out Vec)
292      raises UndefinedDerivative;
293         ---Purpose ;
294         --  Raised if the continuity of the basis surface is not C3.
295
296
297   D3 (me; U, V : Real;  P : out Pnt; 
298       D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV : out Vec)
299      raises UndefinedDerivative;
300         ---Purpose :
301         --  Raised if the continuity of the basis surface is not C4.
302
303
304   DN (me; U, V : Real; Nu, Nv : Integer)   returns Vec
305         ---Purpose :
306         --  Computes the derivative of order Nu in the direction u and Nv
307         --  in the direction v.
308      raises UndefinedDerivative,
309         ---Purpose ;
310         --  Raised if the continuity of the basis surface is not CNu + 1
311         --  in the U direction and CNv + 1 in the V direction.
312             RangeError;
313         ---Purpose : Raised if Nu + Nv < 1 or Nu < 0 or Nv < 0.
314
315
316
317
318
319         ---Purpose  : 
320         --  The following methods compute the value and derivatives
321         --  on the offset surface and returns the derivatives on the
322         --  basis surface too.  
323         --  The computation of the value and derivatives on the basis
324         --  surface are used to evaluate the offset surface.
325         --  
326         --  Warnings :
327         --  The exception UndefinedValue or UndefinedDerivative is 
328         --  raised if it is not possible to compute a unique offset
329         --  direction.
330
331
332
333   Value(me; U, V : Real; P, Pbasis : out Pnt; D1Ubasis, D1Vbasis : out Vec)
334         ---Purpose :
335         --  P (U, V) = Pbasis + Offset * Ndir   where
336         --  Ndir = D1Ubasis ^ D1Vbasis / ||D1Ubasis ^ D1Vbasis|| is 
337         --  the normal direction of the surface.
338         --  If Ndir is undefined this method computes an approched normal
339         --  direction using the following limited development :
340         --  Ndir = N0 + DNdir/DU + DNdir/DV + Eps with Eps->0 which
341         --  requires to compute the second derivatives on the basis surface.
342         --  If the normal direction cannot be approximate for this order
343         --  of derivation the exception UndefinedValue is raised.
344      raises UndefinedValue;
345         ---Purpose :
346         --  Raised if the continuity of the basis surface is not C1.
347         --  Raised if the order of derivation required to compute the normal
348         --  direction is greater than the second order.
349
350
351   D1 (me; U, V : Real; P, Pbasis : out Pnt; D1U, D1V, D1Ubasis, D1Vbasis,
352       D2Ubasis, D2Vbasis, D2UVbasis : out Vec)
353      raises UndefinedDerivative;
354         ---Purpose :
355         --  Raised if the continuity of the basis surface is not C2.
356
357
358   D2 (me; U, V : Real; P, Pbasis : out Pnt; D1U, D1V, D2U, D2V, D2UV,
359       D1Ubasis, D1Vbasis, D2Ubasis, D2Vbasis, D2UVbasis, D3Ubasis, D3Vbasis,
360       D3UUVbasis, D3UVVbasis : out Vec)
361      raises UndefinedDerivative;
362         ---Purpose :
363         --  Raised if the continuity of the basis surface is not C3.
364
365  
366
367
368         ---Purpose :  The  following  private  methods 
369                   --  includes common part of local  and  global methods
370                   --  of  derivative  evaluations. 
371
372   SetD0 (me; U, V : Real; P : out Pnt; D1U, D1V : Vec) 
373                    raises UndefinedDerivative  
374                    is  private;
375   SetD1 (me; U, V : Real; P : out Pnt; D1U, D1V : out Vec; 
376           d2u,d2v,d2uv : Vec) 
377                    raises UndefinedDerivative  
378                    is  private;
379   SetD2 (me; U, V : Real; P : out Pnt; 
380              D1U, D1V, D2U, D2V, D2UV : out Vec; 
381              d3u,d3v,d3uuv,d3uvv :  Vec )    
382                    raises UndefinedDerivative  
383                    is  private;
384   SetD3 (me; U, V : Real;  P : out Pnt; 
385              D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV : out Vec)   
386                    raises UndefinedDerivative  
387                    is  private; 
388                     
389   SetDN(me;  U, V : Real;  Nu,  Nv  :  Integer; 
390              D1U, D1V  : Vec) 
391         returns  Vec 
392         is  private;
393
394         ---Purpose : The following  functions  evaluates the  local 
395         -- derivatives on surface. Useful to manage discontinuities 
396         -- on the surface.   
397         --           if    Side  =  1  ->  P  =  S( U+,V ) 
398         --           if    Side  = -1  ->  P  =  S( U-,V )       
399         --           else  P  is betveen discontinuities   
400         --           can be evaluated using methods  of  
401         --           global evaluations    P  =  S( U ,V )      
402    
403   LocalD0 (me; U, V : Real; USide, VSide : Integer;
404                P : out Pnt);
405
406   LocalD1 (me; U, V : Real;  USide, VSide : Integer;
407           P : out Pnt; D1U, D1V : out Vec);
408
409   LocalD2 (me; U, V : Real; USide, VSide : Integer;
410            P : out Pnt; D1U, D1V, D2U, D2V, D2UV : out Vec);
411
412   LocalD3 (me; U, V : Real; USide, VSide : Integer;
413            P : out Pnt; D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV :
414            out Vec);
415
416   LocalDN (me; U, V : Real; USide, VSide : Integer; 
417            Nu, Nv : Integer)
418      returns Vec;
419
420    LocateSides(me ;  U,V  :  Real; USide,  VSide :  Integer ; 
421                 BSplS  :  BSplineSurface  from  Geom;  
422                 NDir  :  Integer  ;  P  :  out  Pnt ; 
423                 D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV :  out  Vec ) 
424         ---Purpose: This  method locates U,V parameters on basis BSpline surface 
425              -- and calls LocalDi or Di methods corresponding an order 
426              -- of derivative and  position  
427              -- of UV-point relatively the surface discontinuities.                        
428     is  private  ;       
429     
430    Transform (me : mutable; T : Trsf);
431         --- Purpose:
432         -- Applies the transformation T to this offset surface.
433         -- Note: the basis surface is also modified.
434
435   TransformParameters(me; U,V : in out Real; T : Trsf from gp)
436         ---Purpose: Computes the  parameters on the  transformed  surface for
437         --          the transform of the point of parameters U,V on <me>.
438         --          
439         --          me->Transformed(T)->Value(U',V')
440         --          
441         --          is the same point as
442         --          
443         --          me->Value(U,V).Transformed(T)
444         --          
445         --          Where U',V' are the new values of U,V after calling
446         --          
447         --          me->TranformParameters(U,V,T)               
448         --          This methods calls the basis surface method.
449      is redefined;  
450
451   ParametricTransformation(me; T : Trsf from gp) returns GTrsf2d from gp
452         ---Purpose: Returns a 2d transformation  used to find the  new
453         --          parameters of a point on the transformed surface.
454         --          
455         --          me->Transformed(T)->Value(U',V')
456         --          
457         --          is the same point as
458         --          
459         --          me->Value(U,V).Transformed(T)
460         --          
461         --          Where U',V' are  obtained by transforming U,V with
462         --          th 2d transformation returned by
463         --          
464         --          me->ParametricTransformation(T)
465         --          
466         --          This methods calls the basis surface method.
467      is redefined;  
468
469   Copy (me)  returns like me;
470         ---Purpose: Creates a new object which is a copy of this offset surface.  
471     
472   Surface (me) returns Surface from Geom;
473         ---Purpose: returns an  equivalent surface of the offset surface
474         --          when  the basis surface   is a canonic  surface or a
475         --          rectangular  limited surface on canonic surface or if
476         --          the offset is null.
477
478   UOsculatingSurface (me ; U,V : Real ; IsOpposite : out Boolean from Standard 
479                                       ; UOsculSurf : out BSplineSurface from Geom)  
480         ---Purpose: if Standard_True, L is  the local osculating surface
481         --          along U at  the point U,V.   It means that  DL/DU is
482         --          collinear to DS/DU .  If IsOpposite == Standard_True
483         --          these vectors have opposite direction.
484         --          
485       returns Boolean from Standard;
486       
487   VOsculatingSurface (me ; U,V : Real ; IsOpposite : out Boolean from Standard 
488                                       ; VOsculSurf : out BSplineSurface from Geom)  
489         ---Purpose: if Standard_True, L is the local osculating surface  
490         --          along V at the point U,V.
491         --          It means that  DL/DV is
492         --          collinear to DS/DV .  If IsOpposite == Standard_True
493         --          these vectors have opposite direction.
494      returns Boolean from Standard;
495
496   GetBasisSurfContinuity(me)
497     returns Shape from GeomAbs;
498         ---Purpose: Returns continuity of the basis surface.   
499
500 fields
501
502   basisSurf   : Surface from Geom;
503   equivSurf   : Surface from Geom;
504   offsetValue : Real;
505   myOscSurf   : OsculatingSurface from Geom;
506   myBasisSurfContinuity : Shape from GeomAbs;
507 end;