https://github.com/shblock/spatium

🚀Spatium: a fast python spatial math library
https://github.com/shblock/spatium

cython cython-library fast linear-algebra math math-library python spatial-maths vector

Last synced: 3 months ago
JSON representation

🚀Spatium: a fast python spatial math library

• Host: GitHub
• URL: https://github.com/shblock/spatium
• Owner: shBLOCK
• License: lgpl-3.0
• Created: 2023-09-03T01:14:54.000Z (almost 3 years ago)
• Default Branch: master
• Last Pushed: 2024-11-21T09:29:42.000Z (over 1 year ago)
• Last Synced: 2025-12-15T14:23:08.293Z (6 months ago)
• Topics: cython, cython-library, fast, linear-algebra, math, math-library, python, spatial-maths, vector
• Language: Python
• Homepage: https://pypi.org/project/spatium
• Size: 1.3 MB
• Stars: 8
• Watchers: 1
• Forks: 0
• Open Issues: 9
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.txt

Awesome Lists containing this project

README

          
# 🚀Spatium: a fast python spatial math library

[![PyPI Version](https://img.shields.io/pypi/v/spatium?label=PyPI)](https://pypi.org/project/spatium)

[![Python Version](https://img.shields.io/pypi/pyversions/spatium?label=Python)](https://pypi.org/project/spatium)




![Language](https://img.shields.io/badge/Language-Cython-FEDF5B)

![Python Implementation](https://img.shields.io/pypi/implementation/spatium?label=Implementation)

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)




[![Codegen](https://github.com/shBLOCK/spatium/actions/workflows/codegen.yml/badge.svg)](https://github.com/shBLOCK/spatium/actions/workflows/codegen.yml)

[![Tests](https://github.com/shBLOCK/spatium/actions/workflows/tests.yml/badge.svg)](https://github.com/shBLOCK/spatium/actions/workflows/tests.yml)

[![Release](https://github.com/shBLOCK/spatium/actions/workflows/release.yml/badge.svg)](https://github.com/shBLOCK/spatium/actions/workflows/release.yml)

[![Benchmark](https://github.com/shBLOCK/spatium/actions/workflows/benchmark.yml/badge.svg)](https://github.com/shBLOCK/spatium/actions/workflows/benchmark.yml)

[![Charts](https://github.com/shBLOCK/spatium/actions/workflows/charts.yml/badge.svg)](https://github.com/shBLOCK/spatium/actions/workflows/charts.yml)

## ⚙️Main features

- **Fast** Pure Cython Implementation

  - ~***16x*** faster than pure python(3.12) implementation

- Spatial Math

  - [Vector](https://github.com/shBLOCK/spatium/wiki#vectors)

    - Operators +, -, *, /, @(dot), ^(cross), |(distance) ...

    - Fast (compile-time) swizzling (e.g. `Vec3(1, 2, 3).zxy`)

    - Flexible constructor (e.g. `Vec3(Vec2(1, 2), 3)`)

    - Iterating and unpacking (e.g. `x, y, z = Vec3(1, 2, 3)`)

    - Works with other libraries (pygame, numpy, ...)

  - Transform

    - [Transform2D](https://github.com/shBLOCK/spatium/wiki#transform2d) & [Transform3D](https://github.com/shBLOCK/spatium/wiki#transform3d)

  - Double-precision floats

- Pythonic & GLSL-like interface

- Custom code generation

  - IDE-friendly stubs

Please refer to the [wiki](https://github.com/shBLOCK/spatium/wiki) for more details

## 📈Benchmark

[![Benchmark Results](https://github.com/shBLOCK/spatium/raw/master/benchmark/charts/latest.svg)](https://github.com/shBLOCK/spatium/tree/master/benchmark/charts)

## 🔧Implementation details

- **Codegen!**  

  Custom code generation is used throughout this library.


  Every swizzle pattern and constructor are implemented as individual methods and properties (For performance reasons).


  As a result, code generation is required so that I don't have to maintain 50,000+ lines of code by hand...


  Besides, it also handles vector classes of every dimension and type (e.g. Vec2 Vec3 Vec2i Vec3i) are generated from the same template, so a lot of repetitive code is avoided.


  There's also a stub generator that generates stub files from the cython code generated by codegen.

## Credits

- This library is partially inspired by [Godot](https://godotengine.org/)'s math library.

## Notes

- This library was originally named GdMath, as I originally used this to bridge Python and Godot and focus on gamedev.




As development went on,

I realized that it has become a versatile spatial math library which is also one of the fastest,

I also found it useful in many projects.




Thus, I've decided to rename it to Spatium (since Spatial was taken), before it (possibly) gets used by more people.