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

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.

static __new__( cls: type[Mat3T], values: Iterable[float] = (1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0), ) → Mat3T

Return type:: TypeVar (Mat3T, bound = Mat3)

rotate(phi: float) → Mat3

Return type:: Mat3

scale(sx: float, sy: float) → Mat3

Return type:: Mat3

shear(sx: float, sy: float) → Mat3

Return type:: Mat3

translate(tx: float, ty: float) → Mat3

Return type:: Mat3

class Mat4

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.

static __new__( cls: type[Mat4T], 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), ) → Mat4T

Return type:: TypeVar (Mat4T, bound = Mat4)

column(index: int) → tuple

Get a specific column as a tuple.

Return type:: tuple

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

Create a rotation matrix from an angle and Vec3.

Parameters:

angle (float) – The desired angle, in radians.
vector (Vec3) – A Vec3 indicating the direction.

Return type:

Mat4

classmethod from_scale(vector: Vec3) → Mat4T

Create a scale matrix from a Vec3.

Return type:: TypeVar (Mat4T, bound = Mat4)

classmethod from_translation(vector: Vec3) → Mat4T

Create a translation matrix from a Vec3.

Return type:: TypeVar (Mat4T, bound = Mat4)

classmethod look_at( position: Vec3, target: Vec3, up: Vec3, )

Create a viewing matrix that points toward a target.

This method takes three Vec3s, describing the viewer’s position, where they are looking, and the upward axis (typically positive on the Y axis). The resulting Mat4 can be used as the projection matrix.

Parameters:

position (Vec3) – The location of the viewer in the scene.
target (Vec3) – The point that the viewer is looking towards.
up (Vec3) – A vector pointing “up” in the scene, typically Vec3(0.0, 1.0, 0.0).

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.

Return type:: TypeVar (Mat4T, bound = Mat4)

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.

Return type:: TypeVar (Mat4T, bound = Mat4)

rotate(angle: float, vector: Vec3) → Mat4

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

Return type:: Mat4

row(index: int) → tuple

Get a specific row as a tuple.

Return type:: tuple

scale(vector: Vec3) → Mat4

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

Return type:: Mat4

translate(vector: Vec3) → Mat4

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

Return type:: Mat4

transpose() → Mat4

Get a transpose of this Matrix.

Return type:: Mat4

class Quaternion

Quaternion

static __new__( cls, w: float = 1.0, x: float = 0.0, y: float = 0.0, z: float = 0.0, ) → Quaternion

Return type:: Quaternion

conjugate() → Quaternion

Return type:: Quaternion

dot(other: Quaternion) → float

Return type:: float

classmethod from_mat3() → Quaternion

Return type:: Quaternion

classmethod from_mat4() → Quaternion

Return type:: Quaternion

normalize() → Quaternion

Return type:: Quaternion

to_mat3() → Mat3

Return type:: Mat3

to_mat4() → Mat4

Return type:: Mat4

property mag: float

The magnitude, or length, of the Quaternion.

The distance between the coordinates and the origin. Alias of abs(quaternion_instance).

property w: float

property x: float

property y: float

property z: float

class Vec2

A two-dimensional vector represented as an X Y coordinate pair.

__init__(x: float = 0.0, y: float = 0.0) → None

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.

Return type:: Vec2

distance(other: Vec2) → float

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

Return type:: float

dot(other: Vec2) → float

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

Return type:: float

from_heading(heading: float) → Vec2

Create a new vector of the same magnitude with the given heading.

In effect, the vector rotated to the new heading.

Parameters:: heading (float) – The desired heading, in radians.
Return type:: Vec2

from_magnitude(magnitude: float) → Vec2

Create a new vector of the given magnitude

The new vector will be created by first normalizing, then scaling the vector. The heading remains unchanged.

Return type:: Vec2

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

Create a new vector from the given polar coordinates.

Parameters:

mag (float) – The desired magnitude.
angle (float) – The angle, in radians.

Return type:

Vec2

lerp(other: Vec2, alpha: float) → Vec2

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

Parameters:

other (Vec2) – Another Vec2 instance.
alpha (float) – The amount of interpolation between this vector, and the other vector. This should be a value between 0.0 and 1.0. For example: 0.5 is the midway point between both vectors.

Return type:

Vec2

limit(maximum: float) → Vec2

Limit the magnitude of the vector to passed maximum value.

Return type:: Vec2

normalize() → Vec2

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

Return type:: Vec2

reflect(vector: Vec2) → Vec2

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

Parameters:: vector (Vec2) – A normalized vector.
Return type:: Vec2

rotate(angle: float) → Vec2

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

Parameters:: angle (float) – The desired angle, in radians.
Return type:: Vec2

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(vec2_instance).

x

y

class Vec3

A three-dimensional vector represented as X Y Z coordinates.

__init__(x: float = 0.0, y: float = 0.0, z: float = 0.0) → None

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.

Return type:: Vec3

cross(other: Vec3) → Vec3

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

Return type:: Vec3

distance(other: Vec3) → float

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

Return type:: float

dot(other: Vec3) → float

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

Return type:: float

from_magnitude(magnitude: float) → Vec3

Create a new vector of the given magnitude

The new vector will be created by first normalizing, then scaling the vector. The heading remains unchanged.

Return type:: Vec3

lerp(other: Vec3, alpha: float) → Vec3

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

Parameters:

other (Vec3) – Another Vec3 instance.
alpha (float) – The amount of interpolation between this vector, and the other vector. This should be a value between 0.0 and 1.0. For example: 0.5 is the midway point between both vectors.

Return type:

Vec3

limit(maximum: float) → Vec3

Limit the magnitude of the vector to passed maximum value.

Return type:: Vec3

normalize() → Vec3

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

Return type:: Vec3

property mag: float

The magnitude, or length of the vector.

The distance between the coordinates and the origin. Alias of abs(vector_instance).

x

y

z

class Vec4

A four-dimensional vector represented as X Y Z W coordinates.

__init__(x: float = 0.0, y: float = 0.0, z: float = 0.0, w: float = 0.0) → None

clamp(min_val: float, max_val: float) → Vec4

Return type:: Vec4

distance(other: Vec4) → float

Return type:: float

dot(other: Vec4) → float

Return type:: float

lerp(other: Vec4, alpha: float) → Vec4

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

Parameters:

other (Vec4) – Another Vec4 instance.
alpha (float) – The amount of interpolation between this vector, and the other vector. This should be a value between 0.0 and 1.0. For example: 0.5 is the midway point between both vectors.

Return type:

Vec4

normalize() → Vec4

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

Return type:: Vec4

w

x

y

z

clamp(num: float, min_val: float, max_val: float) → float

Clamp a value between a minimum and maximum limit.

Return type:: float