pyGameMath · the gem package

Graphics mathematics, in Python¶

Vectors, transformations, rotations, curves and lighting—small, readable tools for understanding and using graphics mathematics. The gem package is pure Python, with standard-library ctypes integration and six as its only runtime dependency.

Get started Explore the tutorials Browse the API

Your first calculation¶

Install the current repository to use the audited development code:

python -m pip install "git+https://github.com/AlexMarinescu/pyGameMath.git"

from gem.vector import Vector

velocity = Vector(3, [3, 4, 0])
direction = velocity.normalize()  # A fresh unit direction; velocity is preserved.
assert velocity.magnitude() == 5.0
assert direction.vector == [0.6, 0.8, 0.0]
assert velocity.vector == [3, 4, 0]

Follow the installation guide for a virtual environment and compatibility details, then try the quick start.

A practical mathematical core¶

Vectors and algebra¶

Component arithmetic, dot and cross products, stable norms, matrix products and inverses. Start with displacement and direction.

Vectors tutorial · Vector API · Matrix API

Transformations and rotations¶

Compose row-vector transforms, follow camera coordinates and interpolate quaternion orientations. See the order of operations in the results.

Transforms · Quaternions · Camera coordinates

Curves and geometry¶

Quadratic/cubic Bezier evaluation and adaptive sampling, Plane/Ray representations and their supported geometric operations.

Bezier paths · Planes and rays · Geometry APIs

Functions and lighting¶

Legendre functions and real spherical harmonics: project radiance, rotate coefficients analytically and reconstruct diffuse irradiance.

Lighting tutorial · Legendre · SH API

See the mathematics¶

Row-vector transformations and composition — Scale, rotation and translation evaluated through gem's Matrix APIs. Dashed shapes are the original; solid shapes show the transformed result. Inspect the coordinates and composition order.

Diffuse sphere under the original asymmetric HDR lighting — Original L2 spherical-harmonic lighting.

The same sphere after active plus-90-degree Z lighting rotation — Active +90° Z rotation; identical camera, material and display settings.

These CPU reference images are generated from actual gem calculations. The HDR workflow connects canonical RGB coefficients to Python and GLSL evaluation. Explore the visual gallery or regenerate its assets.

Know the conventions¶

Matrices use row-major storage and row-vector mathematics: M * v evaluates the row product vM, and A * B applies A then B. Quaternions store [w,x,y,z] and use Hamilton multiplication. Returning operations and in-place operations have explicit ownership contracts.

Read conventions and mathematical notation before connecting another graphics API. The numerical accuracy tutorial explains finite precision and the limits of the supported domains.

Choose a learning path¶

Movement and animation: vectors → transforms → quaternions → Bezier paths.
Camera and picking: transforms → camera coordinates → planes and rays.
Lighting references: numerical accuracy → SH lighting → HDR environment workflow.

The tutorial index lists all nine tutorials, prerequisites and independent checks. Use the API reference for exact signatures and input/output contracts.

Development status¶

gem 1.0 is in preparation with its mathematical API feature scope frozen. Version 1.0.0 is prepared but not published; historical PyPI 0.1.12 does not contain these audited modernizations. CPython 3.10–3.14 is tested on Linux x86_64. Other platforms and PyPy remain unverified; Python 2.7 is unsupported.

See compatibility, release information and the canonical roadmap for supported, legacy and planned functionality. gem supplies mathematical primitives for graphics tools and reference calculations; rendering, visibility tracing and physics systems remain separate concerns.

Created by Alex Marinescu. Source and examples use the BSD 2-Clause license. See contributing and website verification.