path: root/src/gp/gp_Ax3.cdl

-- File:	gp_Ax3.cdl
-- Created:	Mon Aug  2 18:33:16 1993
-- Author:	Laurent BOURESCHE
--		<lbo@phylox>
---Copyright:	 Matra Datavision 1993


class Ax3   from gp  inherits Storable 

        --- Purpose : Describes a coordinate system in 3D space. Unlike a
        --  gp_Ax2 coordinate system, a gp_Ax3 can be
        -- right-handed ("direct sense") or left-handed ("indirect sense").
        -- A coordinate system is defined by:
        -- -   its origin (also referred to as its "Location point"), and
        -- -   three orthogonal unit vectors, termed the "X
        --   Direction", the "Y Direction" and the "Direction" (also
        --   referred to as the "main Direction").
        -- The "Direction" of the coordinate system is called its
        -- "main Direction" because whenever this unit vector is
        -- modified, the "X Direction" and the "Y Direction" are
        -- recomputed. However, when we modify either the "X
        -- Direction" or the "Y Direction", "Direction" is not modified.
        -- "Direction" is also the "Z Direction".
        -- The "main Direction" is always parallel to the cross
        -- product of its "X Direction" and "Y Direction".
        -- If the coordinate system is right-handed, it satisfies the equation:
        -- "main Direction" = "X Direction" ^ "Y Direction"
        -- and if it is left-handed, it satisfies the equation:
        -- "main Direction" = -"X Direction" ^ "Y Direction"
        -- A coordinate system is used:
        -- -   to describe geometric entities, in particular to position
        --   them. The local coordinate system of a geometric
        --   entity serves the same purpose as the STEP function
        --   "axis placement three axes", or
        -- -   to define geometric transformations.
        -- Note:
        -- -   We refer to the "X Axis", "Y Axis" and "Z Axis",
        --   respectively, as the axes having:
        -- -   the origin of the coordinate system as their origin, and
        -- -   the unit vectors "X Direction", "Y Direction" and
        --    "main Direction", respectively, as their unit vectors.
        -- -   The "Z Axis" is also the "main Axis".
        -- -   gp_Ax2 is used to define a coordinate system that must be always right-handed. 

uses Ax1  from gp,
     Ax2  from gp,
     Dir  from gp,
     Pnt  from gp,
     Trsf from gp,
     Vec  from gp

raises ConstructionError from Standard

is
    
  Create  returns Ax3 from gp;
        --- Purpose : Creates an object corresponding to the reference 
        --            coordinate system (OXYZ).

  Create (A : Ax2 from gp) returns Ax3 from gp;
	---Purpose: Creates  a  coordinate  system from a right-handed
	--          coordinate system.
     
  Create (P : Pnt from gp; N, Vx : Dir from gp)   returns Ax3 from gp
	--- Purpose :  Creates a  right handed axis placement with the
	--  "Location"  point  P  and  two  directions, N    gives the
	--  "Direction" and Vx gives the "XDirection".
        --  Raises ConstructionError if N and Vx are parallel (same or opposite orientation).
    raises ConstructionError;
  

  Create (P : Pnt from gp; V : Dir from gp)  returns Ax3 from gp;
        --- Purpose :
        --  Creates an axis placement with the  "Location" point <P>
        --  and the normal direction <V>.
                            
  XReverse(me : in out)
    ---Purpose: Reverses the X direction of <me>.
  is static;

  YReverse(me : in out)
    ---Purpose: Reverses the Y direction of <me>.
  is static;

  ZReverse(me : in out)
    ---Purpose: Reverses the Z direction of <me>.
  is static;


  SetAxis (me : in out; A1 : Ax1)
        --- Purpose : Assigns the origin and "main Direction" of the axis A1 to
        -- this coordinate system, then recomputes its "X Direction" and "Y Direction".
        -- Note:
        -- -   The new "X Direction" is computed as follows:
        -- new "X Direction" = V1 ^(previous "X Direction" ^ V)
        -- where V is the "Direction" of A1.
        -- -   The orientation of this coordinate system
        --   (right-handed or left-handed) is not modified.
        --  Raises ConstructionError  if the "Direction" of <A1> and the "XDirection" of <me>
        --  are parallel (same or opposite orientation) because it is 
        --  impossible to calculate the new "XDirection" and the new
        --  "YDirection".
     raises ConstructionError
 
     is static;


  SetDirection (me : in out; V : Dir)
        --- Purpose :
        --  Changes the main direction of this coordinate system,
        -- then recomputes its "X Direction" and "Y Direction".
        -- Note:
        -- -   The new "X Direction" is computed as follows:
        -- new "X Direction" = V ^ (previous "X Direction" ^ V).
        -- -   The orientation of this coordinate system (left- or right-handed) is not modified.   
        -- Raises ConstructionError if <V< and the previous "XDirection" are parallel
        --  because it is impossible to calculate the new "XDirection" 
        --  and the new "YDirection".
     raises ConstructionError

     is static;


  SetLocation (me : in out; P : Pnt)   is static;
        --- Purpose :
        --  Changes the "Location" point (origin) of <me>.


  SetXDirection (me : in out; Vx : Dir)
        --- Purpose :
        --  Changes the "Xdirection" of <me>. The main direction 
        --  "Direction" is not modified, the "Ydirection" is modified.
        --  If <Vx> is not normal to the main direction then <XDirection>
        --  is computed as follows XDirection = Direction ^ (Vx ^ Direction).   
    	-- Raises ConstructionError if <Vx> is parallel (same or opposite 
    	-- orientation) to the main direction of <me>
     raises ConstructionError

     is static;


  SetYDirection(me : in out; Vy : Dir)
        ---C++:inline
        --- Purpose :
        --  Changes the "Ydirection" of <me>. The main direction is not 
        --  modified but the "Xdirection" is changed.
        --  If <Vy> is not normal to the main direction then "YDirection"
        --  is computed as  follows 
        --  YDirection = Direction ^ (<Vy> ^ Direction).  
  -- Raises ConstructionError if <Vy> is parallel to the main direction of <me>
     raises ConstructionError

    is static;

  Angle (me; Other : Ax3)  returns Real    is static;
        ---C++:inline 
        --- Purpose :
        --  Computes the angular value between the main direction of
        --  <me> and the main direction of <Other>. Returns the angle
        --  between 0 and PI in radians.

  Axis (me)  returns Ax1         is static;
        ---C++:inline 
        --- Purpose :
        --  Returns the main axis of <me>. It is the "Location" point
        --  and the main "Direction".
    	---C++: return const&

  Ax2 (me) returns Ax2 from gp
        ---Purpose: Computes a right-handed coordinate system with the
        -- same "X Direction" and "Y Direction" as those of this
        -- coordinate system, then recomputes the "main Direction".
        -- If this coordinate system is right-handed, the result
        -- returned is the same coordinate system. If this
        -- coordinate system is left-handed, the result is reversed.
  is static;

  Direction (me)  returns Dir    is static;
        ---C++:inline 
        --- Purpose :
        --  Returns the main direction of <me>. 
    	---C++: return const&


  Location (me)  returns Pnt     is static;
        ---C++:inline 
        --- Purpose :
        --  Returns the "Location" point (origin) of <me>.
    	---C++: return const&


  XDirection (me)  returns Dir   is static;
        ---C++:inline 
        --- Purpose :
        --  Returns the "XDirection" of <me>.
    	---C++: return const&


  YDirection(me)  returns Dir    is static;
        ---C++:inline 
        --- Purpose :
        --  Returns the "YDirection" of <me>.
    	---C++: return const&


  Direct(me) returns Boolean
        ---C++:inline 
	---Purpose: Returns  True if  the  coordinate  system is right-handed. i.e. 
	--          XDirection().Crossed(YDirection()).Dot(Direction()) > 0
  is static;



  IsCoplanar (me; Other : Ax3; LinearTolerance, AngularTolerance : Real)
     returns Boolean
     is static;
        ---C++:inline 
        --- Purpose :
        --  Returns True if 
        --  . the distance between the "Location" point of <me> and
        --    <Other> is lower or equal to LinearTolerance and
        --  . the distance between the "Location" point of <Other> and
        --    <me> is lower or equal to LinearTolerance and
        --  . the main direction of <me> and the main direction of 
        --    <Other> are parallel (same or opposite orientation).


  IsCoplanar (me; A1 : Ax1; LinearTolerance, AngularTolerance : Real)
     returns Boolean
     is static;
        ---C++:inline 
        --- Purpose : Returns True if
        --  . the distance between <me> and the "Location" point of A1
        --    is lower of equal to LinearTolerance and
        --  . the distance between A1 and the "Location" point of <me>
        --    is lower or equal to LinearTolerance and
        --  . the main direction of <me> and the direction of A1 are normal.


  Mirror (me : in out; P : Pnt)          is static;

  Mirrored (me; P : Pnt)  returns Ax3    is static;


        --- Purpose :
        --  Performs the symmetrical transformation of an axis
        --  placement with respect to the point P which is the
        --  center of the symmetry.
        --  Warnings :
        --  The main direction of the axis placement is not changed.
        --  The "XDirection" and the "YDirection" are reversed. 
        --  So the axis placement stay right handed.

  Mirror (me : in out; A1 : Ax1)         is static;

  Mirrored (me; A1 : Ax1)  returns Ax3   is static;

        --- Purpose :
        --  Performs the symmetrical transformation of an axis
        --  placement with respect to an axis placement which
        --  is the axis of the symmetry.
        --  The transformation is performed on the "Location"
        --  point, on the "XDirection" and "YDirection". 
        --  The resulting main "Direction" is the cross product between 
        --  the "XDirection" and the "YDirection" after transformation.
    


  Mirror (me : in out; A2 : Ax2)         is static;

  Mirrored (me; A2 : Ax2)  returns Ax3   is static;

        --- Purpose :
        --  Performs the symmetrical transformation of an axis
        --  placement with respect to a plane.
        --  The axis placement  <A2> locates the plane of the symmetry :
        --  (Location, XDirection, YDirection).
        --  The transformation is performed on the "Location"
        --  point, on the "XDirection" and "YDirection". 
        --  The resulting main "Direction" is the cross product between 
        --  the "XDirection" and the "YDirection" after transformation.


  Rotate (me : in out; A1 : Ax1; Ang : Real)         is static;
  Rotated (me; A1 : Ax1; Ang : Real)  returns Ax3    is static;

        --- Purpose :
        --  Rotates an axis placement. <A1> is the axis of the
        --  rotation . Ang is the angular value of the rotation
        --  in radians.


  Scale (me : in out; P : Pnt; S : Real)             is static;
  Scaled (me; P : Pnt; S : Real)  returns Ax3        is static;
        --- Purpose :
        --  Applies a scaling transformation on the axis placement.
        --  The "Location" point of the axisplacement is modified.
        -- Warnings :
        --  If the scale <S> is negative :
        --   . the main direction of the axis placement is not changed.
        --   . The "XDirection" and the "YDirection" are reversed. 
        --  So the axis placement stay right handed.              

 

  Transform (me : in out; T : Trsf)                  is static;
  Transformed (me; T : Trsf)   returns Ax3           is static;
        --- Purpose :  
        --  Transforms an axis placement with a Trsf.
        --  The "Location" point, the "XDirection" and the
     	--  "YDirection" are transformed with T.  The resulting
    	--  main "Direction" of <me> is the cross product between 
    	--  the "XDirection" and the "YDirection" after transformation.




  Translate (me : in out; V : Vec)                   is static;
  Translated (me; V : Vec)  returns Ax3              is static;
        --- Purpose : 
        --  Translates an axis plaxement in the direction of the vector
        --  <V>. The magnitude of the translation is the vector's magnitude.



  Translate (me : in out; P1, P2 : Pnt)              is static;
  Translated (me; P1, P2 : Pnt)   returns Ax3        is static;
 
        --- Purpose :
        --  Translates an axis placement from the point <P1> to the 
        --  point <P2>.       

fields

   axis  : Ax1 from gp;
   vydir : Dir from gp;
   vxdir : Dir from gp;

end;