use meshloader to support multiple files

Co-authored-by: Tin Lai <tin@tinyiu.com>

.github/workflows/rapier-ci-build.yml

@@ -23,7 +23,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Cargo doc
-        run: cargo doc --features parallel,simd-stable,serde-serialize,debug-render -p rapier3d -p rapier2d -p rapier3d-stl -p rapier3d-urdf
+        run: cargo doc --features parallel,simd-stable,serde-serialize,debug-render -p rapier3d -p rapier2d -p rapier3d-meshloader -p rapier3d-urdf
   build-native:
     runs-on: ubuntu-latest
     env:

Cargo.toml

@@ -14,7 +14,7 @@ members = [
     "examples3d-f64",
     "benchmarks3d",
     "crates/rapier3d-urdf",
-    "crates/rapier3d-stl",
+    "crates/rapier3d-meshloader",
 ]
 resolver = "2"
 

crates/rapier3d-meshloader/CHANGELOG.md

@@ -0,0 +1,22 @@
+## Unreleased
+
+Renamed the crate from `rapier3d-stl` to `rapier3d-meshloader`, to better reflect its support for multiple formats.
+
+### Added
+
+- Add optional support for Collada and Wavefront files through new feature flags `collada` and `wavefront`.
+
+### Modified
+
+- Support for STL is now optional through feature `stl`.
+- Features `stl`, `wavefront` and `collada` are enabled by default.
+
+## 0.3.0
+
+This is the initial release of the `rapier3d-stl` crate.
+
+### Added
+
+- Add `load_from_path` for creating a shape from a stl file.
+- Add `load_from_reader` for creating a shape from an object implementing `Read`.
+- Add `load_from_raw_mesh` for creating a shape from an already loaded `IndexedMesh`.

crates/rapier3d-stl/Cargo.toml → crates/rapier3d-meshloader/Cargo.toml

@@ -1,19 +1,31 @@
 [package]
-name = "rapier3d-stl"
+name = "rapier3d-meshloader"
 version = "0.3.0"
 authors = ["Sébastien Crozet <sebcrozet@dimforge.com>"]
 description = "STL file loader for the 3D rapier physics engine."
-documentation = "https://docs.rs/rapier3d-stl"
+documentation = "https://docs.rs/rapier3d-meshloader"
 homepage = "https://rapier.rs"
 repository = "https://github.com/dimforge/rapier"
 readme = "README.md"
-categories = ["science", "game-development", "mathematics", "simulation", "wasm"]
+categories = [
+    "science",
+    "game-development",
+    "mathematics",
+    "simulation",
+    "wasm",
+]
 keywords = ["physics", "joints", "multibody", "robotics", "urdf"]
 license = "Apache-2.0"
 edition = "2021"
 
+[features]
+default = ["stl", "collada", "wavefront"]
+stl = ["mesh-loader/stl"]
+collada = ["mesh-loader/collada"]
+wavefront = ["mesh-loader/obj"]
+
 [dependencies]
 thiserror = "1.0.61"
-stl_io = "0.7"
+mesh-loader = { version = "0.1.12", optional = true }
 
 rapier3d = { version = "0.22", path = "../rapier3d" }

crates/rapier3d-meshloader/src/lib.rs

@@ -0,0 +1,88 @@
+//! ## Mesh loader for the Rapier physics engine
+//!
+//! See documentation from [`mesh_loader`] for supported formats.
+//!
+//! Rapier is a set of 2D and 3D physics engines for games, animation, and robotics. The `rapier3d-meshloader`
+//! crate lets you create a shape compatible with `rapier3d` and `parry3d` (the underlying collision-detection
+//! library) from different file formats, see the following features list:
+//! `stl`: support .stl files
+//! `collada`: support .dae files
+//! `wavefront`: support .obj files
+
+#![deny(missing_docs)]
+
+use mesh_loader::Mesh;
+use rapier3d::geometry::{MeshConverter, SharedShape};
+use rapier3d::math::{Isometry, Point, Real};
+use rapier3d::prelude::MeshConverterError;
+use std::path::Path;
+
+/// The result of loading a shape.
+pub struct LoadedShape {
+    /// The shape loaded from the file and converted by the [`MeshConverter`].
+    pub shape: SharedShape,
+    /// The shape’s pose.
+    pub pose: Isometry<Real>,
+    /// The raw mesh read from the file without any modification.
+    pub raw_mesh: Mesh,
+}
+
+/// Error while loading an STL file.
+#[derive(thiserror::Error, Debug)]
+pub enum MeshLoaderError {
+    /// An error triggered by rapier’s [`MeshConverter`].
+    #[error(transparent)]
+    MeshConverter(#[from] MeshConverterError),
+    /// A generic IO error.
+    #[error(transparent)]
+    Io(#[from] std::io::Error),
+}
+
+/// Loads an file as shapes from a file.
+///
+/// # Parameters
+/// - `path`: the file’s path.
+/// - `converter`: controls how the shapes are computed from the content. In particular, it lets
+///                you specify if the computed [`SharedShape`] is a triangle mesh, its convex hull,
+///                bounding box, etc.
+// TODO: call a function for each mesh to load ? To be able to have a different mesh converter?
+pub fn load_from_path(
+    path: impl AsRef<Path>,
+    converter: &MeshConverter,
+) -> Result<Vec<Result<LoadedShape, MeshConverterError>>, MeshLoaderError> {
+    let loader = mesh_loader::Loader::default();
+    let mut colliders = vec![];
+    let scene = loader.load(path)?;
+    for (raw_mesh, _) in scene.meshes.into_iter().zip(scene.materials) {
+        let shape = load_from_raw_mesh(&raw_mesh, converter);
+        colliders.push(match shape {
+            Ok((shape, pose)) => Ok(LoadedShape {
+                shape,
+                pose,
+                raw_mesh,
+            }),
+            Err(e) => Err(e),
+        });
+    }
+    Ok(colliders)
+}
+
+/// Loads an file as a shape from a preloaded raw [`mesh_loader::Mesh`].
+///
+/// # Parameters
+/// - `raw_mesh`: the raw mesh.
+/// - `converter`: controls how the shape is computed from the STL content. In particular, it lets
+///                you specify if the computed [`SharedShape`] is a triangle mesh, its convex hull,
+///                bounding box, etc.
+pub fn load_from_raw_mesh(
+    raw_mesh: &Mesh,
+    converter: &MeshConverter,
+) -> Result<(SharedShape, Isometry<Real>), MeshConverterError> {
+    let vertices: Vec<_> = raw_mesh
+        .vertices
+        .iter()
+        .map(|xyz| Point::new(xyz[0], xyz[1], xyz[2]))
+        .collect();
+    let indices: Vec<_> = raw_mesh.faces.clone();
+    converter.convert(vertices, indices)
+}

crates/rapier3d-urdf/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## Unreleased
 
+### Added
+
+- Add optional support for Collada and Wavefront files through new feature flags `collada` and `wavefront`.
+
+## 0.3.0
+
 This is the initial release of the `rapier3d-urdf` crate.
 
 ### Added

crates/rapier3d-urdf/Cargo.toml

@@ -7,13 +7,21 @@ documentation = "https://docs.rs/rapier3d-urdf"
 homepage = "https://rapier.rs"
 repository = "https://github.com/dimforge/rapier"
 readme = "README.md"
-categories = ["science", "game-development", "mathematics", "simulation", "wasm"]
+categories = [
+    "science",
+    "game-development",
+    "mathematics",
+    "simulation",
+    "wasm",
+]
 keywords = ["physics", "joints", "multibody", "robotics", "urdf"]
 license = "Apache-2.0"
 edition = "2021"
 
 [features]
-stl = ["dep:rapier3d-stl"]
+stl = ["dep:rapier3d-meshloader", "rapier3d-meshloader/stl"]
+collada = ["dep:rapier3d-meshloader", "rapier3d-meshloader/collada"]
+wavefront = ["dep:rapier3d-meshloader", "rapier3d-meshloader/wavefront"]
 
 [dependencies]
 log = "0.4"
@@ -23,4 +31,4 @@ bitflags = "2"
 xurdf = "0.2"
 
 rapier3d = { version = "0.22", path = "../rapier3d" }
-rapier3d-stl = { version = "0.3.0", path = "../rapier3d-stl", optional = true }
+rapier3d-meshloader = { version = "0.3.0", path = "../rapier3d-meshloader", default-features = false, optional = true }

crates/rapier3d-urdf/README.md

@@ -1,20 +1,22 @@
-## STL loader for the Rapier physics engine
+## Mesh loader for the Rapier physics engine
 
 Rapier is a set of 2D and 3D physics engines for games, animation, and robotics. The `rapier3d-urdf`
 crate lets you convert an URDF file into a set of rigid-bodies, colliders, and joints, for usage with the
 `rapier3d` physics engine.
 
 ## Optional cargo features
 
-- `stl`: enables loading STL meshes referenced by the URDF file.
+- `stl`: enables loading `.STL` meshes referenced by the URDF file.
+- `collada`: enables loading `.dae` meshes referenced by the URDF file.
+- `wavefront`: enables loading `.obj` meshes referenced by the URDF file.
 
 ## Limitations
 
 Are listed below some known limitations you might want to be aware of before picking this library. Contributions to
 improve
 these elements are very welcome!
 
-- Mesh file types other than `stl` are not supported yet. Contributions are welcome. You my check the `rapier3d-stl`
+- Supported mesh formats are `stl`, `collada` and `wavefront`. Contributions are welcome. You my check the `rapier3d-meshloader`
   repository for an example of mesh loader.
 - When inserting joints as multibody joints, they will be reset to their neutral position (all coordinates = 0).
 - The following fields are currently ignored: