pyglet.math

Matrix and Vector math.

This module provides Vector and Matrix objects, including Vec2, Vec3, Vec4, Mat3, and Mat4. Most common matrix and vector operations are supported. Helper methods are included for rotating, scaling, and transforming. The Mat4 includes class methods for creating orthographic and perspective projection matrixes.

Matrices behave just like they do in GLSL: they are specified in column-major order and multiply on the left of vectors, which are treated as columns.

Note

For performance reasons, Matrix types subclass tuple. They are therefore immutable. All operations return a new object; the object is not updated in-place.

class Mat3(values: Iterable[float] = (1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0))

A 3x3 Matrix

Mat3 is an immutable 3x3 Matrix, including most common operators.

A Matrix can be created with a list or tuple of 12 values. If no values are provided, an “identity matrix” will be created (1.0 on the main diagonal). Mat3 objects are immutable, so all operations return a new Mat3 object.

Note

Matrix multiplication is performed using the “@” operator.

rotate(phi: float) Mat3
scale(sx: float, sy: float) Mat3
shear(sx: float, sy: float) Mat3
translate(tx: float, ty: float) Mat3
class Mat4(values: Iterable[float] = (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))

A 4x4 Matrix

Mat4 is an immutable 4x4 Matrix, which includs most common operators. This includes class methods for creating orthogonal and perspective projection matrixes, to be used by OpenGL.

A Matrix can be created with a list or tuple of 16 values. If no values are provided, an “identity matrix” will be created (1.0 on the main diagonal). Mat4 objects are immutable, so all operations return a new Mat4 object.

Note

Matrix multiplication is performed using the “@” operator.

column(index: int) tuple

Get a specific column as a tuple.

classmethod from_rotation(angle: float, vector: Vec3) Mat4

Create a rotation matrix from an angle and Vec3.

classmethod from_scale(vector: Vec3) Mat4T

Create a scale matrix from a Vec3.

classmethod from_translation(vector: Vec3) Mat4T

Create a translation matrix from a Vec3.

classmethod look_at(position: Vec3, target: Vec3, up: Vec3)
classmethod orthogonal_projection(left: float, right: float, bottom: float, top: float, z_near: float, z_far: float) Mat4T

Create a Mat4 orthographic projection matrix for use with OpenGL.

Given left, right, bottom, top values, and near/far z planes, create a 4x4 Projection Matrix. This is useful for setting projection.

classmethod perspective_projection(aspect: float, z_near: float, z_far: float, fov: float = 60) Mat4T

Create a Mat4 perspective projection matrix for use with OpenGL.

Given a desired aspect ratio, near/far planes, and fov (field of view), create a 4x4 Projection Matrix. This is useful for setting projection.

rotate(angle: float, vector: Vec3) Mat4

Get a rotation Matrix on x, y, or z axis.

row(index: int) tuple

Get a specific row as a tuple.

scale(vector: Vec3) Mat4

Get a scale Matrix on x, y, or z axis.

translate(vector: Vec3) Mat4

Get a translation Matrix along x, y, and z axis.

transpose() Mat4

Get a transpose of this Matrix.

class Quaternion(w: float = 1.0, x: float = 0.0, y: float = 0.0, z: float = 0.0)
conjugate() Quaternion
dot(other: Quaternion) float
classmethod from_mat3() Quaternion
classmethod from_mat4() Quaternion
normalize() Quaternion
to_mat3() Mat3
to_mat4() Mat4
property mag: float
property w: float
property x: float
property y: float
property z: float
class Vec2(x: float = 0.0, y: float = 0.0)
clamp(min_val: float, max_val: float) Vec2

Restrict the value of the X and Y components of the vector to be within the given values.

distance(other: Vec2) float

Calculate the distance between this vector and another 2D vector.

dot(other: Vec2) float

Calculate the dot product of this vector and another 2D vector.

from_heading(heading: float) Vec2

Create a new vector of the same magnitude with the given heading. I.e. Rotate the vector to the heading.

Parameters:
headingint or float :

The angle of the new vector in radians.

from_magnitude(magnitude: float) Vec2

Create a new Vector of the given magnitude by normalizing, then scaling the vector. The heading remains unchanged.

Parameters:
magnitudeint or float :

The magnitude of the new vector.

static from_polar(mag: float, angle: float) Vec2

Create a new vector from the given polar coordinates.

Parameters:
magint or float :

The magnitude of the vector.

angleint or float :

The angle of the vector in radians.

lerp(other: Vec2, alpha: float) Vec2

Create a new Vec2 linearly interpolated between this vector and another Vec2.

Parameters:
otherVec2 :

The vector to linearly interpolate with.

alphafloat or int :

The amount of interpolation. Some value between 0.0 (this vector) and 1.0 (other vector). 0.5 is halfway inbetween.

limit(maximum: float) Vec2

Limit the magnitude of the vector to passed maximum value.

normalize() Vec2

Normalize the vector to have a magnitude of 1. i.e. make it a unit vector.

reflect(normal: Vec2) Vec2

Create a new Vec2 reflected (ricochet) from the given normal.

rotate(angle: float) Vec2

Create a new Vector rotated by the angle. The magnitude remains unchanged.

property heading: float

The angle of the vector in radians.

property mag: float

The magnitude, or length of the vector. The distance between the coordinates and the origin.

Alias of abs(self).

x
y
class Vec3(x: float = 0.0, y: float = 0.0, z: float = 0.0)
clamp(min_val: float, max_val: float) Vec3

Restrict the value of the X, Y and Z components of the vector to be within the given values.

cross(other: Vec3) Vec3

Calculate the cross product of this vector and another 3D vector.

distance(other: Vec3) float

Get the distance between this vector and another 3D vector.

dot(other: Vec3) float

Calculate the dot product of this vector and another 3D vector.

from_magnitude(magnitude: float) Vec3

Create a new Vector of the given magnitude by normalizing, then scaling the vector. The rotation remains unchanged.

lerp(other: Vec3, alpha: float) Vec3

Create a new Vec3 linearly interpolated between this vector and another Vec3.

The alpha parameter dictates the amount of interpolation. This should be a value between 0.0 (this vector) and 1.0 (other vector). For example; 0.5 is the midway point between both vectors.

limit(maximum: float) Vec3

Limit the magnitude of the vector to the passed maximum value.

normalize() Vec3

Normalize the vector to have a magnitude of 1. i.e. make it a unit vector.

property mag: float

The magnitude, or length of the vector. The distance between the coordinates and the origin.

Alias of abs(self).

Type:

float

x
y
z
class Vec4(x: float = 0.0, y: float = 0.0, z: float = 0.0, w: float = 0.0)
clamp(min_val: float, max_val: float) Vec4
distance(other: Vec4) float
dot(other: Vec4) float
lerp(other: Vec4, alpha: float) Vec4

Create a new Vec4 linearly interpolated between this one and another Vec4.

The alpha parameter dictates the amount of interpolation. This should be a value between 0.0 (this vector) and 1.0 (other vector). For example; 0.5 is the midway point between both vectors.

normalize() Vec4

Normalize the vector to have a magnitude of 1. i.e. make it a unit vector.

w
x
y
z
clamp(num: float, min_val: float, max_val: float) float