Release: Collision Name (#2479)

- release #2475 
- release #2474 
- release #2483 
- release #2481 
- release #2486 
- release #2480
- this applies the March 2024 deprecation removing
`Trimesh.remove_degenerate_faces` and `Trimesh.remove_duplicate_faces`.
- moves the `SceneViewer` control instructions from the README to print
on the `h` keypress, and make the default window caption include `h for
help`
- remove `psutil` from dependencies. It was only used to check if a
`scipy.spatial.cdist` call was going to use more than 50% of free system
memory before falling back to a more memory-efficient but slower loop.
This now falls back to a looping method if the `cdist` call is going to
use more than a fixed `4 GB` of memory,
- add check that primitives (i.e. `Cylinder`) mostly override `area` and
`volume` by checking that their primitive area/volume is not exactly
floating point equal to their meshed volume. This caught that `Capsule`
didn't return analytical volume/area which was also fixed. We could
probably make Primitive a multiple inheritance ABC that requires certain
properties but since Primitive already inherits from Trimesh that seems
unnecessary and confusing.
- clean up references to OpenCTM, which [was
deprecated](trimesh/openctm#5) for low use,
being unmaintained, and inflicting a burden on upstream package
management.
- docker images now build with 3.14

Author: mikedh

Makefile

@@ -19,6 +19,9 @@ NAME=trimesh/trimesh
 REPO=docker.io
 IMAGE=$(REPO)/$(NAME)
 
+# the dockerfile location
+DOCKERFILE=helpers/Dockerfile
+
 # the tags we'll be applying
 TAG_LATEST=$(IMAGE):latest
 TAG_GIT_SHA=$(IMAGE):$(GIT_SHA)
@@ -34,12 +37,18 @@ help: ## Print usage help
 # force amd64 builds on non-amd64 hosts (e.g. Apple Silicon)
 export DOCKER_DEFAULT_PLATFORM=linux/amd64
 
+# docker build arguments common to all build paths
+# NEEDS_BUILDCHAIN can probably be false once 3.14 matures a little more
+# `--build-arg=NEEDS_BUILDCHAIN=true`
+
+DOCKER_BUILD_ARGS=--progress=plain --file $(DOCKERFILE) 
+
 # build the output stage image using buildkit
 .PHONY: build
 build: ## Build the docker images
 	DOCKER_BUILDKIT=1 \
 	docker build \
-		--progress=plain \
+		$(DOCKER_BUILD_ARGS) \
 		--target output \
 		--tag $(TAG_LATEST) \
 		--tag $(TAG_VERSION) \
@@ -51,9 +60,9 @@ build: ## Build the docker images
 tests: ## Run unit tests inside docker images.
 	DOCKER_BUILDKIT=1 \
 	docker build \
+		$(DOCKER_BUILD_ARGS) \
 		--target tests \
-		--progress=plain \
-		--build-arg "CODECOV_TOKEN=$(CODECOV_TOKEN)" \
+		--secret id=codecov_token,env=CODECOV_TOKEN \
 		.
 
 # build the docs inside our image and eject the contents
@@ -62,8 +71,8 @@ tests: ## Run unit tests inside docker images.
 docs: ## Build trimesh's sphinx docs
 	DOCKER_BUILDKIT=1 \
 	docker build \
+		$(DOCKER_BUILD_ARGS) \
 		--target docs \
-		--progress=plain \
 		--output html \
 		.
 

README.md

@@ -1,7 +1,7 @@
 Contributing To Trimesh
 =======================
 
-Pull requests are always super welcome! Trimesh is a relatively small open source project and really benefits from the bugfixes, features, and other stuff the 100+ contributors have PR'd, so thanks!
+Pull requests are always super welcome! Trimesh is a relatively small open source project and really benefits from the bugfixes, features, and other stuff the 200+ contributors have PR'd, so thanks!
 
 
 ## Developer Quick Start
@@ -19,6 +19,7 @@ Then when you open a new terminal you can verify it got the right environment wi
 ```
 mikedh@orion:trimesh$ which python
 /home/mikedh/venv/bin/python
+
 mikedh@orion:trimesh$ which pip
 /home/mikedh/venv/bin/pip
 ```
@@ -82,6 +83,20 @@ ruff format
 Trimesh uses the [Sphinx Numpy-style](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy) docstrings which get parsed into the API reference page. 
 
 
+## Deprecations
+
+We try to add a somewhat helpful `DeprecationWarning` one year in advance of a major API change:
+
+```python
+    warnings.warn(
+        "`remove_duplicate_faces` is deprecated "
+        + "and will be removed in March 2024: "
+            + "replace with `mesh.update_faces(mesh.unique_faces())`",
+        category=DeprecationWarning,
+        stacklevel=2,
+    )
+```
+
 ## General Tips
 
 Python can be fast but only when you use it as little as possible. In general, if you ever have a block which loops through faces and vertices it will be basically unusable with even moderately sized meshes. All operations on face or vertex arrays should be vectorized numpy operations unless absolutely unavoidable. Profiling helps figure out what is slow, but some general advice:

docker/openctm.bash

@@ -0,0 +1,33 @@
+Mesh Formats
+=======================
+
+There's lots of mesh formats out there!
+
+
+## Which Mesh Format Should I Use?
+
+Quick recommendation: `GLB`. If you're looking for "the simplest possible ASCII format because I have to write an importer in another language" you should take a look at `OFF`. 
+
+GLTF is nice because it has a [well defined specification](https://github.com/KhronosGroup/glTF/tree/main/specification/2.0), supports most things people would want, and is very fast to load. It's fast because the format has a small JSON header which defines the layout of a packed binary blob, so the arrays can be loaded with `numpy.frombuffer` which is extremely fast. As a counterpoint a format like `3MF` defines each vertex as an `<vertex><x>"1.0123312"</x> ...`, which is almost as far from fast as it is possible to get.
+
+A very popular format is Wavefront `OBJ`. It's supported across many tools, although it lacks a specification and has an internal data structure that requires some pretty heavy conversion to the `trimesh` flat-array format which can lead to some confusion: for example `f 1/2/3 4/5/6 7//7 9/9/9` is a valid face. It's not a bad choice, but going with GLB is probably advisable in most cases.
+
+## Supported Formats
+
+No dependencies indicates a minimal install of just `trimesh` and `numpy` can load the format. If you are working with the textures, images are handled using `pip install pillow`.
+
+| Format | Dependencies | Notes | 
+| ------ | ------------ | ----- |
+| `GLB`/`GLTF` | | A scene format with flat arrays (i.e. very quick loading), wide support, and a well defined specification. Most people should use this is possible. It also supports most things you'd want including texture, point clouds, etc. |
+| `STL`  | | Has both ASCII and binary representations, both of which are supported. This is a very basic format, and it consists of a "triangle soup" with no shared vertices. This format is the reason why `trimesh` has the default `process=True` which merges vertices since an unindexed triangle soup isn't super useful. |
+| `PLY`  | | Has both ASCII and Binary representations, both are supported. It has indexed triangles, and a header format that supports named properties. [Overview](https://paulbourke.net/dataformats/ply/index.html)
+| `OBJ`  | | Wavefront OBJ, relatively slow to parse and may require re-indexing to match the `trimesh` "matching arrays" data structure. |
+| `OFF`  | | Text format that is just vertices and faces in ASCII |
+| `3MF`  | `lxml`, `networkx` | An XML based 3D printing focused mesh format. It  |
+| `3DXML` | `lxml`, `networkx`, `PIL` | Dassault's XML format from CATIA/SolidWorks, the easiest way to get from Solidworks to a nice 3D scene. |
+| `DAE`/`ZAE` | `lxml`, `PIL`, `pycollada` | COLLADA, an XML-based scene format that supports everything. |
+| `STEP`/`STP` | `cascadio` | The only boundary representation format with open-source loaders available. `cascadio` uses OpenCASCADE to convert to GLB before loading. |
+| `XAML` | `lxml` | Microsoft's 3D XAML format which exports from Solidworks |
+| `DXF` | | AutoCAD's drawing format, we only support the ASCII version with 2D geometry. |
+| `SVG` | `svg.path` | We import 2D paths as `trimesh.Path2D` from these, discarding pretty much all visual information other than the curves. |
+| `XYZ` | | Simple ASCII point cloud format with just one coordinate per line. |

docs/content/contributing.md

@@ -12,6 +12,20 @@ Install
 
    install.md
 
+Examples
+==========
+.. toctree::
+   :maxdepth: 1
+	      
+   Examples <examples.rst>
+
+Geometry Formats
+==========
+.. toctree::
+   :maxdepth: 1
+	      
+   Geometry Formats <formats.md>
+   
 Contributing
 ==========  
 .. toctree::
@@ -25,13 +39,6 @@ Docker
    :maxdepth: 1
 
    Docker <docker.md>
-   
-Examples
-==========
-.. toctree::
-   :maxdepth: 1
-	      
-   Examples <examples.rst>
 
 API Reference
 =============

docs/content/formats.md

@@ -4,21 +4,39 @@ Installation
 The only thing required to install `trimesh` is
 [numpy](http://www.numpy.org/).
 
-All other dependencies are \'soft,\' or trimesh will raise the exceptions (usually but not always an `ImportError`) at runtime if a function is called that requires a package that isn\'t installed. If you do the most basic install of `trimesh` it will only install `numpy`:
+All other dependencies are \"soft,\"or `trimesh` will raise the import exceptions (typically an `ImportError`) at runtime if a function is called that requires a package that isn\'t installed. If you do the most basic install of `trimesh` it will only install `numpy`:
 
 ```
 pip install trimesh
 ```
 
-This will enable you to load most formats into numpy arrays: STL, PLY, OBJ, GLB, GLTF.
-
-If you\'d like most soft dependencies which should install cleanly on Mac, Windows, and Linux, you can use the `easy` pip extra:
+This will enable you to load most [formats](/formats.html) into numpy arrays: STL, PLY, OBJ, GLB, GLTF.
 
+To install `trimesh` with the soft dependencies that generally install cleanly on Linux (x86_64), MacOS (ARM), and Windows (x86_64), you can use the `easy` install extra using `pip`:
 ```
 pip install trimesh[easy]
 ```
 
 
+## What makes a dependency `easy`?
+
+"`pip install` always works." What this translates to has changed over time (specifically since MacOS went ARM). The current definition is:
+
+- Using a [current](https://devguide.python.org/versions/) version of CPython.
+- Without a build toolchain installed. So `sdist` that requires compilation is not `easy`: binary wheels are required. 
+- On the latest version of your operating system:
+  - MacOS ARM. ARM took a long time to support because upstream Github Actions runners and `cibuildwheel` had to support it first, but after a few years it has stabilized. MacOS x86_64 wheels will be continued to be built for most projects until [Github turn the lights out in August 2027](https://github.com/actions/runner-images/issues/13045)
+  - Windows x86_64
+  - Linux x86_64 non-MUSL. 
+
+
+## Freezing Dependencies
+
+If you are freezing your dependencies with one of the many methods (version range in `pyproject.toml`, `requirements.txt`, `uv.lock`, etc), we recommend that you do not hard-code extras: i.e. depend on `trimesh scipy` versus `trimesh[easy]`. 
+
+Trimesh's test matrix runs with the latest version of the packages, so you may get functionality mis-matches by using the extra. And if you're relying on one of the smaller more specialized dependencies (`vhacdx`, etc) it is much easier to diagnose a fault with the specific package.
+
+
 ## Conda Packages
 
 If you prefer a `conda` environment, `trimesh` is available on `conda-forge` ([trimesh-feedstock repo](https://github.com/conda-forge/trimesh-feedstock))
@@ -42,8 +60,8 @@ Trimesh has a lot of soft-required upstream packages, and we try to make sure th
 | `lxml` | Parse XML documents. We use this over the built-in ones as it was slightly faster, and there was a format implemented which was extremely annoying to handle without the ability to get parent nodes (which `lxml` has but built-in XML doesn't). | Standard library's XML | `easy` |
 | `networkx` | Pure Python graph library that's reasonably fast and has a nice API. `scipy.sparse.csgraph` is way faster in most cases but is hard to understand and doesn't implement as many algorithms. | `graph-tool`, `scipy.sparse.csgraph` | `easy` |
 | `shapely` | Bindings to `GEOS` for 2D spatial stuff: "set-theoretic analysis and manipulation of planar features" which lets you offset, union, and query polygons. | `clipper` | `easy` | 
-| `rtree` | Query ND rectangles with a spatial tree for a "broad phase" intersection. Used in polygon generation ("given N closed curves which curve contains the other curve?") and as the broad-phase for the built-in-numpy slow ray query engine. | `fcl` maybe? | `easy` |
-|`httpx`| Do network queries in `trimesh.exchange.load_remote`, will *only* make network requests when asked | `requests`, `aiohttp` | `easy`|
+| `rtree` | Query ND rectangles with a spatial tree for a "broad phase" intersection. Used in polygon generation ("given N closed curves which curve contains the other curve?") and as the broad-phase for the built-in-numpy slow ray query engine. |  | `easy` |
+|`httpx`| Do network queries in `trimesh.exchange.load_remote`, we will *only* make network requests when asked | `requests`, `aiohttp` | `easy`|
 |`sympy`| Evaluate symbolic algebra | | `recommend`|
 |`xxhash`| Quickly hash arrays, used for our cache checking | | `easy`|
 |`charset-normalizer`| When we fail to decode text as UTF-8 we then check with charset-normalizer which guesses an encoding,  letting us load files even with weird encodings. | | `easy`|
@@ -55,7 +73,6 @@ Trimesh has a lot of soft-required upstream packages, and we try to make sure th
 |`pyglet<2`| OpenGL bindings for our simple debug viewer. | | `recommend`|
 |`xatlas`| Unwrap meshes to generate UV coordinates quickly and well. | | `recommend`|
 |`python-fcl`| Do collision queries between meshes | | `recommend`|
-|`glooey`| Provide a viewer with widgets. | | `recommend`|
 |`meshio`| Load additional mesh formats. | | `recommend`|
 |`scikit-image`| Used in voxel ops | | `recommend`|
 |`mapbox-earcut`| Triangulate 2D polygons | `triangle` which has an unusual license | `easy`|
@@ -66,7 +83,6 @@ Trimesh has a lot of soft-required upstream packages, and we try to make sure th
 |`pyinstrument`| A sampling based profiler for performance tweaking. | | `test`|
 |`vhacdx`| A binding for VHACD which provides convex decompositions | | `recommend`|
 |`manifold3d`| A binding for the Manifold mesh boolean engine | | `recommend`|
-|`openctm`| A binding for OpenCTM loaders enabling `.ctm` loading | | `recommend`|
 |`cascadio`| A binding for OpenCASCADE enabling `.STEP` loading | | `recommend`|
 
 ## Adding A Dependency

docs/content/index.rst

@@ -1,13 +1,13 @@
-pypandoc==1.15
+pypandoc==1.16.2
 recommonmark==0.7.1
 jupyter==1.1.1
 
 # get sphinx version range from furo install
-furo==2025.7.19
+furo==2025.9.25
 myst-parser==4.0.1
 pyopenssl==25.3.0
 autodocsumm==0.2.14
 jinja2==3.1.6
-matplotlib==3.10.6
+matplotlib==3.10.7
 nbconvert==7.16.6
 

docs/content/install.md

@@ -1,6 +1,6 @@
 
 # Stage 1: Build uv
-FROM ghcr.io/astral-sh/uv:0.8.16 AS uv
+FROM ghcr.io/astral-sh/uv:0.9.8 AS uv
 
 # use a vanilla Debian base image
 FROM debian:trixie-slim AS base
@@ -23,7 +23,9 @@ WORKDIR /home/user
 # but if you use Debian methods like `update-alternatives`
 # it won't provide a `pip` which works easily and it isn't
 # easy to know how system packages interact with pip packages
-RUN uv venv --python=python3.13 venv
+
+ARG PYTHON_VERSION="3.14.0"
+RUN uv venv --python=python${PYTHON_VERSION} venv
 
 # Add `pip` script install location to $PATH
 ENV PATH="/home/user/venv/bin:$PATH"
@@ -34,19 +36,33 @@ RUN echo '#!/bin/sh' > /home/user/venv/bin/pip && \
     chmod +x /home/user/venv/bin/pip
 
 # Install helper script to PATH.
-COPY --chmod=755 docker/trimesh-setup /home/user/venv/bin
+COPY --chmod=755 helpers/trimesh-setup /home/user/venv/bin
 
 #######################################
 ## install things that need building
 FROM base AS build
 
+# the `easy` extra shouldn't need a build chain
+# unless we're on a brand new Python release
+ARG NEEDS_BUILDCHAIN="false"
+USER root
+# install build dependencies
+RUN if [ "$NEEDS_BUILDCHAIN" = "true" ]; then trimesh-setup --install build; fi
+USER user
+
 # copy in essential files
 COPY --chown=499 trimesh/ /home/user/trimesh
 COPY --chown=499 pyproject.toml /home/user/
 
 # install trimesh into the venv
 RUN pip install /home/user[easy]
 
+# recursively delete tests installed with libraries
+# these are about 30mb for no particular reason, and
+# if we break something we are doing this BEFORE tests
+RUN cd /home/user/venv && \
+    find . -type d -name tests -exec rm -rf {} + || true
+
 ####################################
 ### Build output image most things should run on
 FROM base AS output
@@ -71,14 +87,16 @@ USER root
 RUN trimesh-setup --install=test,gmsh,gltf_validator,llvmpipe,binvox,blender,build
 USER user
 
-RUN blender --version
+RUN bash -c "ldconfig & blender --version"
 
 # install things like pytest and make sure we're on Numpy 2.X
 RUN pip install .[all] && \
     python -c "import numpy as n; assert(n.__version__.startswith('2'))"
 
-# check for lint problems
-RUN ruff check trimesh
+# check for lint problems and print the current python version
+RUN ruff check trimesh && \
+    python --version && \
+    python -c "from beartype import __version__ as v; print(v)"
 
 # run pytest wrapped with xvfb for simple viewer tests
 # print more columns so the short summary is usable
@@ -90,11 +108,11 @@ RUN COLUMNS=240 xvfb-run pytest \
     -p no:cacheprovider tests
 
 
-# set codecov token as a build arg to upload
-ARG CODECOV_TOKEN=""
-RUN curl -Os https://uploader.codecov.io/latest/linux/codecov && \
-    	 chmod +x codecov && \
-        ./codecov -t ${CODECOV_TOKEN} 
+# use BuildKit secrets to access codecov token securely
+RUN --mount=type=secret,id=codecov_token \
+    curl -Os https://uploader.codecov.io/latest/linux/codecov && \
+    chmod +x codecov && \
+    ./codecov -t $(cat /run/secrets/codecov_token || echo "") 
 
 ################################
 ### Build Sphinx Docs