Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-12-22 11:03:06 +00:00
Code Issues Projects Releases Packages Wiki Activity
bevy/crates/bevy_math/src/sampling/mod.rs

14 lines
309 B
Rust
Raw Normal View History

Random sampling of directions and quaternions (#12857) # Objective Augment Bevy's random sampling capabilities by providing good tools for producing random directions and rotations. ## Solution The `rand` crate has a natural tool for providing `Distribution`s whose output is a type that doesn't require any additional data to sample values — namely, [`Standard`](https://docs.rs/rand/latest/rand/distributions/struct.Standard.html). Here, our existing `ShapeSample` implementations have been put to good use in providing these, resulting in patterns like the following: ```rust // Using thread-local rng let random_direction1: Dir3 = random(); // Using an explicit rng let random_direction2: Dir3 = rng.gen(); // Using an explicit rng coupled explicitly with Standard let random_directions: Vec<Dir3> = rng.sample_iter(Standard).take(5).collect(); ``` Furthermore, we have introduced a trait `FromRng` which provides sugar for `rng.gen()` that is more namespace-friendly (in this author's opinion): ```rust let random_direction = Dir3::from_rng(rng); ``` The types this has been implemented for are `Dir2`, `Dir3`, `Dir3A`, and `Quat`. Notably, `Quat` uses `glam`'s implementation rather than an in-house one, and as a result, `bevy_math`'s "rand" feature now enables that of `glam`. --- ## Changelog - Created `standard` submodule in `sampling` to hold implementations and other items related to the `Standard` distribution. - "rand" feature of `bevy_math` now enables that of `glam`. --- ## Discussion From a quick glance at `Quat`'s distribution implementation in `glam`, I am a bit suspicious, since it is simple and doesn't match any algorithm that I came across in my research. I will do a little more digging as a follow-up to this and see if it's actually uniform (maybe even using those tools I wrote — what a thrill). As an aside, I'd also like to say that I think [`Distribution`](https://docs.rs/rand/latest/rand/distributions/trait.Distribution.html) is really, really good. It integrates with distributions provided externally (e.g. in `rand` itself and its extensions) along with doing a good job of isolating the source of randomness, so that output can be reliably reproduced if need be. Finally, `Distribution::sample_iter` is quite good for ergonomically acquiring lots of random values. At one point I found myself writing traits to describe random sampling and essentially reinvented this one. I just think it's good, and I think it's worth centralizing around to a significant extent.
2024-04-04 23:13:00 +00:00
//! This module contains tools related to random sampling.
//!
//! To use this, the "rand" feature must be enabled.
Add `no_std` Support to `bevy_math` (#15810) # Objective - Contributes to #15460 ## Solution - Added two new features, `std` (default) and `alloc`, gating `std` and `alloc` behind them respectively. - Added missing `f32` functions to `std_ops` as required. These `f32` methods have been added to the `clippy.toml` deny list to aid in `no_std` development. ## Testing - CI - `cargo clippy -p bevy_math --no-default-features --features libm --target "x86_64-unknown-none"` - `cargo test -p bevy_math --no-default-features --features libm` - `cargo test -p bevy_math --no-default-features --features "libm, alloc"` - `cargo test -p bevy_math --no-default-features --features "libm, alloc, std"` - `cargo test -p bevy_math --no-default-features --features "std"` ## Notes The following items require the `alloc` feature to be enabled: - `CubicBSpline` - `CubicBezier` - `CubicCardinalSpline` - `CubicCurve` - `CubicGenerator` - `CubicHermite` - `CubicNurbs` - `CyclicCubicGenerator` - `RationalCurve` - `RationalGenerator` - `BoxedPolygon` - `BoxedPolyline2d` - `BoxedPolyline3d` - `SampleCurve` - `SampleAutoCurve` - `UnevenSampleCurve` - `UnevenSampleAutoCurve` - `EvenCore` - `UnevenCore` - `ChunkedUnevenCore` This requirement could be relaxed in certain cases, but I had erred on the side of gating rather than modifying. Since `no_std` is a new set of platforms we are adding support to, and the `alloc` feature is enabled by default, this is not a breaking change. --------- Co-authored-by: Benjamin Brienen <benjamin.brienen@outlook.com> Co-authored-by: Matty <2975848+mweatherley@users.noreply.github.com> Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>
2024-12-03 17:14:51 +00:00
#[cfg(feature = "alloc")]
Uniform mesh sampling (#14071) # 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>
2024-07-08 00:57:08 +00:00
pub mod mesh_sampling;
Add `Distribution` access methods for `ShapeSample` trait (#13315) Stolen from #12835. # Objective Sometimes you want to sample a whole bunch of points from a shape instead of just one. You can write your own loop to do this, but it's really more idiomatic to use a `rand` [`Distribution`](https://docs.rs/rand/latest/rand/distributions/trait.Distribution.html) with the `sample_iter` method. Distributions also support other useful things like mapping, and they are suitable as generic items for consumption by other APIs. ## Solution `ShapeSample` has been given two new automatic trait methods, `interior_dist` and `boundary_dist`. They both have similar signatures (recall that `Output` is the output type for `ShapeSample`): ```rust fn interior_dist(self) -> impl Distribution<Self::Output> where Self: Sized { //... } ``` These have default implementations which are powered by wrapper structs `InteriorOf` and `BoundaryOf` that actually implement `Distribution` — the implementations effectively just call `ShapeSample::sample_interior` and `ShapeSample::sample_boundary` on the contained type. The upshot is that this allows iteration as follows: ```rust // Get an iterator over boundary points of a rectangle: let rectangle = Rectangle::new(1.0, 2.0); let boundary_iter = rectangle.boundary_dist().sample_iter(rng); // Collect a bunch of boundary points at once: let boundary_pts: Vec<Vec2> = boundary_iter.take(1000).collect(); ``` Alternatively, you can use `InteriorOf`/`BoundaryOf` explicitly to similar effect: ```rust let boundary_pts: Vec<Vec2> = BoundaryOf(rectangle).sample_iter(rng).take(1000).collect(); ``` --- ## Changelog - Added `InteriorOf` and `BoundaryOf` distribution wrapper structs in `bevy_math::sampling::shape_sampling`. - Added `interior_dist` and `boundary_dist` automatic trait methods to `ShapeSample`. - Made `shape_sampling` module public with explanatory documentation. --- ## Discussion ### Design choices The main point of interest here is just the choice of `impl Distribution` instead of explicitly using `InteriorOf`/`BoundaryOf` return types for `interior_dist` and `boundary_dist`. The reason for this choice is that it allows future optimizations for repeated sampling — for example, instead of just wrapping the base type, `interior_dist`/`boundary_dist` could construct auxiliary data that is held over between sampling operations.
2024-05-22 12:38:08 +00:00
pub mod shape_sampling;
Random sampling of directions and quaternions (#12857) # Objective Augment Bevy's random sampling capabilities by providing good tools for producing random directions and rotations. ## Solution The `rand` crate has a natural tool for providing `Distribution`s whose output is a type that doesn't require any additional data to sample values — namely, [`Standard`](https://docs.rs/rand/latest/rand/distributions/struct.Standard.html). Here, our existing `ShapeSample` implementations have been put to good use in providing these, resulting in patterns like the following: ```rust // Using thread-local rng let random_direction1: Dir3 = random(); // Using an explicit rng let random_direction2: Dir3 = rng.gen(); // Using an explicit rng coupled explicitly with Standard let random_directions: Vec<Dir3> = rng.sample_iter(Standard).take(5).collect(); ``` Furthermore, we have introduced a trait `FromRng` which provides sugar for `rng.gen()` that is more namespace-friendly (in this author's opinion): ```rust let random_direction = Dir3::from_rng(rng); ``` The types this has been implemented for are `Dir2`, `Dir3`, `Dir3A`, and `Quat`. Notably, `Quat` uses `glam`'s implementation rather than an in-house one, and as a result, `bevy_math`'s "rand" feature now enables that of `glam`. --- ## Changelog - Created `standard` submodule in `sampling` to hold implementations and other items related to the `Standard` distribution. - "rand" feature of `bevy_math` now enables that of `glam`. --- ## Discussion From a quick glance at `Quat`'s distribution implementation in `glam`, I am a bit suspicious, since it is simple and doesn't match any algorithm that I came across in my research. I will do a little more digging as a follow-up to this and see if it's actually uniform (maybe even using those tools I wrote — what a thrill). As an aside, I'd also like to say that I think [`Distribution`](https://docs.rs/rand/latest/rand/distributions/trait.Distribution.html) is really, really good. It integrates with distributions provided externally (e.g. in `rand` itself and its extensions) along with doing a good job of isolating the source of randomness, so that output can be reliably reproduced if need be. Finally, `Distribution::sample_iter` is quite good for ergonomically acquiring lots of random values. At one point I found myself writing traits to describe random sampling and essentially reinvented this one. I just think it's good, and I think it's worth centralizing around to a significant extent.
2024-04-04 23:13:00 +00:00
pub mod standard;
Add `no_std` Support to `bevy_math` (#15810) # Objective - Contributes to #15460 ## Solution - Added two new features, `std` (default) and `alloc`, gating `std` and `alloc` behind them respectively. - Added missing `f32` functions to `std_ops` as required. These `f32` methods have been added to the `clippy.toml` deny list to aid in `no_std` development. ## Testing - CI - `cargo clippy -p bevy_math --no-default-features --features libm --target "x86_64-unknown-none"` - `cargo test -p bevy_math --no-default-features --features libm` - `cargo test -p bevy_math --no-default-features --features "libm, alloc"` - `cargo test -p bevy_math --no-default-features --features "libm, alloc, std"` - `cargo test -p bevy_math --no-default-features --features "std"` ## Notes The following items require the `alloc` feature to be enabled: - `CubicBSpline` - `CubicBezier` - `CubicCardinalSpline` - `CubicCurve` - `CubicGenerator` - `CubicHermite` - `CubicNurbs` - `CyclicCubicGenerator` - `RationalCurve` - `RationalGenerator` - `BoxedPolygon` - `BoxedPolyline2d` - `BoxedPolyline3d` - `SampleCurve` - `SampleAutoCurve` - `UnevenSampleCurve` - `UnevenSampleAutoCurve` - `EvenCore` - `UnevenCore` - `ChunkedUnevenCore` This requirement could be relaxed in certain cases, but I had erred on the side of gating rather than modifying. Since `no_std` is a new set of platforms we are adding support to, and the `alloc` feature is enabled by default, this is not a breaking change. --------- Co-authored-by: Benjamin Brienen <benjamin.brienen@outlook.com> Co-authored-by: Matty <2975848+mweatherley@users.noreply.github.com> Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>
2024-12-03 17:14:51 +00:00
#[cfg(feature = "alloc")]
Uniform mesh sampling (#14071) # 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>
2024-07-08 00:57:08 +00:00
pub use mesh_sampling::*;
Random sampling of directions and quaternions (#12857) # Objective Augment Bevy's random sampling capabilities by providing good tools for producing random directions and rotations. ## Solution The `rand` crate has a natural tool for providing `Distribution`s whose output is a type that doesn't require any additional data to sample values — namely, [`Standard`](https://docs.rs/rand/latest/rand/distributions/struct.Standard.html). Here, our existing `ShapeSample` implementations have been put to good use in providing these, resulting in patterns like the following: ```rust // Using thread-local rng let random_direction1: Dir3 = random(); // Using an explicit rng let random_direction2: Dir3 = rng.gen(); // Using an explicit rng coupled explicitly with Standard let random_directions: Vec<Dir3> = rng.sample_iter(Standard).take(5).collect(); ``` Furthermore, we have introduced a trait `FromRng` which provides sugar for `rng.gen()` that is more namespace-friendly (in this author's opinion): ```rust let random_direction = Dir3::from_rng(rng); ``` The types this has been implemented for are `Dir2`, `Dir3`, `Dir3A`, and `Quat`. Notably, `Quat` uses `glam`'s implementation rather than an in-house one, and as a result, `bevy_math`'s "rand" feature now enables that of `glam`. --- ## Changelog - Created `standard` submodule in `sampling` to hold implementations and other items related to the `Standard` distribution. - "rand" feature of `bevy_math` now enables that of `glam`. --- ## Discussion From a quick glance at `Quat`'s distribution implementation in `glam`, I am a bit suspicious, since it is simple and doesn't match any algorithm that I came across in my research. I will do a little more digging as a follow-up to this and see if it's actually uniform (maybe even using those tools I wrote — what a thrill). As an aside, I'd also like to say that I think [`Distribution`](https://docs.rs/rand/latest/rand/distributions/trait.Distribution.html) is really, really good. It integrates with distributions provided externally (e.g. in `rand` itself and its extensions) along with doing a good job of isolating the source of randomness, so that output can be reliably reproduced if need be. Finally, `Distribution::sample_iter` is quite good for ergonomically acquiring lots of random values. At one point I found myself writing traits to describe random sampling and essentially reinvented this one. I just think it's good, and I think it's worth centralizing around to a significant extent.
2024-04-04 23:13:00 +00:00
pub use shape_sampling::*;
pub use standard::*;
Reference in a new issue Copy permalink