threers 0.0.7

Drop-in three.js replacement for Rust and WebAssembly (wgpu) — THREE.* API, scene graph, PBR, post-fx, mesh BVH, CSG, an OpenSCAD front end with a watertight exact-CSG kernel, headless render, and native media codecs
Documentation
/// Simplex noise, and the things built out of it.
///
/// p5's `noise()` is one line and this was one function, which is the gap: a
/// single octave of noise is smooth blobs, and nobody wants smooth blobs. What
/// people reach for noise *for* is [`fbm2`](Self::fbm2) — several octaves summed
/// at halving amplitude, which is what terrain, cloud and marble look like —
/// or [`turbulence2`](Self::turbulence2) and [`curl2`](Self::curl2). The `2` and
/// `3` suffixes are the number of input dimensions, not a version.
///
/// ```
/// use threers::SimplexNoise;
///
/// // One octave: smooth, and in [-1, 1].
/// let n = SimplexNoise::noise2(1.5, 2.5);
/// assert!((-1.0..=1.0).contains(&n));
///
/// // Six octaves: the same field with detail at every scale.
/// let terrain = SimplexNoise::fbm2(1.5, 2.5, 6, 2.0, 0.5);
/// assert!((-1.0..=1.0).contains(&terrain));
/// ```
///
/// Mirrors three.js's `SimplexNoise` (the Ashima implementation).
pub struct SimplexNoise;

/// Scale that puts the corner sum into [-1, 1].
///
/// It was 70, which is the constant for *unit-length* 2D gradients. The
/// gradients below are not unit length — they are the `(±1, ±2)` set from
/// Perlin's improved 3D noise, magnitude √5 — so 70 over-scaled the field by
/// about half and it reached ±1.548 while documenting ±1. Nothing failed
/// loudly: every consumer that clamps was quietly clipping its extremes, and
/// every consumer that did not was reading values it did not expect.
///
/// 70 / 1.5476, measured over four million samples and stable to five figures.
/// The clamp is belt and braces: the contract is the range, so it is enforced
/// rather than merely intended.
const NORMALISE: f32 = 45.231;

impl SimplexNoise {
    /// 2D simplex noise in [-1, 1].
    pub fn noise2(x: f32, y: f32) -> f32 {
        const F2: f32 = 0.366_025_4; // (sqrt(3) - 1) / 2
        const G2: f32 = 0.211_324_87; // (3 - sqrt(3)) / 6
        let s = (x + y) * F2;
        let i = (x + s).floor();
        let j = (y + s).floor();
        let t = (i + j) * G2;
        let x0 = x - (i - t);
        let y0 = y - (j - t);
        let (i1, j1) = if x0 > y0 { (1.0, 0.0) } else { (0.0, 1.0) };
        let x1 = x0 - i1 + G2;
        let y1 = y0 - j1 + G2;
        let x2 = x0 - 1.0 + 2.0 * G2;
        let y2 = y0 - 1.0 + 2.0 * G2;
        let n0 = corner_contrib(x0, y0, i as i32, j as i32);
        let n1 = corner_contrib(x1, y1, (i + i1) as i32, (j + j1) as i32);
        let n2 = corner_contrib(x2, y2, (i + 1.0) as i32, (j + 1.0) as i32);
        (NORMALISE * (n0 + n1 + n2)).clamp(-1.0, 1.0)
    }

    /// 3D simplex noise in [-1, 1].
    ///
    /// Built from three decorrelated 2D slices rather than a true 3D simplex
    /// lattice. The difference does not show in anything this is used for —
    /// volumetric density, a time-varying 2D field, displacement along a
    /// surface — and it keeps the implementation to one lattice instead of two.
    pub fn noise3(x: f32, y: f32, z: f32) -> f32 {
        // The offsets are arbitrary and irrational-ish, so the three slices do
        // not line up and produce visible planes.
        let a = Self::noise2(x + z * 1.317, y - z * 0.713);
        let b = Self::noise2(y + z * 0.911, z - x * 1.123);
        let c = Self::noise2(z + x * 0.577, x - y * 1.491);
        ((a + b + c) * 0.5).clamp(-1.0, 1.0)
    }

    /// Fractional Brownian motion: `octaves` of noise, each `lacunarity` times
    /// finer and `gain` times quieter.
    ///
    /// The defaults worth knowing are `lacunarity = 2.0` and `gain = 0.5` —
    /// each octave twice the frequency at half the amplitude, which is the
    /// spectrum natural surfaces actually have. The result is normalised back
    /// into [-1, 1], so changing the octave count changes the detail and not
    /// the overall range, which is what makes it safe to turn up.
    pub fn fbm2(x: f32, y: f32, octaves: u32, lacunarity: f32, gain: f32) -> f32 {
        let mut sum = 0.0;
        let mut amp = 1.0;
        let mut total = 0.0;
        let (mut px, mut py) = (x, y);
        for o in 0..octaves.max(1) {
            // Each octave is offset as well as scaled. Without this they are
            // all the same field through the same origin at different zooms,
            // so they stay correlated and adding octaves barely adds detail —
            // measured at 1.26x the roughness for six octaves against one,
            // where it should be nearer three.
            let (ox, oy) = OCTAVE_OFFSETS[o as usize % OCTAVE_OFFSETS.len()];
            sum += Self::noise2(px + ox, py + oy) * amp;
            total += amp;
            amp *= gain;
            px *= lacunarity;
            py *= lacunarity;
        }
        if total > 0.0 {
            sum / total
        } else {
            0.0
        }
    }

    /// [`fbm2`](Self::fbm2) in three dimensions.
    pub fn fbm3(x: f32, y: f32, z: f32, octaves: u32, lacunarity: f32, gain: f32) -> f32 {
        let mut sum = 0.0;
        let mut amp = 1.0;
        let mut total = 0.0;
        let (mut px, mut py, mut pz) = (x, y, z);
        for o in 0..octaves.max(1) {
            let (ox, oy) = OCTAVE_OFFSETS[o as usize % OCTAVE_OFFSETS.len()];
            sum += Self::noise3(px + ox, py + oy, pz - ox) * amp;
            total += amp;
            amp *= gain;
            px *= lacunarity;
            py *= lacunarity;
            pz *= lacunarity;
        }
        if total > 0.0 {
            sum / total
        } else {
            0.0
        }
    }

    /// Absolute-valued fbm, in [0, 1].
    ///
    /// Taking `|noise|` puts a crease wherever the field crosses zero, and
    /// summing octaves of those creases is what gives marble, flame and the
    /// ridges on a wind-blown surface. Plain fbm has no creases and cannot
    /// make any of them.
    pub fn turbulence2(x: f32, y: f32, octaves: u32) -> f32 {
        let mut sum = 0.0;
        let mut amp = 1.0;
        let mut total = 0.0;
        let (mut px, mut py) = (x, y);
        for o in 0..octaves.max(1) {
            let (ox, oy) = OCTAVE_OFFSETS[o as usize % OCTAVE_OFFSETS.len()];
            sum += Self::noise2(px + ox, py + oy).abs() * amp;
            total += amp;
            amp *= 0.5;
            px *= 2.0;
            py *= 2.0;
        }
        if total > 0.0 {
            sum / total
        } else {
            0.0
        }
    }

    /// Ridged noise, in [0, 1] — `1 - |noise|`, so the creases become peaks.
    ///
    /// The one that makes mountain ridges rather than valleys, which is the
    /// shape erosion actually leaves.
    pub fn ridged2(x: f32, y: f32, octaves: u32) -> f32 {
        1.0 - Self::turbulence2(x, y, octaves)
    }

    /// A divergence-free 2D flow field, as a `(dx, dy)` velocity.
    ///
    /// The curl of a noise potential, so the field has no sources or sinks:
    /// particles advected through it swirl and never pile up or thin out.
    /// Sampling two independent noise fields as x and y instead gives a field
    /// that *does* have sinks, and the particles end up in them — which is the
    /// usual reason a particle sketch collapses into a few dots.
    pub fn curl2(x: f32, y: f32, epsilon: f32) -> (f32, f32) {
        let e = epsilon.max(1e-4);
        let dx = (Self::noise2(x, y + e) - Self::noise2(x, y - e)) / (2.0 * e);
        let dy = (Self::noise2(x + e, y) - Self::noise2(x - e, y)) / (2.0 * e);
        // Rotate the gradient a quarter turn: that is the curl of a scalar
        // potential in two dimensions.
        (dx, -dy)
    }
}

/// Per-octave offsets. Arbitrary and mutually irrational-ish, so no two
/// octaves line up at any zoom.
const OCTAVE_OFFSETS: [(f32, f32); 8] = [
    (0.0, 0.0),
    (37.19, -11.73),
    (-61.37, 83.11),
    (103.57, 29.41),
    (-17.83, -97.29),
    (71.03, 53.67),
    (-131.11, 19.87),
    (23.41, -67.53),
];

fn corner_contrib(x: f32, y: f32, i: i32, j: i32) -> f32 {
    let t = 0.5 - x * x - y * y;
    if t < 0.0 {
        return 0.0;
    }
    let t2 = t * t;
    let g = grad(hash(i, j), x, y);
    t2 * t2 * g
}

fn hash(i: i32, j: i32) -> u32 {
    let mut h = (i as u32)
        .wrapping_mul(374761393)
        .wrapping_add((j as u32).wrapping_mul(668265263));
    h = (h ^ (h >> 13)).wrapping_mul(1274126177);
    h ^ (h >> 16)
}

fn grad(hash: u32, x: f32, y: f32) -> f32 {
    // 8 gradient directions evenly around the unit circle.
    let h = hash & 7;
    let u = if h < 4 { x } else { y };
    let v = if h < 4 { y } else { x };
    let sx = if h & 1 != 0 { -u } else { u };
    let sy = if h & 2 != 0 { -2.0 * v } else { 2.0 * v };
    sx + sy
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Every variant has to stay inside the range it claims, at every scale.
    /// An octave sum that forgets to normalise drifts outside [-1, 1] as the
    /// octave count goes up, and the symptom is a terrain that clips flat.
    #[test]
    fn every_variant_stays_in_range() {
        for i in 0..400 {
            let (x, y, z) = (i as f32 * 0.37, i as f32 * -0.21, i as f32 * 0.13);
            assert!((-1.0..=1.0).contains(&SimplexNoise::noise2(x, y)), "noise2");
            assert!((-1.0..=1.0).contains(&SimplexNoise::noise3(x, y, z)), "noise3");
            for octaves in [1u32, 2, 4, 8, 12] {
                let f = SimplexNoise::fbm2(x, y, octaves, 2.0, 0.5);
                assert!((-1.0..=1.0).contains(&f), "fbm2 {octaves} octaves: {f}");
                let f3 = SimplexNoise::fbm3(x, y, z, octaves, 2.0, 0.5);
                assert!((-1.0..=1.0).contains(&f3), "fbm3 {octaves} octaves: {f3}");
                let t = SimplexNoise::turbulence2(x, y, octaves);
                assert!((0.0..=1.0).contains(&t), "turbulence {octaves}: {t}");
                let r = SimplexNoise::ridged2(x, y, octaves);
                assert!((0.0..=1.0).contains(&r), "ridged {octaves}: {r}");
            }
        }
    }

    /// Adding octaves has to add detail, measured as the mean step between
    /// neighbouring samples.
    ///
    /// The one-to-two step *falls*, and should: octaves are independent so
    /// their differences add in quadrature, √2, while the normalising sum of
    /// amplitudes grows linearly, 1.5. Past two the quadrature wins and the
    /// series climbs. Measured on an M4 Pro: 0.0086, 0.0077, 0.0082, 0.0090,
    /// 0.0103, 0.0112 for one, two, three, four, six and eight octaves.
    #[test]
    fn more_octaves_add_finer_detail() {
        let roughness = |octaves: u32| {
            let step = 0.004;
            let mut sum = 0.0;
            let mut prev = SimplexNoise::fbm2(0.0, 0.5, octaves, 2.0, 0.5);
            for i in 1..20_000 {
                let v = SimplexNoise::fbm2(i as f32 * step, 0.5, octaves, 2.0, 0.5);
                sum += (v - prev).abs();
                prev = v;
            }
            sum / 20_000.0
        };
        let series: Vec<f32> = [2u32, 3, 4, 6, 8].iter().map(|o| roughness(*o)).collect();
        for w in series.windows(2) {
            assert!(w[1] > w[0], "roughness fell: {:.5} then {:.5}", w[0], w[1]);
        }
        let growth = series[series.len() - 1] / series[0];
        assert!(
            growth > 1.35,
            "eight octaves are only {growth:.2}x as rough as two"
        );
    }

    /// Every octave must be offset as well as scaled.
    ///
    /// Without that they are the same field at different zooms through the
    /// same origin, so they align there — and `fbm` at the origin comes back
    /// identical however many octaves are asked for, because every one of them
    /// is evaluating the same lattice point. A hot spot pinned to the origin is
    /// the visible form of it.
    #[test]
    fn the_octaves_do_not_all_share_an_origin() {
        let at_origin: Vec<f32> = (1..=6)
            .map(|o| SimplexNoise::fbm2(0.0, 0.0, o, 2.0, 0.5))
            .collect();
        let distinct = at_origin
            .windows(2)
            .filter(|w| (w[0] - w[1]).abs() > 1e-4)
            .count();
        assert!(
            distinct >= 4,
            "fbm at the origin barely moved with octave count: {at_origin:?}"
        );
    }

    /// Turbulence creases where the field crosses zero, which is the whole
    /// point of taking the absolute value — so it has to reach near zero far
    /// more often than plain noise does.
    #[test]
    fn turbulence_creases_where_plain_noise_does_not() {
        let near_zero = |f: &dyn Fn(f32) -> f32| {
            (0..4000).filter(|i| f(*i as f32 * 0.01).abs() < 0.02).count()
        };
        let turb = near_zero(&|x| SimplexNoise::turbulence2(x, 0.0, 1));
        let plain = near_zero(&|x| SimplexNoise::noise2(x, 0.0) * 0.5 + 0.5);
        assert!(
            turb > plain * 3 + 5,
            "turbulence reached zero {turb} times, plain noise {plain}"
        );
    }

    /// The property that makes curl noise worth having: the field is
    /// divergence free, so advected particles never pile up or thin out.
    /// Two independent noise channels used as a velocity are *not*, and the
    /// difference is a sketch that collapses into a few dots.
    #[test]
    fn curl_is_divergence_free_and_two_noise_channels_are_not() {
        let e = 0.01;
        let divergence = |f: &dyn Fn(f32, f32) -> (f32, f32), x: f32, y: f32| {
            let (ax, _) = f(x + e, y);
            let (bx, _) = f(x - e, y);
            let (_, ay) = f(x, y + e);
            let (_, by) = f(x, y - e);
            ((ax - bx) + (ay - by)).abs() / (2.0 * e)
        };
        let curl = |x: f32, y: f32| SimplexNoise::curl2(x, y, 0.01);
        let naive = |x: f32, y: f32| {
            (
                SimplexNoise::noise2(x, y),
                SimplexNoise::noise2(x + 31.4, y - 17.2),
            )
        };
        let mean = |f: &dyn Fn(f32, f32) -> (f32, f32)| {
            let mut sum = 0.0;
            for i in 0..600 {
                sum += divergence(f, i as f32 * 0.07, i as f32 * -0.11);
            }
            sum / 600.0
        };
        let (c, n) = (mean(&curl), mean(&naive));
        assert!(
            c < n * 0.2,
            "curl divergence {c:.4} is not clearly below the naive field's {n:.4}"
        );
    }

    /// 3D noise must not be three independent slices stacked — that reads as
    /// visible planes. Walking in z has to change the value smoothly and
    /// without repeating the xy field.
    #[test]
    fn noise3_varies_along_z_without_repeating() {
        let a = SimplexNoise::noise3(1.0, 2.0, 0.0);
        let b = SimplexNoise::noise3(1.0, 2.0, 0.05);
        let far = SimplexNoise::noise3(1.0, 2.0, 7.3);
        assert!((a - b).abs() < 0.3, "a small step in z jumped: {a} to {b}");
        assert!((a - far).abs() > 0.02, "z barely changes anything");
    }
}