Uniform point sampling methods for some primitive shapes.

[13ros27]

Objective

Give easy methods for uniform point sampling in a variety of primitive shapes (particularly useful for circles and spheres) because in a lot of cases its quite easy to get wrong (non-uniform).

Solution

Added the ShapeSample trait to bevy_math and implemented it for Circle, Sphere, Rectangle, Cuboid, Cylinder, Capsule2d and Capsule3d. There are a few other shapes it would be reasonable to implement for like Triangle, Ellipse and Torus but I'm not immediately sure how these would be implemented (other than rejection which could be the best method, and could be more performant than some of the solutions in this pr I'm not sure). This exposes the sample_volume and sample_surface methods to get both a random point from its interior or its surface. EDIT: Renamed sample_volume to sample_interior and sample_surface to sample_boundary

This brings in rand as a default optional dependency (without default features), and the methods take &mut impl Rng which allows them to use any random source implementing RngCore.

---

Changelog

Added

Added the methods sample_interior and sample_boundary to a variety of primitive shapes providing easy uniform point sampling.

[NthTensor]

This is perfect! I'll verify correctness and approve tomorrow, but everything looks great.

I will just note for other reviews, because it's worth repeating: This rand dependency doesn't include any actual pseudorandom number generation, it just an API consumer. This means it's compatible with the deterministic-ecs magic provided by crates like bevy_rand!

[JohnTheCoolingFan]

Awesome feature. But I would like to know how uniform the distribution of sampled points is. Glancing over the implementation, particularly circle/sphere and capsule I suspect have a non-uniform sampling, meaning the "density" of points would not be uniform across the domain, in Cartesian coordinates.

[mweatherley]

Awesome feature. But I would like to know how uniform the distribution of sampled points is. Glancing over the implementation, particularly circle/sphere and capsule I suspect have a non-uniform sampling, meaning the "density" of points would not be uniform across the domain, in Cartesian coordinates.

I am fairly certain they are uniform.

[13ros27]

Awesome feature. But I would like to know how uniform the distribution of sampled points is. Glancing over the implementation, particularly circle/sphere and capsule I suspect have a non-uniform sampling, meaning the "density" of points would not be uniform across the domain, in Cartesian coordinates.

Provided I haven't made any mistakes these should be uniform. The circle and sphere in particular use this disk sampling method (and the sphere equivalent) which uses a square root to skew the points towards the outside for balance. And the capsules are split by surface area / volume (lines like rng.gen_bool((cylinder_vol / capsule_vol) as f64)) and then they just use the methods for circle/sphere/rectangle/cylinder as appropriate.

[Bluefinger]

We probably could do with some statistical tests to give us more confidence that we are indeed getting uniform distributions and sampling. For reference, I do such tests here for turborand: https://github.com/Bluefinger/turborand/blob/main/tests/smoke/mod.rs#L657

[mweatherley]

Just a couple mathematical issues, otherwise this looks good to me! Thanks for putting in the work to do this!

(I realize now that my comments on Cylinder and Capsule3d were left in weird places, hopefully that's not too confusing.)

[NthTensor]

Really pleased with this. Consensus on if a statistical test is blocking here? I'm inclined to move forward without it.

Future work:

• Make primitive meshes and primitive uniform point clouds "agree"
• Experiment with rejection sampling, see if it's faster anywhere
• Think about implementing ShapeSample on triangle meshes maybe

[NthTensor]

Oh also can we change sample_volume/sample_surface to sample_interior/sample_boundary? It's more correct in the 2d case.

[Bluefinger]

I don't think the tests should block this, but maybe be part of follow-up work (since I think there'll be some work to figure out the best way to do them for the provided methods).

[13ros27]

I've added tests for Circle.sample_interior and Circle.sample_boundary. The sample_boundary test just uses the angle its at (essentially which wedge of the circle it is in) and sample_interior checks which random box the point is in (it can be in multiple). The boxes it uses are

[IQuick143]

Seems good, but I will say "Tests, tests, tests".
I haven't found any math mistakes but I still don't feel too sure to sign this off myself.

[IQuick143]

primary_side2... sounds almost like a secondary_side. :)

[13ros27]

Yeah, my naming there is a little questionable, its really the sides that are fully varied in comparison to the one which is just -1 or 1