loadpath 0.1.1__py3-none-any.whl

loadpath/step.py

@@ -0,0 +1,806 @@
+"""
+STEP export: the part as a B-rep a CAD package can work with.
+
+The part's exact pieces stay exact: every box face is a plane, every bore,
+boss and bearing seat a true cylinder, every sphere a sphere, so a CAD user
+can dimension, mate and drill against them. Those pieces come from the CSG
+plan a part was built with (sharp.py for field graphs, reconstruct.py for
+studies): the same exact shapes manifold3d used for the STL, rebuilt in
+OpenCascade, and the organic leaves as faceted solids (one planar face per
+triangle, decimated to a face budget first). OpenCascade's booleans then cut
+the exact shapes from the facets, so the seam where a bore meets the organic
+body is an exact intersection curve on the cylinder, and coplanar facets
+merge into single faces.
+
+A mesh with no plan (any STL) exports fully faceted.
+
+Needs OpenCascade's Python bindings (`pip install "loadpath[step]"`, which is
+cadquery-ocp).
+"""
+from __future__ import annotations
+
+import os
+
+import numpy as np
+
+__all__ = ["attach_plan", "available", "export_step", "plan_of", "read_step", "shape_to_trimesh"]
+
+DEFAULT_FACES = 20_000      # organic facets in the B-rep: ~14 MB of STEP, ~20 s
+FUZZY = 1e-4                # boolean fuzz (mm): facets snapped onto exact faces
+POINT_DECIMALS = 5          # mm places for written points (10 nm)
+DEFAULT_PATCHES = 2000      # surface="smooth": organic triangles to start the patch layout from (refined where it misses)
+
+
+def available():
+    try:
+        import OCP  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+def _need():
+    if not available():
+        raise RuntimeError('STEP export needs OpenCascade: pip install "loadpath[step]" (cadquery-ocp)')
+
+
+def attach_plan(mesh, plan):
+    """Remember the CSG plan a mesh was built from (an attribute, not
+    metadata: metadata is copied and serialized)."""
+    mesh._loadpath_csg = plan
+    return mesh
+
+
+def plan_of(mesh):
+    return getattr(mesh, "_loadpath_csg", None)
+
+
+# ---- OpenCascade shapes ------------------------------------------------------------
+
+def _pnt(v):
+    from OCP.gp import gp_Pnt
+    return gp_Pnt(*(float(x) for x in v))
+
+
+def _faceted(mesh):
+    """A closed trimesh as an OpenCascade solid, one planar face per
+    triangle, sharing edges (BRepBuilderAPI_MakeShapeOnMesh)."""
+    from OCP.BRep import BRep_Builder
+    from OCP.BRepBuilderAPI import (
+        BRepBuilderAPI_MakeShapeOnMesh,
+        BRepBuilderAPI_MakeSolid,
+    )
+    from OCP.Poly import Poly_Triangle, Poly_Triangulation
+    from OCP.TopAbs import TopAbs_FACE
+    from OCP.TopExp import TopExp_Explorer
+    from OCP.TopoDS import TopoDS_Shell
+
+    V = np.asarray(mesh.vertices, float)
+    F = np.asarray(mesh.faces, np.int64)
+    tri = Poly_Triangulation(len(V), len(F), False)
+    for i, v in enumerate(V):
+        tri.SetNode(i + 1, _pnt(v))
+    for i, f in enumerate(F):
+        tri.SetTriangle(i + 1, Poly_Triangle(int(f[0]) + 1, int(f[1]) + 1, int(f[2]) + 1))
+    mk = BRepBuilderAPI_MakeShapeOnMesh(tri)
+    mk.Build()
+    b = BRep_Builder()
+    shell = TopoDS_Shell()
+    b.MakeShell(shell)
+    ex = TopExp_Explorer(mk.Shape(), TopAbs_FACE)
+    while ex.More():
+        b.Add(shell, ex.Current())
+        ex.Next()
+    shell.Closed(True)
+    return BRepBuilderAPI_MakeSolid(shell).Solid()
+
+
+def _exact(shape, faces):
+    """An exact shapes.Shape as an OpenCascade solid."""
+    from OCP.BRepPrimAPI import (
+        BRepPrimAPI_MakeBox,
+        BRepPrimAPI_MakeCylinder,
+        BRepPrimAPI_MakeSphere,
+    )
+    from OCP.gp import gp_Ax2, gp_Dir
+
+    from .shapes import (
+        Box,
+        Cylinder,
+        MeshShape,
+        Shell,
+        Sphere,
+        Union,
+        trimesh_from_manifold,
+    )
+
+    if isinstance(shape, Box):
+        return BRepPrimAPI_MakeBox(_pnt(shape.lo), _pnt(shape.hi)).Shape()
+    if isinstance(shape, Cylinder):
+        ax = gp_Ax2(_pnt(shape.p0), gp_Dir(*(float(x) for x in shape.axis)))
+        outer = BRepPrimAPI_MakeCylinder(ax, shape.r, shape.length).Shape()
+        if shape.r_inner > 0:
+            a = shape.axis
+            ax_i = gp_Ax2(_pnt(shape.p0 - a), gp_Dir(*(float(x) for x in a)))
+            inner = BRepPrimAPI_MakeCylinder(ax_i, shape.r_inner, shape.length + 2.0).Shape()
+            outer = _bool("subtract", [outer, inner])
+        return outer
+    if isinstance(shape, Sphere):
+        return BRepPrimAPI_MakeSphere(_pnt(shape.center), shape.r).Shape()
+    if isinstance(shape, Union):
+        return _bool("union", [_exact(s, faces) for s in shape.shapes])
+    if isinstance(shape, Shell):
+        man = _bool("subtract", [_exact(shape.outer, faces), _exact(shape.inner, faces)])
+        return man if shape.clip is None else _bool("intersect", [man, _exact(shape.clip, faces)])
+    if isinstance(shape, MeshShape):
+        return _faceted(_decimate(shape.mesh, faces))
+    return _faceted(_decimate(trimesh_from_manifold(shape.to_manifold()), faces))
+
+
+def _bool(op, shapes):
+    from OCP.BRepAlgoAPI import BRepAlgoAPI_Common, BRepAlgoAPI_Cut, BRepAlgoAPI_Fuse
+
+    if len(shapes) == 1:
+        return shapes[0]
+    cls = {"union": BRepAlgoAPI_Fuse, "intersect": BRepAlgoAPI_Common, "subtract": BRepAlgoAPI_Cut}[op]
+    if op == "intersect":
+        out = shapes[0]
+        for s in shapes[1:]:
+            out = _bool1(cls, [out], [s])
+        return out
+    return _bool1(cls, shapes[:1], shapes[1:])
+
+
+def _bool1(cls, args, tools, fuzzy=FUZZY):
+    from OCP.OCP.collections import List_TopoDS_Shape
+
+    a, t = List_TopoDS_Shape(), List_TopoDS_Shape()
+    for s in args:
+        a.Append(s)
+    for s in tools:
+        t.Append(s)
+    op = cls()
+    op.SetArguments(a)
+    op.SetTools(t)
+    op.SetFuzzyValue(fuzzy)
+    op.SetRunParallel(True)
+    op.SetNonDestructive(True)
+    op.Build()
+    if not op.IsDone():
+        raise RuntimeError(f"OpenCascade {cls.__name__} failed")
+    return op.Shape()
+
+
+def _closest(mesh, P, chunk=20_000):
+    import trimesh
+
+    out = np.empty_like(P)
+    for i in range(0, len(P), chunk):
+        out[i:i + chunk] = trimesh.proximity.closest_point(mesh, P[i:i + chunk])[0]
+    return out
+
+
+def _sharpness(V, F):
+    """Per vertex: 1 - the least cosine between its faces' normals and its
+    own normal (0 on a flat patch, ~1 on a right-angle crease)."""
+    n = np.cross(V[F[:, 1]] - V[F[:, 0]], V[F[:, 2]] - V[F[:, 0]])
+    n /= np.maximum(np.linalg.norm(n, axis=1, keepdims=True), 1e-300)
+    vn = np.zeros_like(V)
+    for c in range(3):
+        np.add.at(vn, F[:, c], n)
+    vn /= np.maximum(np.linalg.norm(vn, axis=1, keepdims=True), 1e-300)
+    k = np.zeros(len(V))
+    for c in range(3):
+        np.maximum.at(k, F[:, c], 1 - np.einsum("ij,ij->i", n, vn[F[:, c]]))
+    return k
+
+
+def _collapse(V, F, target, locked=None, turn=0.9):
+    """A closed mesh (V, F) coarsened to about `target` faces, shortest
+    edges first, keeping its topology: decimate.py's passes (the link
+    condition, no face turning by more than acos(`turn`)) with no field to
+    hold to. Each collapse keeps the sharper end where it is, so creases
+    and seams stay put and every vertex is one of the original ones.
+    Vertices flagged in `locked` never move. Returns the vertices, faces and
+    lock flags of the result."""
+    from .decimate import decimate
+
+    V = np.asarray(V, float)
+    F = np.asarray(F, np.int64)
+    k = _sharpness(V, F)
+
+    def place(W, a, b):
+        pick = k[a] >= k[b]
+        k[a] = np.maximum(k[a], k[b])
+        return np.where(pick[:, None], W[a], W[b])
+
+    lock = np.zeros(len(V), bool) if locked is None else np.asarray(locked, bool)
+    V2, F2, _, kept = decimate(V, F, None, 0.0, 1.0, locked=lock, max_passes=300, min_gain=0.002,
+                               target=int(target), place=place, turn=turn)
+    return V2, F2, lock[kept]
+
+
+def _fast(mesh, faces):
+    """fast_simplification's quadric decimation, without the zero-area
+    faces (a repeated vertex) it leaves behind, which make an otherwise
+    closed result read as torn."""
+    import trimesh
+
+    c = mesh.simplify_quadric_decimation(face_count=int(faces))
+    F = np.asarray(c.faces)
+    ok = (F[:, 0] != F[:, 1]) & (F[:, 1] != F[:, 2]) & (F[:, 0] != F[:, 2])
+    if ok.all():
+        return c
+    out = trimesh.Trimesh(c.vertices, F[ok], process=False)
+    out.remove_unreferenced_vertices()
+    return out
+
+
+def _decimate(mesh, faces):
+    """`mesh` cut down to about `faces` triangles, still closed. A lattice
+    does not decimate (its walls collapse first): past 4x the budget that is
+    an error, not a STEP file of millions of faces."""
+    if len(mesh.faces) <= faces:
+        return mesh
+    try:
+        out = _fast(mesh, faces)
+        if out.is_watertight and abs(out.volume) > 0.9 * abs(mesh.volume):
+            return out
+    except Exception:  # noqa: BLE001 - decimation is best-effort
+        pass
+    import trimesh
+
+    if len(mesh.faces) <= 20 * faces and mesh.is_watertight and mesh.is_winding_consistent:   # tore: coarsen carefully
+        V, F, _ = _collapse(mesh.vertices, mesh.faces, int(faces))
+        out = trimesh.Trimesh(V, F, process=False)
+        if len(out.faces) <= 1.5 * faces and out.is_watertight:
+            return out
+    if len(mesh.faces) > 4 * faces:
+        raise ValueError(f"an organic region of {len(mesh.faces)} triangles does not decimate to {faces} and stay "
+                         "closed (a lattice?): raise the STEP face budget, or hand over the STL for it")
+    return mesh
+
+
+def _organic_budget(plan, faces):
+    from .sharp import Organic, _leaves
+
+    org = [lf for lf in _leaves(plan) if isinstance(lf, Organic) and lf.mesh is not None]
+    for lf in org:
+        if not hasattr(lf.mesh, "faces"):          # a manifold (reconstruct.py)
+            from .shapes import trimesh_from_manifold
+
+            lf.mesh = trimesh_from_manifold(lf.mesh)
+    total = sum(len(lf.mesh.faces) for lf in org) or 1
+    return {id(lf): max(500, int(faces * len(lf.mesh.faces) / total)) for lf in org}
+
+
+def _pieces(shape, faces):
+    """An exact shape as separate OpenCascade solids (a union's members):
+    booleans take them as separate tools, which survives members that share
+    faces (a motor box against its driver's box) where a pre-fused union
+    can come out invalid."""
+    from .shapes import Union
+
+    if isinstance(shape, Union):
+        return [p for s in shape.shapes for p in _pieces(s, faces)]
+    return [_exact(shape, faces)]
+
+
+def _on_float32(mesh):
+    """The mesh with its vertices on float32's grid. manifold3d's results
+    come back in double precision now (shapes.trimesh_from_manifold), and a
+    study part's organic leaf, decimated from those, leaves OpenCascade's
+    booleans against the exact planes with no clean result (the lug's
+    STEP came out with no solid); rounded as manifold3d's float32 output
+    used to round them, they fuse. Moves a vertex ~1e-5 mm at most."""
+    import trimesh
+
+    V = np.asarray(mesh.vertices, np.float32).astype(float)
+    if np.array_equal(V, mesh.vertices):
+        return mesh
+    return trimesh.Trimesh(V, np.asarray(mesh.faces), process=False)
+
+
+def _build(plan, budget, faces, notes):
+    """(OpenCascade solids, the same thing as a manifold3d Manifold). The
+    manifold is the referee: each OpenCascade boolean is tried a few ways
+    (fuzz, tools separate or fused) until it is valid and its volume agrees
+    with manifold3d's."""
+    import manifold3d as m3d
+
+    from .shapes import manifold_from_trimesh
+    from .sharp import Exact, Organic, exact_manifold
+
+    if isinstance(plan, Exact):
+        return _pieces(plan.shape, faces), exact_manifold(plan.shape)
+    if isinstance(plan, Organic):
+        m = _on_float32(plan.mesh)
+        d = _decimate(m, budget.get(id(plan), faces))
+        if len(d.faces) < len(m.faces):
+            notes.append({"leaf": ",".join(plan.names) or "organic", "faces": len(m.faces),
+                          "stepFaces": len(d.faces), "deviation": _deviation(m, d)})
+        return [_faceted(d)], manifold_from_trimesh(d)
+    kids = [_build(k, budget, faces, notes) for k in plan.kids]
+    kind = {"union": m3d.OpType.Add, "intersect": m3d.OpType.Intersect, "subtract": m3d.OpType.Subtract}[plan.op]
+    want = m3d.Manifold.batch_boolean([k[1] for k in kids], kind)
+    if plan.op == "union":
+        first, tools = kids[0][0][:1], kids[0][0][1:] + [s for k in kids[1:] for s in k[0]]
+    else:
+        first = [_fuse_all(kids[0][0])]
+        tools = [s for k in kids[1:] for s in k[0]]
+        if plan.op == "intersect":
+            tools = [_fuse_all(tools)]
+    shape = _referee(plan.op, first, tools, want.volume(), notes)
+    return [shape], want
+
+
+def _fuse_all(shapes):
+    return shapes[0] if len(shapes) == 1 else _bool1(_cls("union"), shapes[:1], shapes[1:])
+
+
+def _cls(op):
+    from OCP.BRepAlgoAPI import BRepAlgoAPI_Common, BRepAlgoAPI_Cut, BRepAlgoAPI_Fuse
+
+    return {"union": BRepAlgoAPI_Fuse, "intersect": BRepAlgoAPI_Common, "subtract": BRepAlgoAPI_Cut}[op]
+
+
+def _referee(op, first, tools, want, notes):
+    from OCP.BRepCheck import BRepCheck_Analyzer
+
+    tries = [(FUZZY, False), (1e-6, False), (FUZZY, True), (0.0, False), (1e-3, False)]
+    best = None
+    for fuzzy, fused in tries:
+        t = [_fuse_all(tools)] if fused and len(tools) > 1 else tools
+        try:
+            r = _bool1(_cls(op), first, t, fuzzy)
+        except RuntimeError:
+            continue
+        ok = bool(BRepCheck_Analyzer(r).IsValid())
+        err = abs(_volume(r) - want) / max(abs(want), 1e-9)
+        if ok and err < 2e-3:
+            return r
+        score = (not ok, err)
+        if best is None or score < best[0]:
+            best = (score, r)
+    if best is None:
+        raise RuntimeError(f"OpenCascade could not {op} the part")
+    notes.append({"warning": f"{op}: no clean OpenCascade result; kept the closest "
+                             f"(valid {not best[0][0]}, volume off {best[0][1]:.2%})"})
+    return best[1]
+
+
+def _deviation(full, coarse, n=4000):
+    """Distance (mm) from a sample of the full mesh's surface to the
+    decimated one: what the faceting costs."""
+    import trimesh
+
+    P, _ = trimesh.sample.sample_surface(full, n, seed=2)
+    _, d, _ = trimesh.proximity.closest_point(coarse, P)
+    return {"mean": round(float(d.mean()), 4), "p99": round(float(np.percentile(d, 99)), 4)}
+
+
+def _keep_bodies(shape, keep_with=None):
+    """The largest solid and any solid touching `keep_with` (preserved
+    geometry): what reconstruct keeps, fragments dropped."""
+    from OCP.BRep import BRep_Builder
+    from OCP.TopAbs import TopAbs_SOLID
+    from OCP.TopExp import TopExp_Explorer
+    from OCP.TopoDS import TopoDS_Compound
+
+    solids = []
+    ex = TopExp_Explorer(shape, TopAbs_SOLID)
+    while ex.More():
+        solids.append(ex.Current())
+        ex.Next()
+    if len(solids) <= 1:
+        return shape, 0
+    vols = [_volume(s) for s in solids]
+    order = np.argsort(vols)[::-1]
+    kept = [solids[order[0]]]
+    for i in order[1:]:
+        if keep_with is not None and _volume(_bool("intersect", [solids[i], keep_with])) > 1e-6:
+            kept.append(solids[i])
+    b = BRep_Builder()
+    comp = TopoDS_Compound()
+    b.MakeCompound(comp)
+    for s in kept:
+        b.Add(comp, s)
+    return comp, len(solids) - len(kept)
+
+
+def _volume(shape):
+    from OCP.BRepGProp import BRepGProp
+    from OCP.GProp import GProp_GProps
+
+    p = GProp_GProps()
+    BRepGProp.VolumeProperties_s(shape, p)
+    return float(p.Mass())
+
+
+def _faces_report(shape, exact_planes):
+    """Faces of the B-rep by surface type, and the share of its area on
+    exact geometry (cylinders, spheres, and planes of the exact shapes)."""
+    from OCP.BRepAdaptor import BRepAdaptor_Surface
+    from OCP.BRepGProp import BRepGProp
+    from OCP.GeomAbs import (
+        GeomAbs_BezierSurface,
+        GeomAbs_BSplineSurface,
+        GeomAbs_Cylinder,
+        GeomAbs_Plane,
+        GeomAbs_Sphere,
+    )
+    from OCP.GProp import GProp_GProps
+    from OCP.TopAbs import TopAbs_FACE
+    from OCP.TopExp import TopExp_Explorer
+    from OCP.TopoDS import TopoDS
+
+    kinds = {}
+    area = {"exact": 0.0, "faceted": 0.0, "smooth": 0.0}
+    ex = TopExp_Explorer(shape, TopAbs_FACE)
+    while ex.More():
+        f = TopoDS.Face(ex.Current())
+        s = BRepAdaptor_Surface(f)
+        t = s.GetType()
+        p = GProp_GProps()
+        BRepGProp.SurfaceProperties_s(f, p)
+        a = float(p.Mass())
+        if t == GeomAbs_Plane:
+            pl = s.Plane()
+            n = pl.Axis().Direction()
+            o = pl.Location()
+            nv = np.array([n.X(), n.Y(), n.Z()])
+            ov = np.array([o.X(), o.Y(), o.Z()])
+            exact = any(abs(abs(nv @ en) - 1) < 1e-7 and abs((ov - ep) @ en) < 1e-4 for ep, en in exact_planes)
+            key = "plane" if exact else "facet"
+        elif t == GeomAbs_Cylinder:
+            key, exact = "cylinder", True
+        elif t == GeomAbs_Sphere:
+            key, exact = "sphere", True
+        elif t in (GeomAbs_BSplineSurface, GeomAbs_BezierSurface):
+            key, exact = "bspline", None
+        else:
+            key, exact = "other", True
+        kinds[key] = kinds.get(key, 0) + 1
+        area["smooth" if exact is None else "exact" if exact else "faceted"] += a
+        ex.Next()
+    total = sum(area.values()) or 1.0
+    return {"faces": kinds, "exactArea": round(area["exact"], 1), "facetedArea": round(area["faceted"], 1),
+            "smoothArea": round(area["smooth"], 1), "exactAreaFraction": round(area["exact"] / total, 4)}
+
+
+def _planes(shape, out):
+    from .shapes import Box, Cylinder, Shell, Union
+
+    if isinstance(shape, Box):
+        for a in range(3):
+            n = np.zeros(3)
+            n[a] = 1.0
+            out += [(shape.lo.copy(), n), (shape.hi.copy(), n.copy())]
+    elif isinstance(shape, Cylinder):
+        out += [(shape.p0.copy(), shape.axis.copy()), (shape.p1.copy(), shape.axis.copy())]
+    elif isinstance(shape, Union):
+        for s in shape.shapes:
+            _planes(s, out)
+    elif isinstance(shape, Shell):
+        for s in (shape.outer, shape.inner, shape.clip):
+            if s is not None:
+                _planes(s, out)
+    return out
+
+
+def _bezier_faces(shape):
+    """A compound of the shape's Bezier and B-spline faces."""
+    from OCP.BRep import BRep_Builder
+    from OCP.BRepAdaptor import BRepAdaptor_Surface
+    from OCP.GeomAbs import GeomAbs_BezierSurface, GeomAbs_BSplineSurface
+    from OCP.TopAbs import TopAbs_FACE
+    from OCP.TopExp import TopExp_Explorer
+    from OCP.TopoDS import TopoDS, TopoDS_Compound
+
+    bb = BRep_Builder()
+    out = TopoDS_Compound()
+    bb.MakeCompound(out)
+    ex = TopExp_Explorer(shape, TopAbs_FACE)
+    while ex.More():
+        if BRepAdaptor_Surface(TopoDS.Face(ex.Current())).GetType() in (GeomAbs_BezierSurface, GeomAbs_BSplineSurface):
+            bb.Add(out, ex.Current())
+        ex.Next()
+    return out
+
+
+def _smooth_shape(part, plan, patches, notes, degree=None):
+    """surface="smooth": the finished mesh as a B-rep of smooth patches with
+    its exact faces exact (brep.py), or None (and a note) when that does not
+    come out a valid solid within 0.2% of the mesh's volume."""
+    if not hasattr(part, "faces"):
+        notes.append({"warning": "smooth surfaces need the part's mesh, not only its plan; faceted instead"})
+        return None
+    from OCP.BRepCheck import BRepCheck_Analyzer
+
+    from .brep import smooth_brep
+    from .sharp import mesh_distance
+
+    try:
+        solid, rep = smooth_brep(part, plan, patches, **({"order": int(degree)} if degree else {}))
+        vol = _volume(solid)
+        if not BRepCheck_Analyzer(solid).IsValid() or abs(vol - abs(part.volume)) > 2e-3 * abs(part.volume):
+            raise RuntimeError(f"invalid or {abs(vol / abs(part.volume) - 1):.2%} off in volume")
+    except Exception as e:  # noqa: BLE001 - facets always work
+        notes.append({"warning": f"smooth surfaces failed ({e}); faceted instead"})
+        return None
+    # the patches against the mesh; the exact faces are the truth there (a
+    # mesh's facets sag off a big bore by more than the patches miss)
+    back = shape_to_trimesh(_bezier_faces(solid), deflection=0.005, angle=0.05)
+    if len(back.faces):                       # a part of exact faces only has no patches to measure
+        d = mesh_distance(part, back.sample(20000), cap=1.0)
+        rep["deviation"] = {"mean": round(float(d.mean()), 4), "p99": round(float(np.percentile(d, 99)), 4),
+                            "max": round(float(d.max()), 4)}
+    notes.append({"leaf": "smooth", **rep})
+    return solid
+
+
+def export_step(part, path, faces=DEFAULT_FACES, name=None, unify=True, check=True, surface="facets",
+                patches=DEFAULT_PATCHES, degree=None):
+    """Write `part` (a trimesh from a field graph or a study, or a CSG plan)
+    to a STEP file at `path`. `faces` is the budget of organic facets; the
+    exact shapes cost a handful of faces each. Returns a report: faces by
+    type, the share of the area that is exact geometry, solids, volume (and
+    the STL's, to compare), what decimating the organic surface cost, and
+    the file's size."""
+    _need()
+    import time
+
+    from OCP.BRepCheck import BRepCheck_Analyzer
+
+    from .sharp import Exact, Op, Organic, _leaves
+
+    t0 = time.time()
+    plan = part if isinstance(part, (Op, Exact, Organic)) else plan_of(part)
+    mesh_volume = None if isinstance(part, (Op, Exact, Organic)) else float(abs(part.volume))
+    notes = []
+    keep_with = None
+    mesh_plan = plan
+    if plan is None:
+        plan = Organic(None, ["mesh"], mesh=part)
+    keep = getattr(plan, "keep_with", None)
+    budget = _organic_budget(plan, faces)
+    shape = None
+    if surface == "smooth":
+        shape = _smooth_shape(part, mesh_plan if mesh_volume is not None else None, patches, notes, degree)
+    if shape is None:
+        shapes, _ = _build(plan, budget, faces, notes)
+        shape = _fuse_all(shapes) if len(shapes) > 1 else shapes[0]
+        dropped = 0
+        if keep is not None:
+            keep_with = _exact(keep, faces)
+            shape, dropped = _keep_bodies(shape, keep_with)
+        if unify:
+            from OCP.ShapeUpgrade import ShapeUpgrade_UnifySameDomain
+
+            u = ShapeUpgrade_UnifySameDomain(shape, True, True, False)
+            u.SetLinearTolerance(1e-5)
+            u.Build()
+            shape = u.Shape()
+    else:
+        dropped = 0
+    valid = bool(BRepCheck_Analyzer(shape).IsValid()) if check else None
+    if check and not valid:
+        from OCP.ShapeFix import ShapeFix_Shape
+
+        fx = ShapeFix_Shape(shape)
+        fx.Perform()
+        shape = fx.Shape()
+        valid = bool(BRepCheck_Analyzer(shape).IsValid())
+    planes = []
+    for lf in _leaves(plan):
+        if isinstance(lf, Exact):
+            _planes(lf.shape, planes)
+    rep = _faces_report(shape, planes)
+    wrote = write_step(shape, path, name=name, verify=bool(check and valid))
+    from OCP.TopAbs import TopAbs_SOLID
+    from OCP.TopExp import TopExp_Explorer
+
+    n = 0
+    ex = TopExp_Explorer(shape, TopAbs_SOLID)
+    while ex.More():
+        n += 1
+        ex.Next()
+    rep.update({"path": str(path), "bytes": os.path.getsize(path), "solids": n, "valid": valid,
+                "volume": round(_volume(shape), 2), "seconds": round(time.time() - t0, 1)})
+    if "pcurves" in wrote:
+        rep["pcurves"] = wrote["pcurves"]
+        rep["readBackValid"] = wrote["readBackValid"]
+        rep["valid"] = bool(valid and wrote["readBackValid"])
+    if mesh_volume is not None:
+        rep["meshVolume"] = round(mesh_volume, 2)
+    if dropped:
+        rep["droppedFragments"] = dropped
+    if notes:
+        rep["decimated"] = notes
+    rep["shape"] = shape
+    return rep
+
+
+def write_step(shape, path, name=None, pcurves=False, verify=False):
+    """Write an OpenCascade shape to STEP (mm, AP214, points compacted),
+    without the faces' 2-D curves unless `pcurves` (readers rebuild them,
+    and they are half the file). `verify` reads the file back and, if the
+    shape no longer passes OpenCascade's check (a reader projecting an edge
+    onto a sliver patch can fail where the writer's own 2-D curve was fine),
+    writes it again with the 2-D curves. Returns {path, bytes, writeSeconds}
+    (and with verify: pcurves, readBackValid)."""
+    import time
+
+    from OCP.Interface import Interface_Static
+    from OCP.STEPControl import (
+        STEPControl_AsIs,
+        STEPControl_Controller,
+        STEPControl_Writer,
+    )
+
+    t0 = time.time()
+    STEPControl_Controller.Init_s()      # registers the write.* parameters before they are set
+    Interface_Static.SetCVal_s("write.step.unit", "MM")
+    Interface_Static.SetCVal_s("write.step.schema", "AP214IS")
+    Interface_Static.SetIVal_s("write.surfacecurve.mode", 1 if pcurves else 0)
+    if name:
+        Interface_Static.SetCVal_s("write.step.product.name", str(name))
+    w = STEPControl_Writer()
+    w.Transfer(shape, STEPControl_AsIs)
+    os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
+    if int(w.Write(str(path))) != 1:
+        raise RuntimeError(f"OpenCascade could not write {path}")
+    _compact(path)
+    out = {"path": str(path), "bytes": os.path.getsize(path), "writeSeconds": round(time.time() - t0, 1)}
+    if verify:
+        ok = shape_valid(read_step(path))
+        if not ok and not pcurves:
+            out = write_step(shape, path, name=name, pcurves=True, verify=True)
+            out["writeSeconds"] = round(time.time() - t0, 1)
+            return out
+        out.update({"pcurves": bool(pcurves), "readBackValid": bool(ok)})
+    return out
+
+
+BIG_SHELL = 8000      # faces: past this a whole-solid check is checked shell by shell
+
+
+def shape_valid(shape, geom=True):
+    """OpenCascade's check (BRepCheck). A solid with an inner shell of more
+    than BIG_SHELL faces is checked shell by shell (each as a solid of its
+    own): the whole-solid check classifies every shell against every other
+    and went past 12 GB on an arm link's 38k-patch void."""
+    from OCP.BRepBuilderAPI import BRepBuilderAPI_MakeSolid
+    from OCP.BRepCheck import BRepCheck_Analyzer
+    from OCP.TopAbs import TopAbs_FACE, TopAbs_SHELL
+    from OCP.TopExp import TopExp_Explorer
+    from OCP.TopoDS import TopoDS
+
+    def nfaces(x):
+        ex, n = TopExp_Explorer(x, TopAbs_FACE), 0
+        while ex.More():
+            n += 1
+            ex.Next()
+        return n
+
+    shells = []
+    ex = TopExp_Explorer(shape, TopAbs_SHELL)
+    while ex.More():
+        shells.append(TopoDS.Shell(ex.Current()))
+        ex.Next()
+    if len(shells) < 2 or max(nfaces(x) for x in shells) <= BIG_SHELL:
+        return bool(BRepCheck_Analyzer(shape, geom).IsValid())
+    return all(BRepCheck_Analyzer(BRepBuilderAPI_MakeSolid(x).Solid(), geom).IsValid() for x in shells)
+
+
+def _compact(path, decimals=POINT_DECIMALS):
+    """Rewrite a STEP file smaller: points to `decimals` places (mm; 10 nm
+    is a thousandth of the sewing tolerance) and each distinct point once.
+    Three quarters of a smooth STEP file is points, and a patch's edge poles
+    are the same points as its edge curve's and its neighbour's."""
+    import re
+
+    with open(path) as fh:
+        text = fh.read()
+    head, sep, rest = text.partition("DATA;")
+    data, sep2, tail = rest.partition("ENDSEC;")
+    if not sep or not sep2:
+        return
+    ents = re.split(r"\n(?=#\d+\s*=)", data)
+    num = re.compile(r"-?\d+\.\d*(?:E[-+]?\d+)?")
+    point = re.compile(r"#(\d+)\s*=\s*CARTESIAN_POINT\('([^']*)',\((.*)\)\)\s*;\s*$", re.DOTALL)
+
+    def short(x):
+        t = f"{float(x):.{decimals}f}".rstrip("0")
+        return "0." if t in ("-0.", "0.") else t
+
+    first, alias, out = {}, {}, []
+    for e in ents:
+        mo = point.match(e.strip())
+        if mo:
+            coords = ",".join(short(x) for x in num.findall(mo.group(3)))
+            key = (mo.group(2), coords)
+            if key in first:
+                alias[mo.group(1)] = first[key]
+                continue
+            first[key] = mo.group(1)
+            out.append(f"#{mo.group(1)} = CARTESIAN_POINT('{mo.group(2)}',({coords}));")
+        else:
+            out.append(e)
+    if alias:
+        ref = re.compile(r"#(\d+)")
+        body = []
+        for e in out:
+            lhs, eq, rhs = e.partition("=")
+            body.append(lhs + eq + ref.sub(lambda m: "#" + alias.get(m.group(1), m.group(1)), rhs) if eq else e)
+        out = body
+    with open(path, "w") as fh:
+        fh.write(head + sep + "\n".join(x.strip("\n") for x in out) + "\n" + sep2 + tail)
+
+
+def read_step(path):
+    """The shape in a STEP file (OpenCascade TopoDS_Shape)."""
+    _need()
+    from OCP.IFSelect import IFSelect_RetDone
+    from OCP.STEPControl import STEPControl_Reader
+
+    r = STEPControl_Reader()
+    if r.ReadFile(str(path)) != IFSelect_RetDone:
+        raise ValueError(f"could not read STEP file {path}")
+    r.TransferRoots()
+    return r.OneShape()
+
+
+def shape_to_trimesh(shape, deflection=0.002, angle=0.05, chunk=2000):
+    """Triangulate an OpenCascade shape finely (chord `deflection` mm) into a
+    trimesh: how to measure a B-rep with the mesh tools."""
+    import trimesh
+    from OCP.BRep import BRep_Builder, BRep_Tool
+    from OCP.BRepMesh import BRepMesh_IncrementalMesh
+    from OCP.BRepTools import BRepTools
+    from OCP.TopAbs import TopAbs_FACE, TopAbs_REVERSED
+    from OCP.TopExp import TopExp_Explorer
+    from OCP.TopLoc import TopLoc_Location
+    from OCP.TopoDS import TopoDS, TopoDS_Compound
+
+    # in chunks of faces, each meshed (in parallel), read into numpy and its
+    # triangulation dropped: one mesh of a whole lattice part (46k patches,
+    # tens of millions of nodes) held at once went past 13 GB
+    faces = []
+    ex = TopExp_Explorer(shape, TopAbs_FACE)
+    while ex.More():
+        faces.append(TopoDS.Face(ex.Current()))
+        ex.Next()
+    V, F = [], []
+    off = 0
+    bb = BRep_Builder()
+    for c0 in range(0, len(faces), chunk):
+        comp = TopoDS_Compound()
+        bb.MakeCompound(comp)
+        for f in faces[c0:c0 + chunk]:
+            bb.Add(comp, f)
+        BRepMesh_IncrementalMesh(comp, deflection, False, angle, True)
+        for f in faces[c0:c0 + chunk]:
+            loc = TopLoc_Location()
+            tri = BRep_Tool.Triangulation_s(f, loc)
+            if tri is None:
+                continue
+            tr = loc.Transformation()
+            nn, nt = tri.NbNodes(), tri.NbTriangles()
+            v = np.empty((nn, 3))
+            for i in range(nn):
+                p = tri.Node(i + 1).Transformed(tr)
+                v[i] = p.X(), p.Y(), p.Z()
+            t = np.empty((nt, 3), np.int64)
+            for i in range(nt):
+                t[i] = tri.Triangle(i + 1).Get()
+            if f.Orientation() == TopAbs_REVERSED:
+                t = t[:, [0, 2, 1]]
+            V.append(v)
+            F.append(t - 1 + off)
+            off += nn
+        BRepTools.Clean_s(comp)
+    m = trimesh.Trimesh(np.concatenate(V) if V else np.zeros((0, 3)),
+                        np.concatenate(F) if F else np.zeros((0, 3), np.int64), process=True)
+    m.merge_vertices(digits_vertex=6)
+    return m