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 loop: up the inner side,
    /// down the outer side, tapering toward a rounded tip.
    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);
        // Inner 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));
        }
        // Outer side: tip → base (mirror of the inner walk → closed petal).
        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
    }

    /// 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
    }
}

/// 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 loop_pts in r.silhouette() {
        let n = loop_pts.len();
        if n < 3 {
            continue;
        }
        // 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::*;

    /// 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}");
        }
    }
}