path: root/src/gp/gp_Ax2.cdl

---Copyright:   Matra Datavision 1991

class Ax2   from gp  inherits Storable

        --- Purpose :
        --  Describes a right-handed coordinate system in 3D space.
        -- A coordinate system is defined by:
        -- -   its origin (also referred to as its "Location point"), and
        -- -   three orthogonal unit vectors, termed respectively 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.
        -- The "main Direction" is also the "Z Direction".
        -- Since an Ax2 coordinate system is right-handed, its
        -- "main Direction" is always equal to the cross product of
        -- its "X Direction" and "Y Direction". (To define a
        -- left-handed coordinate system, use gp_Ax3.)
        -- 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 two axes", or
        -- -   to define geometric transformations.
        -- Note: we refer to the "X Axis", "Y Axis" and "Z Axis",
        -- respectively, as to 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".


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

raises ConstructionError from Standard

is


  Create  returns Ax2;
        ---C++:inline
        --- Purpose : Creates an object corresponding to the reference 
        --            coordinate system (OXYZ).

     
  Create (P : Pnt; N, Vx : Dir)   returns Ax2
        ---C++:inline
	--- Purpose : 
	--  Creates an axis placement with an origin P such that:
        --   -   N is the Direction, and
        --   -   the "X Direction" is normal to N, in the plane
        --    defined by the vectors (N, Vx): "X
        --    Direction" = (N ^ Vx) ^ N, 
       --  Exception: raises ConstructionError if N and Vx are parallel (same or opposite orientation).
     raises ConstructionError;
    

  Create (P : Pnt; V : Dir)  returns Ax2;
        --- Purpose :
        --  Creates -   a coordinate system with an origin P, where V
        -- gives the "main Direction" (here, "X Direction" and "Y
        --  Direction" are defined automatically).
    
  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.
        -- Exceptions
        -- Standard_ConstructionError if A1 is parallel to the "X
        -- Direction" of this coordinate system.
        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)
        --   Exceptions
        -- Standard_ConstructionError if V is parallel to the "X
        -- Direction" of this coordinate system.
     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).
        -- Exceptions
        -- Standard_ConstructionError if Vx or Vy is parallel to
        -- the "main Direction" of this coordinate system.   
    raises ConstructionError
    
     is static;

  SetYDirection(me : in out; Vy : Dir)
        --- 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).
        -- Exceptions
        -- Standard_ConstructionError if Vx or Vy is parallel to
        -- the "main Direction" of this coordinate system. 
    raises ConstructionError
 
    is static;

  Angle (me; Other : Ax2)  returns Real    is static;
        --- Purpose :
        --  Computes the angular value, in radians, 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&


  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&


  IsCoplanar (me; Other : Ax2; LinearTolerance, AngularTolerance : Real)
     returns Boolean
     is static;
        --  Returns True if 
    	--  -   the "main Direction" of this coordinate system is   parallel to:
    	-- -   the "main Direction" of the coordinate system Other, or
    	--   -   the Direction of axis A1, and
    	--
    	-- Note: the tolerance criterion for angular equality is given by AngularTolerance.


  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 main direction of <me> and the direction of A1 are normal.
        -- Note: the tolerance criterion for angular equality is given by AngularTolerance.

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

       ---Purpose:
       -- Performs a symmetrical transformation of this coordinate
       -- system with respect to:
       -- -   the point P, and assigns the result to this coordinate system.
       -- Warning
       -- This transformation is always performed on the origin.
       -- In case of a reflection with respect to a point:
       -- - the main direction of the coordinate system is not changed, and
       -- - the "X Direction" and the "Y Direction" are simply reversed
       -- In case of a reflection with respect to an axis or a plane:
       --   -   the transformation is applied to the "X Direction"
       --    and the "Y Direction", then
       --   -   the "main Direction" is recomputed as the cross
       --    product "X Direction" ^ "Y   Direction".
       --  This maintains the right-handed property of the
       -- coordinate system.

  Mirrored (me; P : Pnt)  returns Ax2    is static;
       ---Purpose:
       -- Performs a symmetrical transformation of this coordinate
       -- system with respect to:
       -- -   the point P, and creates a new one.
       -- Warning
       -- This transformation is always performed on the origin.
       -- In case of a reflection with respect to a point:
       -- - the main direction of the coordinate system is not changed, and
       -- - the "X Direction" and the "Y Direction" are simply reversed
       -- In case of a reflection with respect to an axis or a plane:
       --   -   the transformation is applied to the "X Direction"
       --    and the "Y Direction", then
       --   -   the "main Direction" is recomputed as the cross
       --    product "X Direction" ^ "Y   Direction".
       --  This maintains the right-handed property of the
       -- coordinate system.



  Mirror (me : in out; A1 : Ax1)         is static;
       ---Purpose:
       -- Performs a symmetrical transformation of this coordinate
       -- system with respect to:
       -- -   the axis A1, and assigns the result to this coordinate systeme.
       -- Warning
       -- This transformation is always performed on the origin.
       -- In case of a reflection with respect to a point:
       -- - the main direction of the coordinate system is not changed, and
       -- - the "X Direction" and the "Y Direction" are simply reversed
       -- In case of a reflection with respect to an axis or a plane:
       --   -   the transformation is applied to the "X Direction"
       --    and the "Y Direction", then
       --   -   the "main Direction" is recomputed as the cross
       --    product "X Direction" ^ "Y   Direction".
       --  This maintains the right-handed property of the
       -- coordinate system.

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

       ---Purpose:
       -- Performs a symmetrical transformation of this coordinate
       -- system with respect to:
       -- -   the axis A1, and  creates a new one.
       -- Warning
       -- This transformation is always performed on the origin.
       -- In case of a reflection with respect to a point:
       -- - the main direction of the coordinate system is not changed, and
       -- - the "X Direction" and the "Y Direction" are simply reversed
       -- In case of a reflection with respect to an axis or a plane:
       --   -   the transformation is applied to the "X Direction"
       --    and the "Y Direction", then
       --   -   the "main Direction" is recomputed as the cross
       --    product "X Direction" ^ "Y   Direction".
       --  This maintains the right-handed property of the
       -- coordinate system.



  Mirror (me : in out; A2 : Ax2)         is static;
       ---Purpose:
       -- Performs a symmetrical transformation of this coordinate
       -- system with respect to:
       -- -   the plane defined by the origin, "X Direction" and "Y
       --   Direction" of coordinate system A2 and  assigns the result to this coordinate systeme.
       -- Warning
       -- This transformation is always performed on the origin.
       -- In case of a reflection with respect to a point:
       -- - the main direction of the coordinate system is not changed, and
       -- - the "X Direction" and the "Y Direction" are simply reversed
       -- In case of a reflection with respect to an axis or a plane:
       --   -   the transformation is applied to the "X Direction"
       --    and the "Y Direction", then
       --   -   the "main Direction" is recomputed as the cross
       --    product "X Direction" ^ "Y   Direction".
       --  This maintains the right-handed property of the
       -- coordinate system.

  Mirrored (me; A2 : Ax2)  returns Ax2   is static;
       ---Purpose:
       -- Performs a symmetrical transformation of this coordinate
       -- system with respect to:
       -- -   the plane defined by the origin, "X Direction" and "Y
       --   Direction" of coordinate system A2 and creates a new one.
       -- Warning
       -- This transformation is always performed on the origin.
       -- In case of a reflection with respect to a point:
       -- - the main direction of the coordinate system is not changed, and
       -- - the "X Direction" and the "Y Direction" are simply reversed
       -- In case of a reflection with respect to an axis or a plane:
       --   -   the transformation is applied to the "X Direction"
       --    and the "Y Direction", then
       --   -   the "main Direction" is recomputed as the cross
       --    product "X Direction" ^ "Y   Direction".
       --  This maintains the right-handed property of the
       -- coordinate system.




  Rotate (me : in out; A1 : Ax1; Ang : Real)         is static;
      ---C++:inline

  Rotated (me; A1 : Ax1; Ang : Real)  returns Ax2    is static;
      ---C++:inline

        --- 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;
      ---C++:inline
  Scaled (me; P : Pnt; S : Real)  returns Ax2        is static;
      ---C++:inline
       --- 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;
      ---C++:inline
  Transformed (me; T : Trsf)   returns Ax2           is static;
      ---C++:inline
        --- 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)                   
      ---C++:inline
      is static;

  Translated (me; V : Vec)  returns Ax2              is static;
       ---C++:inline
       --- 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)              
      ---C++:inline
     is static;

  Translated (me; P1, P2 : Pnt)   returns Ax2        is static;
      ---C++:inline
        --- Purpose :
        --  Translates an axis placement from the point <P1> to the 
        --  point <P2>.




fields

   axis  : Ax1;
   vydir : Dir;
   vxdir : Dir;

end;