path: root/src/Geom/Geom_OffsetSurface.cdl

-- File:	Geom_OffsetSurface.cdl
-- Created:	Wed Mar 10 09:53:39 1993
-- Author:	JCV
--		<fid@phylox>
-- Copyright:	 Matra Datavision 1993
-- Modified: 18/11/96 : JPI : ajout methode Surface

class OffsetSurface from Geom inherits Surface from Geom

        ---Purpose : Describes an offset surface in 3D space.
    	-- An offset surface is defined by:
    	-- - the basis surface to which it is parallel, and
    	-- - the distance between the offset surface and its basis surface.
    	--   A point on the offset surface is built by measuring the
    	-- offset value along the normal vector at a point on the
    	-- basis surface. This normal vector is given by the cross
    	-- product D1u^D1v, where D1u and D1v are the
    	-- vectors tangential to the basis surface in the u and v
    	-- parametric directions at this point. The side of the
    	-- basis surface on which the offset is measured
    	-- depends on the sign of the offset value.
    	-- A Geom_OffsetSurface surface can be
    	-- self-intersecting, even if the basis surface does not
    	-- self-intersect. The self-intersecting portions are not
    	-- deleted at the time of construction.
    	-- Warning
    	-- There must be only one normal vector defined at any
    	-- point on the basis surface. This must be verified by the
    	-- user as no check is made at the time of construction
    	-- to detect points with multiple possible normal
    	-- directions (for example, the top of a conical surface).
       


uses Pnt              from gp, 
     Trsf             from gp,
     GTrsf2d          from gp,
     Vec              from gp,
     Curve            from Geom,
     Geometry         from Geom,
     BSplineSurface   from Geom,
     Shape            from GeomAbs, 
     Surface          from Geom,
     SequenceOfBSplineSurface  from Geom,
     OsculatingSurface from Geom 
     
--     Array1OfBoolean from TColStd
     
raises ConstructionError   from Standard, 
       RangeError          from Standard,
       NoSuchObject        from Standard,
       UndefinedDerivative from Geom, 
       UndefinedValue      from Geom


is



  Create (S : Surface from Geom; Offset : Real)   returns mutable OffsetSurface
        ---Purpose : Constructs a surface offset from the basis surface
    	-- S, where Offset is the distance between the offset
    	-- surface and the basis surface at any point.
    	-- A point on the offset surface is built by measuring
    	-- the offset value along a normal vector at a point on
    	-- S. This normal vector is given by the cross product
    	-- D1u^D1v, where D1u and D1v are the vectors
    	-- tangential to the basis surface in the u and v
    	-- parametric directions at this point. The side of S on
    	-- which the offset value is measured is indicated by
    	-- this normal vector if Offset is positive, or is the
    	-- inverse sense if Offset is negative.
        --  Warnings :
        -- - The offset surface is built with a copy of the
    	--   surface S. Therefore, when S is modified the
    	--   offset surface is not modified.
    	-- - No check is made at the time of construction to
    	--   detect points on S with multiple possible normal directions.
     raises ConstructionError;
        ---Purpose : Raised if S is not at least C1.
        --  Warnings :
        --  No check is done to verify that a unique normal direction is
        --  defined at any point of the basis surface S.



  SetBasisSurface (me : mutable; S : Surface from Geom)
     raises ConstructionError;
        ---Purpose : Raised if S is not at least C1.
        --  Warnings :
        --  No check is done to verify that a unique normal direction is
        --  defined at any point of the basis surface S.
    	-- Exceptions
    	-- Standard_ConstructionError if the surface S is not
    	-- at least "C1" continuous.

  SetOffsetValue (me : mutable; D : Real);
    	---Purpose: Changes this offset surface by assigning D as the offset value.

  Offset (me)   returns Real;

    	---Purpose: Returns the offset value of this offset surface.

  BasisSurface (me)  returns Surface from Geom;

    	--- Purpose: Returns the basis surface of this offset surface.
    	--  Note: The basis surface can be an offset surface.
        
  UReverse (me : mutable);
        ---Purpose : Changes the orientation of this offset surface in the u
    	-- parametric direction. The bounds of the surface
    	-- are not changed but the given parametric direction is reversed. 

  UReversedParameter (me; U : Real) returns Real;
	---Purpose: Computes the u  parameter on the modified
    	-- surface, produced by reversing the u 
    	-- parametric direction of this offset surface, for any
    	-- point of u parameter U  on this offset surface.
  
  
  VReverse (me : mutable);
        ---Purpose :  Changes the orientation of this offset surface in the v parametric direction. The bounds of the surface
    	-- are not changed but the given parametric direction is reversed.

  VReversedParameter (me; V : Real) returns Real;
	---Purpose: Computes the  v parameter on the modified
    	-- surface, produced by reversing the or v
    	-- parametric direction of this offset surface, for any
    	-- point of  v parameter V on this offset surface.
  
  
  Bounds (me; U1, U2, V1, V2 : out Real);
        ---Purpose : Returns the parametric bounds U1, U2, V1 and V2 of
    	-- this offset surface.
    	-- If the surface is infinite, this function can return:
    	-- - Standard_Real::RealFirst(), or
    	-- - Standard_Real::RealLast().

  Continuity (me)   returns Shape from GeomAbs;
        ---Purpose :
        --  This method returns the continuity of the basis surface - 1.
        --  Continuity of the Offset surface : 
        --  C0 : only geometric continuity,
        --  C1 : continuity of the first derivative all along the Surface,
        --  C2 : continuity of the second derivative all along the Surface,
        --  C3 : continuity of the third derivative all along the Surface,
        --  CN : the order of continuity is infinite.
        -- Example : 
        --  If the basis surface is C2 in the V direction and C3 in the U 
        --  direction Shape = C1.
        -- Warnings :
        --  If the basis surface has a unique normal direction defined at 
        --  any point this method gives the continuity of the offset 
        --  surface otherwise the effective continuity can be lower than
        --  the continuity of the basis surface - 1. 


  IsCNu(me; N : Integer)   returns Boolean
        ---Purpose :
        --  This method answer True if the continuity of the basis surface 
        --  is N + 1 in the U parametric direction. We suppose in this
        --  class that a unique normal is defined at any point on the basis
        --  surface.
     raises RangeError;
        ---Purpose : Raised if N <0.


  IsCNv (me; N : Integer)   returns Boolean
        ---Purpose :
        --  This method answer True if the continuity of the basis surface 
        --  is N + 1 in the V parametric direction. We suppose in this
        --  class that a unique normal is defined at any point on the basis
        --  surface.
     raises RangeError;
        ---Purpose : Raised if N <0.

  IsUClosed (me)     returns Boolean;
    	---Purpose: Checks whether this offset surface is closed in the u
    	--  parametric direction.
    	-- Returns true if, taking uFirst and uLast as
    	--   the parametric bounds in the u parametric direction,
    	--   the distance between the points P(uFirst,v)
    	--   and P(uLast,v) is less than or equal to
    	--   gp::Resolution() for each value of the   parameter v.
        
  IsVClosed (me)     returns Boolean;
    	---Purpose: Checks whether this offset surface is closed in the u
    	-- or v parametric direction. Returns true if taking vFirst and vLast as the
    	--   parametric bounds in the v parametric direction, the
    	--   distance between the points P(u,vFirst) and
    	--   P(u,vLast) is less than or equal to
    	--   gp::Resolution() for each value of the parameter u.
        
  IsUPeriodic (me)   returns Boolean;
    	---Purpose:
    	-- Returns true if this offset surface is periodic in the u
    	-- parametric direction, i.e. if the basis
    	-- surface of this offset surface is periodic in this direction.
    
  UPeriod (me)    returns Real from Standard
	---Purpose: Returns the period of this offset surface in the u 
        -- parametric direction respectively, i.e. the period of the
    	-- basis surface of this offset surface in this parametric direction.
  raises
    	NoSuchObject from Standard
	---Purpose: raises if the surface is not uperiodic.
  is redefined;

  IsVPeriodic (me)   returns Boolean;
    	---Purpose:
    	-- Returns true if this offset surface is periodic in the v
    	-- parametric direction, i.e. if the basis
    	-- surface of this offset surface is periodic in this direction.
    
  VPeriod (me)    returns Real from Standard
	---Purpose: Returns the period of this offset surface in the v 
        -- parametric direction respectively, i.e. the period of the
    	-- basis surface of this offset surface in this parametric direction.
  raises
    	NoSuchObject from Standard
	---Purpose: raises if the surface is not vperiodic.
  is redefined;

  UIso (me; U : Real)  returns mutable Curve;
        ---Purpose : Computes the U isoparametric curve.

  VIso (me; V : Real)  returns mutable Curve;
        ---Purpose : Computes the V isoparametric curve.




        ---Purpose : 
        --  Te followings methods compute value and derivatives.
        --  
        --- Warnings
        --  An exception is raised if a unique normal vector is 
        --  not defined on the basis surface for the parametric 
        --  value (U,V).
        --  No check is done at the creation time and we suppose
        --  in this package that the offset surface can be defined
        --  at any point.


  D0 (me; U, V : Real; P : out Pnt)
        ---Purpose :
        --  P (U, V) = Pbasis + Offset * Ndir   where
        --  Ndir = D1Ubasis ^ D1Vbasis / ||D1Ubasis ^ D1Vbasis|| is the 
        --  normal direction of the basis surface. Pbasis, D1Ubasis, 
        --  D1Vbasis are the point and the first derivatives on the basis
        --  surface.
        --  If Ndir is undefined this method computes an approched normal
        --  direction using the following limited development :
        --  Ndir = N0 + DNdir/DU + DNdir/DV + Eps with Eps->0 which
        --  requires to compute the second derivatives on the basis surface. 
        --  If the normal direction cannot be approximate for this order
        --  of derivation the exception UndefinedValue is raised.
     raises UndefinedValue;
        ---Purpose :
        --  Raised if the continuity of the basis surface is not C1.
        --  Raised if the order of derivation required to compute the 
        --  normal direction is greater than the second order.


  D1 (me; U, V : Real; P : out Pnt; D1U, D1V : out Vec)
     raises UndefinedDerivative;
        ---Purpose : 
        --  Raised if the continuity of the basis surface is not C2.


  D2 (me; U, V : Real; P : out Pnt; D1U, D1V, D2U, D2V, D2UV : out Vec)
     raises UndefinedDerivative;
        ---Purpose ;
        --  Raised if the continuity of the basis surface is not C3.


  D3 (me; U, V : Real;  P : out Pnt; 
      D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV : out Vec)
     raises UndefinedDerivative;
        ---Purpose :
        --  Raised if the continuity of the basis surface is not C4.


  DN (me; U, V : Real; Nu, Nv : Integer)   returns Vec
        ---Purpose :
        --  Computes the derivative of order Nu in the direction u and Nv
        --  in the direction v.
     raises UndefinedDerivative,
        ---Purpose ;
        --  Raised if the continuity of the basis surface is not CNu + 1
        --  in the U direction and CNv + 1 in the V direction.
            RangeError;
        ---Purpose : Raised if Nu + Nv < 1 or Nu < 0 or Nv < 0.





        ---Purpose  : 
        --  The following methods compute the value and derivatives
        --  on the offset surface and returns the derivatives on the
        --  basis surface too.  
        --  The computation of the value and derivatives on the basis
        --  surface are used to evaluate the offset surface.
        --  
        --  Warnings :
        --  The exception UndefinedValue or UndefinedDerivative is 
        --  raised if it is not possible to compute a unique offset
        --  direction.



  Value(me; U, V : Real; P, Pbasis : out Pnt; D1Ubasis, D1Vbasis : out Vec)
        ---Purpose :
        --  P (U, V) = Pbasis + Offset * Ndir   where
        --  Ndir = D1Ubasis ^ D1Vbasis / ||D1Ubasis ^ D1Vbasis|| is 
        --  the normal direction of the surface.
        --  If Ndir is undefined this method computes an approched normal
        --  direction using the following limited development :
        --  Ndir = N0 + DNdir/DU + DNdir/DV + Eps with Eps->0 which
        --  requires to compute the second derivatives on the basis surface.
        --  If the normal direction cannot be approximate for this order
        --  of derivation the exception UndefinedValue is raised.
     raises UndefinedValue;
        ---Purpose :
        --  Raised if the continuity of the basis surface is not C1.
        --  Raised if the order of derivation required to compute the normal
        --  direction is greater than the second order.


  D1 (me; U, V : Real; P, Pbasis : out Pnt; D1U, D1V, D1Ubasis, D1Vbasis,
      D2Ubasis, D2Vbasis, D2UVbasis : out Vec)
     raises UndefinedDerivative;
        ---Purpose :
        --  Raised if the continuity of the basis surface is not C2.


  D2 (me; U, V : Real; P, Pbasis : out Pnt; D1U, D1V, D2U, D2V, D2UV,
      D1Ubasis, D1Vbasis, D2Ubasis, D2Vbasis, D2UVbasis, D3Ubasis, D3Vbasis,
      D3UUVbasis, D3UVVbasis : out Vec)
     raises UndefinedDerivative;
        ---Purpose :
        --  Raised if the continuity of the basis surface is not C3.

 


	---Purpose :  The  following  private  methods 
	    	  --  includes common part of local  and  global methods
	    	  --  of  derivative  evaluations. 

  SetD0 (me; U, V : Real; P : out Pnt; D1U, D1V : Vec) 
	   	   raises UndefinedDerivative  
    	    	   is  private;
  SetD1 (me; U, V : Real; P : out Pnt; D1U, D1V : out Vec; 
    	  d2u,d2v,d2uv : Vec) 
    	    	   raises UndefinedDerivative  
    	    	   is  private;
  SetD2 (me; U, V : Real; P : out Pnt; 
    	     D1U, D1V, D2U, D2V, D2UV : out Vec; 
    	     d3u,d3v,d3uuv,d3uvv :  Vec )    
    	    	   raises UndefinedDerivative  
    	    	   is  private;
  SetD3 (me; U, V : Real;  P : out Pnt; 
 	     D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV : out Vec)   
    	    	   raises UndefinedDerivative  
    	    	   is  private; 
		    
  SetDN(me;  U, V : Real;  Nu,  Nv  :  Integer; 
             D1U, D1V  : Vec) 
	returns  Vec 
	is  private;

  	---Purpose : The following  functions  evaluates the  local 
    	-- derivatives on surface. Useful to manage discontinuities 
	-- on the surface.   
	--           if    Side  =  1  ->  P  =  S( U+,V ) 
        --           if    Side  = -1  ->  P  =  S( U-,V )   	 
    	--           else  P  is betveen discontinuities   
	--           can be evaluated using methods  of  
    	--           global evaluations    P  =  S( U ,V )      
   
  LocalD0 (me; U, V : Real; USide, VSide : Integer;
    	       P : out Pnt);

  LocalD1 (me; U, V : Real;  USide, VSide : Integer;
          P : out Pnt; D1U, D1V : out Vec);

  LocalD2 (me; U, V : Real; USide, VSide : Integer;
           P : out Pnt; D1U, D1V, D2U, D2V, D2UV : out Vec);

  LocalD3 (me; U, V : Real; USide, VSide : Integer;
           P : out Pnt; D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV :
           out Vec);

  LocalDN (me; U, V : Real; USide, VSide : Integer; 
           Nu, Nv : Integer)
     returns Vec;

   LocateSides(me ;  U,V  :  Real; USide,  VSide :  Integer ; 
    	    	BSplS  :  BSplineSurface  from  Geom;  
    	    	NDir  :  Integer  ;  P  :  out  Pnt ; 
    	        D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV :  out  Vec ) 
    	---Purpose: This  method locates U,V parameters on basis BSpline surface 
  	     -- and calls LocalDi or Di methods corresponding an order 
    	     -- of derivative and  position  
    	     -- of UV-point relatively the surface discontinuities.                    	   
    is  private  ;   	 
    
   Transform (me : mutable; T : Trsf);
        --- Purpose:
    	-- Applies the transformation T to this offset surface.
    	-- Note: the basis surface is also modified.

  TransformParameters(me; U,V : in out Real; T : Trsf from gp)
	---Purpose: Computes the  parameters on the  transformed  surface for
	--          the transform of the point of parameters U,V on <me>.
	--          
	--          me->Transformed(T)->Value(U',V')
	--          
	--          is the same point as
	--          
	--          me->Value(U,V).Transformed(T)
	--          
	--          Where U',V' are the new values of U,V after calling
	--          
	--          me->TranformParameters(U,V,T)               
	--          This methods calls the basis surface method.
     is redefined;  

  ParametricTransformation(me; T : Trsf from gp) returns GTrsf2d from gp
	---Purpose: Returns a 2d transformation  used to find the  new
	--          parameters of a point on the transformed surface.
	--          
	--          me->Transformed(T)->Value(U',V')
	--          
	--          is the same point as
	--          
	--          me->Value(U,V).Transformed(T)
	--          
	--          Where U',V' are  obtained by transforming U,V with
	--          th 2d transformation returned by
	--          
	--          me->ParametricTransformation(T)
	--          
	--          This methods calls the basis surface method.
     is redefined;  

  Copy (me)  returns mutable like me;
    	---Purpose: Creates a new object which is a copy of this offset surface.  
    
  Surface (me) returns mutable Surface from Geom;
      	---Purpose: returns an  equivalent surface of the offset surface
      	--          when  the basis surface   is a canonic  surface or a
      	--          rectangular  limited surface on canonic surface or if
      	--          the offset is null.

  UOsculatingSurface (me ; U,V : Real ; IsOpposite : out Boolean from Standard 
                                      ; UOsculSurf : out BSplineSurface from Geom)  
      	---Purpose: if Standard_True, L is  the local osculating surface
      	--          along U at  the point U,V.   It means that  DL/DU is
      	--          collinear to DS/DU .  If IsOpposite == Standard_True
      	--          these vectors have opposite direction.
      	--          
      returns Boolean from Standard;
      
  VOsculatingSurface (me ; U,V : Real ; IsOpposite : out Boolean from Standard 
                                      ; VOsculSurf : out BSplineSurface from Geom)  
        ---Purpose: if Standard_True, L is the local osculating surface  
        --          along V at the point U,V.
        --          It means that  DL/DV is
      	--          collinear to DS/DV .  If IsOpposite == Standard_True
      	--          these vectors have opposite direction.
     returns Boolean from Standard;

  
fields

  basisSurf   : Surface from Geom;
  equivSurf   : Surface from Geom;
  offsetValue : Real;
  myOscSurf   : OsculatingSurface from Geom;
end;