brep_kernel/io/step_import/
mod.rs

1//! STEP Part 21 import for NURBS and analytic surfaces, assemblies, and PMI.
2//!
3//! The importer reconstructs and validates BREP topology. Analytic carriers are
4//! converted to NURBS sized to the face bounds. Seam edges occupy opposite
5//! parameter boundaries, and collapsed pole bounds become degenerate edges so
6//! faces close and integrate correctly.
7//!
8//! Pcurves are DERIVED, by projecting each edge onto its carrier; a
9//! `SURFACE_CURVE`/`SEAM_CURVE` bundle contributes only its 3D curve.
10//!
11//! [`supplied`] can read the bundle's `PCURVE` associations instead and seat
12//! the vendor's own stated trim, and does so correctly, but it is OFF unless
13//! `BREP_SUPPLIED_PCURVES=1`. Not caution — measurement. Preferring a supplied
14//! pcurve helps only where the edge's 3D curve has drifted off its own carrier,
15//! and nothing distinguishes that case from the ones where it hurts: our own
16//! exporter writes exact analytic 3D curves with fitted pcurves, so seating the
17//! fit cost a round trip through our writer a factor of 4800 in volume
18//! fidelity. See `supplied::supplied_pcurves_enabled` for the full derivation.
19
20use crate::topology::{
21    BrepSolid, CoedgeRecord, EdgeRecord, FaceRecord, LoopRecord, ShellRecord, VertexRecord,
22};
23use crate::{
24    build_pcurve_on_surface_range, make_arc, make_extrusion, make_hyperbola, make_line,
25    make_parabola, make_plane, make_revolution, offset_surface, transform_brep, AffineTransform,
26    NurbsCurve, NurbsSurface, Vec3, Vec4,
27};
28use rustc_hash::{FxHashMap as HashMap, FxHashSet as HashSet};
29use std::collections::VecDeque;
30
31const TAU: f64 = std::f64::consts::TAU;
32
33mod parse;
34mod supplied;
35mod bodies;
36mod assembly;
37mod assembly_pmi;
38mod mapped;
39mod builder;
40mod geometry;
41mod styles;
42mod pmi;
43mod precision;
44mod trim_readings;
45
46use crate::appearance::{BodyAppearance, ImportedColor};
47use parse::*;
48use supplied::*;
49use bodies::*;
50use mapped::*;
51use builder::*;
52use geometry::*;
53use styles::*;
54pub use assembly::{read_step_assembly, StepAssembly, StepOccurrence, StepProduct};
55pub use assembly_pmi::{occurrence_ref_parts, rewrite_occurrence_refs, OCCURRENCE_REF_PREFIX};
56pub use mapped::StepMappedItemError;
57pub use pmi::read_step_pmi;
58pub use precision::STATED_PRECISION_INCONSISTENCY_RATIO;
59pub use trim_readings::{
60    import_step_trim_readings, StepBodyTrimReadings, StepEdgeReading, StepFaceReading,
61    StepSuppliedTrim, StepTrimReadings,
62};
63pub(crate) use pmi::decode_step_text as decode_step_text_for_tests;
64
65
66// ---------------------------------------------------------------------------
67// Topology assembly
68// ---------------------------------------------------------------------------
69
70/// Public entry: parse a STEP Part 21 document and return one `BrepSolid` per
71/// MANIFOLD_SOLID_BREP, FACETED_BREP, or certified BREP_WITH_VOIDS. Every
72/// returned solid passes `validate()`.
73pub fn import_step(text: &str) -> Result<Vec<BrepSolid>, String> {
74    Ok(import_step_with_appearance(text)?.0)
75}
76
77/// [`import_step`] plus the file's PRESENTATION colours: one
78/// [`BodyAppearance`] per returned solid, in the same order.
79///
80/// This is the lane the IMPORT3D feature uses, because colour is stamped as
81/// scene metadata on the names IT chooses — see
82/// `feature_pipeline::features::import3d` and `io/appearance.rs` for the record
83/// shape. A file with no presentation entities returns default (empty)
84/// appearances, never a short vector, so callers can `zip` unconditionally.
85pub fn import_step_with_appearance(
86    text: &str,
87) -> Result<(Vec<BrepSolid>, Vec<BodyAppearance>), String> {
88    let imported = collect_step_solids(text)?;
89    if imported.solids.is_empty() {
90        return Err(imported.first_error.unwrap_or_else(|| {
91            "step_import: no MANIFOLD_SOLID_BREP/FACETED_BREP/BREP_WITH_VOIDS body imported (unsupported or invalid representation)"
92                .into()
93        }));
94    }
95    Ok((imported.solids, imported.appearances))
96}
97
98/// What [`import_step_report`] returns: the bodies, how gracefully the file
99/// imported, and the import's diagnostics.
100#[derive(Clone, Debug)]
101pub struct StepImportReport {
102    /// One solid per body that reconstructed, in file order.
103    pub solids: Vec<BrepSolid>,
104    /// Things that did not come in (skipped, not fatal): a body that failed to
105    /// reconstruct, an occurrence whose transform failed, or a mapping that was
106    /// refused (`mapped::StepMappedItemError`).
107    pub failed: usize,
108    /// The first such failure's text, when `failed > 0`.
109    pub first_error: Option<String>,
110    /// Every precision the file states, in millimetres, ascending — see
111    /// `parse::stated_precisions_mm`. Empty when it states none.
112    pub stated_precisions_mm: Vec<f64>,
113    /// The import's diagnostics: measurements always, plus one
114    /// `import.stated_precision_inconsistent` warning when the file's stated
115    /// precision is far under the deviation its own geometry shows
116    /// ([`precision::stated_precision_diagnostics`]). Informational only —
117    /// acceptance never depends on it.
118    pub diagnostics: crate::KernelDiagnostics,
119}
120
121/// Like [`import_step`] but reports how many bodies failed and the first error,
122/// so callers can distinguish a fully- from a partially-imported assembly —
123/// and runs the stated-precision consistency check over the imported bodies,
124/// whose result rides in [`StepImportReport::diagnostics`].
125///
126/// The check measures every edge and vertex of every body (the same
127/// `EntityTolerances` reading the per-entity-tolerance census took), which is
128/// why it lives on this lane and not on [`import_step_with_appearance`]: the
129/// feature pipeline has no diagnostics channel to carry the answer, and a
130/// measurement nobody reads is not worth its cost on every IMPORT3D.
131pub fn import_step_report(text: &str) -> Result<StepImportReport, String> {
132    let imported = collect_step_solids(text)?;
133    let diagnostics =
134        precision::stated_precision_diagnostics(&imported.stated_precisions_mm, &imported.solids);
135    Ok(StepImportReport {
136        solids: imported.solids,
137        failed: imported.failed,
138        first_error: imported.first_error,
139        stated_precisions_mm: imported.stated_precisions_mm,
140        diagnostics,
141    })
142}
brep_kernel/io/step_import/mod.rs

brep_kernel/io/step_import/
mod.rs
