From 71f65fe55a5918a721252a1f7bb74531137ee665 Mon Sep 17 00:00:00 2001 From: Thierry Berger Date: Tue, 12 Nov 2024 09:02:55 +0100 Subject: Use meshloader to support multiple file formats loading (#744) Co-authored-by: Tin Lai --- .github/workflows/rapier-ci-build.yml | 2 +- Cargo.toml | 2 +- crates/rapier3d-meshloader/CHANGELOG.md | 22 ++++ crates/rapier3d-meshloader/Cargo.toml | 31 +++++ crates/rapier3d-meshloader/LICENSE | 201 ++++++++++++++++++++++++++++++++ crates/rapier3d-meshloader/README.md | 22 ++++ crates/rapier3d-meshloader/src/lib.rs | 86 ++++++++++++++ crates/rapier3d-stl/CHANGELOG.md | 9 -- crates/rapier3d-stl/Cargo.toml | 19 --- crates/rapier3d-stl/LICENSE | 201 -------------------------------- crates/rapier3d-stl/README.md | 18 --- crates/rapier3d-stl/src/lib.rs | 110 ----------------- crates/rapier3d-urdf/CHANGELOG.md | 6 + crates/rapier3d-urdf/Cargo.toml | 14 ++- crates/rapier3d-urdf/README.md | 8 +- crates/rapier3d-urdf/src/lib.rs | 110 ++++++++--------- scripts/publish-extra-formats.sh | 4 +- 17 files changed, 445 insertions(+), 420 deletions(-) create mode 100644 crates/rapier3d-meshloader/CHANGELOG.md create mode 100644 crates/rapier3d-meshloader/Cargo.toml create mode 100644 crates/rapier3d-meshloader/LICENSE create mode 100644 crates/rapier3d-meshloader/README.md create mode 100644 crates/rapier3d-meshloader/src/lib.rs delete mode 100644 crates/rapier3d-stl/CHANGELOG.md delete mode 100644 crates/rapier3d-stl/Cargo.toml delete mode 100644 crates/rapier3d-stl/LICENSE delete mode 100644 crates/rapier3d-stl/README.md delete mode 100644 crates/rapier3d-stl/src/lib.rs diff --git a/.github/workflows/rapier-ci-build.yml b/.github/workflows/rapier-ci-build.yml index e978550..8603f1d 100644 --- a/.github/workflows/rapier-ci-build.yml +++ b/.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: diff --git a/Cargo.toml b/Cargo.toml index 4797798..8d9b1b9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -14,7 +14,7 @@ members = [ "examples3d-f64", "benchmarks3d", "crates/rapier3d-urdf", - "crates/rapier3d-stl", + "crates/rapier3d-meshloader", ] resolver = "2" diff --git a/crates/rapier3d-meshloader/CHANGELOG.md b/crates/rapier3d-meshloader/CHANGELOG.md new file mode 100644 index 0000000..0663078 --- /dev/null +++ b/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`. diff --git a/crates/rapier3d-meshloader/Cargo.toml b/crates/rapier3d-meshloader/Cargo.toml new file mode 100644 index 0000000..a470afc --- /dev/null +++ b/crates/rapier3d-meshloader/Cargo.toml @@ -0,0 +1,31 @@ +[package] +name = "rapier3d-meshloader" +version = "0.3.0" +authors = ["Sébastien Crozet "] +description = "STL file loader for the 3D rapier physics engine." +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", +] +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" +mesh-loader = { version = "0.1.12", optional = true } + +rapier3d = { version = "0.22", path = "../rapier3d" } diff --git a/crates/rapier3d-meshloader/LICENSE b/crates/rapier3d-meshloader/LICENSE new file mode 100644 index 0000000..97f4383 --- /dev/null +++ b/crates/rapier3d-meshloader/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2020 Sébastien Crozet + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/crates/rapier3d-meshloader/README.md b/crates/rapier3d-meshloader/README.md new file mode 100644 index 0000000..003a7fa --- /dev/null +++ b/crates/rapier3d-meshloader/README.md @@ -0,0 +1,22 @@ +## Mesh loader for the Rapier physics engine + +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 + +## Resources and discussions + +- [Dimforge](https://dimforge.com): See all the open-source projects we are working on! Follow our announcements + on our [blog](https://www.dimforge.com/blog). +- [User guide](https://www.rapier.rs/docs/): Learn to use Rapier in your project by reading the official User Guides. +- [Discord](https://discord.gg/vt9DJSW): Come chat with us, get help, suggest features, on Discord! +- [NPM packages](https://www.npmjs.com/search?q=%40dimforge): Check out our NPM packages for Rapier, if you need to + use it with JavaScript/Typescript. + +Please make sure to familiarize yourself with our [Code of Conduct](CODE_OF_CONDUCT.md) +and our [Contribution Guidelines](CONTRIBUTING.md) before contributing or participating in +discussions with the community. diff --git a/crates/rapier3d-meshloader/src/lib.rs b/crates/rapier3d-meshloader/src/lib.rs new file mode 100644 index 0000000..32051e5 --- /dev/null +++ b/crates/rapier3d-meshloader/src/lib.rs @@ -0,0 +1,86 @@ +#![doc = include_str!("../README.md")] +#![deny(missing_docs)] + +use mesh_loader::Mesh; +use rapier3d::geometry::{MeshConverter, SharedShape}; +use rapier3d::math::{Isometry, Point, Real, Vector}; +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, + /// 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 parry 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. +/// - `scale`: the scaling factor applied to the geometry input to the `converter`. This scale will +/// affect at the geometric level the [`LoadedShape::shape`]. Note that raw mesh value stored +/// in [`LoadedShape::raw_mesh`] remains unscaled. +pub fn load_from_path( + path: impl AsRef, + converter: &MeshConverter, + scale: Vector, +) -> Result>, 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, scale); + + colliders.push(shape.map(|(shape, pose)| LoadedShape { + shape, + pose, + raw_mesh, + })); + } + 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. +/// - `scale`: the scaling factor applied to the geometry input to the `converter`. This scale will +/// affect at the geometric level the [`LoadedShape::shape`]. Note that raw mesh value stored +/// in [`LoadedShape::raw_mesh`] remains unscaled. +pub fn load_from_raw_mesh( + raw_mesh: &Mesh, + converter: &MeshConverter, + scale: Vector, +) -> Result<(SharedShape, Isometry), MeshConverterError> { + let mut vertices: Vec<_> = raw_mesh + .vertices + .iter() + .map(|xyz| Point::new(xyz[0], xyz[1], xyz[2])) + .collect(); + vertices + .iter_mut() + .for_each(|pt| pt.coords.component_mul_assign(&scale)); + let indices: Vec<_> = raw_mesh.faces.clone(); + converter.convert(vertices, indices) +} diff --git a/crates/rapier3d-stl/CHANGELOG.md b/crates/rapier3d-stl/CHANGELOG.md deleted file mode 100644 index bb3ffa3..0000000 --- a/crates/rapier3d-stl/CHANGELOG.md +++ /dev/null @@ -1,9 +0,0 @@ -## Unreleased - -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`. diff --git a/crates/rapier3d-stl/Cargo.toml b/crates/rapier3d-stl/Cargo.toml deleted file mode 100644 index f24f102..0000000 --- a/crates/rapier3d-stl/Cargo.toml +++ /dev/null @@ -1,19 +0,0 @@ -[package] -name = "rapier3d-stl" -version = "0.3.0" -authors = ["Sébastien Crozet "] -description = "STL file loader for the 3D rapier physics engine." -documentation = "https://docs.rs/rapier3d-stl" -homepage = "https://rapier.rs" -repository = "https://github.com/dimforge/rapier" -readme = "README.md" -categories = ["science", "game-development", "mathematics", "simulation", "wasm"] -keywords = ["physics", "joints", "multibody", "robotics", "urdf"] -license = "Apache-2.0" -edition = "2021" - -[dependencies] -thiserror = "1.0.61" -stl_io = "0.7" - -rapier3d = { version = "0.22", path = "../rapier3d" } diff --git a/crates/rapier3d-stl/LICENSE b/crates/rapier3d-stl/LICENSE deleted file mode 100644 index 97f4383..0000000 --- a/crates/rapier3d-stl/LICENSE +++ /dev/null @@ -1,201 +0,0 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright 2020 Sébastien Crozet - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/crates/rapier3d-stl/README.md b/crates/rapier3d-stl/README.md deleted file mode 100644 index 98d61a0..0000000 --- a/crates/rapier3d-stl/README.md +++ /dev/null @@ -1,18 +0,0 @@ -## STL loader for the Rapier physics engine - -Rapier is a set of 2D and 3D physics engines for games, animation, and robotics. The `rapier3d-stl` -crate lets you create a shape compatible with `rapier3d` and `parry3d` (the underlying collision-detection -library) from an STL file. - -## Resources and discussions - -- [Dimforge](https://dimforge.com): See all the open-source projects we are working on! Follow our announcements - on our [blog](https://www.dimforge.com/blog). -- [User guide](https://www.rapier.rs/docs/): Learn to use Rapier in your project by reading the official User Guides. -- [Discord](https://discord.gg/vt9DJSW): Come chat with us, get help, suggest features, on Discord! -- [NPM packages](https://www.npmjs.com/search?q=%40dimforge): Check out our NPM packages for Rapier, if you need to - use it with JavaScript/Typescript. - -Please make sure to familiarize yourself with our [Code of Conduct](CODE_OF_CONDUCT.md) -and our [Contribution Guidelines](CONTRIBUTING.md) before contributing or participating in -discussions with the community. diff --git a/crates/rapier3d-stl/src/lib.rs b/crates/rapier3d-stl/src/lib.rs deleted file mode 100644 index 7b22e74..0000000 --- a/crates/rapier3d-stl/src/lib.rs +++ /dev/null @@ -1,110 +0,0 @@ -//! ## STL loader for the Rapier physics engine -//! -//! Rapier is a set of 2D and 3D physics engines for games, animation, and robotics. The `rapier3d-stl` -//! crate lets you create a shape compatible with `rapier3d` and `parry3d` (the underlying collision-detection -//! library) from an STL file. - -#![warn(missing_docs)] - -use rapier3d::geometry::{MeshConverter, MeshConverterError, SharedShape}; -use rapier3d::math::{Isometry, Point, Real, Vector}; -use std::fs::File; -use std::io::{BufReader, Read, Seek}; -use std::path::Path; -use stl_io::IndexedMesh; - -/// Error while loading an STL file. -#[derive(thiserror::Error, Debug)] -pub enum StlLoaderError { - /// An error triggered by rapier’s [`MeshConverter`]. - #[error(transparent)] - MeshConverter(#[from] MeshConverterError), - /// A generic IO error. - #[error(transparent)] - Io(#[from] std::io::Error), -} - -/// The result of loading a shape from an stl mesh. -pub struct StlShape { - /// The shape loaded from the file and converted by the [`MeshConverter`]. - pub shape: SharedShape, - /// The shape’s pose. - pub pose: Isometry, - /// The raw mesh read from the stl file without any modification. - pub raw_mesh: IndexedMesh, -} - -/// Loads an STL file as a shape from a file. -/// -/// # Parameters -/// - `file_path`: the STL file’s path. -/// - `converter`: controls how the shape is computed from the STL content. In particular, it lets -/// you specify if the computed [`StlShape::shape`] is a triangle mesh, its convex hull, -/// bounding box, etc. -/// - `scale`: the scaling factor applied to the geometry input to the `converter`. This scale will -/// affect at the geometric level the [`StlShape::shape`]. Note that raw mesh value stored -/// in [`StlShape::raw_mesh`] remains unscaled. -pub fn load_from_path( - file_path: impl AsRef, - converter: MeshConverter, - scale: Vector, -) -> Result { - let mut reader = BufReader::new(File::open(file_path)?); - load_from_reader(&mut reader, converter, scale) -} - -/// Loads an STL file as a shape from an arbitrary reader. -/// -/// # Parameters -/// - `reader`: the reader. -/// - `converter`: controls how the shape is computed from the STL content. In particular, it lets -/// you specify if the computed [`StlShape::shape`] is a triangle mesh, its convex hull, -/// bounding box, etc. -/// - `scale`: the scaling factor applied to the geometry input to the `converter`. This scale will -/// affect at the geometric level the [`StlShape::shape`]. Note that raw mesh value stored -/// in [`StlShape::raw_mesh`] remains unscaled. -pub fn load_from_reader( - read: &mut R, - converter: MeshConverter, - scale: Vector, -) -> Result { - let stl_mesh = stl_io::read_stl(read)?; - Ok(load_from_raw_mesh(stl_mesh, converter, scale)?) -} - -/// Loads an STL file as a shape from a preloaded raw stl mesh. -/// -/// # Parameters -/// - `raw_mesh`: the raw stl mesh. -/// - `converter`: controls how the shape is computed from the STL content. In particular, it lets -/// you specify if the computed [`StlShape::shape`] is a triangle mesh, its convex hull, -/// bounding box, etc. -/// - `scale`: the scaling factor applied to the geometry input to the `converter`. This scale will -/// affect at the geometric level the [`StlShape::shape`]. Note that raw mesh value stored -/// in [`StlShape::raw_mesh`] remains unscaled. -pub fn load_from_raw_mesh( - raw_mesh: IndexedMesh, - converter: MeshConverter, - scale: Vector, -) -> Result { - let mut vertices: Vec<_> = raw_mesh - .vertices - .iter() - .map(|xyz| Point::new(xyz[0], xyz[1], xyz[2])) - .collect(); - vertices - .iter_mut() - .for_each(|pt| pt.coords.component_mul_assign(&scale)); - let indices: Vec<_> = raw_mesh - .faces - .iter() - .map(|f| f.vertices.map(|i| i as u32)) - .collect(); - let (shape, pose) = converter.convert(vertices, indices)?; - - Ok(StlShape { - shape, - pose, - raw_mesh, - }) -} diff --git a/crates/rapier3d-urdf/CHANGELOG.md b/crates/rapier3d-urdf/CHANGELOG.md index 852e45a..5284d9c 100644 --- a/crates/rapier3d-urdf/CHANGELOG.md +++ b/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 diff --git a/crates/rapier3d-urdf/Cargo.toml b/crates/rapier3d-urdf/Cargo.toml index ef53da9..d6f74c9 100644 --- a/crates/rapier3d-urdf/Cargo.toml +++ b/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 } diff --git a/crates/rapier3d-urdf/README.md b/crates/rapier3d-urdf/README.md index ae2e21d..48b399c 100644 --- a/crates/rapier3d-urdf/README.md +++ b/crates/rapier3d-urdf/README.md @@ -1,4 +1,4 @@ -## 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 @@ -6,7 +6,9 @@ crate lets you convert an URDF file into a set of rigid-bodies, colliders, and j ## 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 @@ -14,7 +16,7 @@ Are listed below some known limitations you might want to be aware of before pic 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: diff --git a/crates/rapier3d-urdf/src/lib.rs b/crates/rapier3d-urdf/src/lib.rs index 1f913da..8e858c3 100644 --- a/crates/rapier3d-urdf/src/lib.rs +++ b/crates/rapier3d-urdf/src/lib.rs @@ -1,4 +1,4 @@ -//! ## STL loader for the Rapier physics engine +//! ## URDF 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 @@ -7,6 +7,8 @@ //! ## Optional cargo features //! //! - `stl`: enables loading STL meshes referenced by the URDF file. +//! - `collada`: enables loading Collada (`.dae`) meshes referenced by the URDF file. +//! - `wavefront`: enables loading Wavefront (`.obj`) meshes referenced by the URDF file. //! //! ## Limitations //! @@ -14,7 +16,7 @@ //! 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` +//! - Mesh file types are limited. Contributions are welcome. You may 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: @@ -35,6 +37,7 @@ use rapier3d::{ geometry::{Collider, ColliderBuilder, ColliderHandle, ColliderSet, SharedShape, TriMeshFlags}, math::{Isometry, Point, Real, Vector}, na, + prelude::MeshConverter, }; use std::collections::HashMap; use std::path::Path; @@ -289,7 +292,7 @@ impl UrdfRobot { /// (`UrdfRobot`). Both structures are arranged the same way, with matching indices for each part. /// /// If the URDF file references external meshes, they will be loaded automatically if the format - /// is supported. The format is detected from the file’s extension. All the mesh formats are + /// is supported. The format is detected mostly from the file’s extension. All the mesh formats are /// disabled by default and can be enabled through cargo features (e.g. the `stl` feature of /// this crate enabled loading referenced meshes in stl format). /// @@ -310,13 +313,13 @@ impl UrdfRobot { name_to_link_id.insert(&link.name, id); let mut colliders = vec![]; if options.create_colliders_from_collision_shapes { - colliders.extend(link.collisions.iter().filter_map(|co| { - urdf_to_collider(&options, mesh_dir, &co.geometry, &co.origin) + colliders.extend(link.collisions.iter().flat_map(|co| { + urdf_to_colliders(&options, mesh_dir, &co.geometry, &co.origin) })) } if options.create_colliders_from_visual_shapes { - colliders.extend(link.visuals.iter().filter_map(|vis| { - urdf_to_collider(&options, mesh_dir, &vis.geometry, &vis.origin) + colliders.extend(link.visuals.iter().flat_map(|vis| { + urdf_to_colliders(&options, mesh_dir, &vis.geometry, &vis.origin) })) } let mut body = urdf_to_rigid_body(&options, &link.inertial); @@ -488,66 +491,67 @@ fn urdf_to_rigid_body(options: &UrdfLoaderOptions, inertial: &Inertial) -> Rigid builder.build() } -fn urdf_to_collider( +fn urdf_to_colliders( options: &UrdfLoaderOptions, - _mesh_dir: &Path, // NOTO: this isn’t used if there is no external mesh feature enabled (like stl). + mesh_dir: &Path, geometry: &Geometry, origin: &Pose, -) -> Option { - let mut builder = options.collider_blueprint.clone(); +) -> Vec { let mut shape_transform = Isometry::identity(); - let shape = match &geometry { - Geometry::Box { size } => SharedShape::cuboid( - size[0] as Real / 2.0, - size[1] as Real / 2.0, - size[2] as Real / 2.0, - ), + + let mut colliders = Vec::new(); + + match &geometry { + Geometry::Box { size } => { + colliders.push(SharedShape::cuboid( + size[0] as Real / 2.0, + size[1] as Real / 2.0, + size[2] as Real / 2.0, + )); + } Geometry::Cylinder { radius, length } => { // This rotation will make the cylinder Z-up as per the URDF spec, // instead of rapier’s default Y-up. shape_transform = Isometry::rotation(Vector::x() * Real::frac_pi_2()); - SharedShape::cylinder(*length as Real / 2.0, *radius as Real) + colliders.push(SharedShape::cylinder( + *length as Real / 2.0, + *radius as Real, + )); + } + Geometry::Sphere { radius } => { + colliders.push(SharedShape::ball(*radius as Real)); } - Geometry::Sphere { radius } => SharedShape::ball(*radius as Real), Geometry::Mesh { filename, scale } => { - let path: &Path = filename.as_ref(); - let _scale = scale + let full_path = mesh_dir.join(filename); + let scale = scale .map(|s| Vector::new(s.x as Real, s.y as Real, s.z as Real)) .unwrap_or_else(|| Vector::::repeat(1.0)); - match path.extension().and_then(|ext| ext.to_str()) { - #[cfg(feature = "stl")] - Some("stl") | Some("STL") => { - use rapier3d::geometry::MeshConverter; - let full_path = _mesh_dir.join(filename); - match rapier3d_stl::load_from_path( - full_path, - MeshConverter::TriMeshWithFlags(options.trimesh_flags), - _scale, - ) { - Ok(stl_shape) => { - shape_transform = stl_shape.pose; - stl_shape.shape - } - Err(e) => { - log::error!("failed to load STL file {filename}: {e}"); - return None; - } - } - } - _ => { - log::error!("failed to load file with unknown type {filename}"); - return None; - } - } + let Ok(loaded_mesh) = rapier3d_meshloader::load_from_path( + full_path, + &MeshConverter::TriMeshWithFlags(options.trimesh_flags), + scale, + ) else { + return Vec::new(); + }; + colliders.append( + &mut loaded_mesh + .into_iter() + .filter_map(|x| x.map(|s| s.shape).ok()) + .collect(), + ); } - }; + } - builder.shape = shape; - Some( - builder - .position(urdf_to_isometry(origin) * shape_transform) - .build(), - ) + colliders + .drain(..) + .map(move |shape| { + let mut builder = options.collider_blueprint.clone(); + builder.shape = shape; + builder + .position(urdf_to_isometry(origin) * shape_transform) + .build() + }) + .collect() } fn urdf_to_isometry(pose: &Pose) -> Isometry { diff --git a/scripts/publish-extra-formats.sh b/scripts/publish-extra-formats.sh index 1d9a990..af48e77 100755 --- a/scripts/publish-extra-formats.sh +++ b/scripts/publish-extra-formats.sh @@ -2,8 +2,8 @@ currdir=$(pwd) -### Publish rapier3d-stl. -cd "crates/rapier3d-stl" && cargo publish $DRY_RUN || exit 1 +### Publish rapier3d-meshloader. +cd "crates/rapier3d-meshloader" && cargo publish $DRY_RUN || exit 1 cd "$currdir" || exit 2 ### Publish rapier3d-urdf. -- cgit