Statistical assessment of spatial distributions

crates/bevy_math/src/lib.rs

@@ -23,7 +23,7 @@ mod ray;
 mod rects;
 mod rotation2d;
 #[cfg(feature = "rand")]
-mod shape_sampling;
+pub mod sampling;
 
 pub use affine3::*;
 pub use aspect_ratio::AspectRatio;
@@ -34,13 +34,13 @@ pub use ray::{Ray2d, Ray3d};
 pub use rects::*;
 pub use rotation2d::Rotation2d;
 #[cfg(feature = "rand")]
-pub use shape_sampling::ShapeSample;
+pub use sampling::ShapeSample;
 
 /// The `bevy_math` prelude.
 pub mod prelude {
     #[doc(hidden)]
     #[cfg(feature = "rand")]
-    pub use crate::shape_sampling::ShapeSample;
+    pub use crate::sampling::{BoundaryOf, InteriorOf, ShapeSample};
     #[doc(hidden)]
     pub use crate::{
         cubic_splines::{

crates/bevy_math/src/sampling/mod.rs

@@ -0,0 +1,8 @@
+//! This module contains tools related to random sampling.
+//!
+//! To use this, the "rand" feature must be enabled.
+
+mod shape_sampling;
+pub mod statistical_tests;
+
+pub use shape_sampling::*;

crates/bevy_math/src/shape_sampling.rs → crates/bevy_math/src/sampling/shape_sampling.rs

@@ -39,6 +39,70 @@ pub trait ShapeSample {
     /// println!("{:?}", square.sample_boundary(&mut rand::thread_rng()));
     /// ```
     fn sample_boundary<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::Output;
+
+    /// Extract a [`Distribution`] whose samples are points of this shape's interior, taken uniformly.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use bevy_math::prelude::*;
+    /// # use rand::distributions::Distribution;
+    /// let square = Rectangle::new(2.0, 2.0);
+    /// let rng = rand::thread_rng();
+    ///
+    /// // Iterate over points randomly drawn from `square`'s interior:
+    /// for random_val in square.interior_dist().sample_iter(rng).take(5) {
+    ///     println!("{:?}", random_val);
+    /// }
+    /// ```
+    fn interior_dist(self) -> InteriorOf<Self>
+    where
+        Self: Sized,
+    {
+        InteriorOf(self)
+    }
+
+    /// Extract a [`Distribution`] whose samples are points of this shape's boundary, taken uniformly.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use bevy_math::prelude::*;
+    /// # use rand::distributions::Distribution;
+    /// let square = Rectangle::new(2.0, 2.0);
+    /// let rng = rand::thread_rng();
+    ///
+    /// // Iterate over points randomly drawn from `square`'s boundary:
+    /// for random_val in square.boundary_dist().sample_iter(rng).take(5) {
+    ///     println!("{:?}", random_val);
+    /// }
+    /// ```
+    fn boundary_dist(self) -> BoundaryOf<Self>
+    where
+        Self: Sized,
+    {
+        BoundaryOf(self)
+    }
+}
+
+#[derive(Clone, Copy)]
+/// A wrapper struct that allows interior sampling from a [`ShapeSample`] type directly as a [`Distribution`].
+pub struct InteriorOf<T: ShapeSample>(pub T);
+
+#[derive(Clone, Copy)]
+/// A wrapper struct that allows boundary sampling from a [`ShapeSample`] type directly as a [`Distribution`].
+pub struct BoundaryOf<T: ShapeSample>(pub T);
+
+impl<T: ShapeSample> Distribution<<T as ShapeSample>::Output> for InteriorOf<T> {
+    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> <T as ShapeSample>::Output {
+        self.0.sample_interior(rng)
+    }
+}
+
+impl<T: ShapeSample> Distribution<<T as ShapeSample>::Output> for BoundaryOf<T> {
+    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> <T as ShapeSample>::Output {
+        self.0.sample_boundary(rng)
+    }
 }
 
 impl ShapeSample for Circle {