use crate::math::{Box3, Vector3};
#[derive(Clone, Debug)]
pub struct Field {
bounds: Box3,
dims: [usize; 3],
values: Vec<f32>,
}
impl Field {
pub fn grid(bounds: Box3, dims: [usize; 3], values: Vec<f32>) -> Option<Self> {
if dims.contains(&0) || values.len() != dims[0] * dims[1] * dims[2] {
return None;
}
Some(Self {
bounds,
dims,
values,
})
}
pub fn from_fn(
bounds: Box3,
dims: [usize; 3],
f: impl Fn(Vector3) -> f32 + Sync + Send,
) -> Self {
let dims = [dims[0].max(1), dims[1].max(1), dims[2].max(1)];
let total = dims[0] * dims[1] * dims[2];
let values = crate::utils::parallel::par_map_range(total, |n| {
let i = n % dims[0];
let j = (n / dims[0]) % dims[1];
let k = n / (dims[0] * dims[1]);
f(node(bounds, dims, i, j, k))
});
Self {
bounds,
dims,
values,
}
}
pub fn scattered(bounds: Box3, dims: [usize; 3], samples: &[(Vector3, f32)]) -> Self {
let dims = [dims[0].max(1), dims[1].max(1), dims[2].max(1)];
if samples.is_empty() {
return Self {
bounds,
dims,
values: vec![0.0; dims[0] * dims[1] * dims[2]],
};
}
let buckets = Buckets::build(bounds, dims, samples);
let total = dims[0] * dims[1] * dims[2];
let values = crate::utils::parallel::par_map_range(total, |n| {
let i = n % dims[0];
let j = (n / dims[0]) % dims[1];
let k = n / (dims[0] * dims[1]);
buckets.interpolate(node(bounds, dims, i, j, k), samples)
});
Self {
bounds,
dims,
values,
}
}
pub fn from_mesh(
geometry: &crate::core::BufferGeometry,
values: &[f32],
dims: [usize; 3],
) -> Option<Self> {
let positions: Vec<Vector3> = geometry.positions()?.collect();
if positions.len() != values.len() || positions.is_empty() {
return None;
}
let samples: Vec<(Vector3, f32)> = positions
.iter()
.copied()
.zip(values.iter().copied())
.collect();
let mut bounds = Box3::from_points(&positions);
let pad = bounds.size().length() * 0.01 + 1e-6;
bounds.expand_by_scalar(pad);
Some(Self::scattered(bounds, dims, &samples))
}
pub fn bounds(&self) -> Box3 {
self.bounds
}
pub fn dims(&self) -> [usize; 3] {
self.dims
}
pub fn value(&self, p: Vector3) -> f32 {
let size = self.bounds.size();
let axis = |v: f32, lo: f32, extent: f32, n: usize| -> (usize, usize, f32) {
if n < 2 {
return (0, 0, 0.0);
}
let t = if extent > 1e-12 {
(v - lo) / extent * (n - 1) as f32
} else {
0.0
};
let t = t.clamp(0.0, (n - 1) as f32);
let i = (t.floor() as usize).min(n - 2);
(i, i + 1, t - i as f32)
};
let (i0, i1, fx) = axis(p.x, self.bounds.min.x, size.x, self.dims[0]);
let (j0, j1, fy) = axis(p.y, self.bounds.min.y, size.y, self.dims[1]);
let (k0, k1, fz) = axis(p.z, self.bounds.min.z, size.z, self.dims[2]);
let at = |i: usize, j: usize, k: usize| -> f32 {
self.values[(k * self.dims[1] + j) * self.dims[0] + i]
};
let lerp = |a: f32, b: f32, t: f32| a + (b - a) * t;
let y0 = lerp(
lerp(at(i0, j0, k0), at(i1, j0, k0), fx),
lerp(at(i0, j1, k0), at(i1, j1, k0), fx),
fy,
);
let y1 = lerp(
lerp(at(i0, j0, k1), at(i1, j0, k1), fx),
lerp(at(i0, j1, k1), at(i1, j1, k1), fx),
fy,
);
lerp(y0, y1, fz)
}
pub fn range(&self) -> (f32, f32) {
self.values.iter().fold((f32::INFINITY, f32::NEG_INFINITY), |(lo, hi), &v| {
(lo.min(v), hi.max(v))
})
}
pub fn map(mut self, f: impl Fn(f32) -> f32) -> Self {
for v in &mut self.values {
*v = f(*v);
}
self
}
pub fn normalized(self) -> Self {
let (lo, hi) = self.range();
let span = hi - lo;
if !span.is_finite() || span.abs() < 1e-12 {
return self.map(|_| 0.5);
}
self.map(move |v| (v - lo) / span)
}
pub fn clamped(self, lo: f32, hi: f32) -> Self {
self.map(move |v| v.clamp(lo, hi))
}
pub fn smoothed(mut self, passes: usize) -> Self {
let [nx, ny, nz] = self.dims;
for _ in 0..passes {
let src = self.values.clone();
for k in 0..nz {
for j in 0..ny {
for i in 0..nx {
let at = |i: usize, j: usize, k: usize| src[(k * ny + j) * nx + i];
let mut sum = at(i, j, k);
let mut count = 1.0f32;
let mut add = |i: usize, j: usize, k: usize| {
sum += at(i, j, k);
count += 1.0;
};
if i > 0 {
add(i - 1, j, k);
}
if i + 1 < nx {
add(i + 1, j, k);
}
if j > 0 {
add(i, j - 1, k);
}
if j + 1 < ny {
add(i, j + 1, k);
}
if k > 0 {
add(i, j, k - 1);
}
if k + 1 < nz {
add(i, j, k + 1);
}
self.values[(k * ny + j) * nx + i] = sum / count;
}
}
}
}
self
}
pub fn into_grade(self, at_min: f32, at_max: f32) -> impl Fn(Vector3) -> f32 + Sync + Send {
let (lo, hi) = self.range();
let span = hi - lo;
move |p| {
if !span.is_finite() || span.abs() < 1e-12 {
return 0.5 * (at_min + at_max);
}
let t = ((self.value(p) - lo) / span).clamp(0.0, 1.0);
at_min + (at_max - at_min) * t
}
}
}
fn node(bounds: Box3, dims: [usize; 3], i: usize, j: usize, k: usize) -> Vector3 {
let size = bounds.size();
let along = |n: usize, index: usize, lo: f32, extent: f32| -> f32 {
if n < 2 {
lo + extent * 0.5
} else {
lo + extent * index as f32 / (n - 1) as f32
}
};
Vector3::new(
along(dims[0], i, bounds.min.x, size.x),
along(dims[1], j, bounds.min.y, size.y),
along(dims[2], k, bounds.min.z, size.z),
)
}
fn cell_of(bounds: Box3, dims: [usize; 3], p: Vector3) -> [usize; 3] {
let size = bounds.size();
let axis = |v: f32, lo: f32, extent: f32, n: usize| -> usize {
if extent <= 1e-12 {
return 0;
}
(((v - lo) / extent * n as f32).floor() as isize).clamp(0, n as isize - 1) as usize
};
[
axis(p.x, bounds.min.x, size.x, dims[0]),
axis(p.y, bounds.min.y, size.y, dims[1]),
axis(p.z, bounds.min.z, size.z, dims[2]),
]
}
struct Buckets {
bounds: Box3,
dims: [usize; 3],
cells: Vec<Vec<u32>>,
}
impl Buckets {
fn build(bounds: Box3, dims: [usize; 3], samples: &[(Vector3, f32)]) -> Self {
let mut cells = vec![Vec::new(); dims[0] * dims[1] * dims[2]];
for (n, (p, _)) in samples.iter().enumerate() {
let [i, j, k] = cell_of(bounds, dims, *p);
cells[(k * dims[1] + j) * dims[0] + i].push(n as u32);
}
Self {
bounds,
dims,
cells,
}
}
fn interpolate(&self, p: Vector3, samples: &[(Vector3, f32)]) -> f32 {
let [ci, cj, ck] = cell_of(self.bounds, self.dims, p);
let reach = self.dims[0].max(self.dims[1]).max(self.dims[2]) as isize;
let mut sum = 0.0f64;
let mut weight = 0.0f64;
let mut found_at: Option<isize> = None;
for ring in 0..=reach {
if let Some(first) = found_at {
if ring > first + 1 {
break;
}
}
let mut any = false;
for dk in -ring..=ring {
for dj in -ring..=ring {
for di in -ring..=ring {
if ring > 0 && di.abs() != ring && dj.abs() != ring && dk.abs() != ring {
continue;
}
let (i, j, k) = (ci as isize + di, cj as isize + dj, ck as isize + dk);
if i < 0
|| j < 0
|| k < 0
|| i >= self.dims[0] as isize
|| j >= self.dims[1] as isize
|| k >= self.dims[2] as isize
{
continue;
}
let bucket = &self.cells
[(k as usize * self.dims[1] + j as usize) * self.dims[0] + i as usize];
for &n in bucket {
let (q, v) = samples[n as usize];
let w = 1.0 / ((q - p).length_sq().max(1e-12) as f64);
sum += w * v as f64;
weight += w;
any = true;
}
}
}
}
if any && found_at.is_none() {
found_at = Some(ring);
}
}
if weight > 0.0 {
(sum / weight) as f32
} else {
0.0
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn unit_box() -> Box3 {
Box3::from_center_and_size(Vector3::ZERO, Vector3::new(2.0, 2.0, 2.0))
}
#[test]
fn a_baked_function_reads_back() {
let f = Field::from_fn(unit_box(), [17, 17, 17], |p| p.x + 2.0 * p.y);
for (p, want) in [
(Vector3::ZERO, 0.0),
(Vector3::new(0.5, 0.25, 0.0), 1.0),
(Vector3::new(-1.0, 1.0, 0.7), 1.0),
] {
assert!((f.value(p) - want).abs() < 1e-3, "{p:?}: {}", f.value(p));
}
}
#[test]
fn outside_the_bounds_holds_the_edge() {
let f = Field::from_fn(unit_box(), [9, 9, 9], |p| p.x);
assert!((f.value(Vector3::new(50.0, 0.0, 0.0)) - 1.0).abs() < 1e-4);
assert!((f.value(Vector3::new(-50.0, 0.0, 0.0)) + 1.0).abs() < 1e-4);
}
#[test]
fn scattered_samples_land_on_their_own_values() {
let samples = [
(Vector3::new(-0.8, 0.0, 0.0), 10.0),
(Vector3::new(0.8, 0.0, 0.0), 30.0),
];
let f = Field::scattered(unit_box(), [16, 16, 16], &samples);
assert!(f.value(Vector3::new(-0.8, 0.0, 0.0)) < 15.0);
assert!(f.value(Vector3::new(0.8, 0.0, 0.0)) > 25.0);
let mid = f.value(Vector3::ZERO);
assert!((10.0..=30.0).contains(&mid), "{mid}");
}
#[test]
fn a_sparse_field_is_still_defined_everywhere() {
let f = Field::scattered(unit_box(), [8, 8, 8], &[(Vector3::new(-1.0, -1.0, -1.0), 7.0)]);
for p in [
Vector3::new(1.0, 1.0, 1.0),
Vector3::ZERO,
Vector3::new(-1.0, 1.0, 0.0),
] {
assert!((f.value(p) - 7.0).abs() < 1e-3, "{p:?}: {}", f.value(p));
}
}
#[test]
fn grade_maps_the_range_onto_the_multipliers() {
let f = Field::from_fn(unit_box(), [9, 9, 9], |p| p.x);
let grade = f.into_grade(0.5, 2.0);
assert!((grade(Vector3::new(-1.0, 0.0, 0.0)) - 0.5).abs() < 1e-4);
assert!((grade(Vector3::new(1.0, 0.0, 0.0)) - 2.0).abs() < 1e-4);
assert!((grade(Vector3::ZERO) - 1.25).abs() < 1e-4);
assert!((grade(Vector3::new(99.0, 0.0, 0.0)) - 2.0).abs() < 1e-4);
}
#[test]
fn a_constant_field_grades_to_the_middle() {
let f = Field::from_fn(unit_box(), [4, 4, 4], |_| 3.0);
let grade = f.into_grade(0.5, 2.5);
assert!((grade(Vector3::ZERO) - 1.5).abs() < 1e-6);
}
#[test]
fn normalizing_and_smoothing_keep_the_shape() {
let f = Field::from_fn(unit_box(), [9, 9, 9], |p| p.x * 100.0).normalized();
let (lo, hi) = f.range();
assert!((lo - 0.0).abs() < 1e-5 && (hi - 1.0).abs() < 1e-5);
let smooth = f.smoothed(3);
assert!(smooth.value(Vector3::new(-0.5, 0.0, 0.0)) < smooth.value(Vector3::new(0.5, 0.0, 0.0)));
}
#[test]
fn grid_checks_its_own_length() {
assert!(Field::grid(unit_box(), [2, 2, 2], vec![0.0; 8]).is_some());
assert!(Field::grid(unit_box(), [2, 2, 2], vec![0.0; 7]).is_none());
assert!(Field::grid(unit_box(), [0, 2, 2], vec![]).is_none());
}
#[test]
fn empty_samples_are_not_a_panic() {
let f = Field::scattered(unit_box(), [4, 4, 4], &[]);
assert_eq!(f.value(Vector3::ZERO), 0.0);
}
}