Practical graphics mathematics with gem¶
Learn how to turn the existing mathematical primitives into movement, transforms, camera coordinates, geometric queries and lighting references. Each guide explains the calculation before checking independently known values. Complexity labels estimate prerequisites, not runtime cost. Allow roughly 15–25 minutes per guide.
Use current repository installation, not the historical PyPI release. All Python blocks run independently with the installed development package, standard library and existing six dependency; no NumPy, OpenGL context, native backend or renderer is needed. Reference verification is CPython 3.12/Linux, not a new support matrix or Python 2.7 claim.
Choose a learning path¶
| Level | Tutorial | Prerequisites / practical outcome |
|---|---|---|
| Beginner | Vectors and movement | Coordinates and basic algebra; displacement, facing and speed-limited movement |
| Beginner → intermediate | Object transformations | Vectors; transform a point group and recover local coordinates |
| Intermediate | Camera and projection | Matrix composition; trace world → clip → window and back |
| Intermediate | Quaternion orientation | Trigonometry and transforms; interpolate object/camera directions |
| Intermediate | Bezier motion paths | Vectors and a little differentiation; distinguish parameter time from distance |
| Intermediate | Planes, rays and picking | Dot products and camera tutorial; derive a local geometric query |
| Advanced | Spherical-harmonics lighting | Dot products, integration concept; project, rotate and convolve RGB lighting |
| Intermediate | Graphics memory interoperability | Matrix layout, basic ctypes; inspect upload-ready memory without GPU calls |
| Beginner → advanced | Numerical accuracy | Floating-point arithmetic; choose tolerances and recognize domain limits |
For movement, follow vectors → transforms → quaternions → curves. For picking, follow transforms → camera → geometry. For lighting references, follow vectors → numerical accuracy → lighting → the existing HDR/SH workflow.
How to use the examples¶
Copy a complete Python block into a file or interactive environment. Blocks include imports and assertions; displayed rounded values explain the result, while checks use unrounded quantities. No long companion script or additional asset is required in this phase. Local functions in examples are educational calculations, not newly exported gem APIs. The existing HDR example remains the longer executable workflow.
Verification and coverage records every checked block and the installed-wheel/sdist runs. Open decisions links unresolved API policies without choosing new behavior. Use the API reference for exact signatures, shared conventions for units/ownership and ROADMAP.md for planned features.
Return to getting started or the documentation index.