spatialgeometry 1.2.0__tar.gz → 1.4.0__tar.gz

spatialgeometry-1.4.0/.gitattributes

@@ -0,0 +1 @@
+spatialgeometry/cpp-extension/Eigen/** linguist-vendored

{spatialgeometry-1.2.0 → spatialgeometry-1.4.0}/.github/workflows/build.yml

@@ -67,7 +67,7 @@ jobs:
 
       - name: Install docs dependencies
         run: |
-          pip install .[docs]
+          pip install .[docs,collision]
           pip install sympy
           sudo apt-get install -y graphviz
 

{spatialgeometry-1.2.0 → spatialgeometry-1.4.0}/.github/workflows/cibuildwheel.yml

@@ -1,5 +1,13 @@
 # Build wheels for all platforms and publish to PyPI.
-# Triggered on GitHub release creation or manually via workflow_dispatch.
+#
+# To ship a release: bump the version in pyproject.toml, merge that to
+# main, then on GitHub go to Releases -> "Draft a new release", pick a
+# tag matching the new version, and click "Publish release". That single
+# click is the only trigger for this workflow -- it builds every wheel
+# (including Pyodide/wasm32), uploads everything to PyPI, and attaches
+# the Pyodide wheel to the release as a downloadable asset. There is no
+# separate manual/workflow_dispatch path, so there's only one way to
+# publish and it always does the full job.
 #
 # Uses OIDC trusted publishing -- no stored PyPI token required.
 
@@ -7,8 +15,7 @@ name: Publish to PyPI
 
 on:
   release:
-    types: [created]
-  workflow_dispatch:
+    types: [published]
 
 jobs:
   build_wheels:
@@ -84,7 +91,7 @@ jobs:
   upload_pyodide_asset:
     name: Attach Pyodide wheel to GitHub release
     needs: build_pyodide
-    if: github.event_name == 'release' && needs.build_pyodide.result == 'success'
+    if: needs.build_pyodide.result == 'success'
     runs-on: ubuntu-latest
     permissions:
       contents: write

{spatialgeometry-1.2.0 → spatialgeometry-1.4.0}/.gitignore

@@ -159,6 +159,7 @@ devel_isolated/
 # Ignore generated docs
 *.dox
 *.wikidoc
+docs/source/generated/
 
 # eclipse stuff
 .project

spatialgeometry-1.4.0/AGENTS.md

@@ -0,0 +1,23 @@
+# spatialgeometry — Agent Instructions
+
+Part of the RVC ecosystem. **Read [rvc-ecosystem/AGENTS.md](https://github.com/petercorke/rvc-ecosystem/blob/main/AGENTS.md) first** — it defines shared conventions: repo ownership, math invariants, dependency boundaries, git/PR workflow, code standards, tech-debt tracking. This file only adds what's specific to this repo.
+
+| | |
+|---|---|
+| PyPI package | `spatialgeometry` |
+| Nickname | SG |
+| Owner | Jesse Haviland (`jhavl`) — **not Peter Corke** |
+| Default branch | `main` |
+| Contribution model | **PR only** |
+
+## Notes specific to this repo
+
+- **This is not Peter's repo.** Collaborator push access exists but must never be used —
+  every change goes through a PR, even trivial docs fixes. If your local clone has a `fork`
+  remote (Peter's copy) and an `origin` remote (this upstream repo), push branches to `fork`
+  and open the PR from there. Never push to `origin`.
+- Compiles `nanobind` C++ extensions via `scikit-build-core`.
+- Depends on `spatialmath` only. `robotics-toolbox-python` and `swift` both depend on this
+  repo — a breaking API change here has two downstream repos to check.
+- Default branch is `main` — this repo has already migrated off `master`; don't assume
+  otherwise from old references.

spatialgeometry-1.4.0/CHANGELOG.md

@@ -0,0 +1,224 @@
+# Changelog
+
+Notable changes to this project are documented in this file. Starts from
+v1.2.0 — earlier releases aren't documented retroactively.
+
+## [1.4.0] - 2026-08-23
+
+### New
+
+- **`Ellipsoid` shape**: a native `coal.Ellipsoid` collision primitive,
+  parameterised as `radii=[rx, ry, rz]` (three semi-axis lengths), following
+  the same pattern as `Sphere`/`Cylinder`/`Cuboid`.
+- **`Shape.corners()`/`bounds()`/`extents()`** for a shape's axis-aligned
+  bounding box — `corners(world=False)`, `bounds(world=False)`,
+  `extents(world=False)`; pass `world=True` for the posed shape's envelope
+  in the world frame. Implemented for `Cuboid`/`Box`, `Sphere`, `Cylinder`,
+  `Mesh`; `Axes`/`Arrow`/`Polyline` raise `NotImplementedError` for now rather
+  than a silently wrong value.
+- **`SceneNode.tree()`/`tree_children()`**: render a scene graph (or just
+  one node's own subtree) as human-readable indented text, one `repr()` per
+  line, with `tree()` marking the calling node's position with a trailing
+  `<==`. `SceneGroup` needs no special-casing — the tree walk is generic.
+- **`CollisionShapeGroup`**: an ordered, list-like collection of
+  `CollisionShape`/`CollisionShapeGroup` instances that itself behaves like
+  a single collision-checkable shape — `iscollided()`/`closest_point()` work
+  in every combination of shape/group, including arbitrarily nested groups.
+  Comes with a new **`&` operator** (`a & b` is `a.iscollided(b)`) that
+  works uniformly across shapes and groups.
+- **`Shape.opacity` property**: a convenient way to get/set just the alpha
+  channel of `color` without needing to know or re-specify the current
+  `(r, g, b)`. `set_alpha()` is deprecated in its favor.
+- **`Arrow.FromTo(start, end)`**: construct an arrow spanning two 3-vectors
+  directly, with `length` and `pose` computed automatically instead of by
+  hand.
+- Tutorial introduction: substantially expanded, with worked examples
+  covering shape creation, bounding boxes, collision checking, scene
+  graphs, and groups.
+
+### Mesh
+
+A cluster of related `Mesh` improvements landed together this release:
+
+- **New `y_up` param**, for mesh files authored with +Y as "up" (a common
+  convention in general 3D/graphics tooling) rather than this ecosystem's
+  +Z-up convention — applies a fixed correction to the mesh's own vertex
+  data at load time, so it survives re-posing/animation. `scale` also now
+  accepts a single scalar (uniform on all 3 axes), not just a 3-element
+  list.
+- **New `mesh` extra** (`pip install spatialgeometry[mesh]`): just
+  `trimesh`, split out of `collision` — unlike Coal, trimesh has no
+  Windows-wheel problem, so mesh-only functionality that never touches Coal
+  (`corners()`/`bounds()`/`extents()`, which work independent of
+  `collision=True/False`) is now reachable via `pip` on Windows.
+  `collision` still pulls in `mesh` transitively, nothing changes for
+  existing `collision` users.
+- **Now tracks whether an explicit color was ever given**
+  (`use_vertex_colors` in `to_dict()`), so a renderer has a signal to
+  prefer a mesh file's own baked-in per-vertex/per-face colors over a flat
+  default grey when no color was ever actually requested.
+- **`filename`/`y_up` are now read-only.** There's no use case for
+  repointing an existing `Mesh` at a different file or a different up-axis
+  convention — construct a new one instead. (Both are also only ever read
+  once, inside `_init_coal()`, which is cached after first use — a setter
+  would have silently done nothing after a shape's first
+  `closest_point()`/`iscollided()` call.)
+- **`Mesh(filename=...)` now raises `FileNotFoundError` at construction**
+  if the file doesn't exist, instead of deferring the failure to the first
+  `closest_point()`/`iscollided()` call.
+- **Fixed: `corners()`/`bounds()`/`extents()` now correctly apply the
+  `y_up` correction.** Previously the `+Y → +Z` correction was only applied
+  to the collision geometry, not the bounding box, so a `y_up=True` mesh's
+  bounding box didn't match its actual (corrected) orientation.
+
+### Changed
+
+- **`repr()` now shows `color`, and `opacity` when not fully opaque** —
+  previously only subclass-specific params (`radius`, `scale`, ...) and
+  `pose` were shown.
+- **`Path` shape renamed to `Polyline`**, to avoid clashing with the
+  standard library's `pathlib.Path` — a source of confusing type errors in
+  code that imports both. `Path` remains available as a deprecated alias
+  (`class Path(Polyline)`), emitting a `FutureWarning` on construction.
+- **`SceneNode.__init__`'s `T=` kwarg renamed to `pose=`**, now accepting
+  `SE3` as well as a raw `ndarray` — matching the convenience `Shape` (and
+  every concrete shape) already had. `SceneNode` is the base class for the
+  whole scene graph, so this had been implemented one level too low;
+  `SceneGroup` previously had no way to accept an `SE3` pose at
+  construction, only a raw `ndarray` via `T=`.
+- **`update()` is now the public method for refreshing the scene graph's
+  world transforms**, replacing `_propogate_scene_tree()` (a straight
+  misspelling of "propagate", and not actually private in practice —
+  called directly by `robotics-toolbox-python` and `swift`, and
+  demonstrated in this project's own tutorial). `_propogate_scene_tree()`
+  still works, emitting a `FutureWarning`, for one release cycle.
+- **Color-parsing error messages now name matplotlib explicitly** and link
+  to its full named-colors reference, rather than a bare "invalid color
+  name" with no pointer to where valid names are defined.
+- Internal: `src/spatialgeometry/core` renamed to `cpp-extension`, for
+  naming consistency — nothing importable changed.
+- Docs: substantial API reference cleanup — a new page on mesh file format
+  support (which formats work for display vs. collision, and why);
+  `autoclass_content='both'` so each class's own constructor parameters
+  (previously invisible on most pages, since Sphinx's default only shows
+  the class docstring) now actually appear; several stale/incorrect
+  passages fixed in the intro tutorial.
+
+### Fixed
+
+- **`Cylinder`'s collision geometry was half its documented length.**
+  `_init_coal()` passed `length / 2.0` to Coal on the mistaken assumption
+  its constructor took a half-length — it takes the full length, so
+  `Cylinder(radius=1, length=4)`'s actual collision geometry was only 2
+  units tall. No existing test exercised a cylinder along its own axis, only
+  radially, so this went undetected.
+- **`scene_parent` assignments that would create a cycle are now rejected**
+  (`a.scene_parent = b; b.scene_parent = a`, a self-loop, or a longer
+  cycle). Previously nothing validated this, and the scene-graph
+  root-finding walk (used by `update()` every call) has no cycle detection
+  of its own — a cycle made it spin forever rather than raise.
+- **`SceneGroup`'s list mutators (`append`/`extend`/`insert`/`remove`/
+  `pop`/`clear`/item assignment) didn't wire `scene_parent`** — elements
+  added this way never actually became children in the scene graph, only
+  in the list. The constructor also now accepts an initial list
+  (`SceneGroup([a, b])` previously raised `TypeError`).
+- `repr()` could leak `numpy.float64` values (e.g. `np.float64(1.0)`
+  instead of `1.0`) into `color`/`opacity` — harmless functionally, ugly in
+  a repr.
+
+## [1.3.0] - 2026-08-03
+
+### New
+
+- **`Path` shape**: a polyline through a sequence of waypoints — straight
+  segments joining consecutive points, for drawing paths and trajectories
+  in the scene. `radius`/`linewidth` mirror `Arrow`'s existing mutual
+  exclusivity (a real tube when `radius > 0`, a line honoring `linewidth`
+  otherwise). Deliberately a plain `Shape`, not `CollisionShape` — Coal has
+  no native "tube along a polyline" primitive.
+- **`Axes` gains `arrows=False`** (render each axis as a colored `Arrow`
+  instead of a plain line) plus `radius`/`linewidth`, passed straight
+  through to each constituent `Arrow` when `arrows=True`.
+- **`Arrow` gains `linewidth`**: when `radius == 0` (the existing
+  "shaft is a line" fallback), `linewidth` now actually controls that
+  line's width in pixels — previously uncontrolled, whatever the browser's
+  default happened to render.
+- **`__version__`** is now exposed, matching the other packages in the
+  toolbox family (`spatialmath-python`, `robotics-toolbox-python`, `bdsim`,
+  `machinevision-toolbox-python`).
+
+### Changed
+
+- **`Shape` and `CollisionShape` are now abstract base classes.** Neither
+  was meant to be instantiated directly — `Shape.to_dict` and
+  `CollisionShape._init_coal` are `@abstractmethod`; every concrete shape
+  already overrode both.
+- **`T` (pose) moved from `Shape` up to `SceneNode`.** It was a thin
+  wrapper with nothing `Shape`-specific about it; moving it up means
+  `SceneGroup` (and any future `SceneNode` subclass) gets the same
+  convenient, `SE3`-accepting pose property that only `Shape` had before —
+  so a whole group of shapes can now be moved as one unit via `group.T`.
+- **`repr()`/`str()` rewritten.** `repr()` previously showed only the
+  shape's `stype` string plus translation — not unambiguous (`Box`, a
+  deprecated alias of `Cuboid`, was indistinguishable from `Cuboid`) and
+  broke visually the moment more than one shape appeared together (e.g. in
+  a list, or a `SceneGroup`). Now single-line and constructor-style, e.g.
+  `Cylinder(radius=1.0, length=2.0, pose='t = 0, 0, 0; rpy/zyx = 0°, 0°, 0°')`.
+- **Type hints modernized** across the scene-graph/shape classes —
+  `typing.Union`/`List`/`Dict`/`Tuple`/`Optional` replaced with
+  `X | Y`/`list`/`dict`/`tuple`, and filled in on several public
+  constructors/properties that had none at all.
+- Docs: the Sphinx build's `docs` extra now also installs `collision`, so
+  the intro chapter's `closest_point()`/`iscollided()` example actually
+  runs instead of silently baking a traceback into the rendered page.
+- Docs: intro chapter rewritten with mesh/collision worked examples, mouse
+  navigation controls, and scene-graph parenting; `sphinx-copybutton`,
+  `sphinx-codeautolink`, `sphinxcontrib-mermaid`, and a `make livehtml`
+  target wired up for faster doc iteration.
+
+### Fixed
+
+- **`Shape.color`'s setter left an all-integer color input as
+  `numpy.int64`** (e.g. `color=[1, 0, 0, 1]`, a very natural way to write
+  "opaque red") rather than a plain `float` — `self.color[3]` (opacity)
+  being `int64` broke real (non-mocked) `json.dumps()` sends. Never caught
+  by the existing test suite since those tests are `FakeBrowser`-mocked.
+- **`SceneNode._T`'s setter referenced a nonexistent `self.parent.wT`**
+  (should have been `self._scene_parent._wT`) — setting a node's pose
+  while it already had a `scene_parent` raised `AttributeError` instead of
+  composing the world transform. No test coverage existed for this path
+  before.
+- `SceneNode.scene_parent`'s return type was annotated `Type["SceneNode"]`
+  (the class itself) rather than an instance; corrected to
+  `SceneNode | None`.
+
+## [1.2.0] - 2026-07-28
+
+First release since v1.1.0 (2023) — mostly packaging and build-system work, plus a collision-backend swap.
+
+### New
+
+- **Coal replaces PyBullet as the collision backend.** PyBullet wouldn't build with clang on macOS, so all collision checking now runs on [Coal](https://github.com/coal-library/coal) instead.
+- **NumPy 2 support.**
+- **Pyodide (WebAssembly) wheels**, so spatialgeometry can run in-browser (e.g. JupyterLite), alongside the usual platform wheels. Since there's no C++ compiler to target under Pyodide, that wheel ships a pure-Python fallback for the scene-graph transform math instead of the compiled extension — same API, just not compiled.
+- **Prebuilt wheels for more platforms**: native Linux arm64 and macOS arm64 in addition to Linux/Windows x86_64 — no compiler needed on install for any of them.
+
+### Changed
+
+- **Build system rewritten**: the C++ extension now builds with **nanobind + scikit-build-core** (previously a hand-rolled hatchling build hook). Faster builds, and the vendored Eigen copy was trimmed from Eigen's full 337-file tree down to the ~175 files this project actually uses.
+- **Project layout moved to `src/`**, and the build backend moved from setuptools to hatchling and then to scikit-build-core over the course of this work.
+- **Docs rewritten**: the README, intro chapter, and API reference no longer borrow content from the Robotics Toolbox docs — they now describe spatialgeometry on its own terms, with a Swift-based display example.
+- **Dependency cleanup**: `roboticstoolbox` is no longer pulled into the `dev` extra, removing a version-pin collision some installs were hitting.
+
+### Fixed
+
+- macOS build failures caused by PyBullet + clang (resolved by the Coal switch above).
+- NumPy 2 compatibility issues.
+- Windows wheel builds failing over an overly long temp-file path.
+- Several wheel-tagging/build-hook bugs that could produce a stale or wrong-architecture compiled extension, or silently fall back to a non-compiled wheel.
+- The PyPI publish pipeline itself: a workflow bug was letting the Pyodide/wasm32 wheel — which PyPI doesn't accept — get bundled into the same upload batch as the real wheels, aborting the upload partway through. Publishing now uses a single, unambiguous trigger (creating a GitHub Release) that always completes the full publish.
+
+### Known limitations
+
+- Collision checking (Coal) isn't available via `pip` on Windows — one of Coal's own dependencies doesn't publish a Windows wheel. Everything else works there; `pip install spatialgeometry[collision]` will just have no effect on that platform for now.
+  **Workaround:** conda-forge publishes `coal-python` for `win-64` against its own assimp build, so `conda install -c conda-forge coal-python` followed by `pip install spatialgeometry trimesh` gets collision checking working on Windows today.

{spatialgeometry-1.2.0 → spatialgeometry-1.4.0}/CMakeLists.txt

@@ -18,7 +18,7 @@ find_package(nanobind CONFIG REQUIRED HINTS "${NB_DIR}")
 # ---------------------------------------------------------------------------
 # scene — scene-graph transform propagation
 # Eigen is vendored as header-only (Core module only -- see
-# src/spatialgeometry/core/Eigen) in src/spatialgeometry/core/Eigen/
+# src/spatialgeometry/cpp-extension/Eigen) in src/spatialgeometry/cpp-extension/Eigen/
 # scene_nb.cpp is the nanobind glue; math lives inline in that file.
 #
 # Skipped entirely under Pyodide/Emscripten: no compiler there worth
@@ -29,10 +29,10 @@ find_package(nanobind CONFIG REQUIRED HINTS "${NB_DIR}")
 # ---------------------------------------------------------------------------
 if(NOT CMAKE_SYSTEM_NAME STREQUAL "Emscripten")
     nanobind_add_module(scene
-        src/spatialgeometry/core/scene_nb.cpp
+        src/spatialgeometry/cpp-extension/scene_nb.cpp
     )
     target_include_directories(scene PRIVATE
-        src/spatialgeometry/core
+        src/spatialgeometry/cpp-extension
     )
 
     install(TARGETS scene DESTINATION spatialgeometry)

{spatialgeometry-1.2.0 → spatialgeometry-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: spatialgeometry
-Version: 1.2.0
+Version: 1.4.0
 Summary: A Shape and Geometry Description Package
 Keywords: python,robotics,robotics-toolbox,kinematics,dynamics,motion-planning,trajectory-generation,jacobian,hessian,control,simulation,robot-manipulator,mobile-robot
 Author-Email: Jesse Haviland <j.haviland@qut.edu.au>, Peter Corke <rvc@petercorke.com>
@@ -38,9 +38,12 @@ Project-URL: documentation, https://jhavl.github.io/spatialgeometry/
 Project-URL: repository, https://github.com/jhavl/spatialgeometry
 Requires-Python: >=3.10
 Requires-Dist: spatialmath-python>=1.0.0
+Provides-Extra: mesh
+Requires-Dist: trimesh; extra == "mesh"
 Provides-Extra: collision
+Requires-Dist: spatialgeometry[mesh]; extra == "collision"
 Requires-Dist: coal; sys_platform != "win32" and extra == "collision"
-Requires-Dist: trimesh; extra == "collision"
+Requires-Dist: pycollada; extra == "collision"
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"
 Requires-Dist: editables; extra == "dev"
@@ -53,7 +56,10 @@ Requires-Dist: trimesh; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: sphinx_rtd_theme; extra == "docs"
-Requires-Dist: sphinx-autorun; extra == "docs"
+Requires-Dist: sphinx-pyrunblock; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx-codeautolink; extra == "docs"
+Requires-Dist: sphinxcontrib-mermaid; extra == "docs"
 Description-Content-Type: text/markdown
 
 # Spatial Geometry
@@ -136,6 +142,26 @@ required there.
 > version range Coal needs), so the `collision` extra skips it there and
 > collision checking is unavailable via `pip` on Windows. Everything else
 > in the package works normally.
+>
+> Workaround: conda-forge publishes `coal-python` built for `win-64`
+> against its own assimp, sidestepping the missing wheel entirely:
+>
+> ```shell
+> 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](https://trimesh.org) but never touches Coal at
+all -- install just that piece:
+
+```shell
+pip install spatialgeometry[mesh]
+```
+
+Unlike `collision`, this works on Windows too: trimesh has no Windows-wheel
+problem of its own, only Coal does.
 
 ### conda / conda-forge
 

{spatialgeometry-1.2.0 → spatialgeometry-1.4.0}/README.md

@@ -78,6 +78,26 @@ required there.
 > version range Coal needs), so the `collision` extra skips it there and
 > collision checking is unavailable via `pip` on Windows. Everything else
 > in the package works normally.
+>
+> Workaround: conda-forge publishes `coal-python` built for `win-64`
+> against its own assimp, sidestepping the missing wheel entirely:
+>
+> ```shell
+> 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](https://trimesh.org) but never touches Coal at
+all -- install just that piece:
+
+```shell
+pip install spatialgeometry[mesh]
+```
+
+Unlike `collision`, this works on Windows too: trimesh has no Windows-wheel
+problem of its own, only Coal does.
 
 ### conda / conda-forge
 

{spatialgeometry-1.2.0 → spatialgeometry-1.4.0}/docs/Makefile

@@ -12,7 +12,13 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+# Live-rebuild and reload in the browser on every source change.
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) \
+		--open-browser \
+		--ignore "$(SOURCEDIR)/generated/*"
+
+.PHONY: help livehtml Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).