Release: Refactor Load Types (2241)
A very common source of annoyance and confusion is that `trimesh.load`
can return lots of different types depending on what type of file was
passed (i.e. 2239). This refactor changes the return types for the
loading functions to:
- `trimesh.load_scene -> Scene`
- This loads into a `Scene`, the most general container which can hold
any loadable type. Most people should probably use this to load
geometry.
- `trimesh.load_mesh -> Trimesh`
- Forces all mesh objects in a scene into a single `Trimesh` object.
This potentially has to drop information and irreversibly concatenate
multiple meshes.
- The implementation of the concatenation logic is now in
`Scene.to_mesh` rather than load.
- `trimesh.load_path -> Path`
- This loads into either a `Path2D` or `Path3D` which both inherit from
`Path`
- `trimesh.load -> Geometry`
- This was the original load entry point and is deprecated, but there
are no current plans to remove it. It has been modified into a thin
wrapper for `load_scene` that attempts to match the behavior of the
previous loader for backwards compatibility. In my testing against the
current `main` branch it was returning the same types [99.8% of the
time](https://gist.github.com/mikedh/8de541e066ce842932b1f6cd97c214ca)
although there may be other subtle differences.
- `trimesh.load(..., force='mesh')` will emit a deprecation warning in
favor of `load_mesh`
- `trimesh.load(..., force='scene')` will emit a deprecation warning in
favor of `load_scene`
Additional changes:
- Removes `Geometry.metadata['file_path']` in favor of
`Geometry.source.file_path`. Everything that inherits from `Geometry`
should now have a `.source` attribute which is a typed dataclass. This
was something of a struggle as `file_path` was populated into metadata
on load, but we also try to make sure `metadata` is preserved through
round-trips if at all possible. And so the `load` inserted *different*
keys into the metadata. Making it first-class information rather than a
loose key seems like an improvement, but users will have to replace
`mesh.metadata["file_name"]` with `mesh.source.file_name`.
- Moves all network fetching into `WebResolver` so it can be more easily
gated by `allow_remote`.
- Removes code for the following deprecations:
- January 2025 deprecation for `trimesh.resources.get` in favor of the
typed alternatives (`get_json`, `get_bytes`, etc).
- January 2025 deprecation for `Scene.deduplicated` in favor of a very
short list comprehension on `Scene.duplicate_nodes`
- March 2024 deprecation for `trimesh.graph.smoothed` in favor of
`trimesh.graph.smooth_shaded`.
- Adds the following new deprecations:
- January 2026 `Path3D.to_planar` -> `Path3D.to_2D` to be consistent
with `Path2D.to_3D`.
- Fixes 2335
- Fixes 2330
- Fixes 2239
- Releases 2313
- Releases 2327
- Releases 2336
- Releases 2339