diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a60209..eb6a330 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,9 @@ This release introduces two new crates: -- `rapier-urdf` for loading URDF files into rapier3d. This will load the rigid-bodies, +- `rapier3d-urdf` for loading URDF files into rapier3d. This will load the rigid-bodies, colliders, and joints. -- `rapier-stl` for loading an STL file as a collision shape. +- `rapier3d-stl` for loading an STL file as a collision shape. ### Added diff --git a/Cargo.toml b/Cargo.toml index f176685..971dff9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [workspace] members = ["crates/rapier2d", "crates/rapier2d-f64", "crates/rapier_testbed2d", "crates/rapier_testbed2d-f64", "examples2d", "benchmarks2d", - "crates/rapier3d", "crates/rapier3d-f64", "crates/rapier_testbed3d", "crates/rapier_testbed3d-f64", "examples3d", "examples3d-f64", "benchmarks3d", "crates/rapier-urdf", "crates/rapier-stl"] + "crates/rapier3d", "crates/rapier3d-f64", "crates/rapier_testbed3d", "crates/rapier_testbed3d-f64", "examples3d", "examples3d-f64", "benchmarks3d", "crates/rapier3d-urdf", "crates/rapier3d-stl"] resolver = "2" [patch.crates-io] diff --git a/README.md b/README.md index 1174a1c..017cf56 100644 --- a/README.md +++ b/README.md @@ -40,12 +40,6 @@ are `rapier2d`, `rapier3d`, `rapier2d-f64`, and `rapier3d-f64`. They are written programming language, by the [Dimforge](https://dimforge.com) organization. It is forever free and open-source! -## Roadmap - -We update our roadmap at the beginning of each year. Our 2021 roadmap can be seen -[there](https://www.dimforge.com/blog/2021/01/01/physics-simulation-with-rapier-2021-roadmap/#rapier-roadmap-for-2021). -We regularly give updates about our progress on [our blog](https://www.dimforge.com/blog). - ## Getting started The easiest way to get started with Rapier is to: diff --git a/benchmarks2d/Cargo.toml b/benchmarks2d/Cargo.toml index bbab4d9..0d64704 100644 --- a/benchmarks2d/Cargo.toml +++ b/benchmarks2d/Cargo.toml @@ -1,19 +1,19 @@ [package] -name = "rapier-benchmarks-2d" +name = "rapier-benchmarks-2d" version = "0.1.0" -authors = [ "Sébastien Crozet " ] +authors = ["Sébastien Crozet "] edition = "2021" [features] -parallel = [ "rapier2d/parallel", "rapier_testbed2d/parallel" ] -simd-stable = [ "rapier2d/simd-stable" ] -simd-nightly = [ "rapier2d/simd-nightly" ] -other-backends = [ "rapier_testbed2d/other-backends" ] -enhanced-determinism = [ "rapier2d/enhanced-determinism" ] +parallel = ["rapier2d/parallel", "rapier_testbed2d/parallel"] +simd-stable = ["rapier2d/simd-stable"] +simd-nightly = ["rapier2d/simd-nightly"] +other-backends = ["rapier_testbed2d/other-backends"] +enhanced-determinism = ["rapier2d/enhanced-determinism"] [dependencies] -rand = "0.8" -Inflector = "0.11" +rand = "0.8" +Inflector = "0.11" [dependencies.rapier_testbed2d] path = "../crates/rapier_testbed2d" diff --git a/benchmarks3d/Cargo.toml b/benchmarks3d/Cargo.toml index 76d1911..f264543 100644 --- a/benchmarks3d/Cargo.toml +++ b/benchmarks3d/Cargo.toml @@ -1,19 +1,19 @@ [package] -name = "rapier-benchmarks-3d" +name = "rapier-benchmarks-3d" version = "0.1.0" -authors = [ "Sébastien Crozet " ] +authors = ["Sébastien Crozet "] edition = "2021" [features] -parallel = [ "rapier3d/parallel", "rapier_testbed3d/parallel" ] -simd-stable = [ "rapier3d/simd-stable" ] -simd-nightly = [ "rapier3d/simd-nightly" ] -other-backends = [ "rapier_testbed3d/other-backends" ] -enhanced-determinism = [ "rapier3d/enhanced-determinism" ] +parallel = ["rapier3d/parallel", "rapier_testbed3d/parallel"] +simd-stable = ["rapier3d/simd-stable"] +simd-nightly = ["rapier3d/simd-nightly"] +other-backends = ["rapier_testbed3d/other-backends"] +enhanced-determinism = ["rapier3d/enhanced-determinism"] [dependencies] -rand = "0.8" -Inflector = "0.11" +rand = "0.8" +Inflector = "0.11" [dependencies.rapier_testbed3d] path = "../crates/rapier_testbed3d" diff --git a/crates/rapier-stl/Cargo.toml b/crates/rapier-stl/Cargo.toml deleted file mode 100644 index f533170..0000000 --- a/crates/rapier-stl/Cargo.toml +++ /dev/null @@ -1,10 +0,0 @@ -[package] -name = "rapier-stl" -version = "0.1.0" -edition = "2021" - -[dependencies] -thiserror = "1.0.61" -stl_io = "0.7" - -rapier3d = { versions = "0.19", path = "../rapier3d" } diff --git a/crates/rapier-stl/src/lib.rs b/crates/rapier-stl/src/lib.rs deleted file mode 100644 index 87fafec..0000000 --- a/crates/rapier-stl/src/lib.rs +++ /dev/null @@ -1,72 +0,0 @@ -use rapier3d::geometry::{ - Collider, ColliderBuilder, Cuboid, MeshConverter, MeshConverterError, SharedShape, TriMesh, -}; -use rapier3d::math::{Isometry, Point, Real, Vector}; -use rapier3d::parry::bounding_volume; -use std::fs::File; -use std::io::{BufReader, Read, Seek}; -use std::path::Path; -use stl_io::IndexedMesh; - -#[derive(thiserror::Error, Debug)] -pub enum StlLoaderError { - #[error(transparent)] - MeshConverter(#[from] MeshConverterError), - #[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. - pub raw_mesh: IndexedMesh, -} - -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) -} - -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)?) -} - -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] as Real, xyz[1] as Real, xyz[2] as Real)) - .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/rapier-urdf/Cargo.toml b/crates/rapier-urdf/Cargo.toml deleted file mode 100644 index 6837950..0000000 --- a/crates/rapier-urdf/Cargo.toml +++ /dev/null @@ -1,17 +0,0 @@ -[package] -name = "rapier-urdf" -version = "0.1.0" -edition = "2021" - -[features] -stl = ["rapier-stl"] - -[dependencies] -log = "0.4" -anyhow = "1" -bitflags = "2" -# NOTE: we are not using the (more recent) urdf-rs crate because of https://github.com/openrr/urdf-rs/issues/94 -xurdf = "0.2" - -rapier3d = { versions = "0.19", path = "../rapier3d" } -rapier-stl = { version = "0.1.0", path = "../rapier-stl", optional = true } diff --git a/crates/rapier2d-f64/Cargo.toml b/crates/rapier2d-f64/Cargo.toml index 79046bb..059f52d 100644 --- a/crates/rapier2d-f64/Cargo.toml +++ b/crates/rapier2d-f64/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "rapier2d-f64" version = "0.19.0" -authors = ["Sébastien Crozet "] +authors = ["Sébastien Crozet "] description = "2-dimensional physics engine in Rust." documentation = "https://docs.rs/rapier2d" homepage = "https://rapier.rs" diff --git a/crates/rapier2d/Cargo.toml b/crates/rapier2d/Cargo.toml index f0474c8..d270c9d 100644 --- a/crates/rapier2d/Cargo.toml +++ b/crates/rapier2d/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "rapier2d" version = "0.19.0" -authors = ["Sébastien Crozet "] +authors = ["Sébastien Crozet "] description = "2-dimensional physics engine in Rust." documentation = "https://docs.rs/rapier2d" homepage = "https://rapier.rs" diff --git a/crates/rapier3d-f64/Cargo.toml b/crates/rapier3d-f64/Cargo.toml index 95f0d66..98a87a9 100644 --- a/crates/rapier3d-f64/Cargo.toml +++ b/crates/rapier3d-f64/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "rapier3d-f64" version = "0.19.0" -authors = ["Sébastien Crozet "] +authors = ["Sébastien Crozet "] description = "3-dimensional physics engine in Rust." documentation = "https://docs.rs/rapier3d" homepage = "https://rapier.rs" diff --git a/crates/rapier3d-stl/CHANGELOG.md b/crates/rapier3d-stl/CHANGELOG.md new file mode 100644 index 0000000..bb3ffa3 --- /dev/null +++ b/crates/rapier3d-stl/CHANGELOG.md @@ -0,0 +1,9 @@ +## 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 new file mode 100644 index 0000000..dc5bd0e --- /dev/null +++ b/crates/rapier3d-stl/Cargo.toml @@ -0,0 +1,19 @@ +[package] +name = "rapier3d-stl" +version = "0.1.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.19", path = "../rapier3d" } diff --git a/crates/rapier3d-stl/LICENSE b/crates/rapier3d-stl/LICENSE new file mode 100644 index 0000000..97f4383 --- /dev/null +++ b/crates/rapier3d-stl/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-stl/README.md b/crates/rapier3d-stl/README.md new file mode 100644 index 0000000..98d61a0 --- /dev/null +++ b/crates/rapier3d-stl/README.md @@ -0,0 +1,18 @@ +## 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 new file mode 100644 index 0000000..0273bc0 --- /dev/null +++ b/crates/rapier3d-stl/src/lib.rs @@ -0,0 +1,110 @@ +//! ## 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] as Real, xyz[1] as Real, xyz[2] as Real)) + .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 new file mode 100644 index 0000000..852e45a --- /dev/null +++ b/crates/rapier3d-urdf/CHANGELOG.md @@ -0,0 +1,16 @@ +## Unreleased + +This is the initial release of the `rapier3d-urdf` crate. + +### Added + +- Add `UrdfRobot` which is a collection of colliders, rigid-bodies and joints representing a robot loaded from an URDF + file. +- Add `UrdfRobot::from_file` to load an `UrdfRobot` from an URDF file. +- Add `UrdfRobot::from_str` to load an `UrdfRobot` from a string in URDF format. +- Add `UrdfRobot::from_robot` to load an `UrdfRobot` from an already loaded URDF + robot (pre-parsed with the `xurdf` crate). +- Add `UrdfRobot::insert_using_impulse_joints` to insert the robot to the rapier sets. Joints are represented as + **impulse** joints. +- Add `UrdfRobot::insert_using_impulse_joints` to insert the robot to the rapier sets. Joints are represented as + **multibody** joints. diff --git a/crates/rapier3d-urdf/Cargo.toml b/crates/rapier3d-urdf/Cargo.toml new file mode 100644 index 0000000..1394f2a --- /dev/null +++ b/crates/rapier3d-urdf/Cargo.toml @@ -0,0 +1,26 @@ +[package] +name = "rapier3d-urdf" +version = "0.1.0" +authors = ["Sébastien Crozet "] +description = "URDF file loader for the 3D rapier physics engine." +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"] +keywords = ["physics", "joints", "multibody", "robotics", "urdf"] +license = "Apache-2.0" +edition = "2021" + +[features] +stl = ["rapier3d-stl"] + +[dependencies] +log = "0.4" +anyhow = "1" +bitflags = "2" +# NOTE: we are not using the (more recent) urdf-rs crate because of https://github.com/openrr/urdf-rs/issues/94 +xurdf = "0.2" + +rapier3d = { version = "0.19", path = "../rapier3d" } +rapier3d-stl = { version = "0.1.0", path = "../rapier3d-stl", optional = true } diff --git a/crates/rapier3d-urdf/LICENSE b/crates/rapier3d-urdf/LICENSE new file mode 100644 index 0000000..97f4383 --- /dev/null +++ b/crates/rapier3d-urdf/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-urdf/README.md b/crates/rapier3d-urdf/README.md new file mode 100644 index 0000000..ae2e21d --- /dev/null +++ b/crates/rapier3d-urdf/README.md @@ -0,0 +1,37 @@ +## STL 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. + +## 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` + 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: + - `Joint::dynamics` + - `Joint::limit.effort` / `limit.velocity` + - `Joint::mimic` + - `Joint::safety_controller` + +## 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/rapier-urdf/src/lib.rs b/crates/rapier3d-urdf/src/lib.rs similarity index 58% rename from crates/rapier-urdf/src/lib.rs rename to crates/rapier3d-urdf/src/lib.rs index 6feda78..0a9a2fc 100644 --- a/crates/rapier-urdf/src/lib.rs +++ b/crates/rapier3d-urdf/src/lib.rs @@ -1,4 +1,31 @@ -use na::{RealField, UnitQuaternion}; +//! ## STL 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. +//! +//! ## 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` +//! 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: +//! - `Joint::dynamics` +//! - `Joint::limit.effort` / `limit.velocity` +//! - `Joint::mimic` +//! - `Joint::safety_controller` + +#![warn(missing_docs)] + +use na::RealField; use rapier3d::{ dynamics::{ GenericJoint, GenericJointBuilder, ImpulseJointHandle, ImpulseJointSet, JointAxesMask, @@ -13,30 +40,88 @@ use rapier3d::{ na, }; use std::collections::HashMap; -use std::path::{Path, PathBuf}; -use xurdf::{Collision, Geometry, Inertial, Joint, Pose, Robot}; +use std::path::Path; +use xurdf::{Geometry, Inertial, Joint, Pose, Robot}; bitflags::bitflags! { - #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))] + /// Options applied to multibody joints created from the URDF joints. #[derive(Copy, Clone, Debug, PartialEq, Eq, Default)] pub struct UrdfMultibodyOptions: u8 { + /// If this flag is set, the created multibody joint will be marked as kinematic. + /// + /// A kinematic joint is entirely controlled by the user (it is not affected by any force). + /// This particularly useful if you intend to control the robot through inverse-kinematics. const JOINTS_ARE_KINEMATIC = 0b0001; + /// If enabled, any contact between two links belonging to the same generated multibody robot will + /// be ignored. + /// + /// This is useful if the generated colliders are known to be overlapping (e.g. if creating colliders + /// from visual meshes was enabled) or that collision detection is not needed a computationally + /// expensive (e.g. if any of these colliders is a high-quality triangle mesh). const DISABLE_SELF_CONTACTS = 0b0010; } } +/// The index of an urdf link. pub type LinkId = usize; +/// A set of configurable options for loading URDF files. #[derive(Clone, Debug)] pub struct UrdfLoaderOptions { + /// If `true` one collider will be created for each **collision** shape from the urdf file (default: `true`). pub create_colliders_from_collision_shapes: bool, + /// If `true` one collider will be created for each **visual** shape from the urdf file (default: `false`). + /// + /// Note that visual shapes are usually significantly higher-resolution than collision shapes. + /// Most of the time they might also overlap, or generate a lot of contacts due to them being + /// thin triangle meshes. + /// + /// So if this option is set to `true`, it is recommended to also keep + /// [`UrdfLoaderOptions::enable_joint_collisions`] set to `false`. If the model is then added + /// to the physics sets using multibody joints, it is recommended to call + /// [`UrdfRobot::insert_with_multibody_joints`] with the [`UrdfMultibodyOptions::DISABLE_SELF_CONTACTS`] + /// flag enabled. pub create_colliders_from_visual_shapes: bool, + /// If `true`, the mass properties (center-of-mass, mass, and angular inertia) read from the urdf + /// file will be added to the corresponding rigid-body (default: `true`). + /// + /// Note that by default, all colliders created will be given a density of 0.0, meaning that, + /// by default, the imported mass properties are the only ones added to the created rigid-bodies. + /// To give colliders a non-zero density, see [`UrdfLoaderOptions::collider_blueprint`]. pub apply_imported_mass_props: bool, + /// If `true`, collisions between two links sharing a joint will be disabled (default: `false`). + /// + /// It is strongly recommended to leave this to `false` unless you are certain adjacent links + /// colliders don’t overlap. pub enable_joint_collisions: bool, + /// If `true`, the rigid-body at the root of the kinematic chains will be initialized as [`RigidBodyType::Fixed`] + /// (default: `false`). pub make_roots_fixed: bool, + /// This is the set of flags set on all the loaded triangle meshes (default: [`TriMeshFlags::all`]). + /// + /// Note that the default enables all the flags. This is operating under the assumption that the provided + /// mesh are generally well-formed and properly oriented (2-manifolds with outward normals). pub trimesh_flags: TriMeshFlags, + /// The transform appended to every created rigid-bodies (default: [`Isometry::identity`]). pub shift: Isometry, + /// A description of the collider properties that need to be applied to every collider created + /// by the loader (default: `ColliderBuilder::default().density(0.0)`). + /// + /// This collider builder will be used for initializing every collider created by the loader. + /// The shape specified by this builder isn’t important and will be replaced by the shape read + /// from the urdf file. + /// + /// Note that by default, the collider is given a density of 0.0 so that it doesn’t contribute + /// to its parent rigid-body’s mass properties (since they should be already provided by the + /// urdf file assuming the [`UrdfLoaderOptions::apply_imported_mass_props`] wasn’t set `false`). pub collider_blueprint: ColliderBuilder, + /// A description of the rigid-body properties that need to be applied to every rigid-body + /// created by the loader (default: `RigidBodyBuilder::dynamic()`). + /// + /// This rigid-body builder will be used for initializing every rigid-body created by the loader. + /// The rigid-body type is not important as it will always be set to [`RigidBodyType::Dynamic`] + /// for non-root links. Root links will be set to [`RigidBodyType::Fixed`] instead of + /// [`RigidBodyType::Dynamic`] if the [`UrdfLoaderOptions::make_roots_fixed`] is set to `true`. pub rigid_body_blueprint: RigidBodyBuilder, } @@ -50,7 +135,7 @@ impl Default for UrdfLoaderOptions { make_roots_fixed: false, trimesh_flags: TriMeshFlags::all(), shift: Isometry::identity(), - collider_blueprint: ColliderBuilder::ball(0.0).density(0.0), + collider_blueprint: ColliderBuilder::default().density(0.0), rigid_body_blueprint: RigidBodyBuilder::dynamic(), } } @@ -59,7 +144,10 @@ impl Default for UrdfLoaderOptions { /// An urdf link loaded as a rapier [`RigidBody`] and its [`Collider`]s. #[derive(Clone, Debug)] pub struct UrdfLink { + /// The rigid-body created for this link. pub body: RigidBody, + /// All the colliders build from the URDF visual and/or collision shapes (if the corresponding + /// [`UrdfLoaderOptions`] option is enabled). pub colliders: Vec, } @@ -89,28 +177,32 @@ pub struct UrdfRobot { pub joints: Vec, } -impl UrdfRobot { - pub fn append_transform(&mut self, transform: &Isometry) { - for link in &mut self.links { - link.body - .set_position(transform * link.body.position(), true); - } - } -} - +/// Handle of a joint read from the URDF file and inserted into rapier’s `ImpulseJointSet` +/// or a `MultibodyJointSet`. pub struct UrdfJointHandle { + /// The inserted joint handle. pub joint: JointHandle, + /// The handle of the first rigid-body attached by this joint. pub link1: RigidBodyHandle, + /// The handle of the second rigid-body attached by this joint. pub link2: RigidBodyHandle, } +/// The handles related to a link read from the URDF file and inserted into Rapier’s +/// `RigidBodySet` and `ColliderSet`. pub struct UrdfLinkHandle { + /// Handle of the inserted link’s rigid-body. pub body: RigidBodyHandle, + /// Handle of the colliders attached to [`Self::body`]. pub colliders: Vec, } +/// Handles to all the Rapier objects created when inserting this robot into Rapier’s +/// `RigidBodySet`, `ColliderSet`, `ImpulseJointSet`, `MultibodyJointSet`. pub struct UrdfRobotHandles { + /// The handles related to each URDF robot link. pub links: Vec, + /// The handles related to each URDF robot joint. pub joints: Vec>, } @@ -142,27 +234,72 @@ impl JointType { } impl UrdfRobot { + /// Parses a URDF file and returns both the rapier objects (`UrdfRobot`) and the original urdf + /// structures (`Robot`). 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 + /// 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). + /// + /// # Parameters + /// - `path`: the path of the URDF file. + /// - `options`: customize the creation of rapier objects from the URDF description. + /// - `mesh_dir`: the base directory containing the meshes referenced by the URDF file. When + /// a mesh reference is found in the URDF file, this `mesh_dir` is appended + /// to the file path. If `mesh_dir` is `None` then the mesh directory is assumed + /// to be the same directory as the one containing the URDF file. pub fn from_file( path: impl AsRef, options: UrdfLoaderOptions, mesh_dir: Option<&Path>, ) -> anyhow::Result<(Self, Robot)> { - let path = path.as_ref(); - let mesh_dir = mesh_dir.or_else(|| path.parent()); - let robot = xurdf::parse_urdf_from_file(path)?; + let path = path.as_ref().canonicalize()?; + let mesh_dir = mesh_dir + .or_else(|| path.parent()) + .unwrap_or_else(|| Path::new("./")); + let robot = xurdf::parse_urdf_from_file(&path)?; Ok((Self::from_robot(&robot, options, mesh_dir), robot)) } + /// Parses a string in URDF format and returns both the rapier objects (`UrdfRobot`) and the original urdf + /// structures (`Robot`). 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 + /// 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). + /// + /// # Parameters + /// - `str`: the string content of an URDF file. + /// - `options`: customize the creation of rapier objects from the URDF description. + /// - `mesh_dir`: the base directory containing the meshes referenced by the URDF file. When + /// a mesh reference is found in the URDF file, this `mesh_dir` is appended + /// to the file path. pub fn from_str( str: &str, options: UrdfLoaderOptions, - mesh_dir: Option<&Path>, + mesh_dir: &Path, ) -> anyhow::Result<(Self, Robot)> { let robot = xurdf::parse_urdf_from_string(str)?; Ok((Self::from_robot(&robot, options, mesh_dir), robot)) } - pub fn from_robot(robot: &Robot, options: UrdfLoaderOptions, mesh_dir: Option<&Path>) -> Self { + /// From an already loaded urdf file as a `Robot`, this creates the matching rapier objects + /// (`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 + /// 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). + /// + /// # Parameters + /// - `robot`: the robot loaded from an URDF file. + /// - `options`: customize the creation of rapier objects from the URDF description. + /// - `mesh_dir`: the base directory containing the meshes referenced by the URDF file. When + /// a mesh reference is found in the URDF file, this `mesh_dir` is appended + /// to the file path. + pub fn from_robot(robot: &Robot, options: UrdfLoaderOptions, mesh_dir: &Path) -> Self { let mut name_to_link_id = HashMap::new(); let mut link_is_root = vec![true; robot.links.len()]; let mut links: Vec<_> = robot @@ -217,6 +354,11 @@ impl UrdfRobot { Self { links, joints } } + /// Inserts all the robots elements to the rapier rigid-body, collider, and impulse joint, sets. + /// + /// Joints are represented as impulse joints. This implies that joint constraints are simulated + /// in full coordinates using impulses. For a reduced-coordinates approach, see + /// [`UrdfRobot::insert_using_multibody_joints`]. pub fn insert_using_impulse_joints( self, rigid_body_set: &mut RigidBodySet, @@ -253,6 +395,13 @@ impl UrdfRobot { UrdfRobotHandles { links, joints } } + + /// Inserts all the robots elements to the rapier rigid-body, collider, and multibody joint, sets. + /// + /// Joints are represented as multibody joints. This implies that the robot as a whole can be + /// accessed as a single [`Multibody`] from the [`MultibodyJointSet`]. That multibody uses reduced + /// coordinates for modeling joints, meaning that it will be very close to the way they are usually + /// represented for robotics applications. Multibodies also support inverse kinematics. pub fn insert_using_multibody_joints( self, rigid_body_set: &mut RigidBodySet, @@ -303,6 +452,14 @@ impl UrdfRobot { UrdfRobotHandles { links, joints } } + + /// Appends a transform to all the rigid-bodie of this robot. + pub fn append_transform(&mut self, transform: &Isometry) { + for link in &mut self.links { + link.body + .set_position(transform * link.body.position(), true); + } + } } fn urdf_to_rigid_body(options: &UrdfLoaderOptions, inertial: &Inertial) -> RigidBody { @@ -333,13 +490,13 @@ fn urdf_to_rigid_body(options: &UrdfLoaderOptions, inertial: &Inertial) -> Rigid fn urdf_to_collider( options: &UrdfLoaderOptions, - mesh_dir: Option<&Path>, + mesh_dir: &Path, geometry: &Geometry, origin: &Pose, ) -> Option { let mut builder = options.collider_blueprint.clone(); let mut shape_transform = Isometry::identity(); - let mut shape = match &geometry { + let shape = match &geometry { Geometry::Box { size } => SharedShape::cuboid( size[0] as Real / 2.0, size[1] as Real / 2.0, @@ -360,8 +517,8 @@ fn urdf_to_collider( match path.extension().and_then(|ext| ext.to_str()) { #[cfg(feature = "stl")] Some("stl") | Some("STL") => { - let full_path = mesh_dir.map(|dir| dir.join(filename)).unwrap_or_default(); - match rapier_stl::load_from_path( + let full_path = mesh_dir.join(filename); + match rapier3d_stl::load_from_path( &full_path, MeshConverter::TriMeshWithFlags(options.trimesh_flags), scale, @@ -445,7 +602,6 @@ fn urdf_to_joint( .local_axis2(joint_axis); } - /* TODO: panics the multibody match joint_type { JointType::Prismatic => { builder = builder.limits( @@ -461,7 +617,6 @@ fn urdf_to_joint( } _ => {} } - */ // TODO: the following fields are currently ignored: // - Joint::dynamics diff --git a/crates/rapier3d/Cargo.toml b/crates/rapier3d/Cargo.toml index 17a57ae..bd44cfd 100644 --- a/crates/rapier3d/Cargo.toml +++ b/crates/rapier3d/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "rapier3d" version = "0.19.0" -authors = ["Sébastien Crozet "] +authors = ["Sébastien Crozet "] description = "3-dimensional physics engine in Rust." documentation = "https://docs.rs/rapier3d" homepage = "https://rapier.rs" diff --git a/crates/rapier_testbed2d-f64/Cargo.toml b/crates/rapier_testbed2d-f64/Cargo.toml index 800ac49..7a8e314 100644 --- a/crates/rapier_testbed2d-f64/Cargo.toml +++ b/crates/rapier_testbed2d-f64/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "rapier_testbed2d-f64" version = "0.19.0" -authors = ["Sébastien Crozet "] +authors = ["Sébastien Crozet "] description = "Testbed for the Rapier 2-dimensional physics engine in Rust." homepage = "http://rapier.org" repository = "https://github.com/dimforge/rapier" diff --git a/crates/rapier_testbed2d/Cargo.toml b/crates/rapier_testbed2d/Cargo.toml index 3935fcb..3691604 100644 --- a/crates/rapier_testbed2d/Cargo.toml +++ b/crates/rapier_testbed2d/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "rapier_testbed2d" version = "0.19.0" -authors = ["Sébastien Crozet "] +authors = ["Sébastien Crozet "] description = "Testbed for the Rapier 2-dimensional physics engine in Rust." homepage = "http://rapier.org" repository = "https://github.com/dimforge/rapier" diff --git a/crates/rapier_testbed3d-f64/Cargo.toml b/crates/rapier_testbed3d-f64/Cargo.toml index 8fd5628..e987c04 100644 --- a/crates/rapier_testbed3d-f64/Cargo.toml +++ b/crates/rapier_testbed3d-f64/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "rapier_testbed3d-f64" version = "0.19.0" -authors = ["Sébastien Crozet "] +authors = ["Sébastien Crozet "] description = "Testbed for the Rapier 3-dimensional physics engine in Rust." homepage = "http://rapier.org" repository = "https://github.com/dimforge/rapier" diff --git a/crates/rapier_testbed3d/Cargo.toml b/crates/rapier_testbed3d/Cargo.toml index a3f3c5d..8735b39 100644 --- a/crates/rapier_testbed3d/Cargo.toml +++ b/crates/rapier_testbed3d/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "rapier_testbed3d" version = "0.19.0" -authors = ["Sébastien Crozet "] +authors = ["Sébastien Crozet "] description = "Testbed for the Rapier 3-dimensional physics engine in Rust." homepage = "http://rapier.org" repository = "https://github.com/dimforge/rapier" diff --git a/examples2d/Cargo.toml b/examples2d/Cargo.toml index 415f994..771d9d5 100644 --- a/examples2d/Cargo.toml +++ b/examples2d/Cargo.toml @@ -1,22 +1,22 @@ [package] -name = "rapier-examples-2d" +name = "rapier-examples-2d" version = "0.1.0" -authors = [ "Sébastien Crozet " ] +authors = ["Sébastien Crozet "] edition = "2021" default-run = "all_examples2" [features] -parallel = [ "rapier2d/parallel", "rapier_testbed2d/parallel" ] -simd-stable = [ "rapier2d/simd-stable" ] -simd-nightly = [ "rapier2d/simd-nightly" ] -other-backends = [ "rapier_testbed2d/other-backends" ] -enhanced-determinism = [ "rapier2d/enhanced-determinism" ] +parallel = ["rapier2d/parallel", "rapier_testbed2d/parallel"] +simd-stable = ["rapier2d/simd-stable"] +simd-nightly = ["rapier2d/simd-nightly"] +other-backends = ["rapier_testbed2d/other-backends"] +enhanced-determinism = ["rapier2d/enhanced-determinism"] [dependencies] -rand = "0.8" -Inflector = "0.11" -lyon = "0.17" -usvg = "0.14" +rand = "0.8" +Inflector = "0.11" +lyon = "0.17" +usvg = "0.14" [dependencies.rapier_testbed2d] path = "../crates/rapier_testbed2d" diff --git a/examples2d/all_examples2.rs b/examples2d/all_examples2.rs index 39d85f6..6113df4 100644 --- a/examples2d/all_examples2.rs +++ b/examples2d/all_examples2.rs @@ -56,7 +56,7 @@ fn demo_name_from_command_line() -> Option { None } -#[cfg(any(target_arch = "wasm32", target_arch = "asmjs"))] +#[cfg(any(target_arch = "wasm32"))] fn demo_name_from_url() -> Option { None // let window = stdweb::web::window(); @@ -64,7 +64,7 @@ fn demo_name_from_url() -> Option { // Some(hash[1..].to_string()) } -#[cfg(not(any(target_arch = "wasm32", target_arch = "asmjs")))] +#[cfg(not(any(target_arch = "wasm32")))] fn demo_name_from_url() -> Option { None } diff --git a/examples2d/inverse_kinematics2.rs b/examples2d/inverse_kinematics2.rs index 985bdb2..bb62127 100644 --- a/examples2d/inverse_kinematics2.rs +++ b/examples2d/inverse_kinematics2.rs @@ -82,6 +82,7 @@ pub fn init_world(testbed: &mut Testbed) { link_id, &options, &Isometry::from(target_point), + |_| true, &mut displacements, ); multibody.apply_displacements(displacements.as_slice()); diff --git a/examples3d-f64/Cargo.toml b/examples3d-f64/Cargo.toml index 45ffbd2..65e7952 100644 --- a/examples3d-f64/Cargo.toml +++ b/examples3d-f64/Cargo.toml @@ -1,22 +1,22 @@ [package] -name = "rapier-examples-3d-f64" +name = "rapier-examples-3d-f64" version = "0.1.0" -authors = [ "Sébastien Crozet " ] +authors = ["Sébastien Crozet "] edition = "2021" default-run = "all_examples3-f64" [features] -parallel = [ "rapier3d-f64/parallel", "rapier_testbed3d-f64/parallel" ] -simd-stable = [ "rapier3d-f64/simd-stable" ] -simd-nightly = [ "rapier3d-f64/simd-nightly" ] -enhanced-determinism = [ "rapier3d-f64/enhanced-determinism" ] +parallel = ["rapier3d-f64/parallel", "rapier_testbed3d-f64/parallel"] +simd-stable = ["rapier3d-f64/simd-stable"] +simd-nightly = ["rapier3d-f64/simd-nightly"] +enhanced-determinism = ["rapier3d-f64/enhanced-determinism"] [dependencies] rand = "0.8" -getrandom = { version = "0.2", features = [ "js" ] } -Inflector = "0.11" +getrandom = { version = "0.2", features = ["js"] } +Inflector = "0.11" wasm-bindgen = "0.2" -obj-rs = { version = "0.7", default-features = false } +obj-rs = { version = "0.7", default-features = false } bincode = "1" serde = "1" diff --git a/examples3d/Cargo.toml b/examples3d/Cargo.toml index e8b4356..4f09fad 100644 --- a/examples3d/Cargo.toml +++ b/examples3d/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "rapier-examples-3d" version = "0.1.0" -authors = ["Sébastien Crozet "] +authors = ["Sébastien Crozet "] edition = "2021" default-run = "all_examples3" @@ -27,8 +27,8 @@ path = "../crates/rapier_testbed3d" [dependencies.rapier3d] path = "../crates/rapier3d" -[dependencies.rapier-urdf] -path = "../crates/rapier-urdf" +[dependencies.rapier3d-urdf] +path = "../crates/rapier3d-urdf" features = ["stl"] [[bin]] diff --git a/examples3d/all_examples3.rs b/examples3d/all_examples3.rs index ec4f533..72a3cf7 100644 --- a/examples3d/all_examples3.rs +++ b/examples3d/all_examples3.rs @@ -71,7 +71,7 @@ fn demo_name_from_command_line() -> Option { None } -#[cfg(any(target_arch = "wasm32", target_arch = "asmjs"))] +#[cfg(target_arch = "wasm32")] fn demo_name_from_url() -> Option { None // let window = stdweb::web::window(); @@ -83,7 +83,7 @@ fn demo_name_from_url() -> Option { // } } -#[cfg(not(any(target_arch = "wasm32", target_arch = "asmjs")))] +#[cfg(not(target_arch = "wasm32"))] fn demo_name_from_url() -> Option { None } diff --git a/examples3d/urdf3.rs b/examples3d/urdf3.rs index ea65d8c..815cfb6 100644 --- a/examples3d/urdf3.rs +++ b/examples3d/urdf3.rs @@ -1,7 +1,6 @@ use rapier3d::prelude::*; +use rapier3d_urdf::{UrdfLoaderOptions, UrdfMultibodyOptions, UrdfRobot}; use rapier_testbed3d::Testbed; -use rapier_urdf::{UrdfLoaderOptions, UrdfMultibodyOptions, UrdfRobot}; -use std::path::Path; pub fn init_world(testbed: &mut Testbed) { /* @@ -45,5 +44,5 @@ pub fn init_world(testbed: &mut Testbed) { * Set up the testbed. */ testbed.set_world(bodies, colliders, impulse_joints, multibody_joints); - testbed.look_at(point![100.0, 100.0, 100.0], Point::origin()); + testbed.look_at(point![20.0, 20.0, 20.0], point![5.0, 0.0, 0.0]); } diff --git a/src/dynamics/ccd/toi_entry.rs b/src/dynamics/ccd/toi_entry.rs index 426cbb1..82b4532 100644 --- a/src/dynamics/ccd/toi_entry.rs +++ b/src/dynamics/ccd/toi_entry.rs @@ -13,7 +13,6 @@ pub struct TOIEntry { // We call this "pseudo" intersection because this also // includes colliders pairs with mismatching solver_groups. pub is_pseudo_intersection_test: bool, - pub timestamp: usize, } impl TOIEntry { @@ -24,7 +23,6 @@ impl TOIEntry { c2: ColliderHandle, b2: Option, is_pseudo_intersection_test: bool, - timestamp: usize, ) -> Self { Self { toi, @@ -33,7 +31,6 @@ impl TOIEntry { c2, b2, is_pseudo_intersection_test, - timestamp, } } @@ -149,7 +146,6 @@ impl TOIEntry { ch2, co2.parent.map(|p| p.handle), is_pseudo_intersection_test, - 0, )) } diff --git a/src/dynamics/joint/multibody_joint/multibody.rs b/src/dynamics/joint/multibody_joint/multibody.rs index 352f289..acf1444 100644 --- a/src/dynamics/joint/multibody_joint/multibody.rs +++ b/src/dynamics/joint/multibody_joint/multibody.rs @@ -569,8 +569,6 @@ impl Multibody { return; // Nothing to do. } - let mut kinematic_ndofs = 0; - if self.augmented_mass.ncols() != self.ndofs { // TODO: do a resize instead of a full reallocation. self.augmented_mass = DMatrix::zeros(self.ndofs, self.ndofs); @@ -1058,7 +1056,7 @@ impl Multibody { bodies: &RigidBodySet, link_id: usize, displacement: Option<&[Real]>, - mut out_jacobian: Option<&mut Jacobian>, + out_jacobian: Option<&mut Jacobian>, ) -> Isometry { let branch = self.kinematic_branch(link_id); self.forward_kinematics_single_branch(bodies, &branch, displacement, out_jacobian) diff --git a/src/dynamics/joint/multibody_joint/multibody_joint.rs b/src/dynamics/joint/multibody_joint/multibody_joint.rs index 6b37cb9..179b061 100644 --- a/src/dynamics/joint/multibody_joint/multibody_joint.rs +++ b/src/dynamics/joint/multibody_joint/multibody_joint.rs @@ -17,6 +17,10 @@ use na::{UnitQuaternion, Vector3}; pub struct MultibodyJoint { /// The joint’s description. pub data: GenericJoint, + /// Is the joint a kinematic joint? + /// + /// Kinematic joint velocities are never changed by the physics engine. This gives the user + /// total control over the values of their degrees of freedoms. pub kinematic: bool, pub(crate) coords: SpacialVector, pub(crate) joint_rot: Rotation, diff --git a/src/dynamics/joint/multibody_joint/multibody_joint_set.rs b/src/dynamics/joint/multibody_joint/multibody_joint_set.rs index 092a250..6ffdece 100644 --- a/src/dynamics/joint/multibody_joint/multibody_joint_set.rs +++ b/src/dynamics/joint/multibody_joint/multibody_joint_set.rs @@ -158,7 +158,6 @@ impl MultibodyJointSet { kinematic: bool, wake_up: bool, ) -> Option { - println!("Inserting kinematic: {}", kinematic); let link1 = self.rb2mb.get(body1.0).copied().unwrap_or_else(|| { let mb_handle = self.multibodies.insert(Multibody::with_root(body1, true)); MultibodyLinkId { diff --git a/src/dynamics/solver/contact_constraint/contact_constraints_set.rs b/src/dynamics/solver/contact_constraint/contact_constraints_set.rs index 6809c37..4d2b40d 100644 --- a/src/dynamics/solver/contact_constraint/contact_constraints_set.rs +++ b/src/dynamics/solver/contact_constraint/contact_constraints_set.rs @@ -28,6 +28,7 @@ use { #[derive(Debug)] pub struct ConstraintsCounts { pub num_constraints: usize, + #[allow(dead_code)] // Keep this around for now. Might be useful once we rework parallelism. pub num_jacobian_lines: usize, } diff --git a/src/dynamics/solver/joint_constraint/joint_constraint_builder.rs b/src/dynamics/solver/joint_constraint/joint_constraint_builder.rs index 40613c1..c6d5fa0 100644 --- a/src/dynamics/solver/joint_constraint/joint_constraint_builder.rs +++ b/src/dynamics/solver/joint_constraint/joint_constraint_builder.rs @@ -9,11 +9,11 @@ use crate::dynamics::{GenericJoint, ImpulseJoint, IntegrationParameters, JointIn use crate::math::{AngVector, Isometry, Matrix, Point, Real, Rotation, Vector, ANG_DIM, DIM}; use crate::prelude::RigidBodySet; use crate::utils; -use crate::utils::{IndexMut2, SimdCrossMatrix, SimdDot, SimdQuat, SimdRealCopy}; +use crate::utils::{IndexMut2, SimdCrossMatrix, SimdDot, SimdRealCopy}; use na::SMatrix; #[cfg(feature = "dim3")] -use crate::utils::SimdBasis; +use crate::utils::{SimdBasis, SimdQuat}; #[cfg(feature = "simd-is-enabled")] use crate::math::{SimdReal, SIMD_WIDTH}; @@ -345,9 +345,11 @@ impl JointOneBodyConstraintBuilderSimd { #[derive(Debug, Copy, Clone)] pub struct JointTwoBodyConstraintHelper { pub basis: Matrix, + #[cfg(feature = "dim3")] pub basis2: Matrix, // TODO: used for angular coupling. Can we avoid storing this? pub cmat1_basis: SMatrix, pub cmat2_basis: SMatrix, + #[cfg(feature = "dim3")] pub ang_basis: SMatrix, pub lin_err: Vector, pub ang_err: Rotation, @@ -387,7 +389,7 @@ impl JointTwoBodyConstraintHelper { let cmat1 = r1.gcross_matrix(); let cmat2 = r2.gcross_matrix(); - #[allow(unused_mut)] // The mut is needed for 3D + #[cfg(feature = "dim3")] let mut ang_basis = frame1.rotation.diff_conj1_2(&frame2.rotation).transpose(); #[allow(unused_mut)] // The mut is needed for 3D let mut ang_err = frame1.rotation.inverse() * frame2.rotation; @@ -401,9 +403,11 @@ impl JointTwoBodyConstraintHelper { Self { basis, + #[cfg(feature = "dim3")] basis2: frame2.rotation.to_rotation_matrix().into_inner(), cmat1_basis: cmat1 * basis, cmat2_basis: cmat2 * basis, + #[cfg(feature = "dim3")] ang_basis, lin_err, ang_err, diff --git a/src/geometry/mesh_converter.rs b/src/geometry/mesh_converter.rs index 44d5829..5d47f79 100644 --- a/src/geometry/mesh_converter.rs +++ b/src/geometry/mesh_converter.rs @@ -1,6 +1,8 @@ use parry::bounding_volume; -use parry::math::{Isometry, Point, Real, DIM}; +use parry::math::{Isometry, Point, Real}; use parry::shape::{Cuboid, SharedShape, TriMeshFlags}; + +#[cfg(feature = "dim3")] use parry::transformation::vhacd::VHACDParameters; /* @@ -9,8 +11,10 @@ use parry::transformation::vhacd::VHACDParameters; * */ +/// Error that can be generated by the [`MeshConverter`]. #[derive(thiserror::Error, Debug)] pub enum MeshConverterError { + /// The convex hull calculation carried out by the [`MeshConverter::ConvexHull`] failed. #[error("convex-hull computation failed")] ConvexHullFailed, } @@ -47,6 +51,8 @@ pub enum MeshConverter { } impl MeshConverter { + /// Applies the conversion rule described by this [`MeshConverter`] to build a shape from + /// the given vertex and index buffers. pub fn convert( &self, vertices: Vec>, diff --git a/src/lib.rs b/src/lib.rs index 5c660ba..9383546 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -11,7 +11,7 @@ //! User documentation for Rapier is on [the official Rapier site](https://rapier.rs/docs/). #![deny(bare_trait_objects)] -#![warn(missing_docs)] // FIXME: deny that +#![warn(missing_docs)] #![allow(clippy::too_many_arguments)] #![allow(clippy::needless_range_loop)] // TODO: remove this? I find that in the math code using indices adds clarity. #![allow(clippy::module_inception)]