# 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: = (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: = (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)

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:
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:
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)

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,
)
Return type:

`Quaternion`

conjugate()
Return type:

`Quaternion`

dot(other: Quaternion)
Return type:

`float`

classmethod from_mat3()
Return type:

`Quaternion`

classmethod from_mat4()
Return type:

`Quaternion`

normalize()
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)

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

Return type:

`float`

dot(other: Vec2)

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

Return type:

`float`

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:
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`

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)

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

Return type:

`float`

dot(other: Vec3)

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)
Return type:

`float`

dot(other: Vec4)
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)

Clamp a value between a minimum and maximum limit.

Return type:

`float`