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.

All objects are immutable and hashable.

class Mat3

A 3x3 Matrix.

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

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

Note

Matrix multiplication is performed using the “@” operator.

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

a: float

Alias for field number 0

b: float

Alias for field number 1

c: float

Alias for field number 2

d: float

Alias for field number 3

e: float

Alias for field number 4

f: float

Alias for field number 5

g: float

Alias for field number 6

h: float

Alias for field number 7

i: float

Alias for field number 8

class Mat4

A 4x4 Matrix.

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

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

Note

Matrix multiplication is performed using the “@” operator.

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) → Mat4

Create a scale matrix from a Vec3.

Return type:

Mat4

classmethod from_translation(vector: Vec3) → Mat4

Create a translation matrix from a Vec3.

Return type:

Mat4

classmethod look_at(
position: Vec3,
target: Vec3,
up: Vec3,
) → Mat4

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

Return type:

Mat4

classmethod orthogonal_projection(
left: float,
right: float,
bottom: float,
top: float,
z_near: float,
z_far: float,
) → Mat4

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:

Mat4

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

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:

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

a: float

Alias for field number 0

b: float

Alias for field number 1

c: float

Alias for field number 2

d: float

Alias for field number 3

e: float

Alias for field number 4

f: float

Alias for field number 5

g: float

Alias for field number 6

h: float

Alias for field number 7

i: float

Alias for field number 8

j: float

Alias for field number 9

k: float

Alias for field number 10

l: float

Alias for field number 11

m: float

Alias for field number 12

n: float

Alias for field number 13

o: float

Alias for field number 14

p: float

Alias for field number 15

class Quaternion

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

length() → float

Calculate the length of the Quaternion.

The distance between the coordinates and the origin.

Return type:

float

normalize() → Quaternion
Return type:

Quaternion

to_mat3() → Mat3
Return type:

Mat3

to_mat4() → Mat4
Return type:

Mat4

w: float

Alias for field number 0

x: float

Alias for field number 1

y: float

Alias for field number 2

z: float

Alias for field number 3

class Vec2

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

Vec2 is an immutable 2D Vector, including most common operators. As an immutable type, all operations return a new object.

Note

The Python len operator returns the number of elements in the vector. For the vector length, use the length() method.

Note

Python’s sum() requires the first item to be a Vec2.

After that, you can mix Vec2-like tuple and Vec2 instances freely in the iterable.

If you do not, you will see a TypeError about being unable to add a tuple and a int.

clamp(
min_val: Vec2 | tuple[float, float] | float,
max_val: Vec2 | tuple[float, float] | float,
) → Vec2

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

If a single value is provided, it will be used for both X and Y. If a tuple or Vec2 is provided, the first value will be used for X and the second for Y.

Parameters:
Return type:

Vec2

distance(other: Vec2 | tuple[int, int]) → float

Calculate the distance between this vector and another vector.

Parameters:

other (Vec2 | tuple[int, int]) – The point to calculate the distance to.

Return type:

float

dot(other: Vec2 | tuple[float, float]) → float

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

Return type:

float

static from_heading(heading: float, length: float = 1.0) → Vec2

Create a new vector from the given heading and length.

Parameters:

  • heading (float) – The desired heading, in radians

  • length (float) – The desired length of the vector

Return type:

Vec2

static from_polar(angle: float, length: float = 1.0) → Vec2

Create a new vector from the given polar coordinates.

Parameters:

  • angle (float) – The angle, in radians.

  • length (float) – The desired length

Return type:

Vec2

heading() → float

Calculate the heading of the vector in radians.

Shortcut for atan2(y, x) meaning it returns a value between -pi and pi. Vec2(1, 0) will have a heading of 0. Counter-clockwise is positive moving towards pi, and clockwise is negative moving towards -pi.

Return type:

float

index(*args: Any) → int

Return first index of value.

Raises ValueError if the value is not present.

Return type:

int

length() → float

Calculate the length of the vector: sqrt(x ** 2 + y ** 2).

Return type:

float

length_squared() → float

Calculate the squared length of the vector.

This is simply shortcut for x ** 2 + y ** 2 and can be used for faster comparisons without the need for a square root.

Return type:

float

lerp(
other: Vec2 | tuple[float, float],
amount: float,
) → Vec2

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

The equivalent in GLSL is mix.

Parameters:

  • other (Vec2 | tuple[float, float]) – Another Vec2 instance.

  • amount (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

normalize() → Vec2

Return a normalized version of the vector.

This simply means the vector will have a length of 1.0. If the vector has a length of 0, the original vector will be returned.

Return type:

Vec2

reflect(vector: Vec2 | tuple[float, float]) → Vec2

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

Parameters:

vector (Vec2 | tuple[float, float]) – A normalized Vec2 or Vec2-like tuple.

Return type:

Vec2

rotate(angle: float) → Vec2

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

Parameters:

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

Return type:

Vec2

step(edge: Vec2 | tuple[float, float]) → Vec2

A step function that returns 0.0 for a component if it is less than the edge, and 1.0 otherwise.

This can be used enable and disable some behavior based on a condition.

Example:

# First component is less than 1.0, second component is greater than 1.0
Vec2(0.5, 1.5).step((1.0, 1.0))
Vec2(1.0, 0.0)
Parameters:

edge (Vec2 | tuple[float, float]) – A Vec2 instance.

Return type:

Vec2

x: float

Alias for field number 0

y: float

Alias for field number 1

class Vec3

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

Vec3 is an immutable 3D Vector, including most common operators. As an immutable type, all operations return a new object.

Note

The Python len operator returns the number of elements in the vector. For the vector length, use the length() method.

clamp(
min_val: float | Vec3 | tuple[float, float, float],
max_val: float | Vec3 | tuple[float, float, float],
) → Vec3

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

If a single value is provided, it will be used for all components. If a tuple or Vec3 is provided, the first value will be used for X, the second for Y, and the third for Z.

Parameters:
Return type:

Vec3

cross(
other: Vec3 | tuple[float, float, float],
) → Vec3

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

Parameters:

other (Vec3 | tuple[float, float, float]) – Another Vec3 or tuple of 3 floats.

Return type:

Vec3

distance(other: Vec3 | tuple[float, float, float]) → float

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

Parameters:

other (Vec3 | tuple[float, float, float]) – The point to calculate the distance to.

Return type:

float

dot(other: Vec3 | tuple[float, float, float]) → float

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

Parameters:

other (Vec3 | tuple[float, float, float]) – Another Vec3 or tuple of 3 floats.

Return type:

float

classmethod from_pitch_yaw(pitch: float, yaw: float) → Vec3

Create a unit vector from pitch and yaw in radians.

Parameters:

  • pitch (float) – The pitch value in radians

  • yaw (float) – The yaw value in radians

Return type:

Vec3

get_pitch_yaw() → tuple[float, float]

Get the pitch and yaw angles from a unit vector in radians.

Return type:

tuple[float, float]

index(*args: Any) → int

Return first index of value.

Raises ValueError if the value is not present.

Return type:

int

length() → float

Calculate the length of the vector: sqrt(x ** 2 + y ** 2 + z ** 2).

Return type:

float

length_squared() → float

Calculate the squared length of the vector.

This is simply shortcut for x ** 2 + y ** 2 + z ** 2 and can be used for faster comparisons without the need for a square root.

Return type:

float

lerp(
other: Vec3 | tuple[float, float, float],
alpha: float,
) → Vec3

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

Parameters:

  • other (Vec3 | tuple[float, float, float]) – Another Vec3 instance or tuple of 3 floats.

  • 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

normalize() → Vec3

Return a normalized version of the vector.

This simply means the vector will have a length of 1.0. If the vector has a length of 0, the original vector will be returned.

Return type:

Vec3

x: float

Alias for field number 0

y: float

Alias for field number 1

z: float

Alias for field number 2

class Vec4

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

Vec4 is an immutable 4D Vector, including most common operators. As an immutable type, all operations return a new object.

Note

The Python ``len` operator returns the number of elements in the vector. For the vector length, use the length() method.

clamp(
min_val: float | tuple[float, float, float, float],
max_val: float | tuple[float, float, float, float],
) → Vec4

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

The minimum and maximum values can be a single value that will be applied to all components, or a tuple of 4 values that will be applied to each component respectively.

Parameters:
Return type:

Vec4

distance(other: Vec4 | tuple[float, float, float, float]) → float

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

Parameters:

other (Vec4 | tuple[float, float, float, float]) – The point to calculate the distance to.

Return type:

float

dot(other: Vec4 | tuple[float, float, float, float]) → float

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

Parameters:

other (Vec4 | tuple[float, float, float, float]) – Another Vec4 instance.

Return type:

float

index(*args: Any) → int

Return first index of value.

Raises ValueError if the value is not present.

Return type:

int

length() → float

Calculate the length of the vector: sqrt(x ** 2 + y ** 2 + z ** 2 + w ** 2).

Return type:

float

length_squared() → float

Calculate the squared length of the vector.

This is simply shortcut for x ** 2 + y ** 2 + z ** 2 + w ** 2 and can be used for faster comparisons without the need for a square root.

Return type:

float

lerp(
other: Vec4 | tuple[float, float, float, float],
amount: float,
) → Vec4

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

Parameters:

  • other (Vec4 | tuple[float, float, float, float]) – Another Vec4 instance.

  • amount (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

Returns a normalized version of the vector meaning a version that has length 1.

This means that the vector will have the same direction, but a length of 1.0. If the vector has a length of 0, the original vector will be returned.

Return type:

Vec4

w: float

Alias for field number 3

x: float

Alias for field number 0

y: float

Alias for field number 1

z: float

Alias for field number 2

clamp(num: float, minimum: float, maximum: float) → float

Clamp a value between a minimum and maximum limit.

Return type:

float