GitHub repository | Documentation
Spatial Geometry provides simple 3D shape primitives -- cuboids, cylinders, spheres, and triangle meshes -- for representing robot links, obstacles, and other geometry in a scene. Every shape carries a pose (position and orientation) and an optional colour, and can be tested for distance and collision against any other shape using Coal.
It's used by the Robotics Toolbox for Python to describe robot link geometry, and by Swift to render scenes in the browser.
import spatialgeometry as gm
from spatialmath import SE3
cube = gm.Cuboid([1, 1, 1], pose=SE3(0, 0, 0))
sphere = gm.Sphere(0.5, pose=SE3(2, 0, 0), color="red")
d, p1, p2 = cube.closest_point(sphere, inf_dist=10)
cube.iscollided(sphere)See the documentation for the full API reference and more examples, including how to display shapes with Swift.
pip install spatialgeometryFor browser runtimes (JupyterLite/Pyodide), use a pure-Python wheel build:
SPATIALGEOMETRY_BUILD_EXTENSION=0 python -m build --wheelThis disables native C-extension compilation and produces a wheel that uses the
Python scene backend (spatialgeometry.scene).
Collision functionality depends on Coal and is not expected to work in JupyterLite.
For collision support:
pip install spatialgeometry[collision]This installs Coal and trimesh. Coal publishes prebuilt wheels for macOS (including Apple Silicon/arm64) and Linux — no conda or manual build steps required there.
Windows note: Coal doesn't currently install via pip on Windows (one of its own dependencies,
cmeel-assimp, has no Windows wheel in the version range Coal needs), so thecollisionextra skips it there and collision checking is unavailable viapipon Windows. Everything else in the package works normally.Workaround: conda-forge publishes
coal-pythonbuilt forwin-64against its own assimp, sidestepping the missing wheel entirely:conda install -c conda-forge coal-python pip install spatialgeometry trimesh
If you don't need collision checking but do want to work with mesh files --
e.g. Mesh.corners()/bounds()/extents() for a mesh's bounding box, which
reads the file via trimesh but never touches Coal at
all -- install just that piece:
pip install spatialgeometry[mesh]Unlike collision, this works on Windows too: trimesh has no Windows-wheel
problem of its own, only Coal does.
For development, the provided environment.yml installs the package in
editable mode with all dev and collision extras:
conda env create -f environment.yml
conda activate spatialgeometry-devMIT — see LICENSE.