tessl/pypi-pyglm

OpenGL Mathematics (GLM) library for Python providing comprehensive vector and matrix manipulation capabilities for graphics programming.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Matrix Operations

Name: tessl/pypi-pyglm
Author: tessl

Comprehensive matrix mathematics for linear algebra, 3D graphics transformations, and scientific computing. PyGLM provides matrices from 2×2 to 4×4 in multiple precisions with complete linear algebra operations.

Capabilities

Matrix Types

PyGLM provides a complete set of matrix types for all common graphics and scientific computing applications.

# Float32 matrices (default precision)
class mat2x2:
    def __init__(self): ...  # Identity matrix
    def __init__(self, diagonal: float): ...  # Diagonal matrix
    def __init__(self, col0: vec2, col1: vec2): ...  # From column vectors
    def __getitem__(self, index: int) -> vec2: ...  # Column access
    def __setitem__(self, index: int, value: vec2): ...

class mat2x3:
    def __init__(self): ...
    def __getitem__(self, index: int) -> vec3: ...

class mat2x4:
    def __init__(self): ...
    def __getitem__(self, index: int) -> vec4: ...

class mat3x2:
    def __init__(self): ...
    def __getitem__(self, index: int) -> vec2: ...

class mat3x3:
    def __init__(self): ...  # Identity matrix
    def __init__(self, diagonal: float): ...  # Diagonal matrix
    def __init__(self, col0: vec3, col1: vec3, col2: vec3): ...  # From column vectors
    def __getitem__(self, index: int) -> vec3: ...

class mat3x4:
    def __init__(self): ...
    def __getitem__(self, index: int) -> vec4: ...

class mat4x2:
    def __init__(self): ...
    def __getitem__(self, index: int) -> vec2: ...

class mat4x3:
    def __init__(self): ...
    def __getitem__(self, index: int) -> vec3: ...

class mat4x4:
    def __init__(self): ...  # Identity matrix
    def __init__(self, diagonal: float): ...  # Diagonal matrix
    def __init__(self, col0: vec4, col1: vec4, col2: vec4, col3: vec4): ...  # From column vectors
    def __getitem__(self, index: int) -> vec4: ...

# Convenient aliases for square matrices
mat2 = mat2x2  # 2×2 matrix
mat3 = mat3x3  # 3×3 matrix  
mat4 = mat4x4  # 4×4 matrix

# Double precision matrices  
class dmat2x2:
    def __init__(self): ...
    def __getitem__(self, index: int) -> dvec2: ...

class dmat2x3:
    def __init__(self): ...
    def __getitem__(self, index: int) -> dvec3: ...

class dmat2x4:
    def __init__(self): ...
    def __getitem__(self, index: int) -> dvec4: ...

class dmat3x2:
    def __init__(self): ...
    def __getitem__(self, index: int) -> dvec2: ...

class dmat3x3:
    def __init__(self): ...
    def __getitem__(self, index: int) -> dvec3: ...

class dmat3x4:
    def __init__(self): ...
    def __getitem__(self, index: int) -> dvec4: ...

class dmat4x2:
    def __init__(self): ...
    def __getitem__(self, index: int) -> dvec2: ...

class dmat4x3:
    def __init__(self): ...
    def __getitem__(self, index: int) -> dvec3: ...

class dmat4x4:
    def __init__(self): ...
    def __getitem__(self, index: int) -> dvec4: ...

dmat2 = dmat2x2  # Double precision 2×2
dmat3 = dmat3x3  # Double precision 3×3
dmat4 = dmat4x4  # Double precision 4×4

# Integer matrices (signed 32-bit)
class imat2x2:
    def __init__(self): ...
    def __getitem__(self, index: int) -> ivec2: ...

class imat2x3:
    def __init__(self): ...
    def __getitem__(self, index: int) -> ivec3: ...

class imat2x4:
    def __init__(self): ...
    def __getitem__(self, index: int) -> ivec4: ...

class imat3x2:
    def __init__(self): ...
    def __getitem__(self, index: int) -> ivec2: ...

class imat3x3:
    def __init__(self): ...
    def __getitem__(self, index: int) -> ivec3: ...

class imat3x4:
    def __init__(self): ...
    def __getitem__(self, index: int) -> ivec4: ...

class imat4x2:
    def __init__(self): ...
    def __getitem__(self, index: int) -> ivec2: ...

class imat4x3:
    def __init__(self): ...
    def __getitem__(self, index: int) -> ivec3: ...

class imat4x4:
    def __init__(self): ...
    def __getitem__(self, index: int) -> ivec4: ...

imat2 = imat2x2  # Integer 2×2
imat3 = imat3x3  # Integer 3×3
imat4 = imat4x4  # Integer 4×4

# Unsigned integer matrices
class umat2x2:
    def __init__(self): ...
    def __getitem__(self, index: int) -> uvec2: ...

class umat2x3:
    def __init__(self): ...
    def __getitem__(self, index: int) -> uvec3: ...

class umat2x4:
    def __init__(self): ...
    def __getitem__(self, index: int) -> uvec4: ...

class umat3x2:
    def __init__(self): ...
    def __getitem__(self, index: int) -> uvec2: ...

class umat3x3:
    def __init__(self): ...
    def __getitem__(self, index: int) -> uvec3: ...

class umat3x4:
    def __init__(self): ...
    def __getitem__(self, index: int) -> uvec4: ...

class umat4x2:
    def __init__(self): ...
    def __getitem__(self, index: int) -> uvec2: ...

class umat4x3:
    def __init__(self): ...
    def __getitem__(self, index: int) -> uvec3: ...

class umat4x4:
    def __init__(self): ...
    def __getitem__(self, index: int) -> uvec4: ...

umat2 = umat2x2  # Unsigned integer 2×2
umat3 = umat3x3  # Unsigned integer 3×3
umat4 = umat4x4  # Unsigned integer 4×4

Type Aliases: PyGLM provides convenient aliases for matrix types:

f32mat* = fmat* = mat* - 32-bit float matrices
f64mat* = dmat* - 64-bit double matrices
i32mat* = imat* - 32-bit signed integer matrices
u32mat* = umat* - 32-bit unsigned integer matrices

### Basic Matrix Operations

Core linear algebra operations including transpose, inverse, determinant, and matrix multiplication.

```python { .api }
def transpose(m):
    """
    Calculate the transpose of a matrix.

    Args:
        m: Matrix of any supported type and dimension

    Returns:
        Transposed matrix where rows become columns
    """

def inverse(m):
    """
    Calculate the inverse of a square matrix.

    Args:
        m: Square matrix (2×2, 3×3, or 4×4)

    Returns:
        Inverse matrix, or identity if matrix is singular

    Note:
        Only works with square matrices
    """

def determinant(m):
    """  
    Calculate the determinant of a square matrix.

    Args:
        m: Square matrix (2×2, 3×3, or 4×4)

    Returns:
        Scalar determinant value
    """

def matrixCompMult(x, y):
    """
    Component-wise multiplication of two matrices.

    Args:
        x: First matrix
        y: Second matrix of same dimensions

    Returns:
        Matrix where result[i][j] = x[i][j] * y[i][j]

    Note:
        This is NOT standard matrix multiplication
    """

def outerProduct(c, r):
    """
    Calculate the outer product of two vectors.

    Args:
        c: Column vector
        r: Row vector

    Returns:
        Matrix where result[i][j] = c[i] * r[j]
    """

Matrix Construction

Utility functions for creating and manipulating matrices including identity matrix construction and decomposition.

def identity(matrix_type):
    """
    Create an identity matrix of the specified type.

    Args:
        matrix_type: Matrix class (e.g., mat4, mat3, dmat4)

    Returns:
        Identity matrix of the specified type

    Example:
        identity_4x4 = glm.identity(glm.mat4)
    """

def decompose(ModelMatrix, Scale, Orientation, Translation, Skew, Perspective):
    """
    Decompose a transformation matrix into its components.

    Args:
        ModelMatrix: 4×4 transformation matrix to decompose
        Scale: vec3 to receive scaling factors (output)
        Orientation: quat to receive rotation (output)  
        Translation: vec3 to receive translation (output)
        Skew: vec3 to receive skew factors (output)
        Perspective: vec4 to receive perspective factors (output)

    Returns:
        Boolean indicating success of decomposition
    """

Matrix Arithmetic

All matrix types support standard arithmetic operations through operator overloading:

Addition: m1 + m2 - Component-wise addition
Subtraction: m1 - m2 - Component-wise subtraction
Matrix Multiplication: m1 * m2 - Standard matrix multiplication
Scalar Multiplication: m * scalar - Scale all components
Vector Multiplication: m * v - Transform vector by matrix
Negation: -m - Component-wise negation
Column Access: m[i] - Access matrix columns as vectors
Comparison: m1 == m2, m1 != m2 - Component-wise equality

Matrix-Vector Operations

# Matrix-vector multiplication examples:
# For mat4 * vec4: transforms 4D vector (typically homogeneous coordinates)
# For mat3 * vec3: transforms 3D vector (rotation, scaling)
# For mat2 * vec2: transforms 2D vector

# The following operations are supported through operator overloading:
# result_vec4 = mat4_instance * vec4_instance
# result_vec3 = mat3_instance * vec3_instance  
# result_vec2 = mat2_instance * vec2_instance

Usage Examples

from pyglm import glm

# Create matrices
identity_4x4 = glm.mat4()  # 4×4 identity matrix
diagonal_3x3 = glm.mat3(2.0)  # 3×3 matrix with 2.0 on diagonal

# Create from column vectors
col0 = glm.vec3(1, 0, 0)
col1 = glm.vec3(0, 1, 0) 
col2 = glm.vec3(0, 0, 1)
matrix_3x3 = glm.mat3(col0, col1, col2)

# Matrix operations
transposed = glm.transpose(matrix_3x3)
inverse_mat = glm.inverse(matrix_3x3)
det = glm.determinant(matrix_3x3)  # Should be 1.0 for identity

# Matrix arithmetic
m1 = glm.mat3(1.0)  # Identity
m2 = glm.mat3(2.0)  # Diagonal with 2.0
sum_matrix = m1 + m2  # Component-wise addition
product = m1 * m2     # Matrix multiplication

# Transform vectors
point = glm.vec3(1, 2, 3)
transformed = matrix_3x3 * point

# Access matrix columns
first_column = matrix_3x3[0]  # vec3
matrix_3x3[1] = glm.vec3(0, 2, 0)  # Set second column

# 4×4 matrices for 3D graphics
model_matrix = glm.mat4()
view_matrix = glm.mat4()
projection_matrix = glm.mat4()

# Combined transformation (applied right to left)
mvp_matrix = projection_matrix * view_matrix * model_matrix

# Transform homogeneous coordinates
homogeneous_point = glm.vec4(1, 2, 3, 1)  # (x, y, z, w)
transformed_point = mvp_matrix * homogeneous_point

# Matrix decomposition (4×4 only)
scale = glm.vec3()
orientation = glm.quat()
translation = glm.vec3()
skew = glm.vec3()
perspective = glm.vec4()

success = glm.decompose(model_matrix, scale, orientation, translation, skew, perspective)

# Different precision matrices
double_matrix = glm.dmat4()  # Double precision
integer_matrix = glm.imat3()  # Integer matrix
unsigned_matrix = glm.umat2() # Unsigned integer matrix

# Non-square matrices for specialized applications
mat_2x3 = glm.mat2x3()  # 2 columns, 3 rows
mat_3x4 = glm.mat3x4()  # 3 columns, 4 rows

Matrix Layout and Memory

PyGLM matrices use column-major order (like OpenGL):

matrix[0] = first column vector
matrix[1] = second column vector
etc.

For row-major access, use transpose or access individual elements through the column vectors:

# Column-major access (preferred)
first_column = matrix[0]
element = matrix[column][row]

# Get element at row 2, column 1
element = matrix[1][2]  # matrix[column][row]

The memory layout is compatible with OpenGL's expected matrix format, making it easy to pass matrices directly to graphics APIs using the value_ptr() function.

Install with Tessl CLI