PyNGL

PyNGL is the full Python version of NGL, the NCCA graphics library used for teaching 3D computer graphics at the NCCA Bournemouth University. It provides a consistent set of 3D math primitives, geometry loaders, and rendering back-ends for OpenGL, WebGPU, and Qt (PySide6).

Full documentation, tutorials and API reference: https://ncca.github.io/PyNGL/

Features

• 3D math — Vec2/3/4, Mat2/3/4, Quaternion, Transform, Plane, BBox, and the Vec*Array containers, all backed by NumPy float32 with a consistent, well-tested API.
• Geometry — Wavefront OBJ loading (Obj), procedural primitives (PrimData / Primitives), and Bézier curves.
• OpenGL rendering — shader management (ShaderLib), VAO abstractions, textures, and freetype-based text.
• WebGPU rendering — a parallel pipeline stack targeting wgpu.
• Qt Widgets & QML — ready-made PySide6 widgets (ncca.ngl.widgets) and Qt Quick components (ncca.ngl.qml) for editing/displaying NGL math types in a GUI, plus camera event handling.

Installation

PyNGL is published on PyPI as ncca-ngl and the project uses uv.

Add it to a project:

uv add ncca-ngl

Or install into the current environment:

uv pip install ncca-ngl

The importable module is ncca.ngl:

from ncca.ngl import Vec3, look_at, perspective

eye = Vec3(0, 2, 5)
view = look_at(eye, Vec3(0, 0, 0), Vec3(0, 1, 0))
proj = perspective(45.0, 16.0 / 9.0, 0.1, 100.0)

Note: the OpenGL, WebGPU and Qt back-ends require a real graphics context and are imported from their sub-packages, e.g. from ncca.ngl.opengl import ShaderLib and from ncca.ngl.webgpu import ....

Development

Clone the repository and sync the environment (including dev dependencies):

git clone https://github.com/NCCA/PyNGL.git
cd PyNGL
uv sync

Testing

uv run pytest                                   # default (non-GPU) test suite
uv run pytest --cov=src --cov-report=term-missing  # with coverage

Tests that need a real graphics context are deselected by default and only run when their marker is requested:

uv run pytest -m opengl
uv run pytest -m webgpu
uv run pytest -m qt
./test_all.sh

Linting & formatting

uv run ruff format src/
uv run ruff check src/

Documentation

A full class listing and documentations can be found here :-

• Docs site: https://ncca.github.io/PyNGL/
• Getting started / tutorials: https://ncca.github.io/PyNGL/tutorials/ (Getting Started and Tutorials sections)

The site covers the math API design rules, vectors/matrices/quaternions, transforms, cameras and projections, geometry, and the full module-by-module API reference.

Knowledge wiki

Alongside the API reference, wiki/ is an agent-maintained knowledge base about how PyNGL works — architecture narratives, module deep-dives, design decisions, and gotchas — written for both people and coding agents. Start at wiki/index.md.

Every page records which source files it describes and the commit it was last verified against. To check the wiki is in sync with the code:

uv run wiki/tools/check_sync.py

Exit code 0 means every page is fresh; stale pages are listed with the source files that changed. If you use Claude Code, /wiki status, /wiki update, and /wiki build maintain the wiki for you (see .claude/skills/wiki/SKILL.md).

AI Usage

This project has use various AI tools (Claude and Codex and OpenCode) to assist with development.

The initial phases were for the full port of NGL to PyNGL (C++ to Python conversion) and additional testing. Most of the work is shown in the docs section of the repository, and I have also written about various things on my blog here.

There will be a full write-up of my setup and usage of AI on the Blog soon.

License

See LICENSE.txt or just use the Beerware License