mirror of
https://github.com/bevyengine/bevy
synced 2024-09-20 06:22:01 +00:00
900f50d77d
# Objective
Allow random sampling from the surfaces of triangle meshes.
## Solution
This has two parts.
Firstly, rendering meshes can now yield their collections of triangles
through a method `Mesh::triangles`. This has signature
```rust
pub fn triangles(&self) -> Result<Vec<Triangle3d>, MeshTrianglesError> { //... }
```
and fails in a variety of cases — the most obvious of these is that the
mesh must have either the `TriangleList` or `TriangleStrip` topology,
and the others correspond to malformed vertex or triangle-index data.
With that in hand, we have the second piece, which is
`UniformMeshSampler`, which is a `Vec3`-valued
[distribution](https://docs.rs/rand/latest/rand/distributions/trait.Distribution.html)
that samples uniformly from collections of triangles. It caches the
triangles' distribution of areas so that after its initial setup,
sampling is allocation-free. It is constructed via
`UniformMeshSampler::try_new`, which looks like this:
```rust
pub fn try_new<T: Into<Vec<Triangle3d>>>(triangles: T) -> Result<Self, ZeroAreaMeshError> { //... }
```
It fails if the collection of triangles has zero area.
The sum of these parts means that you can sample random points from a
mesh as follows:
```rust
let triangles = my_mesh.triangles().unwrap();
let mut rng = StdRng::seed_from_u64(8765309);
let distribution = UniformMeshSampler::try_new(triangles).unwrap();
// 10000 random points from the surface of my_mesh:
let sample_points: Vec<Vec3> = distribution.sample_iter(&mut rng).take(10000).collect();
```
## Testing
Tested by instantiating meshes and sampling as demonstrated above.
---
## Changelog
- Added `Mesh::triangles` method to get a collection of triangles from a
mesh.
- Added `UniformMeshSampler` to `bevy_math::sampling`. This is a
distribution which allows random sampling over collections of triangles
(such as those provided through meshes).
---
## Discussion
### Design decisions
The main thing here was making sure to have a good separation between
the parts of this in `bevy_render` and in `bevy_math`. Getting the
triangles from a mesh seems like a reasonable step after adding
`Triangle3d` to `bevy_math`, so I decided to make all of the random
sampling operate at that level, with the fallible conversion to
triangles doing most of the work.
Notably, the sampler could be called something else that reflects that
its input is a collection of triangles, but if/when we add other kinds
of meshes to `bevy_math` (e.g. half-edge meshes), the fact that
`try_new` takes an `impl Into<Vec<Triangle3d>>` means that those meshes
just need to satisfy that trait bound in order to work immediately with
this sampling functionality. In that case, the result would just be
something like this:
```rust
let dist = UniformMeshSampler::try_new(mesh).unwrap();
```
I think this highlights that most of the friction is really just from
extracting data from `Mesh`.
It's maybe worth mentioning also that "collection of triangles"
(`Vec<Triangle3d>`) sits downstream of any other kind of triangle mesh,
since the topology connecting the triangles has been effectively erased,
which makes an `Into<Vec<Triangle3d>>` trait bound seem all the more
natural to me.
---------
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
60 lines
2 KiB
TOML
60 lines
2 KiB
TOML
[package]
|
|
name = "bevy_math"
|
|
version = "0.14.0-dev"
|
|
edition = "2021"
|
|
description = "Provides math functionality for Bevy Engine"
|
|
homepage = "https://bevyengine.org"
|
|
repository = "https://github.com/bevyengine/bevy"
|
|
license = "MIT OR Apache-2.0"
|
|
keywords = ["bevy"]
|
|
rust-version = "1.68.2"
|
|
|
|
[dependencies]
|
|
glam = { version = "0.27", features = ["bytemuck"] }
|
|
thiserror = "1.0"
|
|
serde = { version = "1", features = ["derive"], optional = true }
|
|
libm = { version = "0.2", optional = true }
|
|
approx = { version = "0.5", optional = true }
|
|
rand = { version = "0.8", features = [
|
|
"alloc",
|
|
], default-features = false, optional = true }
|
|
rand_distr = { version = "0.4.3", optional = true }
|
|
smallvec = { version = "1.11" }
|
|
|
|
bevy_reflect = { path = "../bevy_reflect", version = "0.14.0-dev", features = [
|
|
"glam",
|
|
], optional = true }
|
|
|
|
[dev-dependencies]
|
|
approx = "0.5"
|
|
# Supply rngs for examples and tests
|
|
rand = "0.8"
|
|
rand_chacha = "0.3"
|
|
# Enable the approx feature when testing.
|
|
bevy_math = { path = ".", version = "0.14.0-dev", features = ["approx"] }
|
|
glam = { version = "0.27", features = ["approx"] }
|
|
|
|
|
|
[features]
|
|
default = ["rand", "bevy_reflect"]
|
|
serialize = ["dep:serde", "glam/serde"]
|
|
# Enable approx for glam types to approximate floating point equality comparisons and assertions
|
|
approx = ["dep:approx", "glam/approx"]
|
|
# Enable interoperation of glam types with mint-compatible libraries
|
|
mint = ["glam/mint"]
|
|
# Enable libm mathematical functions for glam types to ensure consistent outputs
|
|
# across platforms at the cost of losing hardware-level optimization using intrinsics
|
|
libm = ["dep:libm", "glam/libm"]
|
|
# Enable assertions to check the validity of parameters passed to glam
|
|
glam_assert = ["glam/glam-assert"]
|
|
# Enable assertions in debug builds to check the validity of parameters passed to glam
|
|
debug_glam_assert = ["glam/debug-glam-assert"]
|
|
# Enable the rand dependency for shape_sampling
|
|
rand = ["dep:rand", "dep:rand_distr", "glam/rand"]
|
|
|
|
[lints]
|
|
workspace = true
|
|
|
|
[package.metadata.docs.rs]
|
|
rustdoc-args = ["-Zunstable-options", "--cfg", "docsrs"]
|
|
all-features = true
|