Update to 0.4.0

README.md

@@ -24,10 +24,6 @@ documentation: https://docs.rs/mesh_to_sdf/latest/mesh_to_sdf/
 
 ## `mesh_to_sdf`: Convert a mesh to a signed distance field (SDF).
 
-⚠️ This crate is still in its early stages. Expect the API to change.
-
----
-
 This crate provides two entry points:
 
 - [`generate_sdf`]: computes the signed distance field for the mesh defined by `vertices` and `indices` at the points `query_points`.
@@ -47,9 +43,8 @@ let sdf: Vec<f32> = generate_sdf(
     &vertices,
     Topology::TriangleList(Some(&indices)), // TriangleList as opposed to TriangleStrip
     &query_points,
-    AccelerationMethod::Bvh,    // Use bvh to accelerate queries.
-    SignMethod::Raycast,        // How the sign is computed.
-);                              // Raycast is robust but requires the mesh to be watertight.
+    AccelerationMethod::RtreeBvh, // Use an r-tree and a bvh to accelerate queries.
+);
 
 for point in query_points.iter().zip(sdf.iter()) {
     // distance is positive outside the mesh and negative inside.
@@ -67,9 +62,11 @@ let sdf: Vec<f32> = generate_grid_sdf(
     &vertices,
     Topology::TriangleList(Some(&indices)),
     &grid,
-    SignMethod::Normal, // How the sign is computed.
-);                      // Normal might leak negative distances outside the mesh
-                        // but works for all meshes, even surfaces.
+    SignMethod::Raycast, // How the sign is computed.
+                         // Raycast is robust but requires the mesh to be watertight.
+                         // and is more expensive.
+                         // Normal might leak negative distances outside the mesh
+);                       // but works for all meshes, even surfaces.
 
 for x in 0..cell_count[0] {
     for y in 0..cell_count[1] {
@@ -89,7 +86,7 @@ Indices can be of any type that implements `Into<u32>`, e.g. `u16` and `u32`. To
 If the indices are not provided, they are supposed to be `0..vertices.len()`.
 
 For vertices, this library aims to be as generic as possible by providing a trait `Point` that can be implemented for any type.
-Implementations for most common math libraries are gated behind feature flags. By default, only `[f32; 3]` is provided.
+Implementations for most common math libraries are gated behind feature flags. By default, `[f32; 3]` and `nalgebra::[Point3, Vector3]` are provided.
 If you do not find your favorite library, feel free to implement the trait for it and submit a PR or open an issue.
 
 ---
@@ -102,9 +99,26 @@ This crate provides two methods to compute the sign of the distance:
 - [`SignMethod::Normal`]: uses the normals of the triangles to estimate the sign by doing a dot product with the direction of the query point.
     It works for non-watertight meshes but might leak negative distances outside the mesh.
 
-For grid generation, `Raycast` is ~1% slower.
-For query points, `Raycast` is ~10% slower.
-Note that it depends on the query points / grid size to triangle ratio, but this gives a rough idea.
+Using `Raycast` is slower than `Normal` but gives better results. Performances depends on the triangle count and method used.
+On big dataset, `Raycast` is 5-10% slower for grid generation and rtree based methods. On smaller dataset, the difference can be worse
+depending on whether the query is triangle intensive or query point intensive.
+For bvh the difference is negligible between the two methods.
+
+---
+
+##### Acceleration structures
+
+For generic queries, you can use acceleration structures to speed up the computation.
+- [`AccelerationMethod::None`]: no acceleration structure. This is the slowest method but requires no extra memory. Scales really poorly.
+- [`AccelerationMethod::Bvh`]: Bounding Volume Hierarchy. Accepts a `SignMethod`.
+- [`AccelerationMethod::Rtree`]: R-tree. Uses `SignMethod::Normal`. The fastest method assuming you have more than a couple thousands of queries.
+- [`AccelerationMethod::RtreeBvh`] (default): Uses R-tree for nearest neighbor search and Bvh for `SignMethod::Raycast`. 5-10% slower than `Rtree` on big datasets.
+
+If your mesh is watertight and you have more than a thousand queries/triangles, you should use `AccelerationMethod::RtreeBvh` for best performances.
+If it's not watertight, you can use `AccelerationMethod::Rtree` instead.
+
+`Rtree` methods are 3-4x faster than `Bvh` methods for big enough data. On small meshes, the difference is negligible.
+`AccelerationMethod::None` scales really poorly and should be avoided unless for small datasets or if you're really tight on memory.
 
 ---
 
@@ -123,25 +137,15 @@ Currently, the following libraries are supported:
 - [nalgebra] ([`nalgebra::Vector3<f32>`] and [`nalgebra::Point3<f32>`])
 - `[f32; 3]`
 
+[nalgebra] is always available as it's used internally in the bvh tree.
+
 ---
 
 ##### Serialization
 
 If you want to serialize and deserialize signed distance fields, you need to enable the `serde` feature.
 This features also provides helpers to save and load signed distance fields to and from files via `save_to_file` and `read_from_file`.
 
----
-
-##### Benchmarks
-
-[`generate_grid_sdf`] is much faster than [`generate_sdf`] and should be used whenever possible.
-[`generate_sdf`] does not allocate memory (except for the result array) but is slow. A faster implementation is planned for the future.
-
-[`SignMethod::Raycast`] is slightly slower than [`SignMethod::Normal`] but is robust and should be used whenever possible (~1% in [`generate_grid_sdf`], ~10% in [`generate_sdf`]).
-
----
-
-TODO: Add benchmarks against other libraries.
 
 ## `mesh_to_sdf_client` Mesh to SDF visualization client.
 

mesh_to_sdf/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mesh_to_sdf"
-version = "0.3.0"
+version = "0.4.0"
 description = "Mesh to signed distance field (SDF) converter"
 edition = "2021"
 license = "MIT OR Apache-2.0"

mesh_to_sdf/README.md

@@ -1,9 +1,5 @@
 # mesh_to_sdf
 
-⚠️ This crate is still in its early stages. Expect the API to change.
-
----
-
 This crate provides two entry points:
 
 - [`generate_sdf`]: computes the signed distance field for the mesh defined by `vertices` and `indices` at the points `query_points`.
@@ -42,9 +38,11 @@ let sdf: Vec<f32> = generate_grid_sdf(
     &vertices,
     Topology::TriangleList(Some(&indices)),
     &grid,
-    SignMethod::Normal, // How the sign is computed.
-);                      // Normal might leak negative distances outside the mesh
-                        // but works for all meshes, even surfaces.
+    SignMethod::Raycast, // How the sign is computed.
+                         // Raycast is robust but requires the mesh to be watertight.
+                         // and is more expensive.
+                         // Normal might leak negative distances outside the mesh
+);                       // but works for all meshes, even surfaces.
 
 for x in 0..cell_count[0] {
     for y in 0..cell_count[1] {
@@ -64,7 +62,7 @@ Indices can be of any type that implements `Into<u32>`, e.g. `u16` and `u32`. To
 If the indices are not provided, they are supposed to be `0..vertices.len()`.
 
 For vertices, this library aims to be as generic as possible by providing a trait `Point` that can be implemented for any type.
-Implementations for most common math libraries are gated behind feature flags. By default, only `[f32; 3]` is provided.
+Implementations for most common math libraries are gated behind feature flags. By default, `[f32; 3]` and `nalgebra::[Point3, Vector3]` are provided.
 If you do not find your favorite library, feel free to implement the trait for it and submit a PR or open an issue.
 
 ---
@@ -77,22 +75,26 @@ This crate provides two methods to compute the sign of the distance:
 - [`SignMethod::Normal`]: uses the normals of the triangles to estimate the sign by doing a dot product with the direction of the query point.
     It works for non-watertight meshes but might leak negative distances outside the mesh.
 
-Both methods have roughly the same performances, depending on the acceleration structure used for generic queries.
+Using `Raycast` is slower than `Normal` but gives better results. Performances depends on the triangle count and method used.
+On big dataset, `Raycast` is 5-10% slower for grid generation and rtree based methods. On smaller dataset, the difference can be worse
+depending on whether the query is triangle intensive or query point intensive.
+For bvh the difference is negligible between the two methods.
 
 ---
 
 ##### Acceleration structures
 
 For generic queries, you can use acceleration structures to speed up the computation.
-- [`AccelerationMethod::None`]: no acceleration structure. This is the slowest method but requires no extra memory.
+- [`AccelerationMethod::None`]: no acceleration structure. This is the slowest method but requires no extra memory. Scales really poorly.
 - [`AccelerationMethod::Bvh`]: Bounding Volume Hierarchy. Accepts a `SignMethod`.
-- [`AccelerationMethod::Rtree`]: R-tree. Only compatible with `SignMethod::Normal`. The fastest method assuming you have more than a couple thousands of queries.
-- [`AccelerationMethod::RtreeBvh`] (default): Uses R-tree for nearest neighbor search and Bvh for raycasting.
+- [`AccelerationMethod::Rtree`]: R-tree. Uses `SignMethod::Normal`. The fastest method assuming you have more than a couple thousands of queries.
+- [`AccelerationMethod::RtreeBvh`] (default): Uses R-tree for nearest neighbor search and Bvh for `SignMethod::Raycast`. 5-10% slower than `Rtree` on big datasets.
 
 If your mesh is watertight and you have more than a thousand queries/triangles, you should use `AccelerationMethod::RtreeBvh` for best performances.
 If it's not watertight, you can use `AccelerationMethod::Rtree` instead.
 
-`Rtree` methods are ~4x faster than `Bvh` methods for big enough data. `AccelerationMethod::None` scales really poorly and should be avoided unless for small datasets or if you're really tight on memory.
+`Rtree` methods are 3-4x faster than `Bvh` methods for big enough data. On small meshes, the difference is negligible.
+`AccelerationMethod::None` scales really poorly and should be avoided unless for small datasets or if you're really tight on memory.
 
 ---
 
@@ -111,20 +113,13 @@ Currently, the following libraries are supported:
 - [nalgebra] ([`nalgebra::Vector3<f32>`] and [`nalgebra::Point3<f32>`])
 - `[f32; 3]`
 
+[nalgebra] is always available as it's used internally in the bvh tree.
+
 ---
 
 ##### Serialization
 
 If you want to serialize and deserialize signed distance fields, you need to enable the `serde` feature.
 This features also provides helpers to save and load signed distance fields to and from files via `save_to_file` and `read_from_file`.
 
----
-
-##### Benchmarks
-
-[`generate_grid_sdf`] is much faster than [`generate_sdf`] and should be used whenever possible.
-[`generate_sdf`] does not allocate memory (except for the result array) but is slow. A faster implementation is planned for the future.
-
-[`SignMethod::Raycast`] is slightly slower than [`SignMethod::Normal`] but is robust and should be used whenever possible (~1% in [`generate_grid_sdf`], ~10% in [`generate_sdf`]).
-
 License: MIT OR Apache-2.0

mesh_to_sdf_client/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "mesh_to_sdf_client"
 authors = ["Etienne Desbois <[email protected]>"]
-version = "0.3.1"
+version = "0.4.0"
 edition = "2021"
 homepage = "https://github.com/Azkellas/mesh_to_sdf"
 license = "MIT OR Apache-2.0"