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 class

Mat3 is an immutable 3x3 Matrix, including most common operators. Matrix multiplication must be 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))

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.

Parameters

angleA float :

The angle as a float.

vectorA Vec3, or 3 component tuple of float or int :

Vec3 or tuple with x, y and z translation values

classmethod from_scale(vector: Vec3) → Mat4T

Create a scale matrix from a Vec3.

Parameters

vectorA Vec3, or 3 component tuple of float or int

Vec3 or tuple with x, y and z scale values

classmethod from_translation(vector: Vec3) → Mat4T

Create a translation matrix from a Vec3.

Parameters

vectorA Vec3, or 3 component tuple of float or int

Vec3 or tuple with x, y and z translation values

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 Vec2(x: Union[float, int] = 0.0, y: Union[float, int] = 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.

Parameters

min_valint or float :

The minimum value

max_valint or float :

The maximum value

Returns

A new vector with clamped X and Y components.

Return type

Vec2

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.

Parameters

otherVec2 :

The other vector.

Returns

The dot product of the two vectors.

Return type

float

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.

Returns

A new vector with the given heading.

Return type

Vec2

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.

Returns

A new vector with the magnitude.

Return type

Vec2

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.

Returns

A new vector with the given angle and magnitude.

Return type

Vec2

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.

Returns

A new interpolated vector.

Return type

Vec2

limit(maximum: float) → Vec2

Limit the magnitude of the vector to the value used for the max parameter.

Parameters

maximumint or float :

The maximum magnitude for the vector.

Returns

Either self or a new vector with the maximum magnitude.

Return type

Vec2

normalize() → Vec2

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

Returns

A unit vector with the same heading.

Return type

Vec2

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.

Parameters

angleint or float :

The angle to rotate by

Returns

A new rotated vector of the same magnitude.

Return type

Vec2

property heading: float

The angle of the vector in radians.

Type

float

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

class Vec3(x: Union[float, int] = 0.0, y: Union[float, int] = 0.0, z: Union[float, int] = 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.

Parameters

min_valint or float :

The minimum value

max_valint or float :

The maximum value

Returns

A new vector with clamped X, Y and Z components.

Return type

Vec3

cross(other: Vec3) → Vec3

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

Parameters

otherVec3 :

The other vector.

Returns

The cross product of the two vectors.

Return type

float

distance(other: Vec3) → float

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

Parameters

otherVec3 :

The other vector

Returns

The distance between the two vectors.

Return type

float

dot(other: Vec3) → float

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

Parameters

otherVec3 :

The other vector.

Returns

The dot product of the two vectors.

Return type

float

from_magnitude(magnitude: float) → Vec3

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

Parameters

magnitudeint or float :

The magnitude of the new vector.

Returns

A new vector with the magnitude.

Return type

Vec3

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

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

Parameters

otherVec3 :

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.

Returns

A new interpolated vector.

Return type

Vec3

limit(maximum: float) → Vec3

Limit the magnitude of the vector to the value used for the max parameter.

Parameters

maximumint or float :

The maximum magnitude for the vector.

Returns

Either self or a new vector with the maximum magnitude.

Return type

Vec3

normalize() → Vec3

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

Returns

A unit vector with the same rotation.

Return type

Vec3

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: Union[float, int] = 0.0, y: Union[float, int] = 0.0, z: Union[float, int] = 0.0, w: Union[float, int] = 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.

Parameters

otherVec4 :

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.

Returns

A new interpolated vector.

Return type

Vec4

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