path: root/src/Geom/Geom_ToroidalSurface.cdl

-- File:	Geom_ToroidalSurface.cdl
-- Created:	Wed Mar 10 10:56:00 1993
-- Author:	JCV
--		<fid@phylox>
-- Copyright:	 Matra Datavision 1993


class ToroidalSurface from Geom inherits ElementarySurface from Geom


        ---Purpose :  Describes a torus.
    	-- A torus is defined by its major and minor radii, and
    	-- positioned in space with a coordinate system (a
    	-- gp_Ax3 object) as follows:
    	-- - The origin is the center of the torus.
    	-- - The surface is obtained by rotating a circle around
    	--   the "main Direction". This circle has a radius equal
    	--   to the minor radius, and is located in the plane
    	--   defined by the origin, "X Direction" and "main
    	--   Direction". It is centered on the "X Axis", on its
    	--   positive side, and positioned at a distance from the
    	--   origin equal to the major radius. This circle is the
    	--   "reference circle" of the torus.
    	-- - The plane defined by the origin, the "X Direction"
    	--   and the "Y Direction" is called the "reference plane" of the torus.
    	--   This coordinate system is the "local coordinate
    	-- system" of the torus. The following apply:
    	-- - Rotation around its "main Axis", in the trigonometric
    	--   sense given by "X Direction" and "Y Direction",
    	--   defines the u parametric direction.
    	-- - The "X Axis" gives the origin for the u parameter.
    	-- - Rotation around an axis parallel to the "Y Axis" and
    	--   passing through the center of the "reference circle"
    	--   gives the v parameter on the "reference circle".
    	-- - The "X Axis" gives the origin of the v parameter on
    	--   the "reference circle".
    	-- - The v parametric direction is oriented by the
    	--   inverse of the "main Direction", i.e. near 0, as v
    	--   increases, the Z coordinate decreases. (This
    	--   implies that the "Y Direction" orients the reference
    	--   circle only when the local coordinate system is direct.)
    	-- - The u isoparametric curve is a circle obtained by
    	--   rotating the "reference circle" of the torus through
    	--   an angle u about the "main Axis".
    	--   The parametric equation of the torus is :
    	--   P(u, v) = O + (R + r*cos(v)) * (cos(u)*XDir +
    	--   sin(u)*YDir ) + r*sin(v)*ZDir, where:
    	-- - O, XDir, YDir and ZDir are respectively the
    	--   origin, the "X Direction", the "Y Direction" and the "Z
    	--   Direction" of the local coordinate system,
    	-- - r and R are, respectively, the minor and major radius.
    	--   The parametric range of the two parameters is:
    	-- - [ 0, 2.*Pi ] for u
    	-- - [ 0, 2.*Pi ] for v
 
uses Array1OfReal from TColStd,
     Ax3          from gp,
     Pnt          from gp,
     Torus        from gp,
     Trsf         from gp, 
     Vec          from gp,
     Curve        from Geom,
     Geometry     from Geom

raises ConstructionError from Standard, 
       DimensionError    from Standard,
       RangeError        from Standard

is

  Create (A3 : Ax3; MajorRadius, MinorRadius : Real)
     returns mutable ToroidalSurface
        ---Purpose :
        --  A3 is the local coordinate system of the surface.
        --  The orientation of increasing V parametric value is defined 
        --  by the rotation around the main axis (ZAxis) in the 
        --  trigonometric sense. The parametrization of the surface in the
        --  U direction is defined such as the normal Vector (N = D1U ^ D1V)
        --  is oriented towards the "outside region" of the surface. 
        --  Warnings :
        --  It is not forbidden to create a toroidal surface with 
        --  MajorRadius = MinorRadius = 0.0
     raises ConstructionError;
        ---Purpose : 
        --  Raised if MinorRadius < 0.0 or if MajorRadius < 0.0


  Create (T : Torus)  returns mutable ToroidalSurface;
        ---Purpose :
        --  Creates a ToroidalSurface from a non transient Torus from 
        --  package gp.



  SetMajorRadius (me : mutable; MajorRadius : Real)
     raises ConstructionError;
    	---Purpose :  Modifies this torus by changing its major radius.
    	-- Exceptions
    	-- Standard_ConstructionError if:
    	-- - MajorRadius is negative, or
    	-- - MajorRadius - r is less than or equal to
    	--   gp::Resolution(), where r is the minor radius of this torus.


  SetMinorRadius (me : mutable; MinorRadius : Real)
     raises ConstructionError;
        ---Purpose : Modifies this torus by changing its minor radius.
    	-- Exceptions
    	-- Standard_ConstructionError if:
    	-- - MinorRadius is negative, or
    	-- - R - MinorRadius is less than or equal to
    	--   gp::Resolution(), where R is the major radius of this torus.

  SetTorus(me : mutable; T : Torus);
       	---Purpose : Converts the gp_Torus torus T into this torus.
       
  Torus (me)  returns Torus;
        ---Purpose :
        --  Returns the non transient torus with the same geometric
        --  properties as <me>.


  UReversedParameter(me; U : Real) returns Real;
  	---Purpose: Return the  parameter on the  Ureversed surface for
	--          the point of parameter U on <me>.
	-- Return 2.PI - U.         

  VReversedParameter(me; U : Real) returns Real;
  	---Purpose: Return the  parameter on the  Ureversed surface for
	--          the point of parameter U on <me>.
	-- Return 2.PI - U.


  Area (me)  returns Real;
        ---Purpose : Computes the aera of the surface.


  Bounds (me; U1, U2, V1, V2 : out Real);
        ---Purpose : Returns the parametric bounds U1, U2, V1 and V2 of this torus.
    	--  For a torus: U1 = V1 = 0 and V1 = V2 = 2*PI .


  Coefficients (me; Coef : out Array1OfReal from TColStd)
       	---Purpose :
       	--  Returns the coefficients of the implicit equation of the surface
       	--  in the absolute cartesian coordinate system :
       	--  Coef(1) * X**4 + Coef(2) * Y**4 + Coef(3) * Z**4 +
       	--  Coef(4) * X**3 * Y + Coef(5) * X**3 * Z + Coef(6) * Y**3 * X +
       	--  Coef(7) * Y**3 * Z + Coef(8) * Z**3 * X + Coef(9) * Z**3 * Y +
       	--  Coef(10) * X**2 * Y**2 + Coef(11) * X**2 * Z**2 +
       	--  Coef(12) * Y**2 * Z**2 + Coef(13) * X**3 + Coef(14) * Y**3 +
       	--  Coef(15) * Z**3 + Coef(16) * X**2 * Y + Coef(17) * X**2 * Z +
       	--  Coef(18) * Y**2 * X + Coef(19) * Y**2 * Z + Coef(20) * Z**2 * X +
       	--  Coef(21) * Z**2 * Y + Coef(22) * X**2 + Coef(23) * Y**2 +
       	--  Coef(24) * Z**2 + Coef(25) * X * Y + Coef(26) * X * Z +
       	--  Coef(27) * Y * Z + Coef(28) * X + Coef(29) * Y + Coef(30) *  Z + 
       	--  Coef(31) = 0.0
     raises DimensionError;
       	---Purpose : Raised if the length of Coef is lower than 31.


  MajorRadius (me)  returns Real;

    	--- Purpose: Returns the major radius, or the minor radius, of this torus.

  MinorRadius (me)   returns Real;

    	--- Purpose: Returns the major radius, or the minor radius, of this torus.

  Volume (me)  returns Real;
        ---Purpose : Computes the volume.


  IsUClosed (me)   returns Boolean;
        ---Purpose : Returns True.


  IsVClosed (me) returns Boolean;
        ---Purpose : Returns True.


  IsUPeriodic (me)  returns Boolean;
        ---Purpose : Returns True.

  IsVPeriodic (me)  returns Boolean;
        ---Purpose : Returns True.


  UIso (me; U : Real)   returns mutable Curve;
        ---Purpose : Computes the U isoparametric curve.
        --  
        --  For a toroidal surface the UIso curve is a circle.
        --  The center of the Uiso circle is at the distance MajorRadius
        --  from the location point of the toroidal surface. 
        --  Warnings : 
        --  The radius of the circle can be zero if for the surface
        --  MinorRadius = 0.0


  VIso (me; V : Real)   returns mutable Curve;
        ---Purpose : Computes the V isoparametric curve.
        --  
        --  For a ToroidalSurface the VIso curve is a circle.
        --  The axis of the circle is the main axis (ZAxis) of the 
        --  toroidal  surface.
        --  Warnings : 
        --  The radius of the circle can be zero if for the surface
        --  MajorRadius = MinorRadius



  D0 (me; U, V : Real; P : out Pnt);
        ---Purpose :
        --  Computes the  point P (U, V) on the surface.
        --  P (U, V) = Loc + MinorRadius * Sin (V) * Zdir +
        --             (MajorRadius + MinorRadius * Cos(V)) *
        --             (cos (U) * XDir + sin (U) * YDir)
        --  where Loc is the origin of the placement plane (XAxis, YAxis)
        --  XDir is the direction of the XAxis and YDir the direction of
        --  the YAxis and ZDir the direction of the ZAxis.
  

  D1 (me; U, V : Real; P : out Pnt; D1U, D1V : out Vec);
        ---Purpose :
        --  Computes the current point and the first derivatives in 
        --  the directions U and V.


  D2 (me; U, V : Real; P : out Pnt; D1U,D1V, D2U, D2V, D2UV : out Vec);
        ---Purpose :
        --  Computes the current point, the first and the second derivatives 
        --  in the directions U and V.


  D3 (me; U, V : Real;  P : out Pnt; 
      D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV : out Vec);
        ---Purpose :
        --  Computes the current point, the first,the second and the 
        --  third derivatives in the directions U and V.


  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 RangeError;
        ---Purpose : Raised if Nu + Nv < 1 or Nu < 0 or Nv < 0.



  Transform (me : mutable; T : Trsf);

    	---Purpose: Applies the transformation T to this torus.


  Copy (me)  returns mutable like me;
    	---Purpose: Creates a new object which is a copy of this torus.
fields

  majorRadius : Real;
  minorRadius : Real;

end;