Math tools for Python games, graphics and simulations.
gem helps you calculate movement, rotate objects, transform 3D coordinates, create smooth curves and approximate lighting—all using regular Python. No NumPy or compiled extensions are required. Its only runtime dependency is six.
Rotate the lighting, keep the object still. These images show the same sphere before and after a 90-degree lighting rotation. They are calculated on the CPU; you don't need a graphics card or an OpenGL window to run the example. Spherical harmonics compress light arriving from many directions into a small set of numbers, making soft lighting easier to calculate. Try the lighting example.
Directions and movement — add vectors to combine movement. Object placement — use matrices to move, rotate and resize a shape. The order of those steps matters.
Smooth turns — quaternions describe rotations and help blend between them. Smooth paths — Bezier curves let you shape a curve with a few control points. Select a diagram for a larger view, its explanation and runnable source.
Every image above comes from the committed, reproducible examples. Explore the gallery or regenerate the diagrams.
For the current features, install from this repository. The older package on PyPI does not include these updates. The prepared distribution version is 1.0.0; it has not been published. CPython 3.10–3.14 is tested on Linux x86_64. Windows, macOS and PyPy remain unverified. In a terminal with Git and Python 3.12:
git clone https://github.com/AlexMarinescu/pyGameMath.git
cd pyGameMath
python3.12 -m venv .venv
.venv/bin/python -m pip install .These commands are for Linux and macOS. On Windows, and for help setting up a separate Python environment, follow the installation guide. It covers PowerShell, Command Prompt, development edits and package details.
A vector is a list of numbers representing a position, direction or movement. Here, three numbers give the X, Y and Z coordinates. Add a movement to a position to find where it ends up:
from gem.vector import Vector
position = Vector(3, [1, 2, 3])
movement = Vector(3, [4, 0, -1])
new_position = position + movement
print(new_position.vector) # [5, 2, 2]The original position stays unchanged. To run this with the environment above,
save it as move.py and use .venv/bin/python move.py.
The quick start also covers matrices,
rotations, curves and lighting.
- Vectors: calculate directions, distances and movement.
- Matrices: move, rotate and resize objects in 2D or 3D; convert coordinates for a camera or screen.
- Quaternions: rotate objects and blend smoothly between orientations.
- Bezier curves: build smooth paths, evaluate points along them and sample curved sections more closely.
- Planes and rays: describe flat surfaces and directed lines, and move or rotate them. Ray intersection queries are not implemented.
- Legendre functions and spherical harmonics: provide the building blocks for approximating light from the surrounding environment, including rotating that lighting and calculating its effect on a diffuse surface.
These are math tools, not a game engine or renderer. You can use them on their own or connect them to your graphics application. The examples explain the coordinate and rotation rules before showing how to combine operations.
- Getting started — installation and first examples.
- Tutorials — learn through practical calculations.
- API reference — functions, arguments and return values.
- Visual examples — diagrams and reproducible lighting.
- Documentation home — browse the complete documentation.
- Build the documentation website locally — build and navigation instructions.
- Contributing — changes, tests and review.
The library is being prepared for a 1.0 release; it is not released yet. Later work is proposed for finding relationships between shapes, generating repeatable noise for procedural content, measuring distance to surfaces (signed distance fields), working with 3D grids (voxels), and calculating light through volumes such as fog. Future C and C++ versions are proposed as separate projects.
These capabilities are planned, not available today, with no promised dates. The development roadmap gives the full direction and priorities.
CPython 3.10–3.14 is tested on Linux x86_64. Windows, macOS and PyPy remain unverified; Python 2.7 and Python <3.10 are unsupported. Version 1.0.0 is prepared but not published. The historical PyPI release does not contain the current code. See the packaging and release guide for support evidence and the outstanding PyPI publishing-authority check.
Some constructors keep references to lists you provide. Read the
ownership and compatibility guide before
sharing mutable data. The conventions explain
coordinate and angle rules. Use gem.bezier, gem.legendre and
gem.spherical_harmonics for current code; older experimental imports remain
available through compatibility re-exports.
Created by Alex Marinescu, originally for learning graphics mathematics and personal OpenGL projects. Licensed under the BSD 2-Clause license, copyright 2015–2026 Alex Marinescu. Historical attribution remains intact.