ogeom_io/step/

read.rs

//! From parsed exchange structure to a living model.
//!
//! The reader walks every `MANIFOLD_SOLID_BREP` (`BREP_WITH_VOIDS` is one,
//! by subtype) and every `SHELL_BASED_SURFACE_MODEL`, and rebuilds them
//! bottom-up:
//! points, placements, curves and surfaces into geometry; vertices, edges,
//! loops, faces and shells into topology, shared exactly as the file shares
//! them: a vertex referenced by eight edges is one vertex here too, which is
//! what lets a closed shell close. Edge ranges are re-derived on this
//! kernel's own parameterizations from the vertex geometry, because STEP's
//! parameterizations are its own business and carrying them over blind is
//! how off-by-a-period bugs are born.
//!
//! What the reader does not understand it *counts*: every instance never
//! visited lands in the report's skipped table by keyword, and every
//! compromise (a face without a pcurve, a shell that does not close) is a
//! warning with the instance number in it. An import that succeeded with
//! three warnings is a different thing from one that succeeded, and the
//! report is what keeps the difference visible.

use super::parse::{Arg, Exchange, Instance};
use ogeom_algo::{
    make_edge_between, make_face_on, make_shell, make_solid, make_vertex, make_wire,
    project_on_curve,
};
use ogeom_core::{OgeomResult, Tolerances, ogeom_bail};
use ogeom_geom::Curve2d as _;
use ogeom_geom::Curve3d as _;
use ogeom_geom::Surface as _;
use ogeom_geom::Transformable as _;
use ogeom_geom::{
    BSplineCurve, CircleCurve, ConeSurface, Curve, CylinderSurface, EllipseCurve, ExtrusionSurface,
    HyperbolaCurve, LineCurve, ParabolaCurve, PlanarCurve, PlaneSurface, SphereSurface,
    SurfaceGeometry, TorusSurface,
};
use ogeom_math::{
    Axis, Blend as _, Circle, Cone, Cylinder, Direction, Ellipse, Frame, Hyperbola, KnotVector,
    Matrix3, Parabola, Plane, Point, Sphere, Torus, Transform, Vector, Weighted,
};
use ogeom_topo::{Location, Model, Shape};
use std::collections::{BTreeMap, HashMap, HashSet};

/// One use a bound makes of an edge: the edge as the loop walks it, the edge
/// as it was built, the file's id for it, and the curve and range it carries.
type BoundUse = (Shape, Shape, u64, Curve, (f64, f64));

/// How a point of space reads on a surface's unbounded directions, `None`
/// where the direction has none to read.
type ChartReading = dyn Fn(Point) -> (Option<f64>, Option<f64>);

/// How far a plane or a cylinder read from a file extends past what anything
/// in the file uses. A face's trim is its wires; the surface's domain is only
/// the parameter window, and this one is generous without being unbounded.
const SURFACE_EXTENT: f64 = 1e5;

/// What an import brought in, and what it left behind.
#[derive(Debug, Default)]
pub struct StepReport {
    /// Millimetres per file unit, as the file's own unit section states it.
    pub scale_mm: f64,
    /// Instance keywords the reader never visited, with counts. Presentation,
    /// product structure and annotation live here by design; geometry landing
    /// here is a gap worth reading about.
    pub skipped: BTreeMap<String, usize>,
    /// Everything that imported less than perfectly, one line each.
    pub warnings: Vec<String>,
    /// The warning flood, counted: one entry per *kind* of imperfection,
    /// with how often it happened, the worst measured value where the kind
    /// measures one, and one exemplar entity id. A 776-warning community
    /// file summarises to a handful of lines a consumer can actually show;
    /// `warnings` keeps the full prose. Sorted by count, largest first.
    pub summary: Vec<WarningSummary>,
    /// Faces that read without a complete trim: an edge's boundary sat too
    /// far from the surface for any honest pcurve (beyond the one-millimetre
    /// healing cap), so the face will refuse to triangulate. Deduplicated,
    /// in file order: the structured form of the warnings that name them,
    /// carrying the face itself so the instructed follow-up needs no search.
    /// `check` reports the same faces as broken from the model side. A
    /// refused id whose face never finished building has nothing to act on
    /// and stays in the warnings alone.
    pub untrimmed_faces: Vec<UntrimmedFace>,
}

/// One kind of imperfect import, counted rather than repeated.
#[derive(Debug, Clone)]
pub struct WarningSummary {
    /// The kind, stable across runs: `"vertex-miss"`, `"boundary-slop"`,
    /// `"fit-short"`, `"untrimmed"`.
    pub kind: &'static str,
    /// How many times it happened.
    pub count: usize,
    /// The worst measured value among them: a distance, for every kind
    /// that measures one; zero where none applies.
    pub worst: f64,
    /// One entity id to look at first.
    pub exemplar: u64,
}

/// A face the reader could not trim, with the shape to act on.
#[derive(Debug, Clone)]
pub struct UntrimmedFace {
    /// The file's id for the face: the same id the warnings name.
    pub entity: u64,
    /// The face as built; hand it to `ogeom_heal::fix_face_pcurves` with
    /// the cap the situation deserves.
    pub face: Shape,
}

/// A read exchange file: the model, the bodies found, and the report.
#[derive(Debug)]
pub struct StepImport {
    /// The document everything was built into: the model, plus the file's
    /// product structure, names and colours.
    pub document: ogeom_doc::Document,
    /// One shape per `MANIFOLD_SOLID_BREP` (`BREP_WITH_VOIDS` included,
    /// its cavities among its shells), in file order.
    pub solids: Vec<Shape>,
    /// One shape per `SHELL_BASED_SURFACE_MODEL`, in file order: its shell,
    /// or a compound of its shells when it names several.
    ///
    /// A surface body is what a modeller exports for a part built from faces
    /// rather than from a solid. It stays a shell here even when it happens
    /// to close: the file did not call it a solid, and the document carries
    /// it under its product exactly as the file placed it.
    pub shells: Vec<Shape>,
    /// What happened along the way.
    pub report: StepReport,
}

/// Read a STEP exchange file's B-rep content.
///
/// # Errors
///
/// [`OgeomError::Construction`](ogeom_core::OgeomError::Construction) if the file does
/// not parse, contains no solid, or a solid's structure is broken in a way
/// topology cannot represent. Faces the reader cannot complete become
/// warnings, not errors; the report says exactly what was compromised.
pub fn read_step(text: &str, tol: Tolerances) -> OgeomResult<StepImport> {
    let exchange = super::parse::parse(text)?;
    let mut reader = Reader {
        exchange: &exchange,
        model: Model::new(),
        report: StepReport {
            scale_mm: 1.0,
            ..StepReport::default()
        },
        angle_scale: 1.0,
        visited: {
            let top = exchange.data.keys().max().copied().unwrap_or(0);
            let top = usize::try_from(top).unwrap_or(usize::MAX - 1);
            vec![false; top + 1]
        },
        vertices: HashMap::new(),
        edges: HashMap::new(),
        faces: HashMap::new(),
        callout_index: HashMap::new(),
        pcurves: HashMap::new(),
        untrimmed_ids: Vec::new(),
        tallies: HashMap::new(),
        cdsr_of_nauo: None,
        properties_of_definition: None,
        sdrs_of_property: None,
        tol,
    };
    reader.report.scale_mm = reader.unit_scale();
    reader.angle_scale = reader.angle_unit_scale();

    let mut solids = Vec::new();
    let mut shells = Vec::new();
    let mut by_item: HashMap<u64, Shape> = HashMap::new();
    // Solids and surface models, one walk in file order; a body is a body
    // to the progress bar whichever kind it is.
    let mut ids: Vec<(u64, bool)> = exchange
        .data
        .iter()
        .filter_map(|(id, inst)| {
            if inst.part("MANIFOLD_SOLID_BREP").is_some() || inst.part("BREP_WITH_VOIDS").is_some()
            {
                Some((*id, true))
            } else if inst.part("SHELL_BASED_SURFACE_MODEL").is_some() {
                Some((*id, false))
            } else {
                None
            }
        })
        .collect();
    ids.sort_unstable();
    let total = ids.len() as u64;
    for (done, (id, is_solid)) in ids.into_iter().enumerate() {
        ogeom_core::progress::checkpoint()?;
        ogeom_core::progress::stage_at("step: solid", done as u64 + 1, total);
        if is_solid {
            let solid = reader.solid(id)?;
            by_item.insert(id, solid.clone());
            solids.push(solid);
        } else {
            let shell = reader.surface_model(id)?;
            by_item.insert(id, shell.clone());
            shells.push(shell);
        }
    }
    // Every widening the reader made (an edge's tolerance recording how far
    // its pcurves sit from its curve) reaches the vertices that bound it,
    // and a face's reaches its edges: the containment rule the checker holds
    // a solid to, kept by the reader that built it.
    for body in solids.iter().chain(shells.iter()) {
        ogeom_algo::restore_containment(&mut reader.model, body)?;
    }
    // The tallies fold into the summary, largest first, ties by kind so the
    // order is the file's and not the map's.
    {
        let mut entries: Vec<WarningSummary> = reader
            .tallies
            .drain()
            .map(|(kind, (count, worst, exemplar))| WarningSummary {
                kind,
                count,
                worst,
                exemplar,
            })
            .collect();
        entries.sort_by(|a, b| b.count.cmp(&a.count).then(a.kind.cmp(b.kind)));
        reader.report.summary = entries;
    }
    // The noted refusals resolve to the faces themselves, now that they
    // exist: the same cache the shells were assembled from answers by the
    // very id the warnings name.
    for id in std::mem::take(&mut reader.untrimmed_ids) {
        if let Some(face) = reader.faces.get(&id) {
            reader.report.untrimmed_faces.push(UntrimmedFace {
                entity: id,
                face: face.clone(),
            });
        }
    }
    if solids.is_empty() && shells.is_empty() {
        ogeom_bail!(
            Construction,
            "the exchange file contains no MANIFOLD_SOLID_BREP, \
             BREP_WITH_VOIDS or SHELL_BASED_SURFACE_MODEL to read"
        );
    }
    let document = reader.document(&by_item, &solids, &shells)?;

    // Everything never visited, counted by its leading keyword.
    for (id, instance) in &exchange.data {
        if !usize::try_from(*id)
            .ok()
            .and_then(|i| reader.visited.get(i).copied())
            .unwrap_or(false)
        {
            *reader
                .report
                .skipped
                .entry(instance.keyword().to_owned())
                .or_default() += 1;
        }
    }

    Ok(StepImport {
        document,
        solids,
        shells,
        report: reader.report,
    })
}

/// An edge as built: the shape, its curve and range, and whether STEP's edge
/// direction runs against the curve.
type BuiltEdge = (Shape, Curve, (f64, f64), bool);

/// A pcurve derived ahead of the face that needs it.
///
/// Deriving one is a pure function of a curve, its range and a surface (no
/// model, no order), and on a real assembly it is 95% of the time spent
/// building solids. So it is done for a whole solid at once, off the walk
/// that attaches it.
enum PreparedPcurve {
    /// The projection had a closed form.
    Exact(PlanarCurve),
    /// It did not, and this is the fit, with what the fit cost.
    Fitted {
        curve: PlanarCurve,
        error: f64,
        met: bool,
        worst_off: f64,
        warning: Option<String>,
    },
    /// Neither worked; the face gets the warning the walk would have made.
    Refused(String),
}

struct Reader<'a> {
    exchange: &'a Exchange,
    model: Model,
    report: StepReport,
    /// Radians per file angle unit; degrees are common.
    angle_scale: f64,
    /// One slot per possible instance id: the reader touches instances
    /// millions of times, and a direct index beats hashing every touch.
    visited: Vec<bool>,
    vertices: HashMap<u64, Shape>,
    edges: HashMap<u64, BuiltEdge>,
    faces: HashMap<u64, Shape>,
    /// STEP id → index into the callouts just built, for the views pass.
    callout_index: HashMap<u64, usize>,
    /// `(face, edge)` → the pcurve already derived for it, from the parallel
    /// pass at the head of each solid.
    pcurves: HashMap<(u64, u64), PreparedPcurve>,
    /// Faces noted untrimmed, by file id; resolved to shapes once the read
    /// is far enough along for the shapes to exist.
    untrimmed_ids: Vec<u64>,
    /// kind → (count, worst, exemplar), folded into the report's summary.
    tallies: HashMap<&'static str, (usize, f64, u64)>,
    /// Usage → its `CONTEXT_DEPENDENT_SHAPE_REPRESENTATION`, built once.
    /// The lookup used to rescan the whole exchange per assembly edge:
    /// O(usages × entities), 333 × 457 k on one reporting assembly, which
    /// was three quarters of the entire document build.
    cdsr_of_nauo: Option<HashMap<u64, u64>>,
    /// Definition → its `PROPERTY_DEFINITION`s, and property → its
    /// `SHAPE_DEFINITION_REPRESENTATION`s, built together once. The datum
    /// target lookup used to rescan the whole exchange per property *per
    /// target*: the same quadratic shape the assembly index retired, one
    /// storey deeper. Each list ascends by id, so whichever entry answers
    /// is the one the old scan would have reached first.
    properties_of_definition: Option<HashMap<u64, Vec<u64>>>,
    sdrs_of_property: Option<HashMap<u64, Vec<u64>>>,
    tol: Tolerances,
}

impl Reader<'_> {
    fn instance(&mut self, id: u64) -> OgeomResult<&'_ Instance> {
        if let Ok(i) = usize::try_from(id)
            && let Some(slot) = self.visited.get_mut(i)
        {
            *slot = true;
        }
        self.exchange.data.get(&id).ok_or_else(|| {
            ogeom_core::ogeom_err!(
                Construction,
                "the file references #{id}, which does not exist"
            )
        })
    }

    /// A face's arguments (name, bounds, surface, sense), whether the file
    /// wrote it as the `ADVANCED_FACE` every modern writer uses or as the
    /// plain `FACE_SURFACE` it specialises, which carries the same four.
    fn face_args(&mut self, id: u64) -> OgeomResult<Vec<Arg>> {
        let instance = self.instance(id)?;
        if let Some(args) = instance
            .part("ADVANCED_FACE")
            .or_else(|| instance.part("FACE_SURFACE"))
        {
            return Ok(args.to_vec());
        }
        ogeom_bail!(
            Construction,
            "#{id} is {}, where a face (ADVANCED_FACE or FACE_SURFACE) was needed",
            instance.keyword()
        );
    }

    fn args(&mut self, id: u64, keyword: &str) -> OgeomResult<Vec<Arg>> {
        let instance = self.instance(id)?;
        let Some(args) = instance.part(keyword) else {
            ogeom_bail!(
                Construction,
                "#{id} is {}, where {keyword} was needed",
                instance.keyword()
            );
        };
        Ok(args.to_vec())
    }

    // --- units ---------------------------------------------------------------

    /// The unit instances the representation context actually assigns.
    ///
    /// A file may carry both a radian and a degree (definition and
    /// conversion), and which applies is not a matter of existence but of
    /// assignment: `GLOBAL_UNIT_ASSIGNED_CONTEXT` lists the ones in force.
    fn assigned_units(&self) -> Vec<u64> {
        // A file may carry several unit contexts (inches for the model,
        // millimetres for its annotation sheet), and the shapes' own
        // representations name the one their coordinates mean. That context
        // goes first; the rest follow in entity order, so the answer never
        // depends on how a map happens to iterate.
        let mut cited: Vec<u64> = self
            .exchange
            .data
            .values()
            .filter(|inst| {
                inst.parts
                    .iter()
                    .any(|(k, _)| k.ends_with("SHAPE_REPRESENTATION"))
            })
            .filter_map(|inst| {
                inst.parts
                    .iter()
                    .find(|(k, _)| k.ends_with("SHAPE_REPRESENTATION"))
                    .and_then(|(_, args)| args.last())
                    .and_then(Arg::reference)
            })
            .collect();
        cited.sort_unstable();
        cited.dedup();

        let mut contexts: Vec<u64> = self
            .exchange
            .data
            .iter()
            .filter(|(_, inst)| inst.part("GLOBAL_UNIT_ASSIGNED_CONTEXT").is_some())
            .map(|(id, _)| *id)
            .collect();
        contexts.sort_unstable();
        contexts.sort_by_cached_key(|id| !cited.contains(id));

        let mut out = Vec::new();
        for id in contexts {
            if let Some(instance) = self.exchange.data.get(&id)
                && let Some(args) = instance.part("GLOBAL_UNIT_ASSIGNED_CONTEXT")
            {
                for arg in args.iter().filter_map(Arg::list).flatten() {
                    if let Some(r) = arg.reference() {
                        out.push(r);
                    }
                }
            }
        }
        out
    }

    /// Millimetres per file length unit, from the units the context assigns.
    fn unit_scale(&mut self) -> f64 {
        let assigned = self.assigned_units();
        for id in assigned {
            let Some(instance) = self.exchange.data.get(&id) else {
                continue;
            };
            let instance = instance.clone();
            if instance.part("LENGTH_UNIT").is_none() {
                continue;
            }
            if let Some(args) = instance.part("SI_UNIT") {
                return match args.first() {
                    Some(Arg::Enum(prefix)) => match prefix.as_str() {
                        "MILLI" => 1.0,
                        "CENTI" => 10.0,
                        "DECI" => 100.0,
                        "KILO" => 1e6,
                        "MICRO" => 1e-3,
                        other => {
                            self.report
                                .warnings
                                .push(format!("#{id}: unknown SI prefix {other}; taking metres"));
                            1000.0
                        }
                    },
                    _ => 1000.0,
                };
            }
            if let Some(args) = instance.part("CONVERSION_BASED_UNIT")
                && let Some(measure) = args.get(1).and_then(Arg::reference)
                && let Some(inner) = self.exchange.data.get(&measure)
            {
                let factor = inner
                    .parts
                    .iter()
                    .flat_map(|(_, a)| a.iter())
                    .find_map(|a| match a {
                        Arg::Typed(k, v) if k == "LENGTH_MEASURE" => {
                            v.first().and_then(Arg::number)
                        }
                        _ => None,
                    });
                let base = inner
                    .parts
                    .iter()
                    .flat_map(|(_, a)| a.iter())
                    .find_map(Arg::reference)
                    .and_then(|b| self.exchange.data.get(&b))
                    .and_then(|u| u.part("SI_UNIT"))
                    .map_or(1000.0, |args| match args.first() {
                        Some(Arg::Enum(p)) if p == "MILLI" => 1.0,
                        Some(Arg::Enum(p)) if p == "CENTI" => 10.0,
                        _ => 1000.0,
                    });
                if let Some(f) = factor {
                    return f * base;
                }
            }
        }
        self.report
            .warnings
            .push("no length unit found; taking millimetres".to_owned());
        1.0
    }

    /// Radians per file angle unit: the same dance as length, for the files
    /// that measure their cones in degrees.
    fn angle_unit_scale(&mut self) -> f64 {
        let assigned = self.assigned_units();
        for id in assigned {
            let Some(instance) = self.exchange.data.get(&id) else {
                continue;
            };
            let instance = instance.clone();
            if instance.part("PLANE_ANGLE_UNIT").is_none() {
                continue;
            }
            if instance.part("SI_UNIT").is_some() {
                return 1.0;
            }
            if let Some(args) = instance.part("CONVERSION_BASED_UNIT")
                && let Some(measure) = args.get(1).and_then(Arg::reference)
                && let Some(inner) = self.exchange.data.get(&measure)
            {
                let factor = inner
                    .parts
                    .iter()
                    .flat_map(|(_, a)| a.iter())
                    .find_map(|a| match a {
                        Arg::Typed(k, v) if k == "PLANE_ANGLE_MEASURE" => {
                            v.first().and_then(Arg::number)
                        }
                        _ => None,
                    });
                if let Some(f) = factor {
                    return f;
                }
            }
        }
        1.0
    }

    // --- geometry ------------------------------------------------------------

    fn point(&mut self, id: u64) -> OgeomResult<Point> {
        let args = self.args(id, "CARTESIAN_POINT")?;
        let Some(coords) = args.get(1).and_then(Arg::list) else {
            ogeom_bail!(Construction, "#{id}: a point without coordinates");
        };
        let scale = self.report.scale_mm;
        let value = |i: usize| coords.get(i).and_then(Arg::number).unwrap_or(0.0) * scale;
        Ok(Point::new(value(0), value(1), value(2)))
    }

    fn direction(&mut self, id: u64) -> OgeomResult<Direction> {
        let args = self.args(id, "DIRECTION")?;
        let Some(coords) = args.get(1).and_then(Arg::list) else {
            ogeom_bail!(Construction, "#{id}: a direction without components");
        };
        let value = |i: usize| coords.get(i).and_then(Arg::number).unwrap_or(0.0);
        Direction::new(Vector::new(value(0), value(1), value(2)), self.tol)
    }

    /// An `AXIS2_PLACEMENT_3D` as a frame, with the standard's defaults for
    /// what the file leaves out.
    fn frame(&mut self, id: u64) -> OgeomResult<Frame> {
        let args = self.args(id, "AXIS2_PLACEMENT_3D")?;
        let origin = args
            .get(1)
            .and_then(Arg::reference)
            .map(|r| self.point(r))
            .transpose()?
            .unwrap_or(Point::ORIGIN);
        let z = args
            .get(2)
            .and_then(Arg::reference)
            .map(|r| self.direction(r))
            .transpose()?
            .unwrap_or(Direction::Z);
        let x = match args.get(3).and_then(Arg::reference) {
            Some(r) => self.direction(r)?,
            None => Direction::from_cross(z.vector(), Vector::new(0.31, 0.52, 0.8), self.tol)?,
        };
        Frame::new(origin, z, x, self.tol)
    }

    fn surface(&mut self, id: u64) -> OgeomResult<Option<SurfaceGeometry>> {
        let (keyword, args) = {
            let instance = self.instance(id)?;
            (
                instance.keyword().to_owned(),
                instance
                    .parts
                    .first()
                    .map(|(_, a)| a.clone())
                    .unwrap_or_default(),
            )
        };
        let scale = self.report.scale_mm;
        let radius_arg = |args: &[Arg], i: usize| args.get(i).and_then(Arg::number);
        // B-spline surfaces arrive two ways: a simple instance with every
        // attribute in one list, or a complex instance whose parts each
        // carry their own slice, the rational form always the latter.
        {
            let (base, knots_part, weights) = {
                let instance = self.instance(id)?;
                (
                    instance.part("B_SPLINE_SURFACE").map(<[Arg]>::to_vec),
                    instance
                        .part("B_SPLINE_SURFACE_WITH_KNOTS")
                        .map(<[Arg]>::to_vec),
                    instance
                        .part("RATIONAL_B_SPLINE_SURFACE")
                        .map(<[Arg]>::to_vec),
                )
            };
            if let Some(kp) = knots_part {
                let (degrees, grid_arg, mults_knots) = if let Some(base) = base {
                    (
                        (base.first().cloned(), base.get(1).cloned()),
                        base.get(2).cloned(),
                        (
                            kp.first().cloned(),
                            kp.get(1).cloned(),
                            kp.get(2).cloned(),
                            kp.get(3).cloned(),
                        ),
                    )
                } else {
                    (
                        (kp.get(1).cloned(), kp.get(2).cloned()),
                        kp.get(3).cloned(),
                        (
                            kp.get(8).cloned(),
                            kp.get(9).cloned(),
                            kp.get(10).cloned(),
                            kp.get(11).cloned(),
                        ),
                    )
                };
                return self
                    .bspline_surface(id, degrees, grid_arg, mults_knots, weights, None)
                    .map(Some);
            }
        }
        // A complex instance whose knots are implied by its form, or a
        // simple one of those forms.
        {
            let (base, weights, form) = {
                let instance = self.instance(id)?;
                (
                    instance.part("B_SPLINE_SURFACE").map(<[Arg]>::to_vec),
                    instance
                        .part("RATIONAL_B_SPLINE_SURFACE")
                        .map(<[Arg]>::to_vec),
                    ["BEZIER_SURFACE", "UNIFORM_SURFACE", "QUASI_UNIFORM_SURFACE"]
                        .into_iter()
                        .find(|k| instance.part(k).is_some()),
                )
            };
            if let (Some(base), Some(form)) = (base, form) {
                return self
                    .bspline_surface(
                        id,
                        (base.first().cloned(), base.get(1).cloned()),
                        base.get(2).cloned(),
                        (None, None, None, None),
                        weights,
                        Some(form),
                    )
                    .map(Some);
            }
            if let Some(form) = ["BEZIER_SURFACE", "UNIFORM_SURFACE", "QUASI_UNIFORM_SURFACE"]
                .into_iter()
                .find(|k| *k == keyword)
            {
                return self
                    .bspline_surface(
                        id,
                        (args.get(1).cloned(), args.get(2).cloned()),
                        args.get(3).cloned(),
                        (None, None, None, None),
                        None,
                        Some(form),
                    )
                    .map(Some);
            }
        }
        let out = match keyword.as_str() {
            "PLANE" => {
                let frame = self.frame(args[1].reference().unwrap_or(0))?;
                Some(
                    PlaneSurface::over(
                        Plane::new(frame),
                        (-SURFACE_EXTENT, SURFACE_EXTENT),
                        (-SURFACE_EXTENT, SURFACE_EXTENT),
                    )?
                    .into(),
                )
            }
            "CYLINDRICAL_SURFACE" => {
                let frame = self.frame(args[1].reference().unwrap_or(0))?;
                let radius = radius_arg(&args, 2).unwrap_or(0.0) * scale;
                Some(
                    CylinderSurface::new(
                        Cylinder::new(frame, radius, self.tol)?,
                        (-SURFACE_EXTENT, SURFACE_EXTENT),
                    )?
                    .into(),
                )
            }
            "CONICAL_SURFACE" => {
                let frame = self.frame(args[1].reference().unwrap_or(0))?;
                let radius = radius_arg(&args, 2).unwrap_or(0.0) * scale;
                let angle = radius_arg(&args, 3).unwrap_or(0.0) * self.angle_scale;
                Some(
                    ConeSurface::new(
                        Cone::new(frame, radius, angle, self.tol)?,
                        (-SURFACE_EXTENT, SURFACE_EXTENT),
                    )?
                    .into(),
                )
            }
            "SPHERICAL_SURFACE" => {
                let frame = self.frame(args[1].reference().unwrap_or(0))?;
                let radius = radius_arg(&args, 2).unwrap_or(0.0) * scale;
                Some(SphereSurface::new(Sphere::new(frame, radius, self.tol)?).into())
            }
            "TOROIDAL_SURFACE" => {
                let frame = self.frame(args[1].reference().unwrap_or(0))?;
                let major = radius_arg(&args, 2).unwrap_or(0.0) * scale;
                let minor = radius_arg(&args, 3).unwrap_or(0.0) * scale;
                Some(TorusSurface::new(Torus::new(frame, major, minor, self.tol)?).into())
            }
            "SURFACE_OF_LINEAR_EXTRUSION" => {
                // A curve swept along a vector, unbounded either way. A
                // file writes a drum's wall this way as often as it writes a
                // cylinder (a circle swept along its own axis) and a wall
                // as a line swept: those are read as the cylinder and the
                // plane they are, exact and known everywhere downstream.
                // Anything else sweeps as itself, over a window the face's
                // own edges then widen to fit.
                let Some(curve) = self.curve(args[1].reference().unwrap_or(0))? else {
                    self.report.warnings.push(format!(
                        "#{id}: an extrusion's swept curve is not read; its face is skipped"
                    ));
                    return Ok(None);
                };
                let vector = self.args(args[2].reference().unwrap_or(0), "VECTOR")?;
                let direction = self.direction(vector[1].reference().unwrap_or(0))?;
                // Parallel to the file's own precision in directions: a
                // writer states an axis to nine digits, a whisker off the
                // sweep it meant to be exactly along.
                let parallel =
                    |axis: Direction| axis.vector().cross(direction.vector()).magnitude() <= 1e-6;
                match &curve {
                    Curve::Circle(c) if parallel(c.circle().frame().z()) => Some(
                        CylinderSurface::new(
                            Cylinder::new(c.circle().frame(), c.circle().radius(), self.tol)?,
                            (-SURFACE_EXTENT, SURFACE_EXTENT),
                        )?
                        .into(),
                    ),
                    Curve::Line(l) if !parallel(l.axis().direction) => {
                        let axis = l.axis();
                        let normal = Direction::from_cross(
                            axis.direction.vector(),
                            direction.vector(),
                            self.tol,
                        )?;
                        let frame = Frame::new(axis.location, normal, axis.direction, self.tol)?;
                        Some(
                            PlaneSurface::over(
                                Plane::new(frame),
                                (-SURFACE_EXTENT, SURFACE_EXTENT),
                                (-SURFACE_EXTENT, SURFACE_EXTENT),
                            )?
                            .into(),
                        )
                    }
                    _ => Some(
                        ExtrusionSurface::over(
                            curve,
                            direction,
                            (-SURFACE_EXTENT, SURFACE_EXTENT),
                        )?
                        .into(),
                    ),
                }
            }
            "SURFACE_OF_REVOLUTION" => {
                let Some(curve) = self.curve(args[1].reference().unwrap_or(0))? else {
                    self.report.warnings.push(format!(
                        "#{id}: a revolution's swept curve is not read; its face is skipped"
                    ));
                    return Ok(None);
                };
                let placement = self.args(args[2].reference().unwrap_or(0), "AXIS1_PLACEMENT")?;
                let location = self.point(placement[1].reference().unwrap_or(0))?;
                let direction = match placement.get(2).and_then(Arg::reference) {
                    Some(r) => self.direction(r)?,
                    None => Direction::Z,
                };
                Some(
                    ogeom_geom::RevolutionSurface::new(
                        curve,
                        Axis {
                            location,
                            direction,
                        },
                        core::f64::consts::TAU,
                    )?
                    .into(),
                )
            }
            "OFFSET_SURFACE" => {
                let Some(basis) = self.surface(args[1].reference().unwrap_or(0))? else {
                    return Ok(None);
                };
                let distance = args.get(2).and_then(Arg::number).unwrap_or(0.0) * scale;
                if distance == 0.0 {
                    return Ok(Some(basis));
                }
                // An analytic basis offsets to the analytic surface it is,
                // which every downstream path speaks exactly.
                let offset = ogeom_geom::OffsetSurface::new(basis, distance)?;
                Some(match offset.analytic(self.tol)? {
                    Some(analytic) => analytic,
                    None => SurfaceGeometry::Offset(Box::new(offset)),
                })
            }
            // A face's own edges bound it; the window these name is the
            // basis's, restated.
            "RECTANGULAR_TRIMMED_SURFACE" | "CURVE_BOUNDED_SURFACE" => {
                self.surface(args[1].reference().unwrap_or(0))?
            }
            "DEGENERATE_TOROIDAL_SURFACE" => {
                let frame = self.frame(args[1].reference().unwrap_or(0))?;
                let major = radius_arg(&args, 2).unwrap_or(0.0) * scale;
                let minor = radius_arg(&args, 3).unwrap_or(0.0) * scale;
                Some(TorusSurface::new(Torus::new(frame, major, minor, self.tol)?).into())
            }
            "RECTANGULAR_COMPOSITE_SURFACE" => Some(self.composite_surface(id, &args)?),
            "SURFACE_REPLICA" => {
                let Some(parent) = self.surface(args[1].reference().unwrap_or(0))? else {
                    return Ok(None);
                };
                let motion = self.transformation_operator(args[2].reference().unwrap_or(0))?;
                Some(parent.transformed(&motion, self.tol)?)
            }
            other => {
                self.report.warnings.push(format!(
                    "#{id}: surface kind {other} is not read yet; its face is skipped"
                ));
                None
            }
        };
        Ok(out)
    }

    /// Expand STEP's multiplicity-compressed knots.
    fn expand_knots(mults: Option<Arg>, knots: Option<Arg>) -> Vec<f64> {
        let mut out = Vec::new();
        let (Some(Arg::List(mults)), Some(Arg::List(knots))) = (mults, knots) else {
            return out;
        };
        for (m, k) in mults.iter().zip(&knots) {
            let count = m.number().unwrap_or(1.0);
            #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
            let count = count as usize;
            for _ in 0..count {
                out.push(k.number().unwrap_or(0.0));
            }
        }
        out
    }

    #[allow(clippy::type_complexity)]
    fn bspline_surface(
        &mut self,
        id: u64,
        degrees: (Option<Arg>, Option<Arg>),
        grid_arg: Option<Arg>,
        mults_knots: (Option<Arg>, Option<Arg>, Option<Arg>, Option<Arg>),
        weights: Option<Vec<Arg>>,
        form: Option<&str>,
    ) -> OgeomResult<SurfaceGeometry> {
        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
        let deg = |a: Option<Arg>| a.and_then(|x| x.number()).unwrap_or(1.0) as usize;
        let (u_degree, v_degree) = (deg(degrees.0), deg(degrees.1));
        let Some(Arg::List(rows)) = grid_arg else {
            ogeom_bail!(
                Construction,
                "#{id}: a b-spline surface without control points"
            );
        };
        let mut points = Vec::new();
        let (mut u_count, mut v_count) = (0, 0);
        for row in &rows {
            let Some(cells) = row.list() else { continue };
            u_count += 1;
            v_count = cells.len();
            for cell in cells {
                points.push(self.point(cell.reference().unwrap_or(0))?);
            }
        }
        let (u_raw, v_raw) = match form {
            Some(form) => (
                implied_knots(form, u_degree, u_count),
                implied_knots(form, v_degree, v_count),
            ),
            None => (
                Self::expand_knots(mults_knots.0, mults_knots.2),
                Self::expand_knots(mults_knots.1, mults_knots.3),
            ),
        };
        let u_knots = KnotVector::new(u_raw, u_degree)?;
        let v_knots = KnotVector::new(v_raw, v_degree)?;
        let surface = if let Some(weights) = weights {
            let flat: Vec<f64> = weights
                .first()
                .and_then(Arg::list)
                .unwrap_or(&[])
                .iter()
                .filter_map(Arg::list)
                .flatten()
                .filter_map(Arg::number)
                .collect();
            let weighted: Vec<ogeom_math::Weighted<Point>> = points
                .iter()
                .zip(flat.iter().chain(std::iter::repeat(&1.0)))
                .map(|(p, w)| ogeom_math::Weighted::new(*p, *w, self.tol))
                .collect::<OgeomResult<_>>()?;
            ogeom_geom::BSplineSurface::rational(
                u_knots,
                v_knots,
                ogeom_math::ControlGrid::new(weighted, u_count, v_count)?,
            )?
        } else {
            ogeom_geom::BSplineSurface::new(
                u_knots,
                v_knots,
                &ogeom_math::ControlGrid::new(points, u_count, v_count)?,
                self.tol,
            )?
        };
        Ok(surface.into())
    }

    fn curve(&mut self, id: u64) -> OgeomResult<Option<Curve>> {
        let (keyword, args) = {
            let instance = self.instance(id)?;
            (
                instance.keyword().to_owned(),
                instance
                    .parts
                    .first()
                    .map(|(_, a)| a.clone())
                    .unwrap_or_default(),
            )
        };
        let scale = self.report.scale_mm;
        {
            let (base, kp, weights) = {
                let instance = self.instance(id)?;
                (
                    instance.part("B_SPLINE_CURVE").map(<[Arg]>::to_vec),
                    instance
                        .part("B_SPLINE_CURVE_WITH_KNOTS")
                        .map(<[Arg]>::to_vec),
                    instance
                        .part("RATIONAL_B_SPLINE_CURVE")
                        .map(<[Arg]>::to_vec),
                )
            };
            // A complex instance: the base part carries degree and control
            // points; the knots come from the knots part or are implied by
            // the form (Bézier, uniform, quasi-uniform); weights from the
            // rational part where there is one.
            let form = {
                let instance = self.instance(id)?;
                ["BEZIER_CURVE", "UNIFORM_CURVE", "QUASI_UNIFORM_CURVE"]
                    .into_iter()
                    .find(|k| instance.part(k).is_some())
            };
            if let Some(base) = base
                && (kp.is_some() || form.is_some())
            {
                #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
                let degree = base.first().and_then(Arg::number).unwrap_or(1.0) as usize;
                let control: Vec<Point> = base
                    .get(1)
                    .and_then(Arg::list)
                    .unwrap_or(&[])
                    .iter()
                    .filter_map(Arg::reference)
                    .map(|r| self.point(r))
                    .collect::<OgeomResult<_>>()?;
                let knots = match (&kp, form) {
                    (Some(kp), _) => Self::expand_knots(kp.first().cloned(), kp.get(1).cloned()),
                    (None, Some(form)) => implied_knots(form, degree, control.len()),
                    (None, None) => unreachable!("guarded above"),
                };
                let knots = KnotVector::new(knots, degree)?;
                let flat: Vec<f64> = weights
                    .as_ref()
                    .and_then(|w| w.first())
                    .and_then(Arg::list)
                    .unwrap_or(&[])
                    .iter()
                    .filter_map(Arg::number)
                    .collect();
                let weighted: Vec<ogeom_math::Weighted<Point>> = control
                    .iter()
                    .zip(flat.iter().chain(std::iter::repeat(&1.0)))
                    .map(|(p, w)| ogeom_math::Weighted::new(*p, *w, self.tol))
                    .collect::<OgeomResult<_>>()?;
                return Ok(Some(BSplineCurve::rational(knots, weighted)?.into()));
            }
        }
        let out: Option<Curve> = match keyword.as_str() {
            "LINE" => {
                let through = self.point(args[1].reference().unwrap_or(0))?;
                // The vector's magnitude scales STEP's parameter; ranges here
                // are re-derived from vertex geometry, so only the direction
                // matters.
                let vector = self.args(args[2].reference().unwrap_or(0), "VECTOR")?;
                let direction = self.direction(vector[1].reference().unwrap_or(0))?;
                Some(
                    LineCurve::new(Axis {
                        location: through,
                        direction,
                    })
                    .into(),
                )
            }
            "CIRCLE" => {
                let frame = self.frame(args[1].reference().unwrap_or(0))?;
                let radius = args.get(2).and_then(Arg::number).unwrap_or(0.0) * scale;
                Some(CircleCurve::new(Circle::new(frame, radius, self.tol)?).into())
            }
            "ELLIPSE" => {
                let frame = self.frame(args[1].reference().unwrap_or(0))?;
                let a = args.get(2).and_then(Arg::number).unwrap_or(0.0) * scale;
                let b = args.get(3).and_then(Arg::number).unwrap_or(0.0) * scale;
                Some(EllipseCurve::new(Ellipse::new(frame, a, b, self.tol)?).into())
            }
            "B_SPLINE_CURVE_WITH_KNOTS" => {
                let degree = args.get(1).and_then(Arg::number).unwrap_or(0.0);
                #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
                let degree = degree as usize;
                let control: Vec<Point> = args
                    .get(2)
                    .and_then(Arg::list)
                    .unwrap_or(&[])
                    .iter()
                    .filter_map(Arg::reference)
                    .map(|r| self.point(r))
                    .collect::<OgeomResult<_>>()?;
                let mults = args.get(6).and_then(Arg::list).unwrap_or(&[]).to_vec();
                let knots = args.get(7).and_then(Arg::list).unwrap_or(&[]).to_vec();
                let mut expanded = Vec::new();
                for (m, k) in mults.iter().zip(&knots) {
                    let count = m.number().unwrap_or(1.0);
                    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
                    let count = count as usize;
                    for _ in 0..count {
                        expanded.push(k.number().unwrap_or(0.0));
                    }
                }
                Some(
                    BSplineCurve::new(KnotVector::new(expanded, degree)?, control, self.tol)?
                        .into(),
                )
            }
            "SURFACE_CURVE" | "SEAM_CURVE" | "INTERSECTION_CURVE" => {
                // A curve dressed in its surface associations: what every
                // exporter derived from the reference kernel writes for
                // every edge. The 3D curve is the first argument; the
                // pcurve list is advisory and this reader re-derives its
                // own, so unwrapping is the whole job.
                self.curve(args.get(1).and_then(Arg::reference).unwrap_or(0))?
            }
            "BEZIER_CURVE" | "UNIFORM_CURVE" | "QUASI_UNIFORM_CURVE" => {
                #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
                let degree = args.get(1).and_then(Arg::number).unwrap_or(1.0) as usize;
                let control: Vec<Point> = args
                    .get(2)
                    .and_then(Arg::list)
                    .unwrap_or(&[])
                    .iter()
                    .filter_map(Arg::reference)
                    .map(|r| self.point(r))
                    .collect::<OgeomResult<_>>()?;
                let knots = implied_knots(&keyword, degree, control.len());
                Some(BSplineCurve::new(KnotVector::new(knots, degree)?, control, self.tol)?.into())
            }
            "HYPERBOLA" => {
                let frame = self.frame(args[1].reference().unwrap_or(0))?;
                let a = args.get(2).and_then(Arg::number).unwrap_or(0.0) * scale;
                let b = args.get(3).and_then(Arg::number).unwrap_or(0.0) * scale;
                // The branch's reach in its own parameter: cosh 20 carries a
                // hyperbola far past any part.
                Some(HyperbolaCurve::new(Hyperbola::new(frame, a, b, self.tol)?, 20.0)?.into())
            }
            "PARABOLA" => {
                let frame = self.frame(args[1].reference().unwrap_or(0))?;
                let focal = args.get(2).and_then(Arg::number).unwrap_or(0.0) * scale;
                Some(
                    ParabolaCurve::new(Parabola::new(frame, focal, self.tol)?, SURFACE_EXTENT)?
                        .into(),
                )
            }
            "TRIMMED_CURVE" => {
                // An edge's ends are its vertices; the trims restate them.
                self.curve(args.get(1).and_then(Arg::reference).unwrap_or(0))?
            }
            "OFFSET_CURVE_3D" => {
                let Some(basis) = self.curve(args.get(1).and_then(Arg::reference).unwrap_or(0))?
                else {
                    return Ok(None);
                };
                let distance = args.get(2).and_then(Arg::number).unwrap_or(0.0) * scale;
                let reference =
                    self.direction(args.get(4).and_then(Arg::reference).unwrap_or(0))?;
                Some(Curve::Offset(Box::new(ogeom_geom::OffsetCurve::new(
                    basis, distance, reference,
                )?)))
            }
            "POLYLINE" => {
                let points: Vec<Point> = args
                    .get(1)
                    .and_then(Arg::list)
                    .unwrap_or(&[])
                    .iter()
                    .filter_map(Arg::reference)
                    .map(|r| self.point(r))
                    .collect::<OgeomResult<_>>()?;
                if points.len() < 2 {
                    ogeom_bail!(Construction, "#{id}: a polyline of fewer than two points");
                }
                // Degree one through the points, a knot at each.
                let mut knots = vec![0.0];
                #[allow(clippy::cast_precision_loss)]
                knots.extend((0..points.len()).map(|i| i as f64));
                #[allow(clippy::cast_precision_loss)]
                knots.push((points.len() - 1) as f64);
                Some(BSplineCurve::new(KnotVector::new(knots, 1)?, points, self.tol)?.into())
            }
            "COMPOSITE_CURVE" => {
                // Its segments, each over its own trim and in its own
                // sense, as splines joined end to start.
                let mut joined: Option<(KnotVector, Vec<ogeom_math::Weighted<Point>>)> = None;
                let segments: Vec<u64> = args
                    .get(1)
                    .and_then(Arg::list)
                    .unwrap_or(&[])
                    .iter()
                    .filter_map(Arg::reference)
                    .collect();
                for segment in segments {
                    let sargs = self.args(segment, "COMPOSITE_CURVE_SEGMENT")?;
                    let same_sense = !sargs.get(1).is_some_and(|a| a.is_enum("F"));
                    let parent = sargs.get(2).and_then(Arg::reference).unwrap_or(0);
                    let Some((curve, range)) = self.bounded_curve(parent)? else {
                        return Ok(None);
                    };
                    let mut spline = curve.to_bspline_over(range, self.tol)?;
                    if !same_sense {
                        let (knots, control) =
                            ogeom_math::bspline::reverse(spline.knots(), spline.control_points());
                        spline = BSplineCurve::rational(knots, control)?;
                    }
                    joined = Some(match joined {
                        None => (spline.knots().clone(), spline.control_points().to_vec()),
                        Some(held) => join_splines(held, &spline, self.tol)?,
                    });
                }
                let Some((knots, control)) = joined else {
                    ogeom_bail!(Construction, "#{id}: a composite curve with no segments");
                };
                Some(BSplineCurve::rational(knots, control)?.into())
            }
            "CURVE_REPLICA" => {
                let Some(parent) = self.curve(args.get(1).and_then(Arg::reference).unwrap_or(0))?
                else {
                    return Ok(None);
                };
                let motion = self
                    .transformation_operator(args.get(2).and_then(Arg::reference).unwrap_or(0))?;
                Some(parent.transformed(&motion, self.tol)?)
            }
            other => {
                self.report.warnings.push(format!(
                    "#{id}: curve kind {other} is not read yet; its edge is skipped"
                ));
                None
            }
        };
        Ok(out)
    }

    /// A rectangular composite surface: its grid of patches joined into one
    /// B-spline surface, so a face across the grid is a face on one surface
    /// and needs no rebuilding. Each patch in its spline form over its own
    /// bounds, turned where its sense says, raised to the grid's degrees,
    /// its knots unified with its column's and its row's, and joined to its
    /// neighbours on their shared boundary. Neighbours that do not meet
    /// there are refused by name.
    fn composite_surface(&mut self, id: u64, args: &[Arg]) -> OgeomResult<SurfaceGeometry> {
        let rows: Vec<Vec<u64>> = args
            .get(1)
            .and_then(Arg::list)
            .unwrap_or(&[])
            .iter()
            .map(|row| {
                row.list()
                    .unwrap_or(&[])
                    .iter()
                    .filter_map(Arg::reference)
                    .collect()
            })
            .collect();
        if rows.is_empty()
            || rows
                .iter()
                .any(|r| r.len() != rows[0].len() || r.is_empty())
        {
            ogeom_bail!(
                Construction,
                "#{id}: a composite surface's grid is not rectangular"
            );
        }
        let mut grid: Vec<Vec<Patch>> = Vec::with_capacity(rows.len());
        for row in &rows {
            let mut out = Vec::with_capacity(row.len());
            for &patch in row {
                let pargs = self.args(patch, "SURFACE_PATCH")?;
                let parent = pargs.get(1).and_then(Arg::reference).unwrap_or(0);
                let u_sense = !pargs.get(4).is_some_and(|a| a.is_enum("F"));
                let v_sense = !pargs.get(5).is_some_and(|a| a.is_enum("F"));
                let spline = self.bounded_surface_spline(parent)?;
                let mut p = Patch::of(&spline)?;
                if !u_sense {
                    p = p.reversed_u();
                }
                if !v_sense {
                    p = p.transposed().reversed_u().transposed();
                }
                out.push(p);
            }
            grid.push(out);
        }
        join_patches(grid, self.tol).map_err(|e| {
            ogeom_core::ogeom_err!(
                Construction,
                "#{id}: a composite surface's patches do not join: {e}"
            )
        })
    }

    /// A composite's patch surface as a B-spline over its own bounds: a
    /// B-spline as it is; a rectangularly trimmed surface's basis over its
    /// window, in the file's reading of the basis's parameters.
    fn bounded_surface_spline(&mut self, id: u64) -> OgeomResult<ogeom_geom::BSplineSurface> {
        let keyword = self.instance(id)?.keyword().to_owned();
        if keyword == "RECTANGULAR_TRIMMED_SURFACE" {
            let args = self.args(id, "RECTANGULAR_TRIMMED_SURFACE")?;
            let basis_id = args.get(1).and_then(Arg::reference).unwrap_or(0);
            let Some(basis) = self.surface(basis_id)? else {
                ogeom_bail!(Construction, "#{id}: a patch's basis is not read");
            };
            let angular = matches!(
                self.instance(basis_id)?.keyword(),
                "CYLINDRICAL_SURFACE"
                    | "CONICAL_SURFACE"
                    | "SPHERICAL_SURFACE"
                    | "TOROIDAL_SURFACE"
            );
            let n = |i: usize| args.get(i).and_then(Arg::number).unwrap_or(0.0);
            let (u_scale, v_scale) = if angular {
                (self.angle_scale, self.report.scale_mm)
            } else {
                (self.report.scale_mm, self.report.scale_mm)
            };
            let (u1, u2) = (n(2) * u_scale, n(3) * u_scale);
            let (v1, v2) = (n(4) * v_scale, n(5) * v_scale);
            let window = ((u1.min(u2), u1.max(u2)), (v1.min(v2), v1.max(v2)));
            let trimmed = ogeom_geom::TrimmedSurface::new(basis, window.0, window.1, self.tol)?;
            return SurfaceGeometry::Trimmed(Box::new(trimmed)).to_bspline(self.tol);
        }
        let Some(surface) = self.surface(id)? else {
            ogeom_bail!(Construction, "#{id}: a patch's surface is not read");
        };
        surface.to_bspline(self.tol)
    }

    /// A curve with the stretch of it an entity bounds: a trimmed curve's
    /// basis between its trims (a point where the file gives one, else its
    /// parameter in the file's own reading of the basis), in its own sense;
    /// any other curve over its own domain, which must be bounded.
    fn bounded_curve(&mut self, id: u64) -> OgeomResult<Option<(Curve, (f64, f64))>> {
        let keyword = self.instance(id)?.keyword().to_owned();
        if keyword != "TRIMMED_CURVE" {
            let Some(curve) = self.curve(id)? else {
                return Ok(None);
            };
            let (lo, hi) = curve.domain();
            if !lo.is_finite() || !hi.is_finite() || hi - lo > SURFACE_EXTENT {
                ogeom_bail!(
                    Construction,
                    "#{id}: an unbounded curve cannot stand as a composite's segment"
                );
            }
            return Ok(Some((curve, (lo, hi))));
        }
        let args = self.args(id, "TRIMMED_CURVE")?;
        let basis_id = args.get(1).and_then(Arg::reference).unwrap_or(0);
        let Some(basis) = self.curve(basis_id)? else {
            return Ok(None);
        };
        let basis_keyword = self.instance(basis_id)?.keyword().to_owned();
        let forward = !args.get(4).is_some_and(|a| a.is_enum("F"));
        let mut ends = Vec::with_capacity(2);
        for trim in [args.get(2), args.get(3)] {
            let items = trim.and_then(Arg::list).unwrap_or(&[]).to_vec();
            let mut at: Option<Point> = None;
            for item in &items {
                if let Some(r) = item.reference() {
                    at = Some(self.point(r)?);
                }
            }
            if at.is_none() {
                for item in &items {
                    if let Arg::Typed(name, values) = item
                        && name == "PARAMETER_VALUE"
                        && let Some(v) = values.first().and_then(Arg::number)
                    {
                        at =
                            Some(self.step_parameter_point(&basis, &basis_keyword, basis_id, v)?);
                    }
                }
            }
            let Some(point) = at else {
                ogeom_bail!(
                    Construction,
                    "#{id}: a trim names neither point nor parameter"
                );
            };
            let t = match self.parameter_of(&basis, point) {
                Some(t) => t,
                None => project_on_curve(&basis, point, 256, self.tol)?.parameter,
            };
            ends.push(t);
        }
        let (mut a, mut b) = (ends[0], ends[1]);
        if !forward {
            core::mem::swap(&mut a, &mut b);
        }
        if basis.is_periodic() && b <= a {
            let (lo, hi) = basis.domain();
            b += hi - lo;
        }
        let range = if a <= b { (a, b) } else { (b, a) };
        let mut curve = basis;
        if !forward || a > b {
            // Travelled backward: the same points, the parameter turned.
            let spline = curve.to_bspline_over(range, self.tol)?;
            let (knots, control) =
                ogeom_math::bspline::reverse(spline.knots(), spline.control_points());
            curve = BSplineCurve::rational(knots, control)?.into();
            let domain = curve.domain();
            return Ok(Some((curve, domain)));
        }
        Ok(Some((curve, range)))
    }

    /// Where the file's parameter `v` stands on a basis curve, read as the
    /// file reads it: a line's by its own vector's length, a conic's as an
    /// angle in the file's angle unit, a spline's as it is.
    fn step_parameter_point(
        &mut self,
        basis: &Curve,
        keyword: &str,
        basis_id: u64,
        v: f64,
    ) -> OgeomResult<Point> {
        match keyword {
            "LINE" => {
                let args = self.args(basis_id, "LINE")?;
                let through = self.point(args[1].reference().unwrap_or(0))?;
                let vector = self.args(args[2].reference().unwrap_or(0), "VECTOR")?;
                let direction = self.direction(vector[1].reference().unwrap_or(0))?;
                let magnitude = vector.get(2).and_then(Arg::number).unwrap_or(1.0);
                Ok(through + direction.vector() * (v * magnitude * self.report.scale_mm))
            }
            "CIRCLE" | "ELLIPSE" => basis.point_at(v * self.angle_scale, self.tol),
            _ => basis.point_at(v, self.tol),
        }
    }

    /// A Cartesian transformation operator as the motion it states: the
    /// axes it names (completed square to one another), its origin, and
    /// its uniform scale.
    fn transformation_operator(&mut self, id: u64) -> OgeomResult<Transform> {
        let args = self.args(id, "CARTESIAN_TRANSFORMATION_OPERATOR_3D")?;
        let direction_at = |this: &mut Self, i: usize| -> OgeomResult<Option<Vector>> {
            match args.get(i).and_then(Arg::reference) {
                Some(r) => Ok(Some(this.direction(r)?.vector())),
                None => Ok(None),
            }
        };
        let (axis1, axis2, axis3) = (
            direction_at(self, 1)?,
            direction_at(self, 2)?,
            direction_at(self, 5)?,
        );
        let origin = self.point(args.get(3).and_then(Arg::reference).unwrap_or(0))?;
        let scale = args.get(4).and_then(Arg::number).unwrap_or(1.0);
        let z = match (axis3, axis1, axis2) {
            (Some(z), _, _) => z,
            (None, Some(x), Some(y)) => x.cross(y),
            _ => Vector::Z,
        };
        let z = Direction::new(z, self.tol)?.vector();
        let x = match axis1 {
            Some(x) => x - z * x.dot(z),
            None => {
                let seed = if z.x.abs() < 0.9 {
                    Vector::X
                } else {
                    Vector::Y
                };
                seed - z * seed.dot(z)
            }
        };
        let x = Direction::new(x, self.tol)?.vector();
        let y = z.cross(x);
        let linear = Matrix3::new([[x.x, y.x, z.x], [x.y, y.y, z.y], [x.z, y.z, z.z]]);
        Transform::from_parts(linear, scale, origin.to_vector(), self.tol.angular())
    }

    /// The parameter of a point on one of this kernel's curves.
    fn parameter_of(&self, curve: &Curve, p: Point) -> Option<f64> {
        crate::inversion::parameter_on(curve, p)
    }

    // --- topology ------------------------------------------------------------

    fn vertex(&mut self, id: u64) -> OgeomResult<Shape> {
        if let Some(shape) = self.vertices.get(&id) {
            return Ok(shape.clone());
        }
        let args = self.args(id, "VERTEX_POINT")?;
        let point = self.point(args[1].reference().unwrap_or(0))?;
        let shape = make_vertex(&mut self.model, point).shape;
        self.vertices.insert(id, shape.clone());
        Ok(shape)
    }

    /// An `EDGE_CURVE`, built once, curve-forward.
    ///
    /// Returns the edge, its curve, its range, and whether STEP's edge
    /// direction runs *against* the curve, which each use folds into its
    /// own orientation.
    fn edge(&mut self, id: u64) -> OgeomResult<Option<BuiltEdge>> {
        if let Some(found) = self.edges.get(&id) {
            return Ok(Some(found.clone()));
        }
        let args = self.args(id, "EDGE_CURVE")?;
        let v1 = args[1].reference().unwrap_or(0);
        let v2 = args[2].reference().unwrap_or(0);
        let Some(mut curve) = self.curve(args[3].reference().unwrap_or(0))? else {
            return Ok(None);
        };
        let same_sense = !args.get(4).is_some_and(|a| a.is_enum("F"));

        let p1 = {
            let vargs = self.args(v1, "VERTEX_POINT")?;
            self.point(vargs[1].reference().unwrap_or(0))?
        };
        let p2 = {
            let vargs = self.args(v2, "VERTEX_POINT")?;
            self.point(vargs[1].reference().unwrap_or(0))?
        };

        // The edge is built along the curve's own parameter; a STEP edge
        // running the other way is flagged, and every use composes the flag
        // into its orientation.
        let (start, end, mut flipped) = if same_sense {
            (p1, p2, false)
        } else {
            (p2, p1, true)
        };
        let (range, closed) = match (
            self.parameter_of(&curve, start),
            self.parameter_of(&curve, end),
        ) {
            (Some(a), Some(b)) => {
                let period = if curve.is_periodic() {
                    let (lo, hi) = curve.domain();
                    hi - lo
                } else {
                    0.0
                };
                if v1 == v2 {
                    ((a, a + if period > 0.0 { period } else { 0.0 }), true)
                } else if period > 0.0 && b <= a + self.tol.parametric() {
                    ((a, b + period), false)
                } else if b < a - self.tol.parametric() {
                    // The vertices stand at descending parameters on an
                    // open curve whatever the sense flag says: a
                    // mesh-to-STEP converter writes every edge forward and
                    // lets the line run the other way. The edge is built
                    // along the curve's own parameter and runs against it.
                    flipped = !flipped;
                    self.report.warnings.push(format!(
                        "#{id}: the edge's vertices run against its curve's \
                         parameter despite its sense flag; the edge was reversed"
                    ));
                    self.tally("edge-against-curve", a - b, id);
                    ((b, a), false)
                } else {
                    ((a, b), false)
                }
            }
            _ => {
                // No closed-form inversion: take the curve's own domain and
                // hold the endpoints to it.
                //
                // A closed edge whose one vertex sits on the curve but away
                // from its seam (a fitted loop written with its start
                // wherever the fit began, the vertex millimetres along it)
                // would otherwise be held to a seam the vertex misses by
                // that much, and the vertex's tolerance widened to say so.
                // The seam is moved to the vertex instead: the same curve,
                // begun where the edge does.
                if v1 == v2
                    && let Curve::BSpline(spline) = &curve
                {
                    let (lo, hi) = curve.domain();
                    let gap = curve.point_at(lo, self.tol)?.distance(start);
                    if gap > self.tol.confusion() * 10.0 {
                        let samples = (spline.control_points().len() * 8).max(64);
                        if let Ok(found) = project_on_curve(&curve, start, samples, self.tol)
                            && found.distance <= self.tol.confusion() * 1e4
                            && found.parameter > lo + self.tol.parametric()
                            && found.parameter < hi - self.tol.parametric()
                            && let Ok(moved) = spline.reseamed_at(found.parameter, self.tol)
                        {
                            curve = Curve::BSpline(moved);
                            self.report.warnings.push(format!(
                                "#{id}: a closed edge's vertex sits {gap:.2e} along its \
                                 curve from the seam; the seam was moved to the vertex"
                            ));
                            self.tally("reseamed", gap, id);
                        }
                    }
                }
                let (lo, hi) = curve.domain();
                let head = curve.point_at(lo, self.tol)?;
                let tail = curve.point_at(hi, self.tol)?;
                let (head_miss, tail_miss) = (head.distance(start), tail.distance(end));
                if head_miss > self.tol.confusion() * 10.0
                    || tail_miss > self.tol.confusion() * 10.0
                {
                    // An open edge whose vertices stand *on* the curve but
                    // short of its ends (a file that writes the whole
                    // spline and lets the vertices say where the edge
                    // stops, millimetres in) takes the window between the
                    // vertices' own feet. Held to the whole curve, the edge
                    // overshoots its neighbours and the face it bounds draws
                    // as nothing at all.
                    let window = if v1 == v2 {
                        None
                    } else {
                        window_between_feet(&curve, start, end, self.tol)
                    };
                    if let Some(window) = window {
                        self.report.warnings.push(format!(
                            "#{id}: edge endpoints sit {head_miss:.2e} and {tail_miss:.2e} \
                             from its curve's ends; the window between the vertices' \
                             feet on the curve was taken"
                        ));
                        self.tally("vertex-window", head_miss.max(tail_miss), id);
                        (window, false)
                    } else {
                        self.report.warnings.push(format!(
                            "#{id}: edge endpoints sit {head_miss:.2e} and {tail_miss:.2e} \
                             from its curve's ends; the curve's own domain was taken"
                        ));
                        ((lo, hi), v1 == v2)
                    }
                } else {
                    ((lo, hi), v1 == v2)
                }
            }
        };
        let _ = closed;

        let (vlo, vhi) = if flipped {
            (self.vertex(v2)?, self.vertex(v1)?)
        } else {
            (self.vertex(v1)?, self.vertex(v2)?)
        };
        // Real files are imprecise, and NIST's own readme says so of these.
        // Where the curve's end misses its vertex by more than the default
        // tolerance, the vertex's tolerance *grows* to state the gap; the
        // data model's growing tolerances are exactly for this, and the
        // warning keeps the healing visible.
        for (vertex, t) in [(&vlo, range.0), (&vhi, range.1)] {
            let end = curve.point_at(t, self.tol)?;
            let stated = {
                let Some(node) = self.model.node(vertex) else {
                    continue;
                };
                let Some(data) = node.data().as_vertex() else {
                    continue;
                };
                (data.point, data.tolerance)
            };
            let gap = end.distance(stated.0);
            if gap > stated.1.get() {
                if let Some(node) = self.model.node_mut(vertex)
                    && let ogeom_topo::NodeData::Vertex(data) = node.data_mut()
                {
                    data.tolerance = data.tolerance.widen_to(gap + self.tol.confusion());
                }
                self.warn_vertex_miss(id, gap);
            }
        }
        let shape =
            make_edge_between(&mut self.model, curve.clone(), range, &vlo, &vhi, self.tol)?.shape;
        let entry = (shape, curve, range, flipped);
        self.edges.insert(id, entry.clone());
        Ok(Some(entry))
    }

    fn face(&mut self, id: u64) -> OgeomResult<Option<Shape>> {
        if let Some(shape) = self.faces.get(&id) {
            return Ok(Some(shape.clone()));
        }
        let args = self.face_args(id)?;
        let bounds: Vec<u64> = args
            .get(1)
            .and_then(Arg::list)
            .unwrap_or(&[])
            .iter()
            .filter_map(Arg::reference)
            .collect();
        let Some(surface) = self.surface(args[2].reference().unwrap_or(0))? else {
            return Ok(None);
        };
        let face_forward = !args.get(3).is_some_and(|a| a.is_enum("F"));
        let surface_id = self.model.geometry_mut().add_surface(surface.clone());

        // Outer bound first, so the face's first wire is its outer ring.
        let mut ordered = bounds.clone();
        ordered.sort_by_key(|b| {
            self.exchange
                .data
                .get(b)
                .map_or(1, |i| i32::from(i.part("FACE_OUTER_BOUND").is_none()))
        });

        // Which edges this face uses twice: those are seams, and get both
        // sides' pcurves.
        let mut edge_uses: HashMap<u64, usize> = HashMap::new();
        for &bound in &ordered {
            let bargs = self.bound_args(bound)?;
            if self.instance(bargs.0)?.part("VERTEX_LOOP").is_some() {
                continue;
            }
            let loop_args = self.args(bargs.0, "EDGE_LOOP")?;
            for oe in loop_args.get(1).and_then(Arg::list).unwrap_or(&[]) {
                if let Some(oe_id) = oe.reference() {
                    let oargs = self.args(oe_id, "ORIENTED_EDGE")?;
                    if let Some(e) = oargs.get(3).and_then(Arg::reference) {
                        *edge_uses.entry(e).or_default() += 1;
                    }
                }
            }
        }

        let mut wires = Vec::new();
        let mut annotated: HashSet<u64> = HashSet::new();
        for &bound in &ordered {
            let (loop_id, bound_forward) = self.bound_args(bound)?;
            if let Some(vertex_loop) = {
                let instance = self.instance(loop_id)?;
                instance.part("VERTEX_LOOP").map(<[Arg]>::to_vec)
            } {
                // A loop of one vertex: a pole or an apex. It has no edges,
                // but it still bounds the face in parameter space, as a
                // degenerate edge running across the chart at the row the
                // point collapses to, exactly as native cones and spheres
                // are built.
                let vertex_id = vertex_loop.get(1).and_then(Arg::reference).unwrap_or(0);
                let vargs = self.args(vertex_id, "VERTEX_POINT")?;
                let at = self.point(vargs[1].reference().unwrap_or(0))?;
                let vertex = self.vertex(vertex_id)?;
                let projection = ogeom_algo::project_on_surface(&surface, at, 32, self.tol)?;
                let ((ua, ub), _) = surface.domain();
                let row = projection.parameters.1;
                let mut data = ogeom_topo::EdgeData::new();
                data.degenerate = true;
                let edge = self
                    .model
                    .add_edge(data, &[vertex.clone(), vertex.clone()])?;
                let pcurve: PlanarCurve = ogeom_geom::Line2d::segment(
                    ogeom_math::Point2::new(ua, row),
                    ogeom_math::Point2::new(ub, row),
                    self.tol,
                )?
                .into();
                ogeom_algo::attach_pcurve(
                    &mut self.model,
                    &edge,
                    pcurve,
                    surface_id,
                    Location::identity(),
                    (0.0, ub - ua),
                )?;
                wires.push(make_wire(&mut self.model, &[edge], self.tol)?.shape);
                continue;
            }
            let loop_args = self.args(loop_id, "EDGE_LOOP")?;
            let mut uses: Vec<BoundUse> = Vec::new();
            for oe in loop_args.get(1).and_then(Arg::list).unwrap_or(&[]) {
                let Some(oe_id) = oe.reference() else {
                    continue;
                };
                let oargs = self.args(oe_id, "ORIENTED_EDGE")?;
                let Some(edge_id) = oargs.get(3).and_then(Arg::reference) else {
                    continue;
                };
                let forward = !oargs.get(4).is_some_and(|a| a.is_enum("F"));
                let Some((shape, curve, range, flipped)) = self.edge(edge_id)? else {
                    self.report.warnings.push(format!(
                        "#{id}: a bound references unreadable edge #{edge_id}; \
                         the face is skipped"
                    ));
                    return Ok(None);
                };
                // The use's direction composes the loop's, the bound's and
                // the edge-against-curve flag.
                let mut use_forward = forward == bound_forward;
                if flipped {
                    use_forward = !use_forward;
                }
                let placed = if use_forward {
                    shape.clone()
                } else {
                    shape.reversed()
                };
                uses.push((placed, shape, edge_id, curve, range));
            }
            if !bound_forward {
                uses.reverse();
            }
            // The window may have grown to hold this bound, and the images
            // are derived on the surface as it stands.
            self.widen_window(surface_id, &uses)?;
            let widened = self
                .model
                .geometry()
                .surface(surface_id)
                .cloned()
                .unwrap_or_else(|| surface.clone());
            self.chart_bound(id, &uses, &widened, surface_id, &edge_uses, &mut annotated)?;
            let edges: Vec<Shape> = uses.into_iter().map(|(placed, ..)| placed).collect();
            if edges.is_empty() {
                continue;
            }
            wires.push(make_wire(&mut self.model, &edges, self.tol)?.shape);
        }
        if wires.is_empty() {
            self.report
                .warnings
                .push(format!("#{id}: a face with no readable bounds is skipped"));
            return Ok(None);
        }
        // As the bounds left it: a window stretched to hold them is the
        // surface every path below builds on, including the band, which
        // registers the value it is handed rather than the one on record.
        let surface = self
            .model
            .geometry()
            .surface(surface_id)
            .cloned()
            .unwrap_or(surface);

        // A periodic face bound only by closed rings (a cylinder band
        // between two circles) arrives without a seam edge, which is a
        // legitimate STEP shape and an open rectangle in this kernel's
        // chart. The seam is synthesised the way native cylinders build it:
        // one edge at the period join, appearing in the wire twice.
        if wires.len() == 2
            && surface.is_periodic_u()
            && let [(e_lo, _v_lo), (e_hi, _v_hi)] =
                closed_ring_edges(&self.model, &wires)?.as_slice()
            // Only rings that are parallels of the surface make a band.
            // Two closed circles that merely lie on it (a button head's
            // rims, square to the screw on a sphere whose chart runs along
            // z) bound a legitimate face on their own, nested loops in the
            // chart, and take the ordinary path below without a word.
            && ogeom_algo::rings_are_parallels(&self.model, &surface, &[e_lo, e_hi], self.tol)?
        {
            {
                // The band construction is ogeom-algo's make_revolution_band:
                // one authority shared with the healer. Anything it refuses
                // (a spline ring, ring vertices at different angles, a
                // surface with no closed-form iso-curve) becomes a warning
                // and the raw bounds, not an error.
                match ogeom_algo::make_revolution_band(
                    &mut self.model,
                    &surface,
                    e_lo,
                    e_hi,
                    self.tol,
                ) {
                    Ok(built) => {
                        let shape = if face_forward {
                            built
                        } else {
                            built.reversed()
                        };
                        self.faces.insert(id, shape.clone());
                        return Ok(Some(shape));
                    }
                    Err(e) => {
                        self.report.warnings.push(format!(
                            "#{id}: no seam could be synthesised ({e}); the \
                             face may not triangulate"
                        ));
                    }
                }
            }
        }

        // A cone face bounded by a *single* closed ring: the apex is the
        // other boundary, and some files simply never write it: no vertex
        // loop, nothing. The geometry leaves one choice of what the face
        // means, so the apex is synthesised and the band built as if the
        // file had said so.
        if wires.len() == 1
            && matches!(surface, SurfaceGeometry::Cone(_))
            && let [(ring, _)] = closed_ring_edges(&self.model, &wires)?.as_slice()
        {
            match ogeom_algo::make_apex_band(&mut self.model, &surface, ring, self.tol) {
                Ok(built) => {
                    let shape = if face_forward {
                        built
                    } else {
                        built.reversed()
                    };
                    self.faces.insert(id, shape.clone());
                    return Ok(Some(shape));
                }
                Err(e) => {
                    self.report.warnings.push(format!(
                        "#{id}: no apex could be synthesised ({e}); the face \
                         may not triangulate"
                    ));
                }
            }
        }

        // Every wire's images on one branch of a periodic chart: a file's
        // pcurves, or fits of them, answer in whatever phase they like, and
        // a hole loop straddling a drum's seam arrives half on each branch.
        ogeom_algo::chain_wire_branches(&mut self.model, surface_id, &wires, self.tol)?;
        let built = make_face_on(&mut self.model, surface_id, &wires, self.tol)?.shape;
        let shape = if face_forward {
            built
        } else {
            built.reversed()
        };
        self.faces.insert(id, shape.clone());
        Ok(Some(shape))
    }

    /// A bound's loop and orientation, whichever of the two bound kinds it is.
    fn bound_args(&mut self, id: u64) -> OgeomResult<(u64, bool)> {
        let instance = self.instance(id)?;
        let args = instance
            .part("FACE_OUTER_BOUND")
            .or_else(|| instance.part("FACE_BOUND"))
            .ok_or_else(|| ogeom_core::ogeom_err!(Construction, "#{id} is not a face bound"))?
            .to_vec();
        let loop_id = args.get(1).and_then(Arg::reference).unwrap_or(0);
        let forward = !args.get(2).is_some_and(|a| a.is_enum("F"));
        Ok((loop_id, forward))
    }

    /// Attach this face's pcurve (or both seam sides) to an edge.
    #[allow(clippy::too_many_arguments)]
    /// One use a bound makes of an edge: the edge as the loop walks it, the
    /// edge as it was built, the file's id for it, and its curve and range.
    /// Stretch a surface's parameter window to hold the edges that bound it.
    ///
    /// The window a reader gives a plane, a cylinder or a cone is a
    /// convention: those surfaces are unbounded, and [`SURFACE_EXTENT`] is
    /// a guess at how far past its own geometry a file will reach. A file
    /// can falsify the guess: a real assembly places a cylinder's own
    /// origin half a kilometre from the part it belongs to, so the trim's
    /// height parameter runs to −5e5 where the window stopped at −1e5,
    /// and then the surface refuses to be evaluated where its own face
    /// lies, and the face draws as a hole.
    ///
    /// So the window is measured rather than guessed: the edges' own
    /// points, projected onto the surface's chart by the geometry that
    /// defines it, with the guess kept as a floor. Widening is safe for a
    /// surface other faces share, since a window only ever grows.
    fn widen_window(
        &mut self,
        surface_id: ogeom_topo::SurfaceId,
        uses: &[BoundUse],
    ) -> OgeomResult<()> {
        use ogeom_geom::Curve3d as _;
        let Some(surface) = self.model.geometry().surface(surface_id).cloned() else {
            return Ok(());
        };
        // Where each surface keeps its unbounded directions, and how a point
        // of space reads on them.
        let along: Box<ChartReading> = match &surface {
            SurfaceGeometry::Plane(p) => {
                let frame = p.plane().frame();
                let (origin, x, y) = (frame.origin(), frame.x().vector(), frame.y().vector());
                Box::new(move |at: Point| (Some((at - origin).dot(x)), Some((at - origin).dot(y))))
            }
            SurfaceGeometry::Cylinder(c) => {
                let axis = c.cylinder().axis();
                let (origin, direction) = (axis.location, axis.direction.vector());
                Box::new(move |at: Point| (None, Some((at - origin).dot(direction))))
            }
            SurfaceGeometry::Cone(c) => {
                let axis = c.cone().axis();
                let (origin, direction) = (axis.location, axis.direction.vector());
                Box::new(move |at: Point| (None, Some((at - origin).dot(direction))))
            }
            // A swept curve: a point's sweep parameter is its reach along
            // the direction less the swept curve's own, read against the
            // middle of the curve's reach; the curve's half-reach either
            // way is inside the margin the window grows by.
            SurfaceGeometry::Extrusion(e) => {
                let direction = e.direction().vector();
                let (lo, hi) = e.curve().domain();
                let (mut least, mut most) = (f64::INFINITY, f64::NEG_INFINITY);
                for k in 0..=32 {
                    let t = lo + (hi - lo) * f64::from(k) / 32.0;
                    if let Ok(p) = e.curve().point_at(t, self.tol) {
                        let reach = p.to_vector().dot(direction);
                        least = least.min(reach);
                        most = most.max(reach);
                    }
                }
                let middle = f64::midpoint(least, most);
                Box::new(move |at: Point| (None, Some(at.to_vector().dot(direction) - middle)))
            }
            _ => return Ok(()),
        };
        const STATIONS: usize = 4;
        let (mut ua, mut ub) = (-SURFACE_EXTENT, SURFACE_EXTENT);
        let (mut va, mut vb) = (-SURFACE_EXTENT, SURFACE_EXTENT);
        for (_, _, _, curve, range) in uses {
            for step in 0..=STATIONS {
                #[allow(clippy::cast_precision_loss)]
                let t = range.0 + (range.1 - range.0) * (step as f64 / STATIONS as f64);
                let Ok(at) = curve.point_at(t, self.tol) else {
                    continue;
                };
                let (u, v) = along(at);
                if let Some(u) = u {
                    ua = ua.min(u);
                    ub = ub.max(u);
                }
                if let Some(v) = v {
                    va = va.min(v);
                    vb = vb.max(v);
                }
            }
        }
        let ((was_u, was_v), grown) = (surface.domain(), (ub - ua) * 0.05);
        if ua >= was_u.0 && ub <= was_u.1 && va >= was_v.0 && vb <= was_v.1 {
            return Ok(());
        }
        let (u, v) = (
            (ua.min(was_u.0) - grown, ub.max(was_u.1) + grown),
            (va.min(was_v.0) - grown, vb.max(was_v.1) + grown),
        );
        let wider = match surface {
            SurfaceGeometry::Plane(p) => PlaneSurface::over(p.plane(), u, v)?.into(),
            SurfaceGeometry::Cylinder(c) => CylinderSurface::new(c.cylinder(), v)?.into(),
            SurfaceGeometry::Cone(c) => ConeSurface::new(c.cone(), v)?.into(),
            SurfaceGeometry::Extrusion(e) => {
                ExtrusionSurface::over(e.curve().clone(), e.direction(), v)?.into()
            }
            other => other,
        };
        if let Some(held) = self.model.geometry_mut().surface_mut(surface_id) {
            *held = wider;
        }
        Ok(())
    }

    /// One bound's images, chained around the face's chart.
    ///
    /// Each is derived on its own (the exact projection where the pair has
    /// a closed form, the fitted one where it does not), and a periodic
    /// chart then leaves a branch to choose. Chosen edge by edge the choice
    /// is arbitrary and the wire comes apart: a drilled block's bore wall
    /// reads back with one rim two whole turns from the other, both the
    /// right circle and neither meeting the seam the wire closes on. So
    /// each image after the first is slid by whole periods until its start
    /// meets where the last one ended.
    ///
    /// A seam falls out of the same walk. The wire uses it twice, up one
    /// column of the chart and down the other, and those columns are one
    /// image a period apart, so the walk finds both, and the use that runs
    /// forward is the forward side. Where it cannot, because the chart
    /// closes without being periodic, the other column goes a chart's width
    /// over as it always did.
    fn chart_bound(
        &mut self,
        face_id: u64,
        uses: &[BoundUse],
        surface: &SurfaceGeometry,
        surface_id: ogeom_topo::SurfaceId,
        edge_uses: &HashMap<u64, usize>,
        annotated: &mut HashSet<u64>,
    ) -> OgeomResult<()> {
        use ogeom_geom::Curve2d as _;
        let mut images: HashMap<u64, PlanarCurve> = HashMap::new();
        let mut sides: HashMap<u64, (Option<PlanarCurve>, Option<PlanarCurve>)> = HashMap::new();
        let mut order: Vec<u64> = Vec::new();
        let mut previous: Option<ogeom_math::Point2> = None;
        for (placed, shape, edge_id, curve, range) in uses {
            if !images.contains_key(edge_id) {
                let Some(image) =
                    self.image_for(face_id, *edge_id, shape, curve, *range, surface)?
                else {
                    continue;
                };
                images.insert(*edge_id, image);
                order.push(*edge_id);
            }
            let Some(image) = images.get(edge_id).cloned() else {
                continue;
            };
            let backwards = placed.orientation() == ogeom_topo::Orientation::Reversed;
            let (start, end) = if backwards {
                (range.1, range.0)
            } else {
                (range.0, range.1)
            };
            let image =
                crate::pcurves::shifted_to_meet(&image, start, previous, surface, self.tol)?;
            previous = Some(image.point_at(end, self.tol)?);
            let walked = sides.entry(*edge_id).or_default();
            if backwards {
                walked.1 = Some(image);
            } else {
                walked.0 = Some(image);
            }
        }
        for edge_id in order {
            if !annotated.insert(edge_id) {
                continue;
            }
            let Some((shape, range)) = uses
                .iter()
                .find(|(_, _, id, _, _)| *id == edge_id)
                .map(|(_, shape, _, _, range)| (shape.clone(), *range))
            else {
                continue;
            };
            let Some(image) = images.get(&edge_id).cloned() else {
                continue;
            };
            let walked = sides.remove(&edge_id).unwrap_or((None, None));
            let seam = edge_uses.get(&edge_id).copied().unwrap_or(1) > 1;
            let columns = match &walked {
                (Some(forward), Some(reversed)) => {
                    let at = forward.point_at(range.0, self.tol)?;
                    let other = reversed.point_at(range.0, self.tol)?;
                    (at.distance(other) > self.tol.confusion())
                        .then(|| (forward.clone(), reversed.clone()))
                }
                _ => None,
            };
            match (seam, columns) {
                (true, Some((forward, reversed))) => {
                    self.record_columns(&shape, forward, reversed, surface_id, range)?;
                }
                (true, None) => {
                    self.record_pcurve(&shape, image, surface_id, true, range)?;
                }
                (false, _) => {
                    let (forward, reversed) = walked;
                    let placed = forward.or(reversed).unwrap_or(image);
                    self.record_pcurve(&shape, placed, surface_id, false, range)?;
                }
            }
        }
        Ok(())
    }

    fn image_for(
        &mut self,
        face_id: u64,
        edge_id: u64,
        edge: &Shape,
        curve: &Curve,
        range: (f64, f64),
        surface: &SurfaceGeometry,
    ) -> OgeomResult<Option<PlanarCurve>> {
        let widen = |p: PlanarCurve| -> PlanarCurve {
            // A line pcurve evaluates anywhere; its stated domain must still
            // cover the edge's range, which for a wrapped circle runs past
            // one period.
            if let PlanarCurve::Line(l) = &p {
                let (lo, hi) = (l.domain().0.min(range.0), l.domain().1.max(range.1));
                if let Ok(wider) = ogeom_geom::Line2d::over(l.axis(), lo, hi) {
                    return wider.into();
                }
            }
            p
        };
        // Claimed rather than derived, where the pass at the head of the solid
        // already did it. The fallbacks below stay exactly as they were, for
        // the faces no pass covered: a face reached outside a solid walk, or
        // one whose preparation refused.
        if let Some(prepared) = self.pcurves.remove(&(face_id, edge_id)) {
            match prepared {
                PreparedPcurve::Exact(exact) => {
                    return Ok(Some(widen(exact)));
                }
                PreparedPcurve::Fitted {
                    curve: fitted,
                    error,
                    met,
                    worst_off,
                    warning,
                } => {
                    if let Some(w) = warning {
                        self.warn_slop(w, worst_off, face_id);
                    }
                    if !met {
                        self.warn_fit_short(face_id, error);
                    }
                    if worst_off > self.tol.confusion()
                        && let Some(node) = self.model.node_mut(edge)
                        && let ogeom_topo::NodeData::Edge(data) = node.data_mut()
                    {
                        data.tolerance = data.tolerance.widen_to(worst_off + self.tol.confusion());
                    }
                    return Ok(Some(fitted));
                }
                PreparedPcurve::Refused(why) => {
                    self.report.warnings.push(why);
                    self.note_untrimmed(face_id);
                    return Ok(None);
                }
            }
        }
        let pcurve =
            match ogeom_intersect::exact_pcurve_over(curve, range, surface, self.tol).map(widen) {
                Some(exact) => exact,
                None => {
                    // No closed form: a spline surface, or a combination the
                    // projection table lacks. The pcurve is *fitted at the
                    // curve's own parameters*: sample the edge, project each
                    // sample into the chart, fit the trace with the parameters
                    // held fixed, so same-parameter is preserved by construction
                    // and the reported error is the true chart deviation.
                    match crate::pcurves::fit_projected_pcurve(curve, range, surface, self.tol) {
                        Ok((fitted, error, met, worst_off, slop_warning)) => {
                            if let Some(w) = slop_warning {
                                self.warn_slop(w, worst_off, face_id);
                            }
                            if !met {
                                self.warn_fit_short(face_id, error);
                            }
                            // The edge provably sits `worst_off` from the surface
                            // it bounds; its tolerance grows to cover that, the
                            // same honesty the vertex ends get.
                            if worst_off > self.tol.confusion()
                                && let Some(node) = self.model.node_mut(edge)
                                && let ogeom_topo::NodeData::Edge(data) = node.data_mut()
                            {
                                data.tolerance =
                                    data.tolerance.widen_to(worst_off + self.tol.confusion());
                            }
                            fitted
                        }
                        Err(e) => {
                            self.report.warnings.push(format!(
                                "face #{face_id}: no pcurve for an edge on this \
                             surface ({e}); the face may not triangulate"
                            ));
                            self.note_untrimmed(face_id);
                            return Ok(None);
                        }
                    }
                }
            };
        Ok(Some(pcurve))
    }

    /// Count one occurrence of a warning kind toward the summary.
    fn tally(&mut self, kind: &'static str, measured: f64, exemplar: u64) {
        let entry = self.tallies.entry(kind).or_insert((0, 0.0, exemplar));
        entry.0 += 1;
        if measured > entry.1 {
            entry.1 = measured;
            entry.2 = exemplar;
        }
    }

    /// A curve end missing its vertex: the prose, and the count.
    fn warn_vertex_miss(&mut self, id: u64, gap: f64) {
        self.report.warnings.push(format!(
            "#{id}: a curve end misses its vertex by {gap:.2e}; the vertex \
             tolerance grew to say so"
        ));
        self.tally("vertex-miss", gap, id);
    }

    /// A fitted trim that stopped short of its target: prose and count.
    fn warn_fit_short(&mut self, face_id: u64, error: f64) {
        self.report.warnings.push(format!(
            "face #{face_id}: a projected pcurve fit stopped at {error:.2e}; \
             the face's mesh may sit that far off along this edge"
        ));
        self.tally("fit-short", error, face_id);
    }

    /// The file's own boundary slop, carried and counted.
    fn warn_slop(&mut self, prose: String, worst: f64, exemplar: u64) {
        self.report.warnings.push(prose);
        self.tally("boundary-slop", worst, exemplar);
    }

    /// Note a face left without a complete trim, once.
    fn note_untrimmed(&mut self, face_id: u64) {
        if self.untrimmed_ids.last() != Some(&face_id) {
            self.untrimmed_ids.push(face_id);
            self.tally("untrimmed", 0.0, face_id);
        }
    }

    /// Attach a seam whose two columns the wire's own walk already found.
    fn record_columns(
        &mut self,
        edge: &Shape,
        forward: PlanarCurve,
        reversed: PlanarCurve,
        surface_id: ogeom_topo::SurfaceId,
        range: (f64, f64),
    ) -> OgeomResult<()> {
        ogeom_algo::attach_seam(
            &mut self.model,
            edge,
            forward,
            reversed,
            surface_id,
            Location::identity(),
            range,
        )
    }

    /// Attach a derived pcurve, seaming it where the edge bounds the chart
    /// twice and the walk could not say where its other column stands.
    fn record_pcurve(
        &mut self,
        edge: &Shape,
        pcurve: PlanarCurve,
        surface_id: ogeom_topo::SurfaceId,
        seam: bool,
        range: (f64, f64),
    ) -> OgeomResult<()> {
        if seam {
            let Some(surface) = self.model.geometry().surface(surface_id).cloned() else {
                ogeom_bail!(Dangling, "the surface is not in this model");
            };
            // One side is where the projection landed; the other is one
            // period over, along the axis the surface actually closes on.
            let other = crate::pcurves::seam_other_side(&pcurve, range, &surface, self.tol)?;
            ogeom_algo::attach_seam(
                &mut self.model,
                edge,
                pcurve,
                other,
                surface_id,
                Location::identity(),
                range,
            )?;
        } else {
            ogeom_algo::attach_pcurve(
                &mut self.model,
                edge,
                pcurve,
                surface_id,
                Location::identity(),
                range,
            )?;
        }
        Ok(())
    }

    /// Derive every pcurve this solid's faces will want, in parallel.
    ///
    /// Deriving one is a pure function of a curve, its range and a surface:
    /// it reads no model and depends on no order, and measured on a 330-solid
    /// assembly it is 95% of the time spent building solids. The walk that
    /// follows attaches them, in file order, exactly as it did when it derived
    /// them itself.
    ///
    /// Resolving *what* to derive still runs on the walk's own thread, since
    /// it builds edges and vertices into the model. That part is cheap; it is
    /// the projection and the fitting that are not.
    ///
    /// Best-effort by design: anything this cannot resolve is simply left out
    /// of the table, and `attach_pcurves` derives it the old way. So a face
    /// shape this does not anticipate costs time, never correctness.
    fn prepare_pcurves(&mut self, face_ids: &[u64]) {
        struct Job {
            face: u64,
            edge: u64,
            curve: Curve,
            range: (f64, f64),
            /// Index into `surfaces`. The surface is held once per face, not
            /// once per edge: a B-spline patch owns its whole control grid,
            /// and cloning that per edge costs more than the projection it
            /// was cloned for.
            surface: usize,
        }
        let mut surfaces: Vec<SurfaceGeometry> = Vec::new();
        let mut jobs: Vec<Job> = Vec::new();
        let mut seen: HashSet<(u64, u64)> = HashSet::new();
        for &fid in face_ids {
            let Ok(args) = self.face_args(fid) else {
                continue;
            };
            let Some(surface) = args
                .get(2)
                .and_then(Arg::reference)
                .and_then(|sid| self.surface(sid).ok().flatten())
            else {
                continue;
            };
            surfaces.push(surface);
            let at = surfaces.len() - 1;
            let bounds: Vec<u64> = args
                .get(1)
                .and_then(Arg::list)
                .unwrap_or(&[])
                .iter()
                .filter_map(Arg::reference)
                .collect();
            for bound in bounds {
                let Ok((loop_id, _)) = self.bound_args(bound) else {
                    continue;
                };
                let Ok(loop_args) = self.args(loop_id, "EDGE_LOOP") else {
                    continue;
                };
                let uses: Vec<u64> = loop_args
                    .get(1)
                    .and_then(Arg::list)
                    .unwrap_or(&[])
                    .iter()
                    .filter_map(Arg::reference)
                    .collect();
                for oe_id in uses {
                    let Ok(oargs) = self.args(oe_id, "ORIENTED_EDGE") else {
                        continue;
                    };
                    let Some(edge_id) = oargs.get(3).and_then(Arg::reference) else {
                        continue;
                    };
                    if !seen.insert((fid, edge_id)) {
                        continue;
                    }
                    if let Ok(Some((_, curve, range, _))) = self.edge(edge_id) {
                        jobs.push(Job {
                            face: fid,
                            edge: edge_id,
                            curve,
                            range,
                            surface: at,
                        });
                    }
                }
            }
        }
        // Below a handful of edges the threads cost more than the work; the
        // sequential path through `attach_pcurves` is already correct, so the
        // table is simply left empty and the walk derives them itself.
        if jobs.len() < 16 {
            return;
        }
        let tol = self.tol;
        let derived = ogeom_core::parallel::map_ordered(&jobs, |_, job| {
            let surface = &surfaces[job.surface];
            match ogeom_intersect::exact_pcurve_over(&job.curve, job.range, surface, tol) {
                Some(exact) => PreparedPcurve::Exact(exact),
                None => {
                    match crate::pcurves::fit_projected_pcurve(&job.curve, job.range, surface, tol)
                    {
                        Ok((curve, error, met, worst_off, warning)) => PreparedPcurve::Fitted {
                            curve,
                            error,
                            met,
                            worst_off,
                            warning,
                        },
                        Err(e) => PreparedPcurve::Refused(format!(
                            "face #{}: no pcurve for an edge on this surface ({e}); \
                         the face may not triangulate",
                            job.face
                        )),
                    }
                }
            }
        });
        for (job, pcurve) in jobs.iter().zip(derived) {
            self.pcurves.insert((job.face, job.edge), pcurve);
        }
    }

    /// The solid a `MANIFOLD_SOLID_BREP` names: its shell's faces, sewn.
    ///
    /// `BREP_WITH_VOIDS` is the same entity with cavities: a subtype of
    /// `MANIFOLD_SOLID_BREP`, so its first two attributes are the name and
    /// the outer shell, and a third names the shells that bound the voids.
    /// A reader matching on the leading keyword alone does not see it, and
    /// the part simply vanishes: a printed housing with six cavities in
    /// it read as no body at all, its thirteen hundred faces with it. The
    /// voids join the solid as shells of their own, oriented as
    /// the file orients them, so every normal points away from the
    /// material: out of the body on the outside, into the cavity within.
    fn solid(&mut self, id: u64) -> OgeomResult<Shape> {
        let instance = self.instance(id)?;
        let args = instance
            .part("MANIFOLD_SOLID_BREP")
            .or_else(|| instance.part("BREP_WITH_VOIDS"))
            .ok_or_else(|| ogeom_core::ogeom_err!(Construction, "#{id} is not a solid"))?
            .to_vec();
        let shell_id = args.get(1).and_then(Arg::reference).unwrap_or(0);
        let Some(shell) = self.shell(shell_id)? else {
            ogeom_bail!(Construction, "#{id}: a solid with no readable faces");
        };
        if !ogeom_algo::is_shell_closed(&self.model, &shell)? {
            self.report.warnings.push(format!(
                "#{id}: the shell does not close as read; measures needing an \
                 inside will refuse it"
            ));
        }
        let mut shells = vec![shell];
        for void_id in args
            .get(2)
            .and_then(Arg::list)
            .unwrap_or(&[])
            .iter()
            .filter_map(Arg::reference)
            .collect::<Vec<u64>>()
        {
            match self.shell(void_id) {
                Ok(Some(void)) => shells.push(void),
                Ok(None) => self.report.warnings.push(format!(
                    "#{id}: void shell #{void_id} has no readable faces; the \
                     cavity is missing from the solid"
                )),
                Err(refusal) => self.report.warnings.push(format!(
                    "#{id}: void shell #{void_id} could not be read ({refusal}); \
                     the cavity is missing from the solid"
                )),
            }
        }
        Ok(make_solid(&mut self.model, &shells)?.shape)
    }

    /// The shape a `SHELL_BASED_SURFACE_MODEL` names: each of its shells
    /// sewn from its faces, a compound of them when there are several.
    ///
    /// A surface body is what a modeller exports for a part built from
    /// faces rather than from a solid (a motor coupler drawn as
    /// seventy-three single-face bodies is a real case), and a reader that
    /// walks only `MANIFOLD_SOLID_BREP` leaves such a part invisible. The
    /// shells stay shells: the file did not call them solids, and a closed
    /// one is still the file's surface model, not this reader's promotion.
    fn surface_model(&mut self, id: u64) -> OgeomResult<Shape> {
        let args = self.args(id, "SHELL_BASED_SURFACE_MODEL")?;
        let shell_ids: Vec<u64> = args
            .get(1)
            .and_then(Arg::list)
            .unwrap_or(&[])
            .iter()
            .filter_map(Arg::reference)
            .collect();
        let mut shells = Vec::new();
        for shell_id in shell_ids {
            if let Some(shell) = self.shell(shell_id)? {
                shells.push(shell);
            }
        }
        match shells.len() {
            0 => ogeom_bail!(
                Construction,
                "#{id}: a surface model with no readable faces"
            ),
            1 => Ok(shells.remove(0)),
            _ => Ok(ogeom_algo::build::make_compound(&mut self.model, &shells)?.shape),
        }
    }

    /// The faces of a `CLOSED_SHELL` or `OPEN_SHELL`, sewn; `None` when not
    /// one of them could be read.
    ///
    /// An `ORIENTED_CLOSED_SHELL` is a use of another shell the other way
    /// round (how a solid's voids are named) and resolves to that shell,
    /// reversed when the use says so.
    fn shell(&mut self, shell_id: u64) -> OgeomResult<Option<Shape>> {
        let shell_instance = self.instance(shell_id)?;
        if let Some(oriented) = shell_instance
            .part("ORIENTED_CLOSED_SHELL")
            .map(<[Arg]>::to_vec)
        {
            let Some(base) = oriented.get(2).and_then(Arg::reference) else {
                ogeom_bail!(Construction, "#{shell_id}: an oriented shell names none");
            };
            let forward = !oriented.get(3).is_some_and(|a| a.is_enum("F"));
            return Ok(self
                .shell(base)?
                .map(|shell| if forward { shell } else { shell.reversed() }));
        }
        let shell_args = shell_instance
            .part("CLOSED_SHELL")
            .or_else(|| shell_instance.part("OPEN_SHELL"))
            .ok_or_else(|| ogeom_core::ogeom_err!(Construction, "#{shell_id} is not a shell"))?
            .to_vec();
        let face_ids: Vec<u64> = shell_args
            .get(1)
            .and_then(Arg::list)
            .unwrap_or(&[])
            .iter()
            .filter_map(Arg::reference)
            .collect();
        self.prepare_pcurves(&face_ids);
        let mut faces = Vec::new();
        for fid in face_ids {
            if let Some(face) = self.face(fid)? {
                faces.push(face);
            }
        }
        if faces.is_empty() {
            return Ok(None);
        }
        Ok(Some(make_shell(&mut self.model, &faces)?.shape))
    }

    // --- product structure, names, colours -----------------------------------

    /// Assemble the document: the model, plus everything the file says about
    /// products, assemblies, placements and appearance.
    ///
    /// Takes the model out of the reader; geometry reading is over by the
    /// time structure is read. Structure that resists becomes a warning and a
    /// flat document, never an error: the geometry is already good, and a
    /// mangled product tree should not take it down.
    fn document(
        &mut self,
        by_item: &HashMap<u64, Shape>,
        solids: &[Shape],
        shells: &[Shape],
    ) -> OgeomResult<ogeom_doc::Document> {
        // The graph is walked before the model moves, because frames scale
        // through the reader's own unit handling.
        let structure = self.product_structure(by_item);
        let colours = self.colours(by_item);
        let pmi = self.pmi_of();

        let mut document = ogeom_doc::Document::over(std::mem::take(&mut self.model));
        match structure {
            Some(products) => self.build_products(&mut document, products),
            None => {
                for (i, solid) in solids.iter().enumerate() {
                    document.add_part(format!("solid-{i}"), solid.clone());
                }
                for (i, shell) in shells.iter().enumerate() {
                    document.add_part(format!("shell-{i}"), shell.clone());
                }
            }
        }
        for (shape, colour) in colours {
            document.set_colour(&shape, colour);
        }
        *document.pmi_mut() = pmi;
        for view in self.views() {
            document.add_view(view);
        }
        Ok(document)
    }

    /// The file's product graph, or `None` when it has none worth the name.
    fn product_structure(&mut self, by_item: &HashMap<u64, Shape>) -> Option<Vec<PdEntry>> {
        // PRODUCT_DEFINITION -> name, via formation and product.
        let mut pds: Vec<u64> = self
            .exchange
            .data
            .iter()
            .filter(|(_, inst)| inst.part("PRODUCT_DEFINITION").is_some())
            .filter(|(_, inst)| inst.part("PRODUCT_DEFINITION_RELATIONSHIP").is_none())
            .map(|(id, _)| *id)
            .collect();
        pds.sort_unstable();
        if pds.is_empty() {
            return None;
        }

        // SHAPE_DEFINITION_REPRESENTATION: definition (a PRODUCT_DEFINITION_SHAPE
        // over a PD or a usage) -> shape representation.
        let mut sr_of_pd: HashMap<u64, u64> = HashMap::new();
        let sdrs: Vec<(u64, u64)> = self
            .exchange
            .data
            .iter()
            .filter(|(_, inst)| inst.part("SHAPE_DEFINITION_REPRESENTATION").is_some())
            .filter_map(|(id, _)| {
                let args = self.args(*id, "SHAPE_DEFINITION_REPRESENTATION").ok()?;
                Some((args.first()?.reference()?, args.get(1)?.reference()?))
            })
            .collect();
        for (pds_id, sr) in sdrs {
            if let Some(definition) = self.definition_of_shape(pds_id) {
                sr_of_pd.insert(definition, sr);
            }
        }

        // A product's solids may live one representation over: AP203 files
        // routinely tie the product to a bare axis representation and hang
        // the B-rep off it through a plain SHAPE_REPRESENTATION_RELATIONSHIP.
        // Only the plain ones are followed; the transformation-carrying kind
        // is an assembly edge, and following it would leak one product's
        // geometry into another.
        let mut linked: HashMap<u64, Vec<u64>> = HashMap::new();
        let mut srrs: Vec<u64> = self
            .exchange
            .data
            .iter()
            .filter(|(_, inst)| {
                inst.part("SHAPE_REPRESENTATION_RELATIONSHIP").is_some()
                    && inst
                        .part("REPRESENTATION_RELATIONSHIP_WITH_TRANSFORMATION")
                        .is_none()
            })
            .map(|(id, _)| *id)
            .collect();
        srrs.sort_unstable();
        for srr in srrs {
            let args = {
                let Ok(instance) = self.instance(srr) else {
                    continue;
                };
                let Some(args) = instance
                    .part("SHAPE_REPRESENTATION_RELATIONSHIP")
                    .or_else(|| instance.part("REPRESENTATION_RELATIONSHIP"))
                else {
                    continue;
                };
                args.to_vec()
            };
            if let (Some(a), Some(b)) = (
                args.get(2).and_then(Arg::reference),
                args.get(3).and_then(Arg::reference),
            ) {
                linked.entry(a).or_default().push(b);
                linked.entry(b).or_default().push(a);
            }
        }

        let mut entries = Vec::new();
        for pd in pds {
            let name = self.product_name(pd).unwrap_or_else(|| format!("#{pd}"));
            let mut shapes: Vec<Shape> = Vec::new();
            if let Some(&sr) = sr_of_pd.get(&pd) {
                let mut reps = vec![sr];
                reps.extend(linked.get(&sr).into_iter().flatten().copied());
                for rep in reps {
                    if let Some(items) = self.representation_items(rep) {
                        shapes.extend(items.iter().filter_map(|item| by_item.get(item).cloned()));
                    }
                }
            }
            entries.push(PdEntry {
                pd,
                name,
                shapes,
                children: Vec::new(),
            });
        }

        // NEXT_ASSEMBLY_USAGE_OCCURRENCE: parent -> child, with the placement
        // recovered from the CONTEXT_DEPENDENT_SHAPE_REPRESENTATION over it.
        let mut nauos: Vec<u64> = self
            .exchange
            .data
            .iter()
            .filter(|(_, inst)| inst.part("NEXT_ASSEMBLY_USAGE_OCCURRENCE").is_some())
            .map(|(id, _)| *id)
            .collect();
        nauos.sort_unstable();
        let entry_of_pd: HashMap<u64, usize> =
            entries.iter().enumerate().map(|(i, e)| (e.pd, i)).collect();
        for nauo in nauos {
            let Ok(args) = self.args(nauo, "NEXT_ASSEMBLY_USAGE_OCCURRENCE") else {
                continue;
            };
            let (Some(parent), Some(child)) = (
                args.get(3).and_then(Arg::reference),
                args.get(4).and_then(Arg::reference),
            ) else {
                continue;
            };
            let name = args
                .get(5)
                .and_then(|a| match a {
                    Arg::Str(s) if !s.is_empty() => Some(s.clone()),
                    _ => None,
                })
                .or_else(|| {
                    self.args(nauo, "NEXT_ASSEMBLY_USAGE_OCCURRENCE")
                        .ok()
                        .and_then(|args| match args.get(1) {
                            Some(Arg::Str(s)) if !s.is_empty() => Some(s.clone()),
                            _ => None,
                        })
                });
            let child_sr = sr_of_pd.get(&child).copied();
            let at = self
                .usage_transform(nauo, child_sr)
                .unwrap_or(Transform::IDENTITY);
            if let Some(&at_index) = entry_of_pd.get(&parent) {
                entries[at_index].children.push((child, at, name));
            }
        }
        Some(entries)
    }

    /// The `PRODUCT_DEFINITION` (or usage) a `PRODUCT_DEFINITION_SHAPE` is over.
    fn definition_of_shape(&mut self, pds_id: u64) -> Option<u64> {
        let args = self.args(pds_id, "PRODUCT_DEFINITION_SHAPE").ok()?;
        args.get(2).and_then(Arg::reference)
    }

    /// A product definition's product name.
    fn product_name(&mut self, pd: u64) -> Option<String> {
        let formation = self
            .args(pd, "PRODUCT_DEFINITION")
            .ok()?
            .get(2)
            .and_then(Arg::reference)?;
        // The formation, plain or with its source named (a mesh converter's
        // habit, and a modeller's for an assembly's parts) carries the
        // product in its third slot either way, whether it stands alone or
        // as one part of a complex instance.
        let product = [
            "PRODUCT_DEFINITION_FORMATION",
            "PRODUCT_DEFINITION_FORMATION_WITH_SPECIFIED_SOURCE",
        ]
        .into_iter()
        .find_map(|keyword| {
            self.instance(formation)
                .ok()?
                .part(keyword)
                .map(<[Arg]>::to_vec)
                .or_else(|| self.args(formation, keyword).ok())?
                .get(2)
                .and_then(Arg::reference)
        })?;
        // The product's name, or its id where the name is blank: a mesh
        // converter fills the id and leaves the name empty.
        let args = self.args(product, "PRODUCT").ok()?;
        [args.get(1), args.first()]
            .into_iter()
            .find_map(|arg| match arg {
                Some(Arg::Str(name)) if !name.is_empty() => Some(name.clone()),
                _ => None,
            })
    }

    /// A representation's item references.
    fn representation_items(&mut self, sr: u64) -> Option<Vec<u64>> {
        let instance = self.instance(sr).ok()?;
        // Every subtype a file names a shape representation by: the B-rep
        // kinds, the surface-model kinds a mesh converter writes, and the
        // plain one.
        let args = [
            "SHAPE_REPRESENTATION",
            "ADVANCED_BREP_SHAPE_REPRESENTATION",
            "MANIFOLD_SURFACE_SHAPE_REPRESENTATION",
            "FACETED_BREP_SHAPE_REPRESENTATION",
            "GEOMETRICALLY_BOUNDED_SURFACE_SHAPE_REPRESENTATION",
            "GEOMETRICALLY_BOUNDED_WIREFRAME_SHAPE_REPRESENTATION",
            "REPRESENTATION",
        ]
        .into_iter()
        .find_map(|keyword| instance.part(keyword))?
        .to_vec();
        Some(
            args.get(1)?
                .list()?
                .iter()
                .filter_map(Arg::reference)
                .collect(),
        )
    }

    /// The placement a usage's `CONTEXT_DEPENDENT_SHAPE_REPRESENTATION` states.
    ///
    /// The transformation aligns an axis placement in the child's space with
    /// one in the parent's; which item is which follows from which side of
    /// the representation relationship is the child's own shape
    /// representation, not from argument order, because real files disagree
    /// about the order.
    fn usage_transform(&mut self, nauo: u64, child_sr: Option<u64>) -> Option<Transform> {
        if self.cdsr_of_nauo.is_none() {
            // One pass over the CDSRs, each resolved to the usage it
            // describes; ascending id order so a usage described twice keeps
            // the same one the old lowest-id-first scan chose.
            let mut cdsrs: Vec<u64> = self
                .exchange
                .data
                .iter()
                .filter(|(_, inst)| {
                    inst.part("CONTEXT_DEPENDENT_SHAPE_REPRESENTATION")
                        .is_some()
                })
                .map(|(id, _)| *id)
                .collect();
            cdsrs.sort_unstable();
            let mut index: HashMap<u64, u64> = HashMap::new();
            for id in cdsrs {
                let Some(owner) = self
                    .args(id, "CONTEXT_DEPENDENT_SHAPE_REPRESENTATION")
                    .ok()
                    .and_then(|args| args.get(1).and_then(Arg::reference))
                    .and_then(|pds| self.definition_of_shape(pds))
                else {
                    continue;
                };
                index.entry(owner).or_insert(id);
            }
            self.cdsr_of_nauo = Some(index);
        }
        let cdsr = *self.cdsr_of_nauo.as_ref()?.get(&nauo)?;
        let rr = self
            .args(cdsr, "CONTEXT_DEPENDENT_SHAPE_REPRESENTATION")
            .ok()?
            .first()
            .and_then(Arg::reference)?;
        let (rep_1, rep_2) = {
            let args = self.args(rr, "REPRESENTATION_RELATIONSHIP").ok()?;
            (
                args.get(2).and_then(Arg::reference)?,
                args.get(3).and_then(Arg::reference)?,
            )
        };
        let idt = self
            .args(rr, "REPRESENTATION_RELATIONSHIP_WITH_TRANSFORMATION")
            .ok()?
            .first()
            .and_then(Arg::reference)?;
        let (item_1, item_2) = {
            let args = self.args(idt, "ITEM_DEFINED_TRANSFORMATION").ok()?;
            (
                args.get(2).and_then(Arg::reference)?,
                args.get(3).and_then(Arg::reference)?,
            )
        };
        let frame_1 = self.frame(item_1).ok()?;
        let frame_2 = self.frame(item_2).ok()?;
        // item_1 pairs with rep_1. When rep_1 is the child's representation,
        // the child's frame_1 lands on the parent's frame_2.
        let child_first = match child_sr {
            Some(sr) => rep_1 == sr || rep_2 != sr,
            None => true,
        };
        Some(if child_first {
            Transform::from_frame(&frame_2) * Transform::to_frame(&frame_1)
        } else {
            Transform::from_frame(&frame_1) * Transform::to_frame(&frame_2)
        })
    }

    /// Products into the document: assemblies for the parents, parts for the
    /// shaped, instances for the usage edges.
    fn build_products(&mut self, document: &mut ogeom_doc::Document, entries: Vec<PdEntry>) {
        let mut ids: HashMap<u64, ogeom_doc::ProductId> = HashMap::new();
        for entry in &entries {
            let shape = match entry.shapes.len() {
                0 => None,
                1 => Some(entry.shapes[0].clone()),
                _ => match ogeom_algo::build::make_compound(document.model_mut(), &entry.shapes) {
                    Ok(built) => Some(built.shape),
                    Err(_) => Some(entry.shapes[0].clone()),
                },
            };
            if entry.children.is_empty() {
                if let Some(shape) = shape {
                    ids.insert(entry.pd, document.add_part(&entry.name, shape));
                }
                // A product with neither shape nor children holds nothing a
                // document can say; it is left out.
            } else {
                let assembly = document.add_assembly(&entry.name);
                ids.insert(entry.pd, assembly);
                // An assembly with its own geometry keeps it as a body part
                // placed at identity: rare, but files do it.
                if let Some(shape) = shape {
                    let body = document.add_part(format!("{}-body", entry.name), shape);
                    let _ = document.add_instance(assembly, body, Transform::IDENTITY, None);
                }
            }
        }
        for entry in &entries {
            let Some(&parent) = ids.get(&entry.pd) else {
                continue;
            };
            for (child, at, name) in &entry.children {
                let Some(&child_id) = ids.get(child) else {
                    self.report.warnings.push(format!(
                        "#{child}: an assembly child holds nothing readable"
                    ));
                    continue;
                };
                if let Err(e) = document.add_instance(parent, child_id, *at, name.clone()) {
                    self.report
                        .warnings
                        .push(format!("assembly edge #{} -> #{child}: {e}", entry.pd));
                }
            }
        }
    }

    /// Colours from styled items, keyed to the shapes they style.
    fn colours(&mut self, by_item: &HashMap<u64, Shape>) -> Vec<(Shape, ogeom_doc::Colour)> {
        let mut styled: Vec<u64> = self
            .exchange
            .data
            .iter()
            .filter(|(_, inst)| {
                inst.part("STYLED_ITEM").is_some() || inst.part("OVER_RIDING_STYLED_ITEM").is_some()
            })
            .map(|(id, _)| *id)
            .collect();
        // Sorted so an item styled twice resolves the same way every run;
        // overriding styles carry higher instance numbers in practice, and a
        // later same-shape entry wins the map insertion downstream.
        styled.sort_unstable();
        let mut out = Vec::new();
        for id in styled {
            let args = {
                let Ok(instance) = self.instance(id) else {
                    continue;
                };
                let Some(args) = instance
                    .part("STYLED_ITEM")
                    .or_else(|| instance.part("OVER_RIDING_STYLED_ITEM"))
                else {
                    continue;
                };
                args.to_vec()
            };
            let Some(item) = args.get(2).and_then(Arg::reference) else {
                continue;
            };
            let Some(shape) = by_item.get(&item).or_else(|| self.faces.get(&item)) else {
                continue;
            };
            let styles: Vec<u64> = args
                .get(1)
                .and_then(Arg::list)
                .map(|list| list.iter().filter_map(Arg::reference).collect())
                .unwrap_or_default();
            let shape = shape.clone();
            if let Some(colour) = styles.iter().find_map(|&style| self.colour_in(style, 0)) {
                out.push((shape, colour));
            }
        }
        out
    }

    /// The first `COLOUR_RGB` reachable from a presentation style, depth-bounded.
    ///
    /// The styled-item chain has five links and real files rearrange them, so
    /// the walk follows references rather than the textbook path.
    fn colour_in(&mut self, id: u64, depth: usize) -> Option<ogeom_doc::Colour> {
        if depth > 6 {
            return None;
        }
        let (keyword, args) = {
            let instance = self.instance(id).ok()?;
            let all: Vec<Arg> = instance
                .parts()
                .flat_map(|(_, args)| args.iter().cloned())
                .collect();
            (instance.keyword().to_owned(), all)
        };
        if keyword == "COLOUR_RGB" {
            let channel = |i: usize| args.get(i).and_then(Arg::number);
            return Some(ogeom_doc::Colour::rgb(
                channel(1)?,
                channel(2)?,
                channel(3)?,
            ));
        }
        let mut refs: Vec<u64> = Vec::new();
        collect_refs(&args, &mut refs);
        refs.into_iter()
            .find_map(|next| self.colour_in(next, depth + 1))
    }

    // --- semantic PMI --------------------------------------------------------

    /// The file's semantic PMI: dimensions, geometric tolerances, datums.
    ///
    /// Annotations that resist stay out with a warning; PMI never takes the
    /// geometry down.
    fn pmi_of(&mut self) -> ogeom_doc::Pmi {
        let mut pmi = ogeom_doc::Pmi::new();
        // Which STEP instance each annotation came from, so the presentation
        // pass can name the annotation a callout draws exactly rather than by
        // matching a string two annotations may share.
        let mut annotation_ids: HashMap<u64, ogeom_doc::Annotated> = HashMap::new();

        // Which topology each shape aspect describes: directly through
        // GEOMETRIC_ITEM_SPECIFIC_USAGE, and one relationship step outward,
        // because composite aspects hold their pieces through relationships.
        let mut aspect_items: HashMap<u64, Vec<ogeom_topo::TShapeId>> = HashMap::new();
        let mut gisus = self.ids_with("GEOMETRIC_ITEM_SPECIFIC_USAGE");
        gisus.sort_unstable();
        for id in gisus {
            let Ok(args) = self.args(id, "GEOMETRIC_ITEM_SPECIFIC_USAGE") else {
                continue;
            };
            let (Some(aspect), Some(item)) = (
                args.get(2).and_then(Arg::reference),
                args.get(4).and_then(Arg::reference),
            ) else {
                continue;
            };
            let node = self
                .faces
                .get(&item)
                .map(Shape::node)
                .or_else(|| self.edges.get(&item).map(|(shape, ..)| shape.node()));
            if let Some(node) = node {
                aspect_items.entry(aspect).or_default().push(node);
            }
        }
        let mut adjacency: HashMap<u64, Vec<u64>> = HashMap::new();
        for id in self.ids_with("SHAPE_ASPECT_RELATIONSHIP") {
            let Ok(args) = self.args(id, "SHAPE_ASPECT_RELATIONSHIP") else {
                continue;
            };
            if let (Some(a), Some(b)) = (
                args.get(2).and_then(Arg::reference),
                args.get(3).and_then(Arg::reference),
            ) {
                adjacency.entry(a).or_default().push(b);
                adjacency.entry(b).or_default().push(a);
            }
        }
        let items_for = |aspect: u64| -> Vec<ogeom_topo::TShapeId> {
            // Three relationship steps: a composite aspect holds components,
            // a derived aspect sits behind a composite, and a datum one link
            // behind its features: the deepest chain the corpus exhibits.
            let mut reach = vec![aspect];
            for _ in 0..3 {
                let mut next = reach.clone();
                for a in &reach {
                    next.extend(adjacency.get(a).into_iter().flatten().copied());
                }
                next.sort_unstable();
                next.dedup();
                reach = next;
            }
            let mut out: Vec<ogeom_topo::TShapeId> = Vec::new();
            for a in reach {
                out.extend(aspect_items.get(&a).into_iter().flatten().copied());
            }
            out.sort_unstable();
            out.dedup();
            out
        };

        // Dimensions: characteristic -> representation, values from the
        // measure items, bounds from any plus/minus tolerance over the same
        // characteristic.
        let mut plus_minus: HashMap<u64, (Option<f64>, Option<f64>)> = HashMap::new();
        for id in self.ids_with("PLUS_MINUS_TOLERANCE") {
            let Ok(args) = self.args(id, "PLUS_MINUS_TOLERANCE") else {
                continue;
            };
            let (Some(tv), Some(dim)) = (
                args.first().and_then(Arg::reference),
                args.get(1).and_then(Arg::reference),
            ) else {
                continue;
            };
            let Ok(tv_args) = self.args(tv, "TOLERANCE_VALUE") else {
                continue;
            };
            let lower = tv_args
                .first()
                .and_then(Arg::reference)
                .and_then(|r| self.measure_value(r))
                .map(|(v, _)| v);
            let upper = tv_args
                .get(1)
                .and_then(Arg::reference)
                .and_then(|r| self.measure_value(r))
                .map(|(v, _)| v);
            plus_minus.insert(dim, (lower, upper));
        }
        let mut dcrs = self.ids_with("DIMENSIONAL_CHARACTERISTIC_REPRESENTATION");
        dcrs.sort_unstable();
        for id in dcrs {
            let Ok(args) = self.args(id, "DIMENSIONAL_CHARACTERISTIC_REPRESENTATION") else {
                continue;
            };
            let (Some(dim), Some(sdr)) = (
                args.first().and_then(Arg::reference),
                args.get(1).and_then(Arg::reference),
            ) else {
                continue;
            };
            let mut values = Vec::new();
            let mut kind = ogeom_doc::MeasureKind::Length;
            if let Ok(sdr_args) = self.args(sdr, "SHAPE_DIMENSION_REPRESENTATION") {
                for item in sdr_args.get(1).and_then(Arg::list).unwrap_or(&[]) {
                    if let Some(r) = item.reference()
                        && let Some((v, k)) = self.measure_value(r)
                    {
                        values.push(v);
                        kind = k;
                    }
                }
            }
            let (name, location, aspects) = self.dimension_shape(dim);
            let features: Vec<Vec<ogeom_topo::TShapeId>> =
                aspects.into_iter().map(&items_for).collect();
            let (minus, plus) = plus_minus.get(&dim).copied().unwrap_or((None, None));
            annotation_ids.insert(dim, ogeom_doc::Annotated::Dimension(pmi.dimensions.len()));
            pmi.dimensions.push(ogeom_doc::Dimension {
                name,
                values,
                kind,
                plus,
                minus,
                features,
                location,
            });
        }

        // Geometric tolerances: any instance whose subtype names one. The
        // complex form keeps its attributes on the GEOMETRIC_TOLERANCE part;
        // the simple form flattens them into the subtype's own list.
        let is_subtype = |k: &str| {
            k.ends_with("_TOLERANCE")
                && !matches!(
                    k,
                    "GEOMETRIC_TOLERANCE"
                        | "GEOMETRIC_TOLERANCE_WITH_DATUM_REFERENCE"
                        | "GEOMETRIC_TOLERANCE_WITH_DEFINED_UNIT"
                        | "GEOMETRIC_TOLERANCE_WITH_MODIFIERS"
                        | "GEOMETRIC_TOLERANCE_WITH_MAXIMUM_TOLERANCE"
                        | "PLUS_MINUS_TOLERANCE"
                        | "TOLERANCE_VALUE"
                )
        };
        let mut gts: Vec<u64> = self
            .exchange
            .data
            .iter()
            .filter(|(_, inst)| inst.parts().any(|(k, _)| is_subtype(k)))
            .map(|(id, _)| *id)
            .collect();
        gts.sort_unstable();
        for id in gts {
            let (name, magnitude_ref, aspect, kind, modifiers, datum_refs) = {
                let Ok(instance) = self.instance(id) else {
                    continue;
                };
                let subtype = instance
                    .parts()
                    .map(|(k, _)| k.to_owned())
                    .find(|k| is_subtype(k));
                let Some(subtype) = subtype else {
                    continue;
                };
                let base = instance
                    .part("GEOMETRIC_TOLERANCE")
                    .or_else(|| instance.part(&subtype))
                    .unwrap_or(&[])
                    .to_vec();
                let name = match base.first() {
                    Some(Arg::Str(s)) => s.clone(),
                    _ => String::new(),
                };
                let magnitude_ref = base.get(2).and_then(Arg::reference);
                let aspect = base.get(3).and_then(Arg::reference);
                let kind = Some(subtype.trim_end_matches("_TOLERANCE").to_lowercase());
                // Modifiers ride on their own part in the complex form, as
                // a list of enumeration words.
                let modifiers: Vec<String> = instance
                    .part("GEOMETRIC_TOLERANCE_WITH_MODIFIERS")
                    .and_then(|args| args.first())
                    .and_then(Arg::list)
                    .map(|list| {
                        list.iter()
                            .filter_map(|arg| match arg {
                                Arg::Enum(word) => Some(word.to_lowercase()),
                                _ => None,
                            })
                            .collect()
                    })
                    .unwrap_or_default();
                // The complex form keeps the datum list on its own part;
                // the simple form appends it as the subtype's fifth argument.
                let datum_refs: Vec<u64> = instance
                    .part("GEOMETRIC_TOLERANCE_WITH_DATUM_REFERENCE")
                    .and_then(|args| args.first())
                    .and_then(Arg::list)
                    .or_else(|| base.get(4).and_then(Arg::list))
                    .map(|list| list.iter().filter_map(Arg::reference).collect())
                    .unwrap_or_default();
                (name, magnitude_ref, aspect, kind, modifiers, datum_refs)
            };
            let Some(kind) = kind else {
                continue;
            };
            let magnitude = magnitude_ref
                .and_then(|r| self.measure_value(r))
                .map_or(0.0, |(v, _)| v);
            let datums: Vec<String> = datum_refs
                .iter()
                .filter_map(|&r| self.datum_letter(r, 0))
                .collect();
            let items = aspect.map(items_for).unwrap_or_default();
            annotation_ids.insert(id, ogeom_doc::Annotated::Tolerance(pmi.tolerances.len()));
            pmi.tolerances.push(ogeom_doc::GeometricTolerance {
                kind,
                name,
                magnitude,
                modifiers,
                datums,
                items,
            });
        }

        // Datums: the letters, with the features they mark reached through
        // the aspect graph.
        let mut datums = self.ids_with("DATUM");
        datums.sort_unstable();
        for id in datums {
            let letter = {
                let Ok(instance) = self.instance(id) else {
                    continue;
                };
                if instance.part("DATUM_FEATURE").is_some()
                    || instance.part("DATUM_REFERENCE").is_some()
                    || instance.part("DATUM_REFERENCE_COMPARTMENT").is_some()
                    || instance.part("DATUM_SYSTEM").is_some()
                {
                    continue;
                }
                let Some(args) = instance.part("DATUM") else {
                    continue;
                };
                match args.get(4) {
                    Some(Arg::Str(s)) if !s.is_empty() => s.clone(),
                    _ => continue,
                }
            };
            annotation_ids.insert(id, ogeom_doc::Annotated::Datum(pmi.datums.len()));
            pmi.datums.push(ogeom_doc::Datum {
                label: letter,
                items: items_for(id),
            });
        }

        // Datum targets: the pads a datum is actually established at. The
        // target's identifier is the letter's number (`A1` is target 1 of
        // datum A), and its placement and size come through the shape
        // representation the feature is associated with.
        let mut targets = self.ids_with("PLACED_DATUM_TARGET_FEATURE");
        targets.sort_unstable();
        for id in targets {
            if let Some(target) = self.datum_target(id, &items_for) {
                pmi.targets.push(target);
            }
        }

        // Presentation: what a viewer draws. A callout holds tessellated
        // annotation occurrences, each an indexed set of polylines over a
        // coordinates list; an annotation plane says which plane they are
        // drawn in and which callouts it holds; and a model item association
        // says which semantic annotation a callout is the picture of.
        let (callouts, callout_index) = self.callouts(&annotation_ids);
        pmi.callouts = callouts;
        self.callout_index = callout_index;
        pmi
    }

    /// Saved views: every *named* draughting model is one; the unnamed one
    /// is the annotation-plane container this writer emits itself. The
    /// camera item gives the frame; the callout items give the subset.
    fn views(&mut self) -> Vec<ogeom_doc::View> {
        let mut out = Vec::new();
        for id in self.ids_with("DRAUGHTING_MODEL") {
            let Ok(args) = self.args(id, "DRAUGHTING_MODEL") else {
                continue;
            };
            let name = match args.first() {
                Some(Arg::Str(text)) => text.clone(),
                _ => String::new(),
            };
            if name.is_empty() {
                continue;
            }
            let mut frame = None;
            let mut callouts = Vec::new();
            for item in args.get(1).and_then(Arg::list).unwrap_or(&[]) {
                let Some(item) = item.reference() else {
                    continue;
                };
                if let Ok(cam) = self.args(item, "CAMERA_MODEL_D3") {
                    if let Some(placement) = cam.get(1).and_then(Arg::reference) {
                        frame = self.frame(placement).ok();
                    }
                    continue;
                }
                if let Some(&index) = self.callout_index.get(&item) {
                    callouts.push(index);
                }
            }
            let Some(frame) = frame else { continue };
            out.push(ogeom_doc::View {
                name,
                frame,
                clipping: None,
                callouts,
            });
        }
        out
    }

    /// One placed datum target: which datum, which number, where and how big.
    fn datum_target(
        &mut self,
        id: u64,
        items_for: &dyn Fn(u64) -> Vec<ogeom_topo::TShapeId>,
    ) -> Option<ogeom_doc::DatumTarget> {
        let (target_id, description) = {
            let instance = self.instance(id).ok()?;
            let args = instance.part("PLACED_DATUM_TARGET_FEATURE")?;
            let target = match args.get(4) {
                Some(Arg::Str(s)) if !s.is_empty() => s.clone(),
                _ => return None,
            };
            let description = match args.get(1) {
                Some(Arg::Str(s)) => s.to_ascii_lowercase(),
                _ => String::new(),
            };
            (target, description)
        };
        // `A1`: the letter is the datum, the digits its number.
        let split = target_id
            .find(|c: char| c.is_ascii_digit())
            .unwrap_or(target_id.len());
        let (letter, number) = target_id.split_at(split);
        let index = number.parse::<u32>().unwrap_or(1);
        let datum = if letter.is_empty() {
            self.datum_letter(id, 0).unwrap_or_default()
        } else {
            letter.to_owned()
        };

        // The target's placement and size live in a shape representation the
        // target's own property definition names. The lengths come in the
        // file's own unit, as every length does. Both hops go through the
        // indexes: the old form rescanned every entity per property *per
        // target*, the assembly quadratic one storey deeper.
        self.ensure_property_indexes();
        let mut frame = None;
        let mut lengths: Vec<f64> = Vec::new();
        let properties: Vec<u64> = self
            .properties_of_definition
            .as_ref()
            .and_then(|m| m.get(&id).cloned())
            .unwrap_or_default();
        for property in properties {
            let sdrs: Vec<u64> = self
                .sdrs_of_property
                .as_ref()
                .and_then(|m| m.get(&property).cloned())
                .unwrap_or_default();
            for sdr in sdrs {
                let Ok(args) = self.args(sdr, "SHAPE_DEFINITION_REPRESENTATION") else {
                    continue;
                };
                let Some(rep) = args.get(1).and_then(Arg::reference) else {
                    continue;
                };
                for item in self.representation_items(rep).unwrap_or_default() {
                    let keyword = self
                        .instance(item)
                        .map(|i| i.keyword().to_owned())
                        .unwrap_or_default();
                    match keyword.as_str() {
                        "AXIS2_PLACEMENT_3D" => frame = self.frame(item).ok(),
                        "LENGTH_MEASURE_WITH_UNIT" | "MEASURE_REPRESENTATION_ITEM" => {
                            if let Some((value, _)) = self.measure_value(item) {
                                lengths.push(value);
                            }
                        }
                        _ => {}
                    }
                }
            }
        }

        // What the target *is* follows from the description the file gives
        // and how many sizes it carries: an area needs two, a circle one, a
        // line one, a point none.
        let kind = if description.contains("circle") || description.contains("circular") {
            ogeom_doc::DatumTargetKind::Circle {
                diameter: lengths.first().copied().unwrap_or(0.0),
            }
        } else if description.contains("rectangle") || lengths.len() >= 2 {
            ogeom_doc::DatumTargetKind::Rectangle {
                length: lengths.first().copied().unwrap_or(0.0),
                width: lengths.get(1).copied().unwrap_or(0.0),
            }
        } else if description.contains("line") || lengths.len() == 1 {
            ogeom_doc::DatumTargetKind::Line {
                length: lengths.first().copied().unwrap_or(0.0),
            }
        } else {
            ogeom_doc::DatumTargetKind::Point
        };
        Some(ogeom_doc::DatumTarget {
            datum,
            index,
            kind,
            at: frame.map_or(Point::ORIGIN, |f: Frame| f.origin()),
            frame,
            items: items_for(id),
        })
    }

    /// The drawn annotations: callouts, their polylines, their planes, and
    /// which semantic annotation each one draws.
    fn callouts(
        &mut self,
        annotation_ids: &HashMap<u64, ogeom_doc::Annotated>,
    ) -> (Vec<ogeom_doc::Callout>, HashMap<u64, usize>) {
        // Which callout each annotation plane holds, and the plane's frame.
        let mut plane_of: HashMap<u64, Frame> = HashMap::new();
        for id in self.ids_with("ANNOTATION_PLANE") {
            let Ok(args) = self.args(id, "ANNOTATION_PLANE") else {
                continue;
            };
            let frame = args
                .get(2)
                .and_then(Arg::reference)
                .and_then(|plane| {
                    let inner = self.args(plane, "PLANE").ok()?;
                    inner.get(1).and_then(Arg::reference)
                })
                .and_then(|placement| self.frame(placement).ok());
            let Some(frame) = frame else { continue };
            for element in args.get(3).and_then(Arg::list).unwrap_or(&[]) {
                if let Some(callout) = element.reference() {
                    plane_of.insert(callout, frame);
                }
            }
        }

        // Which semantic annotation each callout draws. The association names
        // the annotation's own STEP id, so the link is made by matching that
        // against the ids the semantic pass already resolved.
        // A callout may be associated more than once (once with the shape
        // aspect the annotation is *about*, once with the annotation itself),
        // so every association is kept and the first that resolves to a
        // semantic annotation is the answer.
        let mut draws: HashMap<u64, Vec<u64>> = HashMap::new();
        let mut associations = self.ids_with("DRAUGHTING_MODEL_ITEM_ASSOCIATION");
        associations.sort_unstable();
        for id in associations {
            let Ok(args) = self.args(id, "DRAUGHTING_MODEL_ITEM_ASSOCIATION") else {
                continue;
            };
            if let (Some(definition), Some(item)) = (
                args.get(2).and_then(Arg::reference),
                args.get(4).and_then(Arg::reference),
            ) {
                draws.entry(item).or_default().push(definition);
            }
        }

        let mut out = Vec::new();
        let mut index_of: HashMap<u64, usize> = HashMap::new();
        let mut callouts = self.ids_with("DRAUGHTING_CALLOUT");
        callouts.sort_unstable();
        for id in callouts {
            let Ok(args) = self.args(id, "DRAUGHTING_CALLOUT") else {
                continue;
            };
            let name = match args.first() {
                Some(Arg::Str(s)) => s.clone(),
                _ => String::new(),
            };
            let mut polylines = Vec::new();
            for element in args.get(1).and_then(Arg::list).unwrap_or(&[]).to_vec() {
                let Some(occurrence) = element.reference() else {
                    continue;
                };
                polylines.extend(self.annotation_polylines(occurrence));
            }
            if polylines.is_empty() && !plane_of.contains_key(&id) {
                continue;
            }
            index_of.insert(id, out.len());
            out.push(ogeom_doc::Callout {
                name,
                plane: plane_of.get(&id).copied(),
                polylines,
                annotates: draws
                    .get(&id)
                    .cloned()
                    .unwrap_or_default()
                    .into_iter()
                    .find_map(|d| annotation_ids.get(&d).copied()),
            });
        }
        (out, index_of)
    }

    /// The polylines one annotation occurrence draws.
    ///
    /// A tessellated occurrence names a curve set, which names a coordinates
    /// list and gives each polyline as *one-based* indices into it. That is
    /// the whole of the drawn geometry, and it is read as it is written
    /// rather than resampled.
    fn annotation_polylines(&mut self, occurrence: u64) -> Vec<Vec<Point>> {
        let item = {
            let Ok(instance) = self.instance(occurrence) else {
                return Vec::new();
            };
            let args = instance
                .part("TESSELLATED_ANNOTATION_OCCURRENCE")
                .or_else(|| instance.part("ANNOTATION_OCCURRENCE"))
                .or_else(|| instance.part("STYLED_ITEM"));
            match args.and_then(|a| a.get(2).and_then(Arg::reference)) {
                Some(item) => item,
                None => return Vec::new(),
            }
        };
        self.tessellated_polylines(item, 0)
    }

    /// The polylines a tessellated item holds, however deep it nests them.
    ///
    /// The drawn geometry of one annotation is a *set*: a frame's box, its
    /// leader, its text strokes, each its own curve set over its own
    /// coordinates list, gathered under one item, which may itself be
    /// repositioned by a placement, and that placement is applied here rather
    /// than left for a consumer to discover.
    fn tessellated_polylines(&mut self, item: u64, depth: usize) -> Vec<Vec<Point>> {
        if depth > 4 {
            return Vec::new();
        }
        let (children, curve_set, placement) = {
            let Ok(instance) = self.instance(item) else {
                return Vec::new();
            };
            let children: Vec<u64> = instance
                .part("TESSELLATED_GEOMETRIC_SET")
                .and_then(|args| args.first().and_then(Arg::list))
                .map(|list| list.iter().filter_map(Arg::reference).collect())
                .unwrap_or_default();
            let curve_set = instance.part("TESSELLATED_CURVE_SET").map(<[Arg]>::to_vec);
            let placement = instance
                .part("REPOSITIONED_TESSELLATED_ITEM")
                .and_then(|args| args.first().and_then(Arg::reference));
            (children, curve_set, placement)
        };

        let mut out = Vec::new();
        for child in children {
            out.extend(self.tessellated_polylines(child, depth + 1));
        }
        if let Some(args) = curve_set
            && let Some(list) = args.get(1).and_then(Arg::reference)
        {
            let points = self.coordinates_list(list);
            for line in args.get(2).and_then(Arg::list).unwrap_or(&[]) {
                let Some(indices) = line.list() else { continue };
                let mut polyline = Vec::with_capacity(indices.len());
                for index in indices {
                    // One-based, as the format states them.
                    let Some(k) = index.number() else { continue };
                    #[expect(
                        clippy::cast_possible_truncation,
                        clippy::cast_sign_loss,
                        reason = "an index into a list the file itself sized"
                    )]
                    let k = k as usize;
                    if k >= 1 && k <= points.len() {
                        polyline.push(points[k - 1]);
                    }
                }
                if polyline.len() >= 2 {
                    out.push(polyline);
                }
            }
        }
        if let Some(placement) = placement
            && let Ok(frame) = self.frame(placement)
        {
            for polyline in &mut out {
                for p in polyline.iter_mut() {
                    *p = frame.to_world(*p);
                }
            }
        }
        out
    }

    /// A `COORDINATES_LIST`'s points, in the document's own length unit.
    fn coordinates_list(&mut self, id: u64) -> Vec<Point> {
        let Ok(args) = self.args(id, "COORDINATES_LIST") else {
            return Vec::new();
        };
        let scale = self.report.scale_mm;
        args.get(2)
            .and_then(Arg::list)
            .unwrap_or(&[])
            .iter()
            .filter_map(|entry| {
                let coords = entry.list()?;
                let value = |i: usize| coords.get(i).and_then(Arg::number).unwrap_or(0.0) * scale;
                Some(Point::new(value(0), value(1), value(2)))
            })
            .collect()
    }

    /// Every instance id carrying a part with this keyword.
    fn ids_with(&self, keyword: &str) -> Vec<u64> {
        self.exchange
            .data
            .iter()
            .filter(|(_, inst)| inst.part(keyword).is_some())
            .map(|(id, _)| *id)
            .collect()
    }

    /// One pass over the exchange builds both property-chain indexes:
    /// definition → its `PROPERTY_DEFINITION`s (by the definition argument),
    /// property → its `SHAPE_DEFINITION_REPRESENTATION`s (by the definition
    /// they represent). Ascending ids inside each list, so a lookup visits
    /// candidates in the same order the old full scan would have.
    fn ensure_property_indexes(&mut self) {
        if self.properties_of_definition.is_some() {
            return;
        }
        let mut properties: HashMap<u64, Vec<u64>> = HashMap::new();
        let mut sdrs: HashMap<u64, Vec<u64>> = HashMap::new();
        let exchange = self.exchange;
        for (id, instance) in &exchange.data {
            if let Some(args) = instance.part("PROPERTY_DEFINITION") {
                // Read for the index is read: the skipped table should not
                // claim the reader never looked.
                if let Ok(i) = usize::try_from(*id)
                    && let Some(slot) = self.visited.get_mut(i)
                {
                    *slot = true;
                }
                if let Some(definition) = args.get(2).and_then(Arg::reference) {
                    properties.entry(definition).or_default().push(*id);
                }
            }
            if let Some(args) = instance.part("SHAPE_DEFINITION_REPRESENTATION") {
                if let Ok(i) = usize::try_from(*id)
                    && let Some(slot) = self.visited.get_mut(i)
                {
                    *slot = true;
                }
                if let Some(property) = args.first().and_then(Arg::reference) {
                    sdrs.entry(property).or_default().push(*id);
                }
            }
        }
        for list in properties.values_mut().chain(sdrs.values_mut()) {
            list.sort_unstable();
        }
        self.properties_of_definition = Some(properties);
        self.sdrs_of_property = Some(sdrs);
    }

    /// A measure item's value and kind, scaled into the document's units.
    fn measure_value(&mut self, id: u64) -> Option<(f64, ogeom_doc::MeasureKind)> {
        let args = {
            let instance = self.instance(id).ok()?;
            instance.part("MEASURE_WITH_UNIT")?.to_vec()
        };
        match args.first() {
            Some(Arg::Typed(kind, inner)) => {
                let value = inner.first().and_then(Arg::number)?;
                if kind.contains("ANGLE") {
                    Some((value * self.angle_scale, ogeom_doc::MeasureKind::Angle))
                } else {
                    Some((value * self.report.scale_mm, ogeom_doc::MeasureKind::Length))
                }
            }
            _ => None,
        }
    }

    /// A dimensional characteristic's name, kind and aspects.
    ///
    /// Sizes apply to one feature; locations (linear or angular) run
    /// between two. `ANGULAR_SIZE` and `ANGULAR_LOCATION` are the same
    /// shapes with an extra angle-selection argument at the end.
    fn dimension_shape(&mut self, dim: u64) -> (String, bool, Vec<u64>) {
        let size = {
            let Ok(instance) = self.instance(dim) else {
                return (String::new(), false, Vec::new());
            };
            instance
                .part("DIMENSIONAL_SIZE")
                .or_else(|| instance.part("ANGULAR_SIZE"))
                .map(<[Arg]>::to_vec)
        };
        if let Some(args) = size {
            let name = match args.get(1) {
                Some(Arg::Str(s)) => s.clone(),
                _ => String::new(),
            };
            let aspects = args.first().and_then(Arg::reference).into_iter().collect();
            return (name, false, aspects);
        }
        let location = {
            let Ok(instance) = self.instance(dim) else {
                return (String::new(), false, Vec::new());
            };
            instance
                .part("DIMENSIONAL_LOCATION")
                .or_else(|| instance.part("ANGULAR_LOCATION"))
                .map(<[Arg]>::to_vec)
        };
        if let Some(args) = location {
            let name = match args.first() {
                Some(Arg::Str(s)) => s.clone(),
                _ => String::new(),
            };
            let aspects = [args.get(2), args.get(3)]
                .into_iter()
                .flatten()
                .filter_map(Arg::reference)
                .collect();
            return (name, true, aspects);
        }
        (String::new(), false, Vec::new())
    }

    /// The datum letter reachable from a datum reference, depth-bounded: the
    /// reference chain runs through compartments and systems, and files
    /// arrange it differently.
    fn datum_letter(&mut self, id: u64, depth: usize) -> Option<String> {
        if depth > 4 {
            return None;
        }
        let (letter, members, refs) = {
            let instance = self.instance(id).ok()?;
            let letter = instance.part("DATUM").and_then(|args| match args.get(4) {
                Some(Arg::Str(s)) if !s.is_empty() => Some(s.clone()),
                _ => None,
            });
            // A compartment or common datum carrying a list of constituent
            // references is a composite: every constituent contributes a
            // letter, and the letters act as one datum.
            let members: Vec<u64> = ["DATUM_REFERENCE_COMPARTMENT", "COMMON_DATUM"]
                .iter()
                .find_map(|k| instance.part(k))
                .into_iter()
                .flatten()
                .find_map(Arg::list)
                .map(|list| list.iter().filter_map(Arg::reference).collect())
                .unwrap_or_default();
            let mut refs = Vec::new();
            for (_, args) in instance.parts() {
                collect_refs(args, &mut refs);
            }
            (letter, members, refs)
        };
        if let Some(letter) = letter {
            return Some(letter);
        }
        if !members.is_empty() {
            let letters: Vec<String> = members
                .into_iter()
                .filter_map(|r| self.datum_letter(r, depth + 1))
                .collect();
            if !letters.is_empty() {
                return Some(letters.join("-"));
            }
        }
        refs.into_iter()
            .find_map(|r| self.datum_letter(r, depth + 1))
    }
}

/// A product definition gathered from the file: its shapes and its usage
/// edges, before anything is committed to the document.
struct PdEntry {
    pd: u64,
    name: String,
    shapes: Vec<Shape>,
    children: Vec<(u64, Transform, Option<String>)>,
}

/// Every reference in an argument tree, in order.
fn collect_refs(args: &[Arg], out: &mut Vec<u64>) {
    for arg in args {
        match arg {
            Arg::Ref(id) => out.push(*id),
            Arg::List(inner) | Arg::Typed(_, inner) => collect_refs(inner, out),
            _ => {}
        }
    }
}

/// The chart coordinates of a point on an analytic surface, by closed-form
/// inversion; `None` for surfaces that need iterative projection.
/// For a two-wire periodic face: each wire's single closed edge with its
/// vertex, empty when the shape is anything else.
fn closed_ring_edges(model: &Model, wires: &[Shape]) -> OgeomResult<Vec<(Shape, Shape)>> {
    let mut out = Vec::new();
    for wire in wires {
        let edges = ogeom_topo::explore(
            model,
            wire,
            ogeom_topo::Filter::OfType(ogeom_topo::ShapeType::Edge),
        )?;
        if edges.len() != 1 {
            return Ok(Vec::new());
        }
        let edge = edges[0].clone();
        let Some((a, b)) = ogeom_algo::edge_vertices(model, &edge)? else {
            return Ok(Vec::new());
        };
        if !a.is_same(&b) {
            return Ok(Vec::new());
        }
        out.push((edge, a));
    }
    Ok(out)
}

/// Unused-import guard for kinds only touched via traits.
#[allow(dead_code)]
fn _keep(p: PlanarCurve) -> PlanarCurve {
    p
}

/// The window of `curve` between the feet of two vertices that stand on it
/// short of its ends: both within a hair of the curve, in the curve's own
/// order, and not the whole curve. `None` where the vertices are off the
/// curve, reversed against it, or already at its ends.
fn window_between_feet(
    curve: &Curve,
    start: Point,
    end: Point,
    tol: Tolerances,
) -> Option<(f64, f64)> {
    let (lo, hi) = curve.domain();
    let samples = match curve {
        Curve::BSpline(spline) => (spline.control_points().len() * 8).max(64),
        _ => 64,
    };
    let foot = |p: Point| -> Option<f64> {
        let found = project_on_curve(curve, p, samples, tol).ok()?;
        (found.distance <= tol.confusion() * 1e4).then_some(found.parameter)
    };
    let (a, b) = (foot(start)?, foot(end)?);
    let slack = tol.parametric().max((hi - lo) * 1e-9);
    if b <= a + slack {
        return None;
    }
    if (a - lo).abs() <= slack && (b - hi).abs() <= slack {
        return None;
    }
    Some((a, b))
}

/// The knots a STEP B-spline form implies when it states none: a Bézier
/// form's pieces joined at whole numbers, a uniform form's knots one apart
/// from `-degree`, a quasi-uniform form's the same clamped at both ends.
fn implied_knots(form: &str, degree: usize, count: usize) -> Vec<f64> {
    let p = degree.max(1);
    #[allow(clippy::cast_precision_loss)]
    let at = |i: usize| i as f64;
    if form.starts_with("BEZIER") {
        let pieces = (count.saturating_sub(1) / p).max(1);
        let mut out = vec![0.0; p + 1];
        for s in 1..pieces {
            out.extend(std::iter::repeat_n(at(s), p));
        }
        out.extend(std::iter::repeat_n(at(pieces), p + 1));
        out
    } else if form.starts_with("QUASI_UNIFORM") {
        let interior = count.saturating_sub(p + 1);
        let mut out = vec![0.0; p + 1];
        out.extend((1..=interior).map(at));
        out.extend(std::iter::repeat_n(at(interior + 1), p + 1));
        out
    } else {
        #[allow(clippy::cast_precision_loss)]
        (0..count + p + 1).map(|i| i as f64 - p as f64).collect()
    }
}

/// Two splines joined end to start: the lower degree raised to the
/// higher, the second's weights scaled to meet the first's at the join (a
/// rational curve is unchanged by scaling all its weights), and the join
/// knot left at full multiplicity.
fn join_splines(
    held: (KnotVector, Vec<Weighted<Point>>),
    next: &BSplineCurve,
    tol: Tolerances,
) -> OgeomResult<(KnotVector, Vec<Weighted<Point>>)> {
    let (mut knots, mut control) = held;
    let mut next = next.clone();
    while next.degree() < knots.degree() {
        next = next.elevated(tol)?;
    }
    while knots.degree() < next.degree() {
        (knots, control) = ogeom_math::bspline::elevate_degree(&knots, &control, tol)?;
    }
    let (Some(end), Some(start)) = (control.last(), next.control_points().first()) else {
        ogeom_bail!(Construction, "a composite segment has no control points");
    };
    let factor = end.weight / start.weight;
    let scaled: Vec<Weighted<Point>> = next
        .control_points()
        .iter()
        .map(|w| Weighted {
            scaled: w.scaled.scale(factor),
            weight: w.weight * factor,
        })
        .collect();
    ogeom_math::bspline::join(&(knots, control), &(next.knots().clone(), scaled))
}

/// One patch of a composite surface as a tensor spline: its knots each way,
/// on the unit interval, and its net indexed `[u][v]`.
#[derive(Debug, Clone)]
struct Patch {
    u: KnotVector,
    v: KnotVector,
    net: Vec<Vec<Weighted<Point>>>,
}

impl Patch {
    fn of(surface: &ogeom_geom::BSplineSurface) -> OgeomResult<Self> {
        let grid = surface.grid();
        let (nu, nv) = (grid.u_count(), grid.v_count());
        let points = grid.points();
        let net = (0..nu)
            .map(|i| (0..nv).map(|j| points[i * nv + j]).collect())
            .collect();
        Ok(Self {
            u: surface.u_knots().reparameterized(0.0, 1.0)?,
            v: surface.v_knots().reparameterized(0.0, 1.0)?,
            net,
        })
    }

    fn transposed(self) -> Self {
        let (nu, nv) = (self.net.len(), self.net[0].len());
        let net = (0..nv)
            .map(|j| (0..nu).map(|i| self.net[i][j]).collect())
            .collect();
        Self {
            u: self.v,
            v: self.u,
            net,
        }
    }

    fn reversed_u(mut self) -> Self {
        self.net.reverse();
        self.u = self.u.reversed();
        self
    }

    /// Apply a curve operation along `u` to every column of the net.
    fn along_u(
        self,
        op: impl Fn(&KnotVector, &[Weighted<Point>]) -> OgeomResult<(KnotVector, Vec<Weighted<Point>>)>,
    ) -> OgeomResult<Self> {
        let nv = self.net[0].len();
        let mut knots = self.u.clone();
        let mut columns = Vec::with_capacity(nv);
        for j in 0..nv {
            let column: Vec<Weighted<Point>> = self.net.iter().map(|row| row[j]).collect();
            let (k, c) = op(&self.u, &column)?;
            knots = k;
            columns.push(c);
        }
        let nu = columns[0].len();
        let net = (0..nu)
            .map(|i| (0..nv).map(|j| columns[j][i]).collect())
            .collect();
        Ok(Self {
            u: knots,
            v: self.v,
            net,
        })
    }
}

/// A grid of patches (`grid[i][j]`, `i` along `u`) joined into one surface.
fn join_patches(mut grid: Vec<Vec<Patch>>, tol: Tolerances) -> OgeomResult<SurfaceGeometry> {
    let (m, n) = (grid.len(), grid[0].len());
    // Degrees raised to the grid's highest each way.
    let pu = grid
        .iter()
        .flatten()
        .map(|p| p.u.degree())
        .max()
        .unwrap_or(1);
    let pv = grid
        .iter()
        .flatten()
        .map(|p| p.v.degree())
        .max()
        .unwrap_or(1);
    for patch in grid.iter_mut().flatten() {
        let mut p = patch.clone();
        while p.u.degree() < pu {
            p = p.along_u(|k, c| ogeom_math::bspline::elevate_degree(k, c, tol))?;
        }
        p = p.transposed();
        while p.u.degree() < pv {
            p = p.along_u(|k, c| ogeom_math::bspline::elevate_degree(k, c, tol))?;
        }
        *patch = p.transposed();
    }
    // Knots unified: along u within each grid row of patches sharing an
    // index `i` (their u knots must agree to share v boundaries), along v
    // within each index `j`.
    let unify = |patches: Vec<Patch>, along_v: bool| -> OgeomResult<Vec<Patch>> {
        let turned: Vec<Patch> = if along_v {
            patches.into_iter().map(Patch::transposed).collect()
        } else {
            patches
        };
        let mut wanted: Vec<(f64, usize)> = Vec::new();
        for p in &turned {
            for (value, count) in p.u.distinct() {
                if value <= 1e-12 || value >= 1.0 - 1e-12 {
                    continue;
                }
                match wanted.iter_mut().find(|(v, _)| (v - value).abs() <= 1e-12) {
                    Some(slot) => slot.1 = slot.1.max(count),
                    None => wanted.push((value, count)),
                }
            }
        }
        let mut out = Vec::with_capacity(turned.len());
        for mut p in turned {
            for &(value, count) in &wanted {
                let have = p.u.multiplicity_of(value);
                if have < count {
                    p = p.along_u(|k, c| {
                        ogeom_math::bspline::insert_knot(k, c, value, count - have, tol)
                    })?;
                }
            }
            out.push(if along_v { p.transposed() } else { p });
        }
        Ok(out)
    };
    for row in &mut grid {
        *row = unify(std::mem::take(row), true)?;
    }
    for j in 0..n {
        let column: Vec<Patch> = grid.iter().map(|row| row[j].clone()).collect();
        for (row, p) in grid.iter_mut().zip(unify(column, false)?) {
            row[j] = p;
        }
    }
    // Joined: shared boundaries once, each join a knot of full multiplicity.
    let near = |a: &Weighted<Point>, b: &Weighted<Point>| {
        a.point().distance(b.point()) <= tol.confusion() * 100.0
            && (a.weight - b.weight).abs() <= 1e-9 * a.weight.abs().max(1.0)
    };
    let mut rows: Vec<Vec<Weighted<Point>>> = Vec::new();
    for (i, grid_row) in grid.iter().enumerate() {
        let nu = grid_row[0].net.len();
        for a in 0..nu {
            if i > 0 && a == 0 {
                // The row this patch shares with the one before it.
                let prev = rows.len() - 1;
                let mut shared = 0;
                for (j, patch) in grid_row.iter().enumerate() {
                    for (b, cell) in patch.net[0].iter().enumerate() {
                        if j > 0 && b == 0 {
                            continue;
                        }
                        if !near(&rows[prev][shared], cell) {
                            ogeom_bail!(Construction, "neighbouring patches part along u");
                        }
                        shared += 1;
                    }
                }
                continue;
            }
            let mut row = Vec::new();
            for (j, patch) in grid_row.iter().enumerate() {
                for (b, cell) in patch.net[a].iter().enumerate() {
                    if j > 0 && b == 0 {
                        if !near(row.last().unwrap_or(cell), cell) {
                            ogeom_bail!(Construction, "neighbouring patches part along v");
                        }
                        continue;
                    }
                    row.push(*cell);
                }
            }
            rows.push(row);
        }
    }
    // Each patch's knots shifted to its own unit of the whole; at a join
    // one copy of the shared end goes, leaving the multiplicity at the
    // degree, and the next patch's run follows past its own clamped start.
    let joined_knots = |parts: Vec<&KnotVector>, degree: usize| -> OgeomResult<KnotVector> {
        let mut out: Vec<f64> = Vec::new();
        for (k, knots) in parts.iter().enumerate() {
            #[allow(clippy::cast_precision_loss)]
            let shift = k as f64;
            let values: Vec<f64> = knots.knots().iter().map(|x| x + shift).collect();
            if k == 0 {
                out.extend(values);
            } else {
                out.pop();
                out.extend_from_slice(&values[degree + 1..]);
            }
        }
        KnotVector::new(out, degree)
    };
    let u = joined_knots((0..m).map(|i| &grid[i][0].u).collect(), pu)?;
    let v = joined_knots((0..n).map(|j| &grid[0][j].v).collect(), pv)?;
    let (nu, nv) = (rows.len(), rows[0].len());
    let cells: Vec<Weighted<Point>> = rows.into_iter().flatten().collect();
    Ok(
        ogeom_geom::BSplineSurface::rational(u, v, ogeom_math::ControlGrid::new(cells, nu, nv)?)?
            .into(),
    )
}

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

    const T: Tolerances = Tolerances::millimetres();

    /// An edge's window between the feet of vertices standing on the
    /// curve short of its ends: taken in the curve's order, refused where
    /// the vertices are the ends already, run against the curve, or off it.
    #[test]
    fn an_edges_window_is_taken_between_its_vertices_feet() {
        let spline: Curve = BSplineCurve::new(
            KnotVector::clamped_uniform(3, 6).unwrap(),
            vec![
                Point::new(0.0, 0.0, 0.0),
                Point::new(1.0, 2.0, 0.5),
                Point::new(2.5, 1.0, -0.5),
                Point::new(4.0, 3.0, 1.0),
                Point::new(5.0, 0.5, 0.0),
                Point::new(6.0, 2.0, 2.0),
            ],
            T,
        )
        .unwrap()
        .into();
        let at = |t: f64| spline.point_at(t, T).unwrap();
        let (a, b) = window_between_feet(&spline, at(0.3), at(0.7), T).unwrap();
        assert!(
            (a - 0.3).abs() < 1e-9 && (b - 0.7).abs() < 1e-9,
            "{a} .. {b}"
        );
        let (a, b) = window_between_feet(&spline, at(0.0), at(0.7), T).unwrap();
        assert!(a.abs() < 1e-9 && (b - 0.7).abs() < 1e-9, "{a} .. {b}");
        assert!(window_between_feet(&spline, at(0.0), at(1.0), T).is_none());
        assert!(window_between_feet(&spline, at(0.7), at(0.3), T).is_none());
        let off = at(0.3) + Vector::new(0.0, 0.0, 0.5);
        assert!(window_between_feet(&spline, off, at(0.7), T).is_none());
    }
}