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.

note:For performance, Matrixes subclass the tuple type. They are therefore immutable - all operations return a new object; the object is not updated in-place.
class Mat3

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)
scale(sx: float, sy: float)
shear(sx: float, sy: float)
translate(tx: float, ty: float)
class Mat4

A 4x4 Matrix class

Mat4 is an immutable 4x4 Matrix, including most common operators. Matrix multiplication must be performed using the “@” operator. Class methods are available for creating orthogonal and perspective projections matrixes.

column(index: int)

Get a specific column as a tuple.

classmethod from_rotation(angle: float, vector: pyglet.math.Vec3) → pyglet.math.Mat4

Create a rotation matrix from an angle and Vec3.

Parameters:
angle : A float :

The angle as a float.

vector : A Vec3, or 3 component tuple of float or int :

Vec3 or tuple with x, y and z translation values

classmethod from_translation(vector: pyglet.math.Vec3) → pyglet.math.Mat4

Create a translation matrix from a Vec3.

Parameters:
vector : A Vec3, or 3 component tuple of float or int

Vec3 or tuple with x, y and z translation values

classmethod look_at(position: pyglet.math.Vec3, target: pyglet.math.Vec3, up: pyglet.math.Vec3) → pyglet.math.Mat4
classmethod look_at_direction(direction: pyglet.math.Vec3, up: pyglet.math.Vec3) → pyglet.math.Mat4
classmethod orthogonal_projection(left, right, bottom, top, z_near, z_far) → pyglet.math.Mat4

Create a Mat4 orthographic projection matrix.

classmethod perspective_projection(aspect, z_near, z_far, fov=60) → pyglet.math.Mat4

Create a Mat4 perspective projection matrix.

Parameters:aspect : The aspect ratio as a float z_near : The near plane as a float z_far : The far plane as a float fov : Field of view in degrees as a float
rotate(angle: float, vector: pyglet.math.Vec3) → pyglet.math.Mat4

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

row(index: int)

Get a specific row as a tuple.

scale(vector: pyglet.math.Vec3) → pyglet.math.Mat4

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

translate(vector: pyglet.math.Vec3) → pyglet.math.Mat4

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

transpose() → pyglet.math.Mat4

Get a transpose of this Matrix.

class Vec2(x=0.0, y=0.0)
clamp(min_val, max_val)

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

Parameters:
min_val : int or float :

The minimum value

max_val : int or float :

The maximum value

Returns:

A new vector with clamped X and Y components.

Return type:

Vec2

distance(other)

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

Parameters:
other : Vec2 :

The other vector

Returns:

The distance between the two vectors.

Return type:

float

dot(other)

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

Parameters:
other : Vec2 :

The other vector.

Returns:

The dot product of the two vectors.

Return type:

float

from_heading(heading)

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

Parameters:
heading : int or float :

The angle of the new vector in radians.

Returns:

A new vector with the given heading.

Return type:

Vec2

from_magnitude(magnitude)

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

Parameters:
magnitude : int or float :

The magnitude of the new vector.

Returns:

A new vector with the magnitude.

Return type:

Vec2

static from_polar(mag, angle)

Create a new vector from the given polar coordinates.

Parameters:
mag : int or float :

The magnitude of the vector.

angle : int or float :

The angle of the vector in radians.

Returns:

A new vector with the given angle and magnitude.

Return type:

Vec2

lerp(other, alpha)

Create a new vector lineraly interpolated between this vector and another vector.

Parameters:
other : Vec2 :

The vector to be linerly interpolated to.

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

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

Parameters:
maximum : int or float :

The maximum magnitude for the vector.

Returns:

Either self or a new vector with the maximum magnitude.

Return type:

Vec2

normalize()

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
rotate(angle)

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

Parameters:
angle : int or float :

The angle to rotate by

Returns:

A new rotated vector of the same magnitude.

Return type:

Vec2

scale(value)

Multiply the vector by a scalar value.

Parameters:
value : int or float :

The ammount to be scaled by

Returns:

A new vector scaled by the value.

Return type:

Vec2

heading

The angle of the vector in radians.

Type:float
mag

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=0.0, y=0.0, z=0.0)
clamp(min_val, max_val)

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

Parameters:
min_val : int or float :

The minimum value

max_val : int or float :

The maximum value

Returns:

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

Return type:

Vec3

cross(other)

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

Parameters:
other : Vec3 :

The other vector.

Returns:

The cross product of the two vectors.

Return type:

float

distance(other)

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

Parameters:
other : Vec3 :

The other vector

Returns:

The distance between the two vectors.

Return type:

float

dot(other)

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

Parameters:
other : Vec3 :

The other vector.

Returns:

The dot product of the two vectors.

Return type:

float

from_magnitude(magnitude)

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

Parameters:
magnitude : int or float :

The magnitude of the new vector.

Returns:

A new vector with the magnitude.

Return type:

Vec3

lerp(other, alpha)

Create a new vector lineraly interpolated between this vector and another vector.

Parameters:
other : Vec3 :

The vector to be linerly interpolated to.

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

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

Parameters:
maximum : int or float :

The maximum magnitude for the vector.

Returns:

Either self or a new vector with the maximum magnitude.

Return type:

Vec3

normalize()

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
scale(value)

Multiply the vector by a scalar value.

Parameters:
value : int or float :

The ammount to be scaled by

Returns:

A new vector scaled by the value.

Return type:

Vec3

mag

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=0.0, y=0.0, z=0.0, w=0.0)
clamp(min_val, max_val)
distance(other)
dot(other)
lerp(other, alpha)
normalize()
scale(value)
w
x
y
z
clamp(num, min_val, max_val)