Transformation

This module contains a Matrix class used for our Graphics calculations. We currently support:

• rotation, translation and scaling matrices
• multiplication matrix
• clip matrix (with or without perspective)
• transformation matrix for 3d touch

For more information on transformation matrices, please see the OpenGL Matrices Tutorial.

Changed in version 1.6.0: Added Matrix.perspective(), Matrix.look_at() and Matrix.transpose().

class kivy.graphics.transformation.Matrix

Bases: builtins.object

>>> from kivy.graphics.transformation import Matrix
>>> m = Matrix()
>>> print(m)
[[ 1.000000 0.000000 0.000000 0.000000 ]
[ 0.000000 1.000000 0.000000 0.000000 ]
[ 0.000000 0.000000 1.000000 0.000000 ]
[ 0.000000 0.000000 0.000000 1.000000 ]]

[ 0 1 2 3] [ 4 5 6 7] [ 8 9 10 11] [ 12 13 14 15]

get()

Retrieve the value of the current as a flat list.

New in version 1.9.1.

identity() → Matrix

Reset the matrix to the identity matrix (inplace).

inverse() → Matrix

Return the inverse of the matrix as a new Matrix.

look_at(double eyex, double eyey, double eyez, double centerx, double centery, double centerz, double upx, double upy, double upz)

Returns a new lookat Matrix (similar to gluLookAt).

Parameters:

eyex: float

Eyes X co-ordinate

eyey: float

Eyes Y co-ordinate

eyez: float

Eyes Z co-ordinate

centerx: float

The X position of the reference point

centery: float

The Y position of the reference point

centerz: float

The Z position of the reference point

upx: float

The X value up vector.

upy: float

The Y value up vector.

upz: float

The Z value up vector.

New in version 1.6.0.

multiply(mb, Matrix ma) → Matrix

Multiply the given matrix with self (from the left) i.e. we premultiply the given matrix by the current matrix and return the result (not inplace):

m.multiply(n) -> n * m

Parameters:

ma: Matrix

The matrix to multiply by

normal_matrix() → Matrix

Computes the normal matrix, which is the inverse transpose of the top left 3x3 modelview matrix used to transform normals into eye/camera space.

New in version 1.6.0.

perspective(double fovy, double aspect, double zNear, double zFar) → Matrix

Creates a perspective matrix (inplace).

Parameters:

fovy: float

“Field Of View” angle

aspect: float

Aspect ratio

zNear: float

Near clipping plane

zFar: float

Far clippin plane

New in version 1.6.0.

project(double objx, double objy, double objz, Matrix model, Matrix proj, double vx, double vy, double vw, double vh)

Project a point from 3d space into a 2d viewport.

Parameters:

objx: float

Points X co-ordinate

objy: float

Points Y co-ordinate

objz: float

Points Z co-ordinate

model: Matrix

The model matrix

proj: Matrix

The projection matrix

vx: float

Viewports X co-ordinate

vy: float

Viewports y co-ordinate

vw: float

Viewports width

vh: float

Viewports height

New in version 1.7.0.

rotate(double angle, double x, double y, double z) → Matrix

Rotate the matrix through the angle around the axis (x, y, z) (inplace).

Parameters:

angle: float

The angle through which to rotate the matrix

x: float

X position of the point

y: float

Y position of the point

z: float

Z position of the point

scale(double x, double y, double z) → Matrix

Scale the current matrix by the specified factors over each dimension (inplace).

Parameters:

x: float

The scale factor along the X axis

y: float

The scale factor along the Y axis

z: float

The scale factor along the Z axis

set(flat=None, array=None)

Insert custom values into the matrix in a flat list format or 4x4 array format like below:

m.set(array=[
    [1.0, 0.0, 0.0, 0.0],
    [0.0, 1.0, 0.0, 0.0],
    [0.0, 0.0, 1.0, 0.0],
    [0.0, 0.0, 0.0, 1.0]]
)

New in version 1.9.0.

tolist()

Retrieve the value of the current matrix in numpy format. for example m.tolist() will return:

[[1.000000, 0.000000, 0.000000, 0.000000],
[0.000000, 1.000000, 0.000000, 0.000000],
[0.000000, 0.000000, 1.000000, 0.000000],
[0.000000, 0.000000, 0.000000, 1.000000]]

you can use this format to plug the result straight into numpy in this way numpy.array(m.tolist())

New in version 1.9.0.

transform_point(double x, double y, double z, t=None) → tuple

Transforms the point by the matrix and returns the transformed point as a (x, y, z) tuple. If the point is a vector v, the returned values is v2 = matrix * v.

If t is provided, it multiplies it with the last column of the matrix and returns the transformed (x, y, z, t).

translate(double x, double y, double z) → Matrix

Translate the matrix.

Parameters:

x: float

The translation factor along the X axis

y: float

The translation factor along the Y axis

z: float

The translation factor along the Z axis

transpose() → Matrix

Return the transposed matrix as a new Matrix.

New in version 1.6.0.

view_clip(double left, double right, double bottom, double top, double near, double far, int perspective) → Matrix

Create a clip matrix (inplace).

Parameters:

left: float

Co-ordinate

right: float

Co-ordinate

bottom: float

Co-ordinate

top: float

Co-ordinate

near: float

Co-ordinate

far: float

Co-ordinate

perpective: int

Co-ordinate

Changed in version 1.6.0: Enable support for perspective parameter.