# 9. `coordsys` — Coordinate Systems.

class `coordsys.``CoordSys`(oab=None, points=None, rot=None, trl=None)

  A Cartesian coordinate system in 3D space.

  The coordinate system is stored as a rotation matrix and a translation vector, which transform the global coordinate axes into the axes of the CoordSys. Clearly, the translation vector is the origin of the CoordSys, and the rows of the rotation matrix are the unit vectors along the three axes.

  The CoordSys can be initialized in different ways and has only optional parameters to achieve this. If none are specified at all, the global coordinate axis results.

  Parameters: | oab (float array-like (3,3), optional) – Three non-collinear points O, A and B, that define the CoordSys in the following way: O is the origin of the coordinate system, A is a point along the positive first axis and B is a point B in the plane of the first two axes. points (float array-like (4,3), optional) – The CoordSys is specified by four points: the first three are points on the three coordinate axes, at distance +1 from the origin; the fourth point is the origin. The use of this parameter is deprecated. It can be replaced with oab=points[3,0,1]. rot (float array-like (3,3), optional) – Rotation matrix that transforms the global global axes to be parallel to the constructed CoordSys. The user is responsible to make sure that rot is a proper orthonormal rotation matrix. trl (float array-like (3,)) – Translation vector that moves the global origin to the origin of the CoordSys, in other words, this is the origin of the new CoordSys in global coordinates.

  Notes

  If oab is provided, it takes precedence and the other parameters are ignored. If not, and points is provided, this takes precedence and the remaining are ignored. If neither oab nor points are provided, rot and trl are used and have default values equal to the rotation matrix and translation vector of the global coordinatee axes.

  A Coords object has a number of attributes that provide quick acces to its internal data. Of these, trl and rot can be used to set the data of the CoordSys and thus change the CoordSys in-place.

  `trl`

    The origin of the CoordSys

    Type: | float array (3,)

  `rot`

    The rotation matrix of the CoordSys

    Type: | float array (3,3)

  `u`

    The unit vector along the first axis (0).

    Type: | float array (3,)

  `v`

    The unit vector along the second axis (1).

    Type: | float array (3,)

  `w`

    The unit vector along the third axis (2).

    Type: | float array (3,)

  `o`

    The origin of the CoordSys.

    Type: | float array (3,)

  Examples

  Three points O,A,B in the xy-plane, first two parallel to x-axis, third at higher y-value. The resulting CoordSys is global axes translated to point O.

      >>> OAB = Coords([[ 2.,1.,0.],[ 5.,1.,0.],[ 0.,3.,0.]])
      >>> print(CoordSys(oab=OAB))
      CoordSys: trl=[ 2. 1. 0.]; rot=[[ 1. 0. 0.]
                                      [ 0. 1. 0.]
                                      [ 0. 0. 1.]]

  Now translate the points so that O is on the z-axis, and rotate the points 30 degrees around z-axis.

      >>> OAB = OAB.trl([-2.,-1.,5.]).rot(30)
      >>> print(OAB)
      [[ 0.    0.    5.  ]
       [ 2.6   1.5   5.  ]
       [-2.73  0.73  5.  ]]
      >>> C = CoordSys(oab=OAB)
      >>> print(C)
      CoordSys: trl=[ 0. 0. 5.]; rot=[[ 0.87  0.5   0.  ]
                                      [-0.5   0.87  0.  ]
                                      [ 0.   -0.    1.  ]]

  Reverse axes x and y. The resulting CoordSys is still righthanded. This is equivalent to a rotation over 180 degrees around z-axis.

      >>> print(C.reverse(0,1))
      CoordSys: trl=[ 0. 0. 5.]; rot=[[-0.87 -0.5  -0.  ]
                                      [ 0.5  -0.87 -0.  ]
                                      [ 0.   -0.    1.  ]]

  Now rotate C over 150 degrees around z-axis to become parallel with the global axes.

      >>> print(C.rotate(150,2))
      CoordSys: trl=[ 0.  0.  5.]; rot=[[ 1.  0.  0.]
                                        [-0.  1.  0.]
                                        [ 0.  0.  1.]]

  `trl`

    Return the origin as a (3,) vector

  `rot`

    Return the (3,3) rotation matrix

  `u`

    Return unit vector along axis 0 (x)

  `v`

    Return unit vector along axis 1 (y)

  `w`

    Return unit vector along axis 2 (z)

  `o`

    Return the origin

  `origin`

    Return the origin

  `axes`

    Return the (3,3) rotation matrix

  `axis`(i)

    Return the unit vector along an axis.

    Parameters: | i (int (0,1,2)) – The axis number.
    Returns: | float array (3,) – A unit vector along axis i.

    Notes

    If the axis is known in advance, it is more appropriate to use one of the u, v or w attributes

    Examples

        >>> CoordSys().rotate(30).axis(1)
        array([-0.5 ,  0.87,  0.  ], dtype=float32)

  `points`()

    Return origin and endpoints of unit vectors along axes.

    Returns: | Coords (4,3) – A Coords object with four points: the endpoints of the unit vectors along the three axes of the CoordSys, and the origin of the CoordSys.

    Examples

        >>> CoordSys().rotate(30).points()
        Coords([[ 0.87,  0.5 ,  0.  ],
                [-0.5 ,  0.87,  0.  ],
                [ 0.  ,  0.  ,  1.  ],
                [ 0.  ,  0.  ,  0.  ]])

  `translate`(*args, **kargs)

    Translate the CoordSys like a Coords object.

    Parameters are like `Coords.translate()`.

    Returns: | A new CoordSys obtained by giving self a translation.

    Examples

        >>> print(CoordSys().translate([-2.,-1.,5.]))
        CoordSys: trl=[-2. -1.  5.]; rot=[[ 1.  0.  0.]
                                          [ 0.  1.  0.]
                                          [ 0.  0.  1.]]

  `rotate`(*args, **kargs)

    Rotate the CoordSys like a Coords object.

    Parameters are like `Coords.rotate()`.

    Returns: | A new CoordSys obtained by giving self a rotation.

    Examples

        >>> print(CoordSys().rotate(30))
        CoordSys: trl=[ 0.  0.  0.]; rot=[[ 0.87  0.5   0.  ]
                                          [-0.5   0.87  0.  ]
                                          [ 0.    0.    1.  ]]

  `reverse`(*axes)

    Reverse some axes of the CoordSys.

    Parameters: | axes (int (0,1,2) or tuple of ints) – The axes to be reversed.

    Note

    The reversing a single axis (or all three axes) will change a right-hand-sided CoordSys into a left-hand-sided one. Therefore, this method is normally used only with two axes.

    Examples

        >>> print(CoordSys().reverse(0,1))
        CoordSys: trl=[ 0.  0.  0.]; rot=[[-1. -0. -0.]
                                          [-0. -1. -0.]
                                          [ 0.  0.  1.]]