BREP_gizmos 0.2.1

//! Feature-dimension LEADER geometry (R29) for the render engine's overlay pass.
//!
//! A dimension annotation is the classic CAD witness/leader drawing: extension
//! (witness) lines running out from the measured feature to an offset dimension
//! line, the dimension line itself, and an arrowhead at each end. This module
//! builds ONLY that 3D leader/extension/arrow geometry as an [`Overlay`] of
//! world-space line segments and flat arrowhead triangles. The numeric TEXT
//! label is drawn by the UI layer — never here — anchored at a world point
//! the engine projects with [`GizmoCamera::world_to_screen`]. Each builder
//! returns that point as [`DimensionAnnotation::label_anchor`].
//!
//! # Where the inputs come from (integration)
//! The main-repo feature-dimension resolver
//! (`FeatureDimensionOverlay`, geometry in
//! `dimensionGeometry`) already extracts, per feature, the
//! measured endpoints / vertex / directions / radius from the selected topology
//! (edges, faces, sketch profiles). That resolver feeds this module:
//! - [`linear_dimension`]: measured points `a`, `b`; `offset_dir` = which way to
//!   push the dimension line off the measured segment (the resolver's `tangent`,
//!   typically `normal × (b-a)`); `offset_dist` = world offset.
//! - [`angular_dimension`]: the corner `vertex` and the two ray `dir_a`/`dir_b`
//!   plus a world `radius` for the arc.
//! - [`radial_dimension`]: the circle `center` (or an edge point) and a
//!   `point_on_circle`.
//!
//! # Label placement (integration)
//! The engine calls `camera.world_to_screen(annotation.label_anchor)` and pins
//! the text label at that pixel (nudging in screen space for arrow
//! clearance — the UI layer owns collision avoidance). `label_anchor` is a pure
//! attach point; it is NOT part of the drawn overlay.
//!
//! # Sizing
//! Arrowheads are screen-CONSTANT: their world length/width are derived from
//! [`GizmoCamera::world_per_pixel`] at the arrowhead tip, so they stay a fixed
//! pixel size at any zoom (orthographic or perspective). Distances the caller
//! passes (`offset_dist`, angular `radius`) are world units.
//!
//! Conventions: +Z-up world, RGBA colors are linear-space. No kernel/GPU dep.

use crate::{GizmoCamera, Overlay, Vec3};

/// Screen-constant arrowhead length, CSS pixels.
pub const ARROW_LEN_PX: f32 = 14.0;
/// Screen-constant arrowhead half-width, CSS pixels.
pub const ARROW_HALF_WIDTH_PX: f32 = 5.0;
/// Radial facets of an arrowhead cone.
pub const ARROW_CONE_SEGMENTS: usize = 12;
/// Default world radius for an angular arc when the caller passes `radius <= 0`,
/// expressed in pixels (converted via `world_per_pixel`).
pub const DEFAULT_ANGLE_RADIUS_PX: f32 = 120.0;
/// Minimum on-screen arc radius (pixels) so a tiny world radius stays readable.
pub const MIN_ANGLE_RADIUS_PX: f32 = 40.0;
/// How far (pixels) the angular direction (witness) lines overshoot the arc.
pub const ANGLE_EXT_PX: f32 = 18.0;
/// Gap (pixels) from the measured feature to the label attach point on a radial
/// or the small landing leader.
pub const LABEL_GAP_PX: f32 = 10.0;

/// Default dimension color (linear-space RGBA) — a warm CAD amber matching the
/// main-repo feature-dimension line color.
pub const DIMENSION_COLOR: [f32; 4] = [1.0, 0.72, 0.30, 1.0];

/// The return value of every dimension builder: the overlay geometry to draw
/// plus the world-space point the engine projects to place the text label.
///
/// `label_anchor` is not drawn — see the module docs. The engine does
/// `camera.world_to_screen(label_anchor)` and pins the text label there.
#[derive(Debug, Clone)]
pub struct DimensionAnnotation {
    /// Extension lines, dimension line(s)/arc (in `overlay.lines`) and filled
    /// arrowheads (in `overlay.tris`), all world-space.
    pub overlay: Overlay,
    /// World point for text placement (dimension-line midpoint / arc
    /// midpoint / just outside the circle). Not part of the drawn geometry.
    pub label_anchor: Vec3,
}

// --- small local geometry helpers ------------------------------------------

/// Rotate `v` about a UNIT `axis` by `angle` radians (Rodrigues).
fn rotate_about_axis(v: Vec3, axis: Vec3, angle: f32) -> Vec3 {
    let (s, c) = angle.sin_cos();
    v.scale(c)
        .add(axis.cross(v).scale(s))
        .add(axis.scale(axis.dot(v) * (1.0 - c)))
}

/// Emit one filled, radially-symmetric arrowhead CONE: sharp apex at `apex`
/// aiming along unit `dir` (the arrow "points" this way), base circle of world
/// `radius` centered `len` back from the apex. Reads as a solid 3D cone (side
/// facets + a base cap) from any view — no billboarding needed.
fn arrowhead(
    ov: &mut Overlay,
    apex: Vec3,
    dir: Vec3,
    len: f32,
    radius: f32,
    color: [f32; 4],
) {
    let axis = dir.normalized();
    if axis.length() < 1e-9 || len <= 0.0 || radius <= 0.0 {
        return;
    }
    let base = apex.sub(axis.scale(len));
    let u = axis.any_perp();
    let v = axis.cross(u).normalized();
    let ring = |k: usize| -> Vec3 {
        let ang = (k as f32 / ARROW_CONE_SEGMENTS as f32) * std::f32::consts::TAU;
        base.add(u.scale(ang.cos() * radius))
            .add(v.scale(ang.sin() * radius))
    };
    let mut prev = ring(0);
    for k in 1..=ARROW_CONE_SEGMENTS {
        let cur = ring(k);
        ov.tri(apex, prev, cur, color); // side facet
        ov.tri(base, cur, prev, color); // base cap
        prev = cur;
    }
}

// --- linear dimension -------------------------------------------------------

/// A linear (distance) dimension between measured points `a` and `b`, with the
/// dimension line pushed off the segment by `offset_dist` along `offset_dir`.
///
/// Emits: extension line `a → da`, extension line `b → db`, the dimension line
/// `da → db`, and an arrowhead at each end (`da`, `db`) whose sharp apex sits on
/// the extension line and whose body opens inward toward the label — the
/// standard `|<——>|` CAD look. `offset_dir` is orthogonalized against `a→b`, so
/// the extension lines are perpendicular to the dimension line and the
/// dimension line stays parallel to the measured segment.
///
/// The label anchor is the dimension-line midpoint `(da + db) / 2` — the engine
/// projects it for text placement.
pub fn linear_dimension(
    a: Vec3,
    b: Vec3,
    offset_dir: Vec3,
    offset_dist: f32,
    camera: &GizmoCamera,
) -> DimensionAnnotation {
    linear_dimension_colored(a, b, offset_dir, offset_dist, camera, DIMENSION_COLOR)
}

/// [`linear_dimension`] with an explicit color.
pub fn linear_dimension_colored(
    a: Vec3,
    b: Vec3,
    offset_dir: Vec3,
    offset_dist: f32,
    camera: &GizmoCamera,
    color: [f32; 4],
) -> DimensionAnnotation {
    let mut ov = Overlay::new();

    let dir_raw = b.sub(a);
    let len_ab = dir_raw.length();
    let dir = if len_ab < 1e-9 {
        Vec3::X
    } else {
        dir_raw.scale(1.0 / len_ab)
    };

    // Orthogonalize the offset direction against the measured segment so the
    // witness lines come off perpendicular (CAD standard).
    let mut od = offset_dir.sub(dir.scale(offset_dir.dot(dir)));
    if od.length() < 1e-9 {
        od = dir.any_perp();
    }
    od = od.normalized();

    let da = a.add(od.scale(offset_dist));
    let db = b.add(od.scale(offset_dist));

    // Extension (witness) lines: measured point out to the dimension line.
    ov.line(a, da, color);
    ov.line(b, db, color);
    // Dimension line.
    ov.line(da, db, color);

    // Arrowheads: apex on each extension line, opening inward.
    let wpp_a = camera.world_per_pixel(da);
    let wpp_b = camera.world_per_pixel(db);
    arrowhead(
        &mut ov,
        da,
        dir.scale(-1.0),
        ARROW_LEN_PX * wpp_a,
        ARROW_HALF_WIDTH_PX * wpp_a,
        color,
    );
    arrowhead(
        &mut ov,
        db,
        dir,
        ARROW_LEN_PX * wpp_b,
        ARROW_HALF_WIDTH_PX * wpp_b,
        color,
    );

    let label_anchor = da.lerp(db, 0.5);
    DimensionAnnotation {
        overlay: ov,
        label_anchor,
    }
}

// --- angular dimension ------------------------------------------------------

/// The polyline of world points sampling the dimension arc, from the `dir_a`
/// ray to the `dir_b` ray, swept about the plane normal `dir_a × dir_b` at
/// `radius` from `vertex`. Exposed so callers/tests can inspect the arc (and the
/// engine can reuse the raw samples). Returns an empty vec for parallel rays.
pub fn angular_arc_points(vertex: Vec3, dir_a: Vec3, dir_b: Vec3, radius: f32) -> Vec<Vec3> {
    let a = dir_a.normalized();
    let b = dir_b.normalized();
    let mut normal = a.cross(b);
    if normal.length() < 1e-9 {
        return Vec::new();
    }
    normal = normal.normalized();
    let sweep = a.dot(b).clamp(-1.0, 1.0).acos();
    // ~1 sample per 5 degrees, minimum 8 segments.
    let steps = (((sweep / (5.0_f32).to_radians()).ceil()) as usize).max(8);
    let mut out = Vec::with_capacity(steps + 1);
    for i in 0..=steps {
        let t = i as f32 / steps as f32;
        let d = rotate_about_axis(a, normal, sweep * t);
        out.push(vertex.add(d.scale(radius)));
    }
    out
}

/// An angular (included-angle) dimension at `vertex` between rays `dir_a` and
/// `dir_b`, drawn as an arc at `radius` with an arrowhead at each arc end and a
/// short witness line along each ray running just past the arc.
///
/// `radius` is world units; pass `<= 0` to get a screen-constant default
/// ([`DEFAULT_ANGLE_RADIUS_PX`]). The label anchor is the arc midpoint (on the
/// angle bisector, at `radius`).
pub fn angular_dimension(
    vertex: Vec3,
    dir_a: Vec3,
    dir_b: Vec3,
    radius: f32,
    camera: &GizmoCamera,
) -> DimensionAnnotation {
    angular_dimension_colored(vertex, dir_a, dir_b, radius, camera, DIMENSION_COLOR)
}

/// [`angular_dimension`] with an explicit color.
pub fn angular_dimension_colored(
    vertex: Vec3,
    dir_a: Vec3,
    dir_b: Vec3,
    radius: f32,
    camera: &GizmoCamera,
    color: [f32; 4],
) -> DimensionAnnotation {
    let mut ov = Overlay::new();
    let a = dir_a.normalized();
    let b = dir_b.normalized();
    let wpp = camera.world_per_pixel(vertex);

    // Resolve a readable world radius.
    let mut r = if radius > 1e-6 {
        radius
    } else {
        DEFAULT_ANGLE_RADIUS_PX * wpp
    };
    r = r.max(MIN_ANGLE_RADIUS_PX * wpp);

    let mut normal = a.cross(b);
    if normal.length() < 1e-9 {
        // Parallel/degenerate rays: no arc, anchor along the (single) direction.
        return DimensionAnnotation {
            overlay: ov,
            label_anchor: vertex.add(a.scale(r)),
        };
    }
    normal = normal.normalized();
    let sweep = a.dot(b).clamp(-1.0, 1.0).acos();

    let pts = angular_arc_points(vertex, a, b, r);
    for w in pts.windows(2) {
        ov.line(w[0], w[1], color);
    }

    // Witness lines along each ray, out past the arc.
    let ext = r + ANGLE_EXT_PX * wpp;
    ov.line(vertex, vertex.add(a.scale(ext)), color);
    ov.line(vertex, vertex.add(b.scale(ext)), color);

    // Arrowheads at the arc ends, pointing tangentially outward.
    if pts.len() >= 2 {
        let n = pts.len();
        let start_dir = pts[0].sub(pts[1]).normalized();
        arrowhead(
            &mut ov,
            pts[0],
            start_dir,
            ARROW_LEN_PX * wpp,
            ARROW_HALF_WIDTH_PX * wpp,
            color,
        );
        let end_dir = pts[n - 1].sub(pts[n - 2]).normalized();
        arrowhead(
            &mut ov,
            pts[n - 1],
            end_dir,
            ARROW_LEN_PX * wpp,
            ARROW_HALF_WIDTH_PX * wpp,
            color,
        );
    }

    // Label anchor at the arc midpoint (on the bisector, at radius).
    let mid_dir = rotate_about_axis(a, normal, sweep * 0.5);
    let label_anchor = vertex.add(mid_dir.scale(r));

    DimensionAnnotation {
        overlay: ov,
        label_anchor,
    }
}

// --- radial dimension -------------------------------------------------------

/// A radial dimension: a leader from `center` out to `point_on_circle` with an
/// arrowhead at the circle (apex on the circle, opening inward along the
/// radius), plus a short landing leader continuing outward to the label anchor.
///
/// The label anchor sits just outside the circle, along the radial leader.
pub fn radial_dimension(
    center: Vec3,
    point_on_circle: Vec3,
    camera: &GizmoCamera,
) -> DimensionAnnotation {
    radial_dimension_colored(center, point_on_circle, camera, DIMENSION_COLOR)
}

/// [`radial_dimension`] with an explicit color.
pub fn radial_dimension_colored(
    center: Vec3,
    point_on_circle: Vec3,
    camera: &GizmoCamera,
    color: [f32; 4],
) -> DimensionAnnotation {
    let mut ov = Overlay::new();
    let radial = point_on_circle.sub(center);
    let dist = radial.length();
    let dir = if dist < 1e-9 {
        Vec3::X
    } else {
        radial.scale(1.0 / dist)
    };
    let wpp = camera.world_per_pixel(point_on_circle);

    // Leader from center to the circle.
    ov.line(center, point_on_circle, color);
    // Arrowhead at the circle, apex on the circle pointing outward, body inward.
    arrowhead(
        &mut ov,
        point_on_circle,
        dir,
        ARROW_LEN_PX * wpp,
        ARROW_HALF_WIDTH_PX * wpp,
        color,
    );
    // Short landing leader outward to the label.
    let gap = LABEL_GAP_PX * wpp;
    let anchor = point_on_circle.add(dir.scale(gap.max(0.0)));
    ov.line(point_on_circle, anchor, color);

    DimensionAnnotation {
        overlay: ov,
        label_anchor: anchor,
    }
}

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

    /// A square top-down ortho camera looking down -Z at the XY plane, with a
    /// `vp_px` viewport (bigger viewport = smaller world_per_pixel = zoomed in).
    fn cam(vp_px: f32) -> GizmoCamera {
        let view_proj =
            crate::raster::test_view_proj([0.0, 0.0, 20.0], [0.0, 0.0, 0.0], vp_px, vp_px);
        GizmoCamera {
            view_proj,
            eye: Vec3::new(0.0, 0.0, 20.0),
            forward: Vec3::new(0.0, 0.0, -1.0),
            // test_view_proj's up for the near-vertical -Z pose (+Y fallback).
            up: Vec3::Y,
            viewport: [vp_px, vp_px],
            orthographic: true,
        }
    }

    fn approx(a: Vec3, b: Vec3, tol: f32) -> bool {
        a.sub(b).length() < tol
    }

    /// Vertices per arrowhead cone: side + base-cap tri (3 verts) per segment.
    const PER_CONE_VERTS: usize = 6 * ARROW_CONE_SEGMENTS;

    /// World length of arrowhead cone `i` (apex → base-center) in an overlay.
    /// The cone's first side tri starts at the apex and its first base-cap tri
    /// starts at the base center, so those two vertices give the axial length.
    fn arrowhead_len(ann: &DimensionAnnotation, i: usize) -> f32 {
        let base_idx = i * PER_CONE_VERTS;
        let apex = Vec3::from(ann.overlay.tris[base_idx].pos);
        let base_center = Vec3::from(ann.overlay.tris[base_idx + 3].pos);
        apex.sub(base_center).length()
    }

    #[test]
    fn linear_emits_extensions_dimension_line_and_two_arrowheads() {
        let c = cam(200.0);
        let a = Vec3::new(-3.0, 0.0, 0.0);
        let b = Vec3::new(3.0, 0.0, 0.0);
        let ann = linear_dimension(a, b, Vec3::new(0.0, -1.0, 0.0), 2.0, &c);
        // 3 segments: two extension lines + one dimension line => 6 line verts.
        assert_eq!(ann.overlay.lines.len(), 6, "expected 3 line segments");
        // 2 arrowhead cones => 2 * PER_CONE_VERTS tri verts.
        assert_eq!(
            ann.overlay.tris.len(),
            2 * PER_CONE_VERTS,
            "expected 2 arrowhead cones"
        );
        // Label anchor at the dimension-line midpoint (0, -2, 0).
        assert!(
            approx(ann.label_anchor, Vec3::new(0.0, -2.0, 0.0), 1e-4),
            "label anchor {:?} should be dimension-line midpoint",
            ann.label_anchor
        );
    }

    #[test]
    fn linear_arrowhead_apexes_sit_on_the_dimension_line_ends() {
        let c = cam(200.0);
        let a = Vec3::new(-3.0, 0.0, 0.0);
        let b = Vec3::new(3.0, 0.0, 0.0);
        let ann = linear_dimension(a, b, Vec3::new(0.0, -1.0, 0.0), 2.0, &c);
        // da = (-3,-2,0), db = (3,-2,0); each cone's apex is its first vertex.
        let apex0 = Vec3::from(ann.overlay.tris[0].pos);
        let apex1 = Vec3::from(ann.overlay.tris[PER_CONE_VERTS].pos);
        assert!(approx(apex0, Vec3::new(-3.0, -2.0, 0.0), 1e-4), "{:?}", apex0);
        assert!(approx(apex1, Vec3::new(3.0, -2.0, 0.0), 1e-4), "{:?}", apex1);
    }

    #[test]
    fn arrowheads_are_screen_constant_across_two_zooms() {
        let a = Vec3::new(-3.0, 0.0, 0.0);
        let b = Vec3::new(3.0, 0.0, 0.0);
        let od = Vec3::new(0.0, -1.0, 0.0);
        let c1 = cam(100.0);
        let c2 = cam(200.0);
        let ann1 = linear_dimension(a, b, od, 2.0, &c1);
        let ann2 = linear_dimension(a, b, od, 2.0, &c2);
        let apex = Vec3::new(-3.0, -2.0, 0.0);
        // world size / world_per_pixel == constant pixel size (ARROW_LEN_PX).
        let px1 = arrowhead_len(&ann1, 0) / c1.world_per_pixel(apex);
        let px2 = arrowhead_len(&ann2, 0) / c2.world_per_pixel(apex);
        assert!((px1 - ARROW_LEN_PX).abs() < 0.5, "px1 {px1}");
        assert!((px2 - ARROW_LEN_PX).abs() < 0.5, "px2 {px2}");
        assert!((px1 - px2).abs() < 0.5, "pixel sizes differ: {px1} vs {px2}");
        // And the world sizes genuinely differ (different zoom).
        assert!(
            arrowhead_len(&ann1, 0) > arrowhead_len(&ann2, 0) * 1.5,
            "zoomed-out arrowhead should be larger in world units"
        );
    }

    #[test]
    fn angular_arc_has_the_right_sweep() {
        let v = Vec3::ZERO;
        let a = Vec3::new(1.0, 0.0, 0.0);
        let b = Vec3::new(0.0, 1.0, 0.0); // 90 degrees
        let pts = angular_arc_points(v, a, b, 3.0);
        assert!(pts.len() >= 9, "arc should be sampled");
        let d0 = pts[0].sub(v).normalized();
        let dn = pts[pts.len() - 1].sub(v).normalized();
        let sweep = d0.dot(dn).clamp(-1.0, 1.0).acos();
        assert!(
            (sweep - std::f32::consts::FRAC_PI_2).abs() < 1e-2,
            "sweep {} should be 90 deg",
            sweep.to_degrees()
        );
        // Endpoints land on the rays at radius.
        assert!(approx(pts[0], Vec3::new(3.0, 0.0, 0.0), 1e-3));
        assert!(approx(pts[pts.len() - 1], Vec3::new(0.0, 3.0, 0.0), 1e-3));
    }

    #[test]
    fn angular_emits_arc_witness_lines_and_two_arrowheads() {
        let c = cam(200.0);
        let v = Vec3::ZERO;
        let a = Vec3::new(1.0, 0.0, 0.0);
        let b = Vec3::new(0.0, 1.0, 0.0);
        let ann = angular_dimension(v, a, b, 3.0, &c);
        // arc segments + 2 witness lines; at least 8 arc segments + 2 = 10.
        assert!(ann.overlay.lines.len() >= (10) * 2, "arc+witness line count");
        // Two arrowhead cones at the arc ends.
        assert_eq!(
            ann.overlay.tris.len(),
            2 * PER_CONE_VERTS,
            "expected 2 arrowhead cones"
        );
        // Label anchor on the bisector at radius: dir (1,1,0)/sqrt2 * 3.
        let expect = Vec3::new(1.0, 1.0, 0.0).normalized().scale(3.0);
        assert!(
            approx(ann.label_anchor, expect, 1e-3),
            "angular label anchor {:?} vs {:?}",
            ann.label_anchor,
            expect
        );
    }

    #[test]
    fn radial_emits_leader_and_one_arrowhead() {
        let c = cam(200.0);
        let center = Vec3::ZERO;
        let pc = Vec3::new(4.0, 0.0, 0.0);
        let ann = radial_dimension(center, pc, &c);
        // leader (center->circle) + landing leader (circle->anchor) = 2 segments.
        assert_eq!(ann.overlay.lines.len(), 4, "expected 2 leader segments");
        assert_eq!(ann.overlay.tris.len(), PER_CONE_VERTS, "expected 1 arrowhead cone");
        // Anchor just outside the circle along +X.
        assert!(ann.label_anchor.x > 4.0, "anchor {:?}", ann.label_anchor);
        assert!(ann.label_anchor.sub(Vec3::new(4.0, 0.0, 0.0)).length() < 1.0);
    }

    #[test]
    fn parallel_rays_yield_no_arc() {
        let c = cam(200.0);
        let ann = angular_dimension(
            Vec3::ZERO,
            Vec3::new(1.0, 0.0, 0.0),
            Vec3::new(1.0, 0.0, 0.0),
            2.0,
            &c,
        );
        assert!(ann.overlay.tris.is_empty());
        assert!(angular_arc_points(Vec3::ZERO, Vec3::X, Vec3::X, 2.0).is_empty());
    }
}