Release: Refactor Load Types

[mikedh]

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 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).
  • 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 Vertices are missing when trimesh.load(process=False) #2335
• Fixes Fix path for show() in notebooks on Windows #2330
• Fixes AttributeError: 'list' object has no attribute 'area_faces' #2239
• Releases Updated use of weights in procrustes analysis (update to #1647) #2313
• Releases Fix nearest.ipynb Typo #2327
• Releases [BUG] fix rounding issue in uv_to_color() #2336
• Releases fixed not loading point cloud colors from glb format files #2339