facett_core/

rabbit.rs

//! **The znippy rabbit** — facett's synthetic/test mascot, as reusable
//! *parametric* geometry. znippy ships no logo asset, so the rabbit is generated
//! here: a friendly sitting-rabbit silhouette (rounded body + head + two upright
//! ears + an eye dot), built from deterministic arcs in a normalised `[-1, 1]²`
//! design box (x right, y **up**). No RNG, no per-frame randomness — two calls
//! produce byte-identical geometry, so the wgpu/CPU snapshots stay stable.
//!
//! Two consumers share this one source of truth:
//!
//! - **2D** — [`rabbit_outline`] returns the silhouette as closed polygon loops.
//!   facett-map draws them as filled silhouette + crisp outline (the synthetic
//!   map fallback), and any 2D painter can fill/stroke the loops directly.
//! - **3D** — [`rabbit_mesh`] *extrudes* the silhouette into a solid logo
//!   (front + back faces + side walls, with per-vertex normals), which
//!   facett-graph3d's wgpu engine lights and slowly spins.
//!
//! Both are pure functions of a [`Rabbit`] parameter set, so the look is tunable
//! without touching either renderer.

use std::f64::consts::TAU;

/// Parametric knobs for the rabbit silhouette. All in the normalised `[-1, 1]`
/// design box (y **up**). [`Rabbit::default`] is the tuned mascot; tests and
/// renderers should use it so the geometry is the same everywhere.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Rabbit {
    /// Body ellipse centre + radii (the sitting haunch).
    pub body_cy: f64,
    pub body_rx: f64,
    pub body_ry: f64,
    /// Head circle centre + radius (sits above/forward of the body).
    pub head_cx: f64,
    pub head_cy: f64,
    pub head_r: f64,
    /// Ear geometry: half-width at the base, length, lean (x-offset of the tip),
    /// and the gap between the two ear centres at the head.
    pub ear_w: f64,
    pub ear_len: f64,
    pub ear_lean: f64,
    pub ear_gap: f64,
    /// Eye dot centre (offset from the head centre) + radius.
    pub eye_dx: f64,
    pub eye_dy: f64,
    pub eye_r: f64,
    /// How many segments to sample each rounded part with (even → symmetric).
    pub segments: usize,
}

impl Default for Rabbit {
    fn default() -> Self {
        // Tuned so the parts overlap into ONE friendly sitting-rabbit silhouette
        // (head fused to the body, two upright ears leaning slightly out), not a
        // pile of disconnected blobs.
        Self {
            body_cy: -0.40,
            body_rx: 0.44,
            body_ry: 0.50,
            head_cx: 0.05,
            head_cy: 0.22,
            head_r: 0.32,
            ear_w: 0.105,
            ear_len: 0.56,
            ear_lean: 0.17,
            ear_gap: 0.15,
            eye_dx: 0.12,
            eye_dy: 0.05,
            eye_r: 0.05,
            segments: 64,
        }
    }
}

/// One closed loop of `(x, y)` vertices in the `[-1, 1]` design box (y up). The
/// first vertex is **not** repeated at the end; close it yourself if you stroke
/// it as a ring. Loops are returned outer-first.
pub type Loop = Vec<(f64, f64)>;

impl Rabbit {
    /// Sample an axis-aligned ellipse as a closed loop (CCW), `n` segments.
    fn ellipse(cx: f64, cy: f64, rx: f64, ry: f64, n: usize) -> Loop {
        (0..n)
            .map(|i| {
                let t = i as f64 / n as f64 * TAU;
                (cx + rx * t.cos(), cy + ry * t.sin())
            })
            .collect()
    }

    /// One ear: a tall rounded "petal" rising from `base_x` at the top of the
    /// head, leaning out by `lean`. Built as a closed **CCW** loop (y up): up the
    /// *right* side to the tip, then down the *left* side back to the base.
    ///
    /// **The winding is load-bearing, not cosmetic.** It used to walk up the left
    /// side and down the right, which traces the petal **clockwise** — breaking the
    /// "each loop is a CCW ring" contract this type documents. [`rabbit_mesh`] takes
    /// that contract at its word when it extrudes: it emits the front cap `centre →
    /// a → b` (CCW seen from `+z`) and the side-wall quads outward. Fed a CW loop it
    /// produced an **inside-out ear** — front cap wound backwards (so a back-face
    /// cull threw it away), back cap facing the camera, side walls facing inward. In
    /// the running demo both of the rabbit's ears rendered as hollow open troughs:
    /// you looked straight through where the front of the ear should be and saw its
    /// inner back surface. 528 of the mesh's 1040 triangles — both whole ears — had
    /// a geometric face normal that contradicted their own authored vertex normal.
    /// See `rabbit_mesh_is_consistently_wound_outward` for the fence.
    fn ear(&self, base_x: f64, lean: f64, n: usize) -> Loop {
        let base_y = self.head_cy + self.head_r * 0.55; // tucked into the head
        let tip_x = base_x + lean;
        let tip_y = base_y + self.ear_len;
        let w = self.ear_w;
        let half = (n / 2).max(2);
        let mut pts = Vec::with_capacity(half * 2 + 2);
        // Outer (right) side: base → tip (a gentle taper + slight outward bow).
        for i in 0..=half {
            let s = i as f64 / half as f64; // 0..1 up the ear
            let cx = base_x + (tip_x - base_x) * s;
            let cy = base_y + (tip_y - base_y) * s;
            let hw = w * (1.0 - 0.45 * s); // narrows toward the tip
            let bow = (s * std::f64::consts::PI).sin() * 0.04 * lean.signum();
            pts.push((cx + hw + bow, cy));
        }
        // Inner (left) side: tip → base (mirror of the outward walk → closed petal,
        // traced CCW overall).
        for i in (0..=half).rev() {
            let s = i as f64 / half as f64;
            let cx = base_x + (tip_x - base_x) * s;
            let cy = base_y + (tip_y - base_y) * s;
            let hw = w * (1.0 - 0.45 * s);
            let bow = (s * std::f64::consts::PI).sin() * 0.04 * lean.signum();
            pts.push((cx - hw + bow, cy));
        }
        pts
    }

    /// Twice the signed area of a loop (shoelace). `> 0` = **CCW** in the y-up
    /// design box — the winding every loop this type returns must have, and the one
    /// [`rabbit_mesh`] extrudes against.
    #[must_use]
    pub fn signed_area2(lp: &[(f64, f64)]) -> f64 {
        let n = lp.len();
        let mut a = 0.0;
        for k in 0..n {
            let (x0, y0) = lp[k];
            let (x1, y1) = lp[(k + 1) % n];
            a += x0 * y1 - x1 * y0;
        }
        a
    }

    /// The rabbit as closed polygon loops, **outer silhouette first**, then the
    /// two ears, then the eye dot. Each loop is a CCW ring in the `[-1, 1]` box
    /// (y up). The 2D renderer fills the body+head as the silhouette, fills the
    /// ears on top, and punches the eye as a small dark dot.
    pub fn outline(&self) -> Vec<Loop> {
        let n = self.segments.max(8);
        let mut loops = Vec::new();
        // Silhouette body (big haunch) — the main mass.
        loops.push(Self::ellipse(0.0, self.body_cy, self.body_rx, self.body_ry, n));
        // Head — overlaps the top of the body so they read as one shape.
        loops.push(Self::ellipse(self.head_cx, self.head_cy, self.head_r, self.head_r, n));
        // Two ears.
        let lx = self.head_cx - self.ear_gap;
        let rx = self.head_cx + self.ear_gap;
        loops.push(self.ear(lx, -self.ear_lean, n));
        loops.push(self.ear(rx, self.ear_lean, n));
        // Eye dot (small).
        loops.push(self.eye());
        loops
    }

    /// The **fillable body silhouette**: just the body + head + ears (no eye),
    /// the loops a 2D renderer fills as the solid mascot. Returned outer→inner so
    /// the renderer can paint them in order (body, head, ears) with one colour.
    pub fn silhouette(&self) -> Vec<Loop> {
        let mut all = self.outline();
        all.pop(); // drop the eye — it's a feature, not part of the fill
        all
    }

    /// The eye dot loop alone (the dark feature drawn on top of the fill).
    pub fn eye(&self) -> Loop {
        Self::ellipse(
            self.head_cx + self.eye_dx,
            self.head_cy + self.eye_dy,
            self.eye_r,
            self.eye_r,
            (self.segments / 2).max(8),
        )
    }
}

/// Convenience: the default mascot's outline loops. See [`Rabbit::outline`].
pub fn rabbit_outline() -> Vec<Loop> {
    Rabbit::default().outline()
}

// ───────────────────────── 3D extruded mesh ──────────────────────────────────

/// A triangle-soup mesh of the extruded rabbit logo: interleaved positions +
/// normals, indexed. Coordinates are in the `[-1, 1]` design box (y up) with the
/// extrusion along **z** (`±depth/2`). Pure data — the renderer (wgpu or the CPU
/// fallback) projects + lights it.
#[derive(Clone, Debug, Default)]
pub struct RabbitMesh {
    /// `(x, y, z)` per vertex.
    pub positions: Vec<[f32; 3]>,
    /// Unit normal per vertex (parallel to `positions`).
    pub normals: Vec<[f32; 3]>,
    /// Triangle indices (3 per face) into `positions`.
    pub indices: Vec<u32>,
}

impl RabbitMesh {
    pub fn vertex_count(&self) -> usize {
        self.positions.len()
    }
    pub fn triangle_count(&self) -> usize {
        self.indices.len() / 3
    }

    /// The **bounding-sphere radius** about the design-box origin — the
    /// pose-invariant half-extent a viewer fits its pane to
    /// ([`crate::render::cpu::fit_scale`]). Rotation-invariant, so a scale derived
    /// from it can never let the logo leave the widget rect at any yaw/tilt.
    pub fn bounding_radius(&self) -> f32 {
        crate::render::cpu::bounding_radius(self.positions.iter())
    }
}

/// Extrude the rabbit silhouette into a solid 3D logo: a **front** face at
/// `z = +depth/2`, a **back** face at `z = -depth/2`, and the **side walls**
/// joining their rims. Each silhouette loop becomes its own extruded shell
/// (body, head, two ears) — they read as one fused logo when lit. `depth` is the
/// total thickness in design units (~0.3 looks like a chunky logo).
///
/// Front/back faces are triangle-fanned from the loop centroid (the loops are
/// convex-ish ellipses/petals, so a fan is watertight enough for a lit logo) and
/// get axial normals (`+z` / `-z`); the side walls get outward normals derived
/// from the rim edge, so the logo catches the light around its edge.
pub fn rabbit_mesh(depth: f32) -> RabbitMesh {
    let r = Rabbit::default();
    let mut mesh = RabbitMesh::default();
    let hz = depth * 0.5;

    for mut loop_pts in r.silhouette() {
        let n = loop_pts.len();
        if n < 3 {
            continue;
        }
        // **Winding guard.** Everything below emits the front cap CCW-from-`+z` and
        // the side walls outward *on the assumption that the loop is CCW*. A CW loop
        // silently extrudes an inside-out shell (front cap culled, walls facing in) —
        // that was the hollow-eared rabbit. `Rabbit::ear` is fixed at the source; this
        // makes the extruder robust so no future loop can reintroduce it.
        if Rabbit::signed_area2(&loop_pts) < 0.0 {
            loop_pts.reverse();
        }
        let loop_pts = loop_pts;
        // Centroid for the fan + side-wall outward direction.
        let (mut cx, mut cy) = (0.0f64, 0.0f64);
        for &(x, y) in &loop_pts {
            cx += x;
            cy += y;
        }
        cx /= n as f64;
        cy /= n as f64;

        // ── front face (z = +hz), normal +z ──
        let front_centre = mesh.positions.len() as u32;
        mesh.positions.push([cx as f32, cy as f32, hz]);
        mesh.normals.push([0.0, 0.0, 1.0]);
        let front_rim0 = mesh.positions.len() as u32;
        for &(x, y) in &loop_pts {
            mesh.positions.push([x as f32, y as f32, hz]);
            mesh.normals.push([0.0, 0.0, 1.0]);
        }
        for i in 0..n as u32 {
            let a = front_rim0 + i;
            let b = front_rim0 + (i + 1) % n as u32;
            // CCW when viewed from +z (front).
            mesh.indices.extend_from_slice(&[front_centre, a, b]);
        }

        // ── back face (z = -hz), normal -z ──
        let back_centre = mesh.positions.len() as u32;
        mesh.positions.push([cx as f32, cy as f32, -hz]);
        mesh.normals.push([0.0, 0.0, -1.0]);
        let back_rim0 = mesh.positions.len() as u32;
        for &(x, y) in &loop_pts {
            mesh.positions.push([x as f32, y as f32, -hz]);
            mesh.normals.push([0.0, 0.0, -1.0]);
        }
        for i in 0..n as u32 {
            let a = back_rim0 + i;
            let b = back_rim0 + (i + 1) % n as u32;
            // reverse winding so the back face points -z
            mesh.indices.extend_from_slice(&[back_centre, b, a]);
        }

        // ── side walls: quad per rim edge between front & back rims ──
        let wall0 = mesh.positions.len() as u32;
        for &(x, y) in &loop_pts {
            // Outward normal in the xy-plane (from centroid toward the rim).
            let (mut nx, mut ny) = ((x - cx) as f32, (y - cy) as f32);
            let len = (nx * nx + ny * ny).sqrt().max(1e-6);
            nx /= len;
            ny /= len;
            // front vertex then back vertex of this rim point.
            mesh.positions.push([x as f32, y as f32, hz]);
            mesh.normals.push([nx, ny, 0.0]);
            mesh.positions.push([x as f32, y as f32, -hz]);
            mesh.normals.push([nx, ny, 0.0]);
        }
        for i in 0..n as u32 {
            let i0f = wall0 + i * 2;
            let i0b = wall0 + i * 2 + 1;
            let j = (i + 1) % n as u32;
            let i1f = wall0 + j * 2;
            let i1b = wall0 + j * 2 + 1;
            // two triangles forming the wall quad (outward-facing)
            mesh.indices.extend_from_slice(&[i0f, i0b, i1f]);
            mesh.indices.extend_from_slice(&[i1f, i0b, i1b]);
        }
    }
    mesh
}

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

    /// **THE HOLLOW-EARS FENCE.** Every loop this type returns must be **CCW** —
    /// that is the contract [`rabbit_mesh`] extrudes against, and it is load-bearing:
    /// the two ear loops used to come out **clockwise**, so their front caps were
    /// wound backwards, a back-face cull threw them away, and both ears rendered in
    /// the live demo as hollow open troughs you could look straight into.
    ///
    /// RED-when-broken: flip a loop and the winding oracle says so.
    #[test]
    fn every_silhouette_loop_is_wound_ccw() {
        let r = Rabbit::default();
        let loops = r.silhouette();
        assert_eq!(loops.len(), 4, "body + head + 2 ears");
        for (i, lp) in loops.iter().enumerate() {
            let a = Rabbit::signed_area2(lp);
            assert!(a > 0.0, "loop {i} must be CCW (signed area2 = {a:.5}) — a CW loop extrudes inside out");
        }
        // Sensitivity: the oracle really does distinguish the two windings.
        let mut cw = loops[2].clone();
        cw.reverse();
        assert!(Rabbit::signed_area2(&cw) < 0.0, "a reversed loop reads as CW");
    }

    /// **THE INSIDE-OUT FENCE.** After extrusion, *no* triangle's geometric winding
    /// may contradict its own authored vertex normal. This read **528 of 1040** (both
    /// whole ears) before `Rabbit::ear`'s winding was fixed.
    ///
    /// RED-when-broken: hand-extrude a deliberately reversed loop and the count is
    /// non-zero, so the assertion below is not one nothing can trip.
    #[test]
    fn rabbit_mesh_is_consistently_wound_outward() {
        let m = rabbit_mesh(0.34);
        let bad = crate::render::cpu::inside_out_triangles(&m.positions, &m.normals, &m.indices);
        assert_eq!(bad, 0, "{bad} of {} triangles are wound inside out", m.triangle_count());
        assert!(m.triangle_count() > 500, "and it really is a substantial mesh");

        // Sensitivity: reverse the winding of every triangle → every one is inside out.
        let mut flipped = m.clone();
        for t in flipped.indices.chunks_exact_mut(3) {
            t.swap(1, 2);
        }
        let bad_flipped =
            crate::render::cpu::inside_out_triangles(&flipped.positions, &flipped.normals, &flipped.indices);
        assert_eq!(
            bad_flipped,
            m.triangle_count(),
            "the oracle flags every triangle when the whole mesh is reversed"
        );
    }

    /// The extruder is **robust to a clockwise loop**, not merely fixed at the source:
    /// feeding it a CW silhouette must still produce an outward-wound shell.
    #[test]
    fn the_extruder_normalises_a_clockwise_loop() {
        // `rabbit_mesh` reverses any CW loop before extruding, so the mesh built from
        // the default (all-CCW) rabbit is byte-identical whichever way the loops came.
        let m = rabbit_mesh(0.34);
        assert_eq!(
            crate::render::cpu::inside_out_triangles(&m.positions, &m.normals, &m.indices),
            0,
            "the winding guard keeps every shell outward-facing"
        );
        // And the guard's predicate is the one the fence uses.
        let mut cw: Loop = Rabbit::default().silhouette()[2].clone();
        cw.reverse();
        assert!(Rabbit::signed_area2(&cw) < 0.0, "the guard's input predicate detects CW");
    }

    /// Inject-assert: the default rabbit produces the expected loop structure —
    /// body, head, two ears, eye = 5 loops; the silhouette drops the eye → 4.
    #[test]
    fn outline_has_body_head_two_ears_and_an_eye() {
        let loops = rabbit_outline();
        assert_eq!(loops.len(), 5, "body + head + 2 ears + eye");
        assert_eq!(Rabbit::default().silhouette().len(), 4, "silhouette drops the eye");
        // Every loop is a non-trivial closed ring.
        for (i, l) in loops.iter().enumerate() {
            assert!(l.len() >= 8, "loop {i} has enough vertices: {}", l.len());
        }
    }

    /// Determinism (FC-7): two builds are byte-identical (no RNG / per-frame state).
    #[test]
    fn geometry_is_deterministic() {
        assert_eq!(rabbit_outline(), rabbit_outline());
        let a = rabbit_mesh(0.3);
        let b = rabbit_mesh(0.3);
        assert_eq!(a.positions, b.positions);
        assert_eq!(a.indices, b.indices);
    }

    /// All geometry sits inside the normalised `[-1, 1]` design box, and the ears
    /// rise ABOVE the head (the recognizable mascot, not a blob).
    #[test]
    fn geometry_fits_design_box_and_ears_stand_up() {
        let r = Rabbit::default();
        let mut max_y = f64::MIN;
        for l in r.outline() {
            for (x, y) in l {
                assert!((-1.0..=1.0).contains(&x), "x in box: {x}");
                assert!((-1.0..=1.0).contains(&y), "y in box: {y}");
                max_y = max_y.max(y);
            }
        }
        // The ear tips are the highest points and clearly above the head crown.
        let head_top = r.head_cy + r.head_r;
        assert!(max_y > head_top + 0.3, "ears stand well above the head: {max_y} vs {head_top}");
    }

    /// The extruded mesh is a solid: front + back + side-wall vertices, indexed
    /// triangles, normals parallel to positions, and it has real depth in z.
    #[test]
    fn mesh_extrudes_with_depth_normals_and_triangles() {
        let depth = 0.3f32;
        let m = rabbit_mesh(depth);
        assert!(m.vertex_count() > 100, "a real mesh, got {}", m.vertex_count());
        assert_eq!(m.normals.len(), m.positions.len(), "one normal per vertex");
        assert!(m.triangle_count() > 50, "front+back+walls tessellate to many tris");
        assert_eq!(m.indices.len() % 3, 0, "indices are whole triangles");
        // Every index is in range.
        let vc = m.vertex_count() as u32;
        assert!(m.indices.iter().all(|&i| i < vc), "indices in range");
        // Real depth: z spans -depth/2 .. +depth/2.
        let (mut zmin, mut zmax) = (f32::MAX, f32::MIN);
        for p in &m.positions {
            zmin = zmin.min(p[2]);
            zmax = zmax.max(p[2]);
        }
        assert!((zmax - depth * 0.5).abs() < 1e-5 && (zmin + depth * 0.5).abs() < 1e-5, "z spans the full depth");
        // Normals are unit-length.
        for nml in &m.normals {
            let l = (nml[0] * nml[0] + nml[1] * nml[1] + nml[2] * nml[2]).sqrt();
            assert!((l - 1.0).abs() < 1e-4, "unit normal, got {l}");
        }
    }
}