Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

57.1 KB
Raw Blame
//! Threads: the cosmetic thread on a cylindrical face, and the modelled
//! thread's groove cut along a helix.

use super::*;
use crate::thread_forms::{SteepFlank, ThreadForm, ThreadHand, ThreadTip};

/// A cosmetic thread: on which cylinder, its size, and the threaded part of the axis.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct ThreadInfo {
    pub feature: u64,
    pub body: String,
    pub designation: String,
    pub major_diameter: f64,
    /// Radius of the actual cylindrical face when the cosmetic thread is evaluated (0 in a
    /// state saved without it: the cosmetic display then leaves the thread out).
    #[serde(default)]
    pub radius: f64,
    pub pitch: f64,
    pub internal: bool,
    pub axis_point: Vec3,
    pub axis: UnitVec3,
    /// Threaded part along the axis from `axis_point`.
    pub start: f64,
    pub end: f64,
    #[serde(default)]
    pub form: ThreadForm,
    #[serde(default)]
    pub hand: ThreadHand,
    #[serde(default = "crate::thread_forms::one_start")]
    pub starts: u32,
}

/// Nominal diameters and coarse pitches (mm) used for automatic ISO metric thread sizing.
/// Other diameter/pitch pairs can be supplied as explicit designations.
pub fn metric_thread_sizes() -> &'static [(f64, f64)] {
    crate::thread_forms::ISO_COARSE
}

/// "M8" or "M8x1" → (nominal diameter, pitch).
pub fn parse_metric_thread(s: &str) -> Option<(f64, f64)> {
    ThreadForm::Metric.parse(s, 1).ok().filter(|z| (z.lead - z.pitch).abs() < 1e-12).map(|z| (z.major, z.pitch))
}

/// The automatic ISO metric designation for a cylindrical face, using the same fit check as
/// a thread feature without an explicit size. This query does not change the model.
pub fn suggested_thread(st: &ModelState, p: Vec3) -> Result<String> {
    suggested_thread_in(st, p, ThreadForm::Metric)
}

/// The standard designation of `form` that fits the cylindrical face at `p` (a shaft its major
/// diameter, a hole its drill), with the same fit check as a thread feature without an explicit
/// size. This query does not change the model.
pub fn suggested_thread_in(st: &ModelState, p: Vec3, form: ThreadForm) -> Result<String> {
    thread_on(st, 0, p, &ThreadAsk { form: Some(form), ..Default::default() }).map(|t| t.info.designation)
}

/// How far a thread runs along its face.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub(super) enum Extent {
    /// The whole face.
    #[default]
    Full,
    /// This long, from the end it starts at.
    Length(f64),
    /// From the end it starts at to where this plane crosses the axis.
    UpTo(Plane),
    /// From the end it starts at to this point's place along the axis.
    UpToPoint(Vec3),
}

/// What a thread feature asks for: its size, how far it runs and from which end.
#[derive(Clone, Copy, Debug, Default)]
pub(super) struct ThreadAsk<'a> {
    /// The form; `None`: the one `designation`'s prefix names, else metric.
    pub form: Option<ThreadForm>,
    pub designation: Option<&'a str>,
    pub hand: ThreadHand,
    /// Starts; 0 is taken as 1.
    pub starts: u32,
    pub steep: SteepFlank,
    pub extent: Extent,
    /// A point near the end of the face the thread starts at.
    pub from: Option<Vec3>,
    /// A modelled thread needs to know how each of its ends meets the face's ends.
    pub modeled: bool,
    /// The runout at the end away from where the thread starts, as (mm, pitches): its length
    /// is mm + pitches x the pitch. The start never fades: it runs off its free end.
    pub ease_out: (f64, f64),
    /// A tapped hole's thread: `designation` is a catalogue size (ISO metric, or a catalogued
    /// UNC/UNF, G, Rp, Rc or NPT size), and a size that is not metric fits the hole drilled for it.
    pub tapped: bool,
    /// A design saved before holes were sized by their nominal diameter: with no designation, a
    /// hole is matched by its tap drill alone ([`ThreadForm::fit_with`]), so it keeps its size.
    pub old_auto_size: bool,
}

/// How one end of a thread's length meets its face.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum End {
    /// At an end of the face past which there is no material in the groove's way: the groove
    /// runs out into the air (or through a chamfer).
    Free,
    /// At (or within half a pitch of) an end of the face where material goes on past it, a
    /// shoulder, a head, a blind hole's bottom: the groove stops short, clear of it.
    Closed,
    /// At an end of an external thread's face where a shoulder starts and stays beyond the face's
    /// end: the groove runs on through the plane of that end and is trimmed there, so the root
    /// reaches the shoulder at every angle, a nut bottoms out on it, and nothing past the plane
    /// is cut.
    Shoulder,
    /// Inside the face: the groove stops square there.
    Inside,
}

/// A thread resolved on its face.
pub(super) struct ThreadOn {
    pub info: ThreadInfo,
    cyl: kernel::CylinderFace,
    /// How the thread's start and end meet the face (modelled threads only).
    ends: [End; 2],
    steep: SteepFlank,
    /// Runout lengths (mm) at the thread's start and end along the axis.
    ease: [f64; 2],
    /// The end of the axis (0: its start, 1: its end) the thread starts from.
    from: usize,
    /// A modelled internal thread in a hole wider than it needs: the radius the bore is narrowed
    /// to (the thread's minor radius) before the groove is cut, with the hole's own radius.
    narrow: Option<f64>,
    /// A shoulder keeps the square stop because the kernel couldn't check whether it stays beyond
    /// the face's end.
    shoulder_unchecked: bool,
}

/// The free-end test of a face's two ends (`side` 0 at its start, 1 at its end), each made
/// once. The groove's one-pitch overrun past a free end reaches 1.5 pitches past it. An end is
/// closed when, within that reach, material lies outside the face's cylinder (inside it, for a
/// hole) at the radii the groove cuts beyond the face: a shoulder, a plate, a head, a blind
/// hole's bottom, however thin, the material stepping out past the face. It is closed too when
/// material lies in the groove's band of radii beyond its first pitch: the face's cylinder going
/// on past a split. A chamfer, a neck, a countersink or a counterbore steps the other way and
/// leaves the end free: the groove runs out through it.
struct FaceEnds<'a> {
    body: &'a Body,
    cyl: &'a kernel::CylinderFace,
    band: (f64, f64),
    /// The radii the groove cuts beyond the face's own: from it out to the groove's outer edge
    /// (external), or in to its inner edge (internal).
    beyond: (f64, f64),
    pitch: f64,
    free: [Option<bool>; 2],
}

impl FaceEnds<'_> {
    fn free(&mut self, side: usize) -> Result<bool> {
        if let Some(Some(f)) = self.free.get(side) {
            return Ok(*f);
        }
        let p = self.pitch;
        let past =
            |from: f64, to: f64| if side == 0 { (self.cyl.start - to, self.cyl.start - from) } else { (self.cyl.end + from, self.cyl.end + to) };
        // Material that only touches the band's rims (a counterbore as wide as the thread, the
        // face's own end) is not in the groove's way.
        let e = p * 1e-3;
        let stepped_out = kernel::material_in_ring(self.body, self.cyl, self.beyond.0 + e, self.beyond.1 - e, past(e, 1.5 * p))?;
        let free = !stepped_out && !kernel::material_in_ring(self.body, self.cyl, self.band.0 + e, self.band.1 - e, past(p, 1.5 * p))?;
        if let Some(slot) = self.free.get_mut(side) {
            *slot = Some(free);
        }
        Ok(free)
    }

    /// Does the shoulder at this closed end stay beyond the plane of the face's end? Not where it
    /// rises back along the face (a slanted plate, a boss on a round body), which a groove
    /// running to that plane would cut into: there is material outside the face just inside it.
    /// The caller keeps the square stop, and says so, when the kernel can't make the check.
    fn clear_of_end_plane(&self, side: usize) -> Result<bool> {
        #[cfg(test)]
        if tests::FAIL_CLEARANCE.get() {
            return Err(kernel::KernelError::Failed("clearance refused for the test".into()).into());
        }
        let (p, e) = (self.pitch, self.pitch * 1e-3);
        let inside = if side == 0 { (self.cyl.start + e, self.cyl.start + p) } else { (self.cyl.end - p, self.cyl.end - e) };
        // All the radii the groove cuts beyond the face; only touching their rims is not in its
        // way, as in `free`.
        kernel::material_in_ring(self.body, self.cyl, self.beyond.0 + e, self.beyond.1 - e, inside).map(|hit| !hit).map_err(DocError::from)
    }
}

/// A thread on the cylindrical face at `p`: its size, and the part of the face it runs over.
pub(super) fn thread_on(st: &ModelState, feature: u64, p: Vec3, ask: &ThreadAsk) -> Result<ThreadOn> {
    let (bi, cyl) = st
        .bodies
        .iter()
        .enumerate()
        .filter_map(|(i, b)| {
            #[cfg(test)]
            super::cost_tests::count(|c| c.cylinder_search += 1);
            kernel::cylinder_face_at(&b.body, p).map(|c| (i, c))
        })
        .min_by(|a, b| {
            let dist = |c: &kernel::CylinderFace| ((p - c.axis_point - c.axis * (p - c.axis_point).dot(c.axis)).len() - c.radius).abs();
            dist(&a.1).total_cmp(&dist(&b.1))
        })
        .ok_or_else(|| DocError::Invalid("no cylindrical face there to thread".into()))?;
    let mb = st.bodies.get(bi).ok_or_else(|| DocError::Invalid("threaded body".into()))?;
    let dia = cyl.radius * 2.0;
    let form = match (ask.form, ask.designation.and_then(ThreadForm::of_designation)) {
        (Some(f), _) | (None, Some(f)) => f,
        (None, None) => ThreadForm::Metric,
    };
    if let Some(why) = form.refused() {
        return Err(DocError::Invalid(why.into()));
    }
    let starts = ask.starts.max(1);
    if starts > 8 {
        return Err(DocError::Invalid("a thread has 1 to 8 starts".into()));
    }
    // A tapped hole's size is the catalogue's.
    let tapped = match (ask.tapped, ask.designation) {
        (false, _) => None,
        (true, None) => return Err(DocError::Invalid("a tapped hole needs a designation".into())),
        (true, Some(name)) => Some(crate::parse_tapped_thread(name).ok_or_else(|| {
            DocError::Invalid(format!("unknown tapped thread `{name}` (ISO metric or a catalogued UNC/UNF, G, Rp, Rc or NPT size)"))
        })?),
    };
    let size = match (&tapped, ask.designation) {
        (Some(t), _) => crate::thread_forms::ThreadSize { form, major: t.major_diameter, pitch: t.pitch, lead: t.pitch },
        (None, Some(s)) => form.parse(s, starts).map_err(DocError::Invalid)?,
        (None, None) => {
            let (d, p) = form.fit_with(dia, cyl.internal, ask.old_auto_size).ok_or_else(|| {
                DocError::Invalid(if form.sizes().is_empty() {
                    format!("{} threads have no size table: give the designation ({})", form.name(), form.format(50.8, 25.4 / 8.0, 25.4 / 8.0))
                } else {
                    format!("no {} thread fits a {dia:.2} mm cylinder", form.name())
                })
            })?;
            crate::thread_forms::ThreadSize { form, major: d, pitch: p, lead: p * f64::from(starts) }
        }
    };
    let (major, pitch) = (size.major, size.pitch);
    // A designation that gives the lead (M16xPh3P1.5, Tr40x14(P7)) gives the starts.
    let named = (size.lead / pitch).round() as u32;
    if ask.starts > 1 && named != starts {
        return Err(DocError::Invalid(format!("`{}` has {named} start(s), not {starts}", ask.designation.unwrap_or_default())));
    }
    let starts = named.max(1);
    let mut designation = tapped.as_ref().map(|t| t.designation.clone()).unwrap_or_else(|| form.format(major, pitch, size.lead));
    if !form.pipe_sizes().is_empty() && tapped.is_none() {
        if ask.hand == ThreadHand::Both {
            return Err(DocError::Invalid("a pipe thread turns one way: right or left".into()));
        }
        // ISO 7-1's Rp is the parallel internal thread an R screws into; there is no external Rp.
        if form == ThreadForm::Rp && !cyl.internal {
            return Err(DocError::Invalid(format!(
                "`{designation}` on this shaft: Rp is an internal thread (ISO 7-1); an external pipe thread is R (taper, ISO 7-1) or G (ISO 228-1)"
            )));
        }
        // ISO 7-1 names the internal taper thread Rc and the external one R.
        if form == ThreadForm::Bspt {
            if let Some(given) = ask.designation
                && ThreadForm::pipe_internal(given) != cyl.internal
            {
                let want = if cyl.internal { "an internal taper thread is Rc" } else { "an external taper thread is R" };
                return Err(DocError::Invalid(format!("`{given}` on this {}: {want} (ISO 7-1)", if cyl.internal { "hole" } else { "shaft" })));
            }
            if cyl.internal {
                designation = designation.replacen("R ", "Rc ", 1);
            }
        }
    }
    let minor = 2.0 * form.groove(major, pitch, true).crest_r;
    let fits = if let Some(t) = tapped.as_ref().filter(|t| t.family != crate::TappedThreadFamily::Metric) {
        // The hole drilled for it, without borrowing an ISO minor-diameter rule.
        cyl.internal && (t.tap_drill - dia).abs() < 0.15 * major
    } else if cyl.internal {
        (minor - dia).abs() < 0.2 * major || (form.drill(major, pitch) - dia).abs() < 0.15 * major || (major - dia).abs() < 0.15 * major
    } else {
        (major - dia).abs() < 0.15 * major
    };
    if !fits {
        let kind = if cyl.internal { "hole" } else { "shaft" };
        let try_instead = form
            .fit(dia, cyl.internal)
            .map(|(n, q)| form.format(n, q, q))
            .filter(|a| *a != designation)
            .map(|a| format!("; this {kind} takes {a}"))
            .unwrap_or_default();
        return Err(DocError::Invalid(format!("an {designation} thread does not fit a {dia:.2} mm {kind}{try_instead}")));
    }
    // The radii the groove cuts: from the external thread's minor diameter (a nut's: its minor)
    // to the major (a nut's root), and to the face itself where it lies outside that.
    let (r_lo, r_hi) = if cyl.internal {
        let g = form.groove(major, pitch, true);
        (g.crest_r, g.root_r)
    } else {
        (form.groove(major, pitch, false).root_r, major / 2.0)
    };
    let band = (cyl.radius.min(r_lo), cyl.radius.max(r_hi));
    // As far beyond the face as the groove's section reaches ([`thread_grooves`]).
    let beyond =
        if cyl.internal { ((cyl.radius.min(r_lo) - 0.1 * pitch).max(0.0), cyl.radius) } else { (cyl.radius, cyl.radius.max(r_hi) + 0.05 * pitch) };
    let mut ends = FaceEnds { body: &mb.body, cyl: &cyl, band, beyond, pitch, free: [None; 2] };
    let (lo, hi) = (cyl.start, cyl.end);
    let along = |q: Vec3| (q - cyl.axis_point).dot(cyl.axis);
    let span = |side: usize, to: f64| -> Result<(f64, f64)> {
        let (a, b) = if side == 0 { (lo, to.min(hi)) } else { (to.max(lo), hi) };
        if !(b - a > pitch * 1e-3) {
            return Err(DocError::Invalid("the thread's limit is not along the face from the end it starts at".into()));
        }
        Ok((a, b))
    };
    let from_side = |ends: &mut FaceEnds| start_side(ends, ask.from.map(along), along(p));
    // An external taper thread runs its standard length (ISO 7-1's useful thread, NPT's
    // effective thread L2) unless told otherwise; an internal one the face, as a tapped hole.
    let extent = match (ask.extent, form.is_taper() && !cyl.internal) {
        (Extent::Full, true) => form.pipe_size(major).map_or(Extent::Full, |z| Extent::Length(z.length)),
        (e, _) => e,
    };
    let (a, b, side) = match extent {
        Extent::Full => (lo, hi, ask.from.map(|q| usize::from((along(q) - lo).abs() > (hi - along(q)).abs())).unwrap_or(0)),
        Extent::Length(l) => {
            if !(l > 0.0) {
                return Err(DocError::Invalid("thread length must be positive".into()));
            }
            if l >= hi - lo - pitch * 1e-3 {
                // As long as the face (or longer): it runs the whole face from either end.
                (lo, hi, ask.from.map(|q| usize::from((along(q) - lo).abs() > (hi - along(q)).abs())).unwrap_or(0))
            } else {
                let side = from_side(&mut ends)?;
                let (a, b) = span(side, if side == 0 { lo + l } else { hi - l })?;
                (a, b, side)
            }
        }
        Extent::UpTo(pl) => {
            let n = pl.normal();
            let k = n.dot(*cyl.axis);
            if k.abs() < 1e-9 {
                return Err(DocError::Invalid("the plane the thread runs up to is parallel to its axis".into()));
            }
            let to = n.dot(pl.origin - cyl.axis_point) / k;
            let side = from_side(&mut ends)?;
            let (a, b) = span(side, to)?;
            (a, b, side)
        }
        Extent::UpToPoint(q) => {
            let side = from_side(&mut ends)?;
            let (a, b) = span(side, along(q))?;
            (a, b, side)
        }
    };
    // The runout at each end of the axis: only at the end away from where it starts.
    let e_out = ask.ease_out.0 + ask.ease_out.1 * pitch;
    let ease = if side == 0 { [0.0, e_out] } else { [e_out, 0.0] };
    if ease.iter().any(|e| !(*e >= 0.0 && e.is_finite())) {
        return Err(DocError::Invalid("a runout length must be positive".into()));
    }
    // How each end of the thread meets the face: at a face end, or within half a pitch (and its
    // runout) of one, where the groove would reach past it, that end's free-end test decides.
    let near = |at: f64, side: usize| if side == 0 { at - lo } else { hi - at } < pitch / 2.0 + ease.get(side).copied().unwrap_or(0.0);
    // A shoulder whose check the kernel couldn't make keeps the square stop, and the feature says so.
    let mut unchecked = false;
    let mut kind = |at: f64, side: usize| -> Result<End> {
        Ok(if !ask.modeled || !near(at, side) {
            End::Inside
        } else if !ends.free(side)? {
            let at_end = (if side == 0 { at - lo } else { hi - at }) < pitch * 1e-3;
            let square = ease.get(side).copied().unwrap_or(0.0) == 0.0;
            let clear = at_end && square && !cyl.internal && !form.is_taper() && {
                let check = ends.clear_of_end_plane(side);
                unchecked |= matches!(check, Err(DocError::Kernel(_)));
                match check {
                    Err(DocError::Kernel(_)) => false,
                    other => other?,
                }
            };
            if clear { End::Shoulder } else { End::Closed }
        } else if (if side == 0 { at - lo } else { hi - at }) < pitch * 1e-3 {
            End::Free
        } else {
            End::Inside
        })
    };
    let ends = [kind(a, 0)?, kind(b, 1)?];
    if form.is_taper() && ask.modeled && ends.get(side) != Some(&End::Free) {
        return Err(DocError::Invalid(format!(
            "a taper pipe thread starts at a free end, the pipe's end or the {}: start it there (`from`, a point near that end)",
            if cyl.internal { "hole's mouth" } else { "shaft's end" }
        )));
    }
    let info = ThreadInfo {
        feature,
        body: mb.name.clone(),
        designation,
        major_diameter: major,
        radius: cyl.radius,
        pitch,
        internal: cyl.internal,
        axis_point: cyl.axis_point,
        axis: cyl.axis,
        start: a,
        end: b,
        form,
        hand: ask.hand,
        starts,
    };
    // A hole already as wide as the thread's major diameter (a 12 mm hole for M12) has no wall to
    // cut a groove into: the bore is narrowed to the thread's minor diameter first.
    let narrow = (ask.modeled && cyl.internal && tapped.is_none() && !form.is_taper())
        .then(|| form.groove(major, pitch, true))
        .filter(|g| !(g.root_r - cyl.radius >= g.basic_depth / 4.0))
        .map(|g| g.crest_r);
    Ok(ThreadOn { info, cyl, ends, steep: ask.steep, ease, from: side, narrow, shoulder_unchecked: unchecked })
}

/// The end of the face (0: its start, 1: its end) a thread of limited length starts at: the end
/// nearest `from` (an axial position) when given, else the face's only free end, else the end the
/// pick `at` lies near (within a third of the face). A pick in the middle of a face whose ends are
/// alike is refused rather than guessed.
fn start_side(ends: &mut FaceEnds, from: Option<f64>, at: f64) -> Result<usize> {
    let (lo, hi) = (ends.cyl.start, ends.cyl.end);
    if let Some(s) = from {
        return match (s - lo).abs().total_cmp(&(hi - s).abs()) {
            std::cmp::Ordering::Less => Ok(0),
            std::cmp::Ordering::Greater => Ok(1),
            std::cmp::Ordering::Equal => Err(DocError::Invalid("`from` is as near one end of the face as the other".into())),
        };
    }
    match (ends.free(0)?, ends.free(1)?) {
        (true, false) => return Ok(0),
        (false, true) => return Ok(1),
        _ => {}
    }
    let third = (hi - lo) / 3.0;
    if at - lo < third {
        Ok(0)
    } else if hi - at < third {
        Ok(1)
    } else {
        let alike = if ends.free(0)? { "both ends of the face are free" } else { "material goes on past both ends of the face" };
        Err(DocError::Invalid(format!("{alike}: say which end the thread starts from (`from`, a point near that end)")))
    }
}

/// A thread's groove as a screw sweep: its `section` in `plane` (an axial plane through `base`),
/// carried `turns` turns about `axis` through `base`, rising `pitch` per turn (negative: a
/// left-handed groove).
struct GrooveShape {
    plane: Plane,
    section: Vec<Vec2>,
    base: Vec3,
    axis: Vec3,
    pitch: f64,
    turns: f64,
    /// The section's move off the axis (turn, mm), piecewise linear: the runouts. Empty: none.
    law: Vec<(f64, f64)>,
}

/// The helical spaces between the teeth of a modelled thread of the form's profile: cut from
/// the shaft (external) or the hole wall (internal), running from `start` to `end` along the
/// axis, one groove per start and hand. `radius` is the face's own radius, `face` its extent
/// along the axis and `ends` how the thread's two ends meet it. A taper thread's `taper` is
/// (its major diameter where it starts, the end of the axis it starts from): its diameters grow
/// 1 in 16 from there into an external thread's material and shrink into an internal one's.
fn thread_grooves(
    t: &ThreadInfo,
    radius: f64,
    face: (f64, f64),
    ends: [End; 2],
    steep: SteepFlank,
    ease: [f64; 2],
    taper: Option<(f64, usize)>,
) -> Result<Vec<GrooveShape>> {
    let (p, d, form) = (t.pitch, t.major_diameter, t.form);
    let lead = p * f64::from(t.starts.max(1));
    let len = t.end - t.start;
    if !(p > 1e-3 && len > 1e-6) {
        return Err(DocError::Invalid("thread too short".into()));
    }
    if len / lead > 190.0 {
        return Err(DocError::Invalid(format!(
            "a modelled thread is limited to 190 turns ({:.0} mm at this lead); use a cosmetic one",
            190.0 * lead
        )));
    }
    // The major diameter at axial position z: fixed, or a taper's from where it starts.
    let major_at = |z: f64| match taper {
        Some((d0, from)) => {
            let (z0, into) = if from == 0 { (t.start, 1.0) } else { (t.end, -1.0) };
            let grow = if t.internal { -1.0 } else { 1.0 };
            d0 + grow * into * (z - z0) / 16.0
        }
        None => d,
    };
    let d = taper.map_or(d, |(d0, _)| d0);
    let profile = |d: f64| {
        let mut g = form.groove(d, p, t.internal);
        if steep == SteepFlank::Start {
            std::mem::swap(&mut g.flank_lo, &mut g.flank_hi);
        }
        g
    };
    let g = profile(d);
    let alt = |dia: f64| form.fit(dia, t.internal).map(|(n, q)| form.format(n, q, q)).filter(|a| *a != t.designation);
    // How deep the groove cuts into the material: from the hole wall out to the internal
    // thread's root, or from the shaft's surface in to the external thread's root. Next to
    // nothing (a hole as wide as the thread, #995) is refused: the cut would leave the face
    // unthreaded.
    let basic = g.basic_depth;
    let depth = if t.internal { g.root_r - radius } else { radius - g.root_r };
    let drill = show_mm(form.drill(d, p));
    if !(depth >= basic / 4.0) {
        let (m, dia) = (&t.designation, 2.0 * radius);
        let cut = format!("it would cut {:.2} mm of the thread's {basic:.2} mm depth", depth.max(0.0));
        let shown = show_mm(dia);
        return Err(DocError::Invalid(if t.internal {
            let alt = alt(dia).map(|a| format!(", or thread this hole {a}")).unwrap_or_default();
            format!("this {shown} mm hole is too wide for a modelled {m} thread: {cut}; drill {drill} mm for {m}{alt}")
        } else {
            let alt = alt(dia).map(|a| format!(", or thread this shaft {a}")).unwrap_or_default();
            format!("this {shown} mm shaft is too thin for a modelled {m} thread: {cut}; make the shaft {} mm for {m}{alt}", show_mm(d))
        }));
    }
    // The section: from the root out past the surface (external), or from inside the hole wall
    // out to the root (internal), so the cut leaves no skin, its flanks the groove's.
    // A taper thread's crests are cut by its major cone (external) or minor cone (internal),
    // as the die or tap cuts them ([`taper_envelope`]): its groove reaches past the crest by as
    // much as narrows the tooth's crest flat by a quarter (NPT's flat is 0.038 P). The cone
    // changes 1 in 32 along the axis (`major_at`) across the section's own width, so its edge
    // there follows the cone at that margin rather than being cut square: square, its deeper
    // corner stops short of the cone and leaves a sliver of each flank.
    let cone = taper.map_or(0.0, |_| (major_at(t.start + 1.0) - major_at(t.start)) / 2.0);
    let section_of = |g: &crate::thread_forms::GrooveProfile| -> (Vec<Vec2>, f64) {
        let (tl, th) = (g.flank_lo.tan(), g.flank_hi.tan());
        if taper.is_none() {
            let (r0, r1) = if t.internal { (radius.min(g.crest_r) - 0.1 * p, g.root_r) } else { (g.root_r, radius.max(d / 2.0) + 0.05 * p) };
            let ((lo0, hi0), (lo1, hi1)) = (g.extents(p, r0), g.extents(p, r1));
            let wide = g.width(p, if t.internal { r0 } else { r1 });
            return (vec![Vec2::new(r0, -lo0), Vec2::new(r1, -lo1), Vec2::new(r1, hi1), Vec2::new(r0, hi0)], wide);
        }
        // Depth from the root, out towards the crest: d(z) = dc + q·z along the edge, which
        // meets the flanks z = −(h + d·tl) and z = h + d·th.
        let o = if t.internal { -1.0 } else { 1.0 };
        let q = o * cone;
        let h = g.width(p, g.root_r) / 2.0;
        let dc = o * (g.crest_r - g.root_r) + 0.25 * g.crest_flat / (tl + th);
        let (z_lo, z_hi) = (-(h + dc * tl) / (1.0 + q * tl), (h + dc * th) / (1.0 - q * th));
        let r = |z: f64| g.root_r + o * (dc + q * z);
        let (root, edge) = ([Vec2::new(g.root_r, -h), Vec2::new(g.root_r, h)], [Vec2::new(r(z_lo), z_lo), Vec2::new(r(z_hi), z_hi)]);
        // In the order the square section has: the inner radius's corners first.
        let pts = if t.internal { vec![edge[0], root[0], root[1], edge[1]] } else { vec![root[0], edge[0], edge[1], root[1]] };
        (pts, z_hi - z_lo)
    };
    let (mut section, wide) = section_of(&g);
    let radii = |s: &[Vec2]| s.iter().fold((f64::INFINITY, f64::NEG_INFINITY), |(a, b), v| (a.min(v.x), b.max(v.x)));
    let (r0, r1) = radii(&section);
    if wide >= p * 0.98 {
        // The groove would be wider than a pitch: the face is far inside the thread (a hole
        // narrower than its minor diameter, a shaft thicker than its major one, #2688).
        let (m, dia) = (&t.designation, 2.0 * radius);
        let shown = show_mm(dia);
        return Err(DocError::Invalid(if t.internal {
            let alt = alt(dia).map(|a| format!(", or thread this hole {a}")).unwrap_or_default();
            format!("this {shown} mm hole is too narrow for a modelled {m} thread (its teeth would fill the hole); drill {drill} mm for {m}{alt}")
        } else {
            let alt = alt(dia).map(|a| format!(", or thread this shaft {a}")).unwrap_or_default();
            format!("this {shown} mm shaft is too thick for a modelled {m} thread; make the shaft {} mm for {m}{alt}", show_mm(d))
        }));
    }
    if !(r0.is_finite() && r1.is_finite() && r0 > 0.0) {
        return Err(DocError::Invalid("thread dimensions are out of range".into()));
    }
    // Past a free end of the face the groove runs out into the air, a pitch beyond it. Before
    // a closed one it stops with its section clear of the face's end (its centre as far inside
    // as the section reaches that way), so it never cuts into the shoulder there; inside the
    // face it stops square at the threaded length's end. At a shoulder it can be trimmed against
    // ([`End::Shoulder`]) its whole section runs past the plane of the face's end, so every angle
    // of the last turn is cut down to that plane ([`trim_at_shoulders`] takes off the rest).
    //
    // A runout `e` at an end (ISO 3508) fades the groove out over `e`: its section moves out of
    // the material (an external thread's away from the axis, past the surface; an internal
    // one's towards it, into the hole) as it turns. It lies past the full-form length, up to the
    // shoulder's clearance; at a free end, inside the face, the groove reaching nothing there.
    // How far the section reaches each way along the axis.
    let (w_lo, w_hi) = section.iter().fold((0.0_f64, 0.0_f64), |(a, b), v| (a.max(-v.y), b.max(v.y)));
    let s0 = match (ends[0], ease[0] > 0.0) {
        (End::Free, false) => t.start - p,
        (End::Free, true) => t.start,
        (End::Closed, _) => (t.start - ease[0]).max(face.0 + w_lo),
        (End::Shoulder, _) => face.0 - w_hi - 0.1 * p,
        (End::Inside, _) => t.start - ease[0],
    };
    let s1 = match (ends[1], ease[1] > 0.0) {
        (End::Free, false) => t.end + p,
        (End::Free, true) => t.end,
        (End::Closed, _) => (t.end + ease[1]).min(face.1 - w_hi),
        (End::Shoulder, _) => face.1 + w_lo + 0.1 * p,
        (End::Inside, _) => t.end + ease[1],
    };
    if !(s1 - s0 > p * 1e-3) {
        return Err(DocError::Invalid(format!(
            "the thread is too short to model between the shoulders: its groove needs {} mm clear of each",
            show_mm(w_lo.max(w_hi))
        )));
    }
    let turns = (s1 - s0) / lead;
    // A taper thread's section is the profile where the sweep begins, moved off the axis as it
    // turns by the taper's 1/32 of the axial travel.
    let mut r0 = r0;
    let taper_rate = match taper {
        Some(_) => {
            section = section_of(&profile(major_at(s0))).0;
            r0 = radii(&section).0;
            (major_at(s0 + lead) - major_at(s0)) / 2.0
        }
        None => 0.0,
    };
    // How far the section moves to leave the material, a little past it.
    let out = if t.internal { -(r1 - radius + 0.05 * p) } else { radius - r0 + 0.05 * p };
    if t.internal && r0 + out < 0.1 * p {
        return Err(DocError::Invalid("the hole is too small for this thread's runout".into()));
    }
    let (r_in, r_out) = (ease[0] / lead, ease[1] / lead);
    let mut law = Vec::new();
    if r_in > 0.0 {
        law.extend([(0.0, out), (r_in, 0.0)]);
    }
    if r_out > 0.0 {
        law.extend([(turns - r_out, 0.0), (turns, out)]);
    }
    if r_in > 0.0 && r_out > 0.0 && !(turns - r_out > r_in + 1e-9) || r_in.max(r_out) > turns {
        return Err(DocError::Invalid(format!("the runout ({} mm) is longer than the thread", show_mm(ease[0].max(ease[1])))));
    }
    if taper_rate != 0.0 {
        law = with_taper(&law, turns, taper_rate);
        if t.internal && law.iter().any(|(_, o)| r0 + o < 0.1 * p) {
            return Err(DocError::Invalid("the hole is too small for this taper thread".into()));
        }
    }
    let k = *t.axis;
    let u = k.cross(if k.x.abs() < 0.9 { Vec3::new(1.0, 0.0, 0.0) } else { Vec3::new(0.0, 1.0, 0.0) });
    let u = u.normalized().ok_or_else(|| DocError::Invalid("thread axis".into()))?;
    let base = t.axis_point + k * s0;
    let hands: &[f64] = match t.hand {
        ThreadHand::Right => &[1.0],
        ThreadHand::Left => &[-1.0],
        ThreadHand::Both => &[1.0, -1.0],
    };
    let n = t.starts.max(1);
    let mut grooves = Vec::new();
    for &h in hands {
        for j in 0..n {
            // Start j is the first turned a j-th of a turn on: the same helix a j-th of the
            // lead along.
            let a = std::f64::consts::TAU * f64::from(j) / f64::from(n);
            let x = u * a.cos() + k.cross(u) * a.sin();
            // A left-handed groove: turning the same way about the reversed axis while rising
            // along it (the screw motion about −k rising −lead per turn).
            let (axis, pitch) = if h > 0.0 { (k, lead) } else { (-k, -lead) };
            grooves.push(GrooveShape {
                plane: Plane { origin: base, x, y: k },
                section: section.clone(),
                base,
                axis,
                pitch,
                turns,
                law: law.clone(),
            });
        }
    }
    Ok(grooves)
}

/// A radial law (turn, offset) with a taper's `rate` mm per turn added: the law's own points and
/// both ends, each offset the law's (held past its first and last points) plus the taper's.
fn with_taper(law: &[(f64, f64)], turns: f64, rate: f64) -> Vec<(f64, f64)> {
    let at = |t: f64| -> f64 {
        match (law.first(), law.last()) {
            (Some(a), _) if t <= a.0 => a.1,
            (_, Some(b)) if t >= b.0 => b.1,
            _ => law
                .windows(2)
                .find_map(|w| match w {
                    [a, b] if t >= a.0 && t <= b.0 && b.0 > a.0 => Some(a.1 + (b.1 - a.1) * (t - a.0) / (b.0 - a.0)),
                    _ => None,
                })
                .unwrap_or(0.0),
        }
    };
    let mut ts: Vec<f64> = law.iter().map(|(t, _)| *t).chain([0.0, turns]).collect();
    ts.sort_by(f64::total_cmp);
    ts.dedup_by(|a, b| (*a - *b).abs() < 1e-12);
    ts.into_iter().map(|t| (t, at(t) + rate * t)).collect()
}

/// A taper thread's crests, as its die or tap cuts them: the ring of material outside its major
/// cone (external) or inside its minor cone (internal) along the thread, from a pitch past the
/// end it starts at (`from`, a free end; `d0` its major diameter there) to its other end (a pitch
/// past that too when it is free). None when the cone misses the material.
fn taper_envelope(t: &ThreadInfo, radius: f64, ends: [End; 2], (d0, from): (f64, usize)) -> Result<Option<Body>> {
    let p = t.pitch;
    let k = *t.axis;
    let u = k.cross(if k.x.abs() < 0.9 { Vec3::new(1.0, 0.0, 0.0) } else { Vec3::new(0.0, 1.0, 0.0) });
    let u = u.normalized().ok_or_else(|| DocError::Invalid("thread axis".into()))?;
    let (at, into) = if from == 0 { (t.start, k) } else { (t.end, -k) };
    let far = 1 - from.min(1);
    let len = t.end - t.start + if ends.get(far) == Some(&End::Free) { p } else { 0.0 };
    let e = p;
    // In the plane: x radial, y along the axis into the material from the start.
    let plane = Plane { origin: t.axis_point + k * at, x: u, y: into };
    let pts = if t.internal {
        // The minor cone shrinks into the hole: what lies inside it, down to well inside the hole.
        let minor0 = t.form.groove(d0, p, true).crest_r;
        let rm = |y: f64| minor0 - y / 32.0;
        if !(rm(-e) > radius) {
            return Ok(None);
        }
        let r_in = 0.5 * radius.min(rm(len));
        if !(r_in > 0.0) {
            return Err(DocError::Invalid("the hole is too small for this taper thread".into()));
        }
        vec![Vec2::new(r_in, -e), Vec2::new(rm(-e), -e), Vec2::new(rm(len), len), Vec2::new(r_in, len)]
    } else {
        // The major cone grows into the shaft: what lies outside it, out past the surface.
        let rc = |y: f64| d0 / 2.0 + y / 32.0;
        let r_out = radius + 0.1 * p;
        if !(rc(-e) < r_out) {
            return Ok(None);
        }
        let hit = (r_out - d0 / 2.0) * 32.0;
        if hit < len {
            vec![Vec2::new(rc(-e), -e), Vec2::new(r_out, hit), Vec2::new(r_out, -e)]
        } else {
            vec![Vec2::new(rc(-e), -e), Vec2::new(rc(len), len), Vec2::new(r_out, len), Vec2::new(r_out, -e)]
        }
    };
    let region = Region2 { outer: solidcore_record::Loop2::polygon(&pts), holes: Vec::new() };
    let mut ring = kernel::revolve(&plane, &[region], Vec2::new(0.0, 0.0), Vec2::new(0.0, 1.0), std::f64::consts::TAU)?;
    Ok(ring.pop())
}

/// The groove with what runs past a shoulder's plane taken off ([`End::Shoulder`]), so cutting it
/// leaves the shoulder whole.
fn trim_at_shoulders(mut tool: Body, axis: Vec3, ends: [End; 2], face: (f64, f64), k: UnitVec3) -> Result<Body> {
    for (end, at, keep_positive) in [(ends[0], face.0, true), (ends[1], face.1, false)] {
        if end != End::Shoulder {
            continue;
        }
        let plane = Plane::from_normal(axis + k * at, *k).ok_or_else(|| DocError::Invalid("thread axis".into()))?;
        // An error of the cut, like the kernel's own: `cut` then falls back to the square stop.
        let missed = || kernel::KernelError::Failed("the thread's groove misses its face".into());
        let kept = kernel::half_space(&tool, &plane, keep_positive)?.0;
        #[cfg(test)]
        let kept = kept.filter(|_| !tests::EMPTY_TRIM.get());
        tool = kept.ok_or_else(missed)?;
    }
    Ok(tool)
}

/// Evaluate a thread feature: a cosmetic thread is listed in the model's threads, a modelled
/// one cut into its body.
pub(super) fn eval(doc: &Document, vals: &BTreeMap<String, Value>, f: &Feature, st: &mut ModelState, warning: &mut Option<String>) -> Result<()> {
    let FeatureKind::Thread {
        face,
        designation,
        length,
        modeled,
        from,
        up_to,
        form,
        hand,
        starts,
        ease_out,
        tip,
        chamfer_angle,
        chamfer_depth,
        steep_flank,
        old_auto_size,
    } = &f.kind
    else {
        return Err(DocError::Invalid("not a thread".into()));
    };
    if *tip != ThreadTip::None && !*modeled {
        return Err(DocError::Invalid("a chamfered tip is cut only on a modelled thread".into()));
    }
    let extent = match (length, up_to) {
        (Some(e), _) => Extent::Length(val(vals, e, Kind::Length)?),
        (None, Some(crate::ThreadLimit::Face(q))) => Extent::UpToPoint(q.0),
        (None, Some(crate::ThreadLimit::Plane(pl))) => Extent::UpTo(doc.resolve_plane_in(vals, pl, 0, Some(st))?),
        (None, None) => Extent::Full,
    };
    // A form left at its default is the one the designation names (`Tr20x4`).
    let form = (*form != ThreadForm::Metric).then_some(*form);
    let ask = ThreadAsk {
        form,
        designation: designation.as_deref(),
        hand: *hand,
        starts: *starts,
        steep: *steep_flank,
        extent,
        from: from.map(|q| q.0),
        modeled: *modeled,
        ease_out: (0.0, 0.0),
        tapped: false,
        old_auto_size: *old_auto_size,
    };
    if ease_out.is_some() && !*modeled {
        return Err(DocError::Invalid("a runout is cut only on a modelled thread".into()));
    }
    let ask = ThreadAsk { ease_out: runout(vals, ease_out)?, ..ask };
    let on = thread_on(st, f.id, face.0, &ask)?;
    if !*modeled {
        st.threads.push(on.info);
        return Ok(());
    }
    let angle = chamfer_angle.as_deref().map(|e| val(vals, e, Kind::Angle)).transpose()?;
    let depth = chamfer_depth.as_deref().map(|e| val(vals, e, Kind::Length)).transpose()?;
    if let Some(r) = on.narrow {
        let note = format!(
            "narrowed the {} mm hole to {} mm (the {} thread's minor diameter) so the thread has material to cut into",
            show_mm(2.0 * on.cyl.radius),
            show_mm(2.0 * r),
            on.info.designation
        );
        *warning = Some(match warning.take() {
            Some(w) => format!("{w}; {note}"),
            None => note,
        });
    }
    if let Some(note) = cut(st, on, (*tip, angle, depth))? {
        *warning = Some(match warning.take() {
            Some(w) => format!("{w}; {note}"),
            None => note,
        });
    }
    Ok(())
}

/// A runout as (mm, pitches): ISO 3508's standard 2.5 P and short 1.25 P, or a length.
pub(super) fn runout(vals: &BTreeMap<String, Value>, e: &Option<crate::ThreadRunout>) -> Result<(f64, f64)> {
    Ok(match e {
        None => (0.0, 0.0),
        Some(crate::ThreadRunout::Standard) => (0.0, 2.5),
        Some(crate::ThreadRunout::Short) => (0.0, 1.25),
        Some(crate::ThreadRunout::Length { length }) => (val(vals, length, Kind::Length)?, 0.0),
    })
}

/// Cut a modelled thread resolved on its face into its body: the grooves (SMLib's exact screw
/// sweeps, a taper's crests by its envelope) by one B-rep boolean, then the chamfered tip
/// (`tip`, with its angle and depth when given). What the user should be told about the result, if
/// anything, is returned.
pub(super) fn cut(st: &mut ModelState, on: ThreadOn, (tip, angle, depth): (ThreadTip, Option<f64>, Option<f64>)) -> Result<Option<String>> {
    let ThreadOn { info: t, cyl, ends, steep, ease, from: from_side, narrow, shoulder_unchecked } = on;
    let i = st.bodies.iter().position(|b| b.name == t.body).ok_or_else(|| DocError::Invalid("threaded body".into()))?;
    let Some(mb) = st.bodies.get(i).cloned() else { return Err(DocError::Invalid("body".into())) };
    let (mut input, radius) = (mb.traced(), cyl.radius);
    // A hole wider than the thread needs is filled in to the thread's minor radius over the
    // threaded length first, so the groove has the wall to cut into.
    let mut groove_radius = radius;
    if let Some(r_min) = narrow {
        let (lo, hi) = ((t.start - ease[0]).max(cyl.start), (t.end + ease[1]).min(cyl.end));
        let k = *t.axis;
        let u = k.cross(if k.x.abs() < 0.9 { Vec3::new(1.0, 0.0, 0.0) } else { Vec3::new(0.0, 1.0, 0.0) });
        let u = u.normalized().ok_or_else(|| DocError::Invalid("thread axis".into()))?;
        let plane = Plane { origin: t.axis_point + k * lo, x: u, y: k };
        let r_out = radius + 0.1 * t.pitch;
        let pts = [Vec2::new(r_min, 0.0), Vec2::new(r_out, 0.0), Vec2::new(r_out, hi - lo), Vec2::new(r_min, hi - lo)];
        let region = Region2 { outer: solidcore_record::Loop2::polygon(&pts), holes: Vec::new() };
        let sleeve = kernel::revolve(&plane, &[region], Vec2::new(0.0, 0.0), Vec2::new(0.0, 1.0), std::f64::consts::TAU)?
            .pop()
            .ok_or_else(|| DocError::Invalid("the narrowed bore".into()))?;
        let faces = sleeve.face_count();
        let filled =
            kernel::boolean(&input.body, &sleeve, BoolOp::Union)?.ok_or_else(|| DocError::Invalid("narrowing the hole removed everything".into()))?;
        let unnamed = crate::lineage::Lineage::unnamed_faces(faces);
        let lineage = input.lineage.and_then(|l| crate::lineage::Lineage::step(&filled, &[&l, &unnamed]));
        input = Traced { body: filled, lineage };
        groove_radius = r_min;
    }
    // The exact grooves: SMLib's screw sweeps, cut by one B-rep boolean.
    // A taper thread starts at its free end at the major diameter its standard puts there: an
    // internal one's gauge (reference) plane at its face, an external one's that far in.
    let taper = match t.form.is_taper() {
        true => {
            let z = t.form.pipe_size(t.major_diameter).ok_or_else(|| DocError::Invalid(format!("no pipe size {}", t.designation)))?;
            Some((if t.internal { t.major_diameter } else { t.major_diameter - z.gauge / 16.0 }, from_side))
        }
        false => None,
    };
    let cut_grooves = |ends: [End; 2]| -> Result<(Option<Body>, usize)> {
        let mut grooves = Vec::new();
        for g in thread_grooves(&t, groove_radius, (cyl.start, cyl.end), ends, steep, ease, taper)? {
            let section = Region2 { outer: solidcore_record::Loop2::polygon(&g.section), holes: Vec::new() };
            grooves.push(kernel::sweep_helix_radial(&g.plane, &section, g.base, g.axis, g.pitch, g.turns, &g.law)?);
        }
        if let Some(taper) = taper
            && let Some(envelope) = taper_envelope(&t, radius, ends, taper)?
        {
            grooves.push(envelope);
        }
        let tool = match grooves.as_slice() {
            [one] => one.clone(),
            many => kernel::union_all(&many.iter().collect::<Vec<_>>())?,
        };
        let tool = trim_at_shoulders(tool, t.axis_point, ends, (cyl.start, cyl.end), t.axis)?;
        let cut = kernel::boolean(&input.body, &tool, BoolOp::Cut)?;
        // Now rather than at the feature's end, where it could only fail the feature.
        if ends.contains(&End::Shoulder)
            && let Some(body) = &cut
        {
            kernel::check_kept(body)?;
        }
        Ok((cut, tool.face_count()))
    };
    // A design that built with the square stop keeps building: where the kernel can't make the
    // trimmed cut, the groove stops clear of the shoulder as it did, and the feature says so.
    let mut made = cut_grooves(ends);
    let mut square_stop = shoulder_unchecked;
    if matches!(made, Err(DocError::Kernel(_))) && ends.contains(&End::Shoulder) {
        made = cut_grooves(ends.map(|e| if e == End::Shoulder { End::Closed } else { e }));
        square_stop = true;
    }
    let note = (square_stop && made.is_ok()).then(|| {
        format!(
            "the {} thread's groove could not be run down to the shoulder here, so it stops clear of it and its last turn is left uncut",
            t.designation
        )
    });
    let (nb, groove_faces) = made?;
    let nb = nb.ok_or_else(|| DocError::Invalid("the thread removed everything".into()))?;
    // The groove's faces have no role to name them by.
    let groove = crate::lineage::Lineage::unnamed_faces(groove_faces);
    let lineage = input.lineage.and_then(|l| crate::lineage::Lineage::step(&nb, &[&l, &groove]));
    let mut nb = Traced { body: nb, lineage };
    if tip != ThreadTip::None {
        for cone in tip_cones(&t, radius, ends, (tip, from_side), angle, depth, taper)? {
            let faces = cone.face_count();
            let cut = kernel::boolean(&nb.body, &cone, BoolOp::Cut)?.ok_or_else(|| DocError::Invalid("the chamfer removed everything".into()))?;
            let unnamed = crate::lineage::Lineage::unnamed_faces(faces);
            let lineage = nb.lineage.and_then(|l| crate::lineage::Lineage::step(&cut, &[&l, &unnamed]));
            nb = Traced { body: cut, lineage };
        }
    }
    if let Some(slot) = st.bodies.get_mut(i) {
        *slot = ModelBody::traced_new(mb.name, nb, mb.feature);
    }
    Ok(note)
}

/// The chamfered tip of an external thread (ISO 4753, chamfered end CH) at the free ends `tip`
/// names (`Start`: the end of the axis `from`, which must be free; `Both`: each free end):
/// the material outside a cone `angle` to the axis (default 45°) that reaches the diameter
/// d_f = d - 2 `depth` at the face's end, as a ring to cut after the groove, so the last teeth
/// taper into it. ISO 4753 bounds d_f by the external thread's minor diameter; the default is
/// that bound, d3 = d - 1.226869 P (ISO 724, the rounded root of the design profile). It lies
/// below the modelled basic root d1, so the cone crosses the root cylinder and leaves a whole
/// ring on the end; one ending on the root itself would pinch to nothing wherever the groove
/// reaches the end. ISO 4753 is for ISO metric threads: other forms give `depth`. A taper
/// thread's `taper` (its major diameter where it starts, the end it starts from) puts each end's
/// major diameter where the taper has it there, and `depth` is measured from that.
fn tip_cones(
    t: &ThreadInfo,
    radius: f64,
    ends: [End; 2],
    (tip, from): (ThreadTip, usize),
    angle: Option<f64>,
    depth: Option<f64>,
    taper: Option<(f64, usize)>,
) -> Result<Vec<Body>> {
    if t.internal {
        return Err(DocError::Invalid("a chamfered tip is for an external thread (ISO 4753); countersink the hole's entry instead".into()));
    }
    let g = t.form.groove(t.major_diameter, t.pitch, false);
    let a = angle.unwrap_or(std::f64::consts::FRAC_PI_4);
    if !(a > 1f64.to_radians() && a < 89f64.to_radians()) {
        return Err(DocError::Invalid("the chamfer's angle to the axis must be between 1° and 89°".into()));
    }
    // The major diameter at each end of the axis: a taper's grows 1 in 16 from where it starts.
    let major = |side: usize| match taper {
        Some((d0, start)) if side == start => d0,
        Some((d0, _)) => d0 + (t.end - t.start) / 16.0,
        None => t.major_diameter,
    };
    let depth = match (depth, t.form) {
        (Some(d), _) => d,
        // ISO 724: d3 = d1 - H/6 = d - 2 (17/24) H.
        (None, ThreadForm::Metric) => 17.0 / 24.0 * t.pitch * 3f64.sqrt() / 2.0,
        (None, form) => {
            return Err(DocError::Invalid(format!(
                "ISO 4753's chamfered end is for ISO metric threads: give a {} thread its chamfer depth (its root is {} mm deep)",
                form.name(),
                show_mm(t.major_diameter / 2.0 - g.root_r)
            )));
        }
    };
    let smallest = major(0).min(major(1)) / 2.0;
    if !(depth > 0.0 && smallest - depth > 1e-3) {
        return Err(DocError::Invalid(format!("the chamfer's depth must be between 0 and {} mm", show_mm(smallest))));
    }
    let k = *t.axis;
    let u = k.cross(if k.x.abs() < 0.9 { Vec3::new(1.0, 0.0, 0.0) } else { Vec3::new(0.0, 1.0, 0.0) });
    let u = u.normalized().ok_or_else(|| DocError::Invalid("thread axis".into()))?;
    let slope = a.tan();
    // Past the end only the radii the groove's overrun already reaches (r >= d_f / 2), so
    // nothing past a free end beyond the thread is touched.
    let e = 0.5 * t.pitch;
    let mut out = Vec::new();
    let free = |side: usize| ends.get(side) == Some(&End::Free);
    if tip == ThreadTip::Start && !free(from) {
        return Err(DocError::Invalid("the end the thread starts from is not a free end (material goes on past it, or the thread stops inside the face): chamfer it with `tip: both`, or start the thread from its free end".into()));
    }
    for (side, at, out_dir) in [(0usize, t.start, -k), (1, t.end, k)] {
        if !free(side) || (tip == ThreadTip::Start && side != from) {
            continue;
        }
        let r_f = major(side) / 2.0 - depth;
        let r_out = radius.max(major(side) / 2.0) + 0.1 * t.pitch;
        // In the plane: x radial, y outward along the axis from the end.
        let plane = Plane { origin: t.axis_point + k * at, x: u, y: out_dir };
        let pts = [Vec2::new(r_f, 0.0), Vec2::new(r_f, e), Vec2::new(r_out, e), Vec2::new(r_out, -(r_out - r_f) / slope)];
        let region = Region2 { outer: solidcore_record::Loop2::polygon(&pts), holes: Vec::new() };
        let mut ring = kernel::revolve(&plane, &[region], Vec2::new(0.0, 0.0), Vec2::new(0.0, 1.0), std::f64::consts::TAU)?;
        out.push(ring.pop().ok_or_else(|| DocError::Invalid("chamfer".into()))?);
    }
    if out.is_empty() {
        return Err(DocError::Invalid("a chamfered tip needs a free end of the thread (one with no material past it)".into()));
    }
    Ok(out)
}

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

    thread_local! {
        /// Make [`trim_at_shoulders`] find nothing of the groove left.
        pub(super) static EMPTY_TRIM: Cell<bool> = const { Cell::new(false) };
        /// Make the rising-shoulder check fail as the kernel would.
        pub(super) static FAIL_CLEARANCE: Cell<bool> = const { Cell::new(false) };
    }

    fn ask() -> ThreadAsk<'static> {
        ThreadAsk {
            form: None,
            designation: Some("M10"),
            hand: ThreadHand::Right,
            starts: 1,
            steep: SteepFlank::default(),
            extent: Extent::Full,
            from: None,
            modeled: true,
            ease_out: (0.0, 0.0),
            tapped: false,
            old_auto_size: false,
        }
    }

    /// How a thread's ends meet the face at (5, 0, z) of `body`.
    fn ends_of(body: Body, z: f64) -> [End; 2] {
        let mut st = ModelState::default();
        st.bodies.push(ModelBody::new("Part".into(), body, 1));
        thread_on(&st, 1, Vec3::new(5.0, 0.0, z), &ask()).unwrap().ends
    }

    /// A shoulder that stays beyond the face's end takes the trim. One rising back along the face
    /// (a slanted plate, a boss on a round body) keeps the square stop.
    #[test]
    fn only_a_shoulder_that_stays_beyond_the_faces_end_takes_the_trim() {
        let z = Vec3::new(0.0, 0.0, 1.0);
        let join = |a: &Body, b: &Body| kernel::boolean(a, b, BoolOp::Union).unwrap().unwrap();
        let boss = kernel::cylinder(Vec3::new(0.0, 0.0, 2.0), z, 5.0, 26.0).unwrap();
        let plate = kernel::box_solid(Vec3::new(-20.0, -20.0, -6.0), Vec3::new(20.0, 20.0, 2.0)).unwrap();
        let flat = ends_of(join(&plate, &boss), 20.0);
        assert!(flat.contains(&End::Shoulder), "{flat:?}");
        let tilted = kernel::cylinder(Vec3::new(0.0, 0.0, 0.0), Vec3::new(0.2, 0.0, 1.0), 20.0, 6.0).unwrap();
        let slanted = ends_of(join(&tilted, &boss), 20.0);
        assert!(slanted.contains(&End::Closed) && !slanted.contains(&End::Shoulder), "{slanted:?}");
        let round = kernel::cylinder(Vec3::new(0.0, -20.0, 0.0), Vec3::new(0.0, 1.0, 0.0), 10.0, 40.0).unwrap();
        let on_round = ends_of(join(&round, &boss), 20.0);
        assert!(on_round.contains(&End::Closed) && !on_round.contains(&End::Shoulder), "{on_round:?}");
    }

    /// Where the kernel can't check the shoulder, the thread still builds with the square stop, and
    /// the feature says its last turn is left uncut.
    #[test]
    fn a_shoulder_the_kernel_cannot_check_keeps_the_square_stop_and_says_so() {
        let plate = kernel::box_solid(Vec3::new(-20.0, -20.0, 0.0), Vec3::new(20.0, 20.0, 6.0)).unwrap();
        let boss = kernel::cylinder(Vec3::new(0.0, 0.0, 6.0), Vec3::new(0.0, 0.0, 1.0), 5.0, 16.0).unwrap();
        let body = kernel::boolean(&plate, &boss, BoolOp::Union).unwrap().unwrap();
        let mut st = ModelState::default();
        st.bodies.push(ModelBody::new("Part".into(), body, 1));
        FAIL_CLEARANCE.set(true);
        let on = thread_on(&st, 1, Vec3::new(5.0, 0.0, 14.0), &ask());
        FAIL_CLEARANCE.set(false);
        let on = on.unwrap();
        assert!(on.ends.contains(&End::Closed) && !on.ends.contains(&End::Shoulder), "{:?}", on.ends);
        let note = cut(&mut st, on, (ThreadTip::None, None, None)).unwrap();
        assert!(note.is_some_and(|n| n.contains("M10") && n.contains("left uncut")));
    }

    /// Where the trim leaves nothing of the groove, a thread at a shoulder that built with the
    /// square stop still builds with it, and the feature says its last turn is left uncut.
    #[test]
    fn a_shoulder_cut_the_kernel_refuses_falls_back_to_the_square_stop_and_says_so() {
        let plate = kernel::box_solid(Vec3::new(-20.0, -20.0, 0.0), Vec3::new(20.0, 20.0, 6.0)).unwrap();
        let boss = kernel::cylinder(Vec3::new(0.0, 0.0, 6.0), Vec3::new(0.0, 0.0, 1.0), 5.0, 16.0).unwrap();
        let body = kernel::boolean(&plate, &boss, BoolOp::Union).unwrap().unwrap();
        let build = |fail: bool| {
            let mut st = ModelState::default();
            st.bodies.push(ModelBody::new("Part".into(), body.clone(), 1));
            let on = thread_on(&st, 1, Vec3::new(5.0, 0.0, 14.0), &ask()).unwrap();
            EMPTY_TRIM.set(fail);
            let note = cut(&mut st, on, (ThreadTip::None, None, None));
            EMPTY_TRIM.set(false);
            (note.unwrap(), kernel::measure(&st.bodies[0].body).unwrap().volume)
        };
        let (none, trimmed) = build(false);
        assert_eq!(none, None);
        let (note, square) = build(true);
        assert!(note.is_some_and(|n| n.contains("M10") && n.contains("left uncut")));
        // The square stop leaves about half a pitch's worth of groove uncut: well over a mm³.
        assert!(square > trimmed + 1.0, "{square} vs {trimmed}");
    }

    /// A modelled thread on one hole leaves the other hole's wall a cylinder to thread: the
    /// second hole still takes its thread (#11367).
    ///
    /// The modelled thread cuts the body, and the cut must not take the body's other cylinders
    /// with it: the second hole's wall is still a cylinder, so it still takes a thread, modelled
    /// or cosmetic.
    #[test]
    fn a_modelled_thread_leaves_the_next_hole_a_cylinder_to_thread() {
        // An 80 x 80 x 20 mm block with two 5 mm holes.
        let block = kernel::box_solid(Vec3::new(-40.0, -40.0, 0.0), Vec3::new(40.0, 40.0, 20.0)).unwrap();
        let hole = |x: f64| kernel::cylinder(Vec3::new(x, 0.0, -1.0), Vec3::new(0.0, 0.0, 1.0), 2.5, 22.0).unwrap();
        let mut body = kernel::boolean(&block, &hole(-20.0), BoolOp::Cut).unwrap().unwrap();
        body = kernel::boolean(&body, &hole(20.0), BoolOp::Cut).unwrap().unwrap();
        let mut st = ModelState::default();
        st.bodies.push(ModelBody::new("Part".into(), body, 1));
        let ask = ThreadAsk { designation: Some("M6"), ..ask() };
        // The first hole takes a modelled M6 thread.
        let on = thread_on(&st, 1, Vec3::new(-17.5, 0.0, 10.0), &ask).unwrap();
        cut(&mut st, on, (ThreadTip::None, None, None)).unwrap();
        // The second hole's wall is still a cylinder: it takes a thread too.
        let on = thread_on(&st, 1, Vec3::new(22.5, 0.0, 10.0), &ask);
        assert!(on.is_ok(), "the second hole still has a cylinder to thread: {:?}", on.err());
        // And a modelled one cuts there as well.
        let on = thread_on(&st, 1, Vec3::new(22.5, 0.0, 10.0), &ask).unwrap();
        assert!(cut(&mut st, on, (ThreadTip::None, None, None)).is_ok());
    }
}