.. _mat3:
mat3 - 3x3 matrix
-----------------
A :class:`mat3` represents a 3x3 matrix which can be used to store linear
transformations (if you want to store translations or perspective
transformations, you have to use a :class:`mat4`). You can construct a
:class:`mat3` in several ways::
# all components are set to zero
M = mat3()
[ 0.0000, 0.0000, 0.0000]
[ 0.0000, 0.0000, 0.0000]
[ 0.0000, 0.0000, 0.0000]
# identity matrix
M = mat3(1.0)
[ 1.0000, 0.0000, 0.0000]
[ 0.0000, 1.0000, 0.0000]
[ 0.0000, 0.0000, 1.0000]
# The elements on the diagonal are set to 2.5
M = mat3(2.5)
[ 2.5000, 0.0000, 0.0000]
[ 0.0000, 2.5000, 0.0000]
[ 0.0000, 0.0000, 2.5000]
# All elements are explicitly set (values must be given in row-major order)
M = mat3(a,b,c,d,e,f,g,h,i)
M = mat3([a,b,c,d,e,f,g,h,i])
[ a, b, c]
[ d, e, f]
[ g, h, i]
# Create a copy of matrix N (which also has to be a mat3)
M = mat3(N)
# Specify the 3 columns of the matrix (as vec3's or sequences with 3 elements)
M = mat3(a,b,c)
[ a[0], b[0], c[0] ]
[ a[1], b[1], c[1] ]
[ a[2], b[2], c[2] ]
# All elements are explicitly set and are stored inside a string
M = mat3("1,2,3,4,5,6,7,8,9")
[ 1.0000, 2.0000, 3.0000]
[ 4.0000, 5.0000, 6.0000]
[ 7.0000, 8.0000, 9.0000]
**Mathematical operations:**
The mathematical operators are supported with the following combination of
types::
mat3 = mat3 + mat3
mat3 = mat3 - mat3
mat3 = mat3 * mat3
vec3 = mat3 * vec3
vec3 = vec3 * mat3
mat3 = float * mat3
mat3 = mat3 * float
mat3 = mat3 / float
mat3 = mat3 % float # each component
mat3 = -mat3
vec3 = mat3[i] # get or set column i (as vec3)
float = mat3[i,j] # get or set element in row i and column j
Additionally, you can compare matrices with ``==`` and ``!=``.
.. class:: mat3([args])
.. method:: mat3.getColumn(index)
Return column index (0-based) as a :class:`vec3`.
.. method:: mat3.setColumn(index, value)
Set column index (0-based) to *value* which has to be a sequence of 3 floats
(this includes :class:`vec3`).
.. method:: mat3.getRow(index)
Return row index (0-based) as a :class:`vec3`.
.. method:: mat3.setRow(index, value)
Set row index (0-based) to *value* which has to be a sequence of 3 floats (this
includes :class:`vec3`).
.. method:: mat3.getDiag()
Return the diagonal as a :class:`vec3`.
.. method:: mat3.setDiag(value)
Set the diagonal to *value* which has to be a sequence of 3 floats (this
includes :class:`vec3`).
.. method:: mat3.toList(rowmajor=False)
Returns a list containing the matrix elements. By default, the list is in
column-major order. If you set the optional argument *rowmajor* to ``True``,
you'll get the list in row-major order.
.. method:: mat3.identity()
Returns the identity matrix. This is a static method.
.. method:: mat3.transpose()
Returns the transpose of the matrix.
.. method:: mat3.determinant()
Returns the determinant of the matrix.
.. method:: mat3.inverse()
Returns the inverse of the matrix.
.. method:: mat3.scaling(s)
Returns a scaling transformation. The scaling vector *s* must be a 3-sequence
(e.g. a :class:`vec3`).
.. math::
\left( \begin{array}{ccc}
s.x & 0 & 0 \\
0 & s.y & 0 \\
0 & 0 & s.z \\
\end{array} \right)
This is a static method.
.. method:: mat3.rotation(angle, axis)
Returns a rotation transformation. The angle must be given in radians, *axis*
has to be a 3-sequence (e.g. a :class:`vec3`). --- This is a static method.
.. method:: mat3.scale(s)
Concatenates a scaling transformation and returns *self*. The scaling vector s
must be a 3-sequence (e.g. a :class:`vec3`).
.. method:: mat3.rotate(angle, axis)
Concatenates a rotation transformation and returns *self*. The angle must be
given in radians, axis has to be a 3-sequence (e.g. a :class:`vec3`).
.. method:: mat3.ortho()
Returns a matrix with orthogonal base vectors.
.. method:: mat3.decompose()
Decomposes the matrix into a rotation and scaling part. The method returns a
tuple (rotation, scaling). The scaling part is given as a :class:`vec3`, the
rotation is still a :class:`mat3`.
.. method:: mat3.fromEulerXYZ(x, y, z)
Returns a rotation matrix created from Euler angles. *x* is the angle around the
x axis, *y* the angle around the y axis and *z* the angle around the z axis. All
angles must be given in radians. The order of the individual rotations is X-Y-Z
(where each axis refers to the local axis, i.e. the first rotation is about the
x axis which rotates the Y and Z axis, then the second rotation is about the
rotated Y axis and so on). --- This is a static method.
.. method:: mat3.fromEulerYZX(x, y, z)
See above. The order is YZX. This is a static method.
.. method:: mat3.fromEulerZXY(x, y, z)
See above. The order is ZXY. This is a static method.
.. method:: mat3.fromEulerXZY(x, y, z)
See above. The order is XZY. This is a static method.
.. method:: mat3.fromEulerYXZ(x, y, z)
See above. The order is YXZ. This is a static method.
.. method:: mat3.fromEulerZYX(x, y, z)
See above. The order is ZYX. This is a static method.
.. method:: mat3.toEulerXYZ()
Return the Euler angles of a rotation matrix. The order is XYZ.
.. method:: mat3.toEulerYZX()
Return the Euler angles of a rotation matrix. The order is YZX.
.. method:: mat3.toEulerZXY()
Return the Euler angles of a rotation matrix. The order is ZXY.
.. method:: mat3.toEulerXZY()
Return the Euler angles of a rotation matrix. The order is XZY.
.. method:: mat3.toEulerYXZ()
Return the Euler angles of a rotation matrix. The order is YXZ.
.. method:: mat3.toEulerZYX()
Return the Euler angles of a rotation matrix. The order is ZYX.
.. method:: mat3.fromToRotation(_from, to)
Returns a rotation matrix that rotates one vector into another. The generated
rotation matrix will rotate the vector *_from* into the vector *to*. *_from* and
*to* must be unit vectors!
This method is based on the code from:
| Tomas MÃ¶ller and John Hughes
| *Efficiently Building a Matrix to Rotate One Vector to Another*
| Journal of Graphics Tools, 4(4):1-4, 1999
| ``_
This is a static method.