polyhedral 0.3.0__py3-none-any.whl

polyhedral/__init__.py

@@ -0,0 +1,107 @@
+"""polyhedral -- 3D solids with self-verified 2D drawing geometry.
+
+Pure Python: only numpy + shapely + pyclipper are required (all ship
+with Pyodide); the [dxf] extra (ezdxf + Pillow) adds DXF/SVG export. Model
+space is millimetres, always; geometry exports at true size (1:1).
+
+The whole golden path:
+
+>>> from polyhedral import Plot, Sheet, View, Viewport, make, subtract
+>>> plate = subtract(make.box((450, 450, 25)),
+...                  make.cylinder(r=15, h=60, center=(150, 150, 0)),
+...                  pid="PL-01")
+>>> round(plate.volume)
+5044942
+>>> sheet = Sheet([plate], [Viewport(View.from_eye((1, -1, 1)),
+...                                  at=(0, 0))])
+>>> doc = sheet.to_dxf_doc()          # annotate with ezdxf, save, or:
+>>> svg = sheet.to_svg(plot=Plot(paper=(160, 120)))   # doctest: +SKIP
+
+Booleans have one spelling (union/subtract/intersect); cross-section
+profiles (I-sections, channels, CHS, ...) live in ``shapes.*`` and are
+shapely Polygons (the class is re-exported as ``polyhedral.Polygon``);
+color is yours via Look + by_kind/by_id/highlight; plotting is a Plot
+value.
+
+The normative contract is docs/SPEC.md, shipped in the source
+distribution (sdist).
+"""
+from shapely.geometry import Polygon as Polygon  # profiles ARE shapely
+
+from . import make, mesh, shapes, validate
+from .bool3d import intersect, subtract, union
+from .camera import Section, Vec3, View
+from .core import CheckIssue, ClashVolume, Point3, RenderResult, Solid, render
+from .looks import (
+    Linework,
+    Look,
+    RenderStyle,
+    Resolver,
+    Shaded,
+    by_id,
+    by_kind,
+    highlight,
+)
+from .sheet import (
+    A0,
+    A1,
+    A2,
+    A3,
+    A4,
+    A5,
+    A6,
+    Plot,
+    Sheet,
+    Vec2,
+    Viewport,
+    Window,
+    WindowLike,
+    extent,
+    plot_svg,
+    row,
+)
+
+__version__ = "0.3.0"
+__all__ = [
+    "A0",
+    "A1",
+    "A2",
+    "A3",
+    "A4",
+    "A5",
+    "A6",
+    "CheckIssue",
+    "ClashVolume",
+    "Linework",
+    "Look",
+    "Plot",
+    "Point3",
+    "Polygon",
+    "RenderResult",
+    "RenderStyle",
+    "Resolver",
+    "Section",
+    "Shaded",
+    "Sheet",
+    "Solid",
+    "Vec2",
+    "Vec3",
+    "View",
+    "Viewport",
+    "Window",
+    "WindowLike",
+    "by_id",
+    "by_kind",
+    "extent",
+    "highlight",
+    "intersect",
+    "make",
+    "mesh",
+    "plot_svg",
+    "render",
+    "row",
+    "shapes",
+    "subtract",
+    "union",
+    "validate",
+]

polyhedral/bool3d.py

@@ -0,0 +1,445 @@
+"""polyhedral.bool3d -- B-rep 3D booleans decided on integer 2D coordinates.
+
+Classic B-rep formulation:
+    A - B = (faces of A outside B) + (faces of B inside A, flipped)
+
+Every decision happens inside the plane of one face, i.e. as 2D work,
+and all 2D work already runs on integer coordinates through Clipper --
+there is no ambiguous floating-point predicate, unlike BSP approaches
+(pycsg) that decide in 3D floats.
+
+Coplanar faces are the classic failure mode; this engine resolves them the
+manifold way, adapted to per-face 2D decisions:
+
+* The other solid's cross-section is NEVER taken exactly at a face plane
+  (float-ambiguous when the plane coincides with the other solid's own
+  boundary). It is sampled at d +- SECTION_EPS, on the side the operation needs:
+  when classifying X's faces against Y, sample just inside Y's material
+  side for subtract/intersect, just outside for union. Both loops use the
+  same rule with the roles swapped, which is what makes the operations
+  commute.
+* Exactly-coincident face pairs are excluded from the epsilon
+  classification and routed by a fixed ownership table (overlap region):
+
+      op          same-oriented       anti-oriented
+      union       A keeps, B drops    both drop
+      intersect   A keeps, B drops    both drop
+      subtract    both drop           A keeps, B drops
+
+  B always drops, so the B loop only ever subtracts coincident A regions.
+
+Engine primitives used: Solid.cut_face(n, d) and clip2d.Region.
+"""
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import numpy as np
+
+from .clip2d import SCALE, Region
+from .core import Solid, _nest, _newell, _plane_frame, _unit
+
+WELD = 0.005
+SECTION_EPS = 2e-3   # plane offset for coplanar-safe sectioning; must exceed COP
+COP = 1e-3   # planes closer than this count as coincident: quantized
+             # rotated geometry drifts plane offsets by up to ~5e-4, so
+             # the band is twice that, and SECTION_EPS samples clear of it
+FINE = 10    # extra 2D resolution over clip2d.SCALE: 0.1 um grid, so projecting
+             # the engine's 1e-4 mm vertex grid into a face frame stays EXACT --
+             # at 1 um the org-relative fraction rounds differently per face and
+             # coplanar edges land 0.2 um apart (open-edge check failures).
+
+
+def _is_convex(solid: Solid, tol: float = 1e-6) -> bool:
+    """Convex iff every vertex lies on the inner side of every face plane."""
+    P = np.array([v for f in solid.faces for r in f for v in r], float)
+    lo, hi = P.min(0), P.max(0)
+    scale = max(float((hi - lo).max()), 1.0)
+    for face, n in zip(solid.faces, solid.normals()):
+        d = float(n @ np.asarray(face[0][0], float))
+        if float((P @ n).max()) > d + tol * scale + 1e-6:
+            return False
+    return True
+
+
+def _frame(n: Any, org: Any) -> Any:
+    U, V = _plane_frame(n)
+    return U, V, org
+
+
+def _to_region(rings: Any, U: Any, V: Any, org: Any) -> Any:
+    out = []
+    for r in rings:
+        out.append([(float((np.asarray(p) - org) @ U) * FINE,
+                     float((np.asarray(p) - org) @ V) * FINE) for p in r])
+    if not out:
+        return Region()
+    reg = Region.from_rings(out[:1])
+    for hole in out[1:]:
+        reg = reg.subtract(Region.from_rings([hole]))
+    return reg
+
+
+def _to_faces(reg: Any, U: Any, V: Any, org: Any, n: Any,
+              flip: bool = False) -> Any:
+    faces = []
+    for shell, holes in _nest(reg):
+        rings = []
+        for path in [shell, *holes]:
+            rings.append([org + u / (SCALE * FINE) * U + v / (SCALE * FINE) * V
+                          for u, v in path])
+        if len(rings[0]) < 3:
+            continue
+        want = -n if flip else n
+        if float(_unit(_newell(rings[0])) @ want) < 0:
+            rings[0] = rings[0][::-1]
+        faces.append(rings)
+    return faces
+
+
+def _section_region(solid: Solid, n: Any, d: float, off: float, U: Any,
+                    V: Any, org: Any) -> Any:
+    """Cross-section of `solid` near plane (n, d) as a Region in frame
+    (U, V, org). ``off`` (+-SECTION_EPS) shifts only the membership band inside
+    _clip_ring; the section GEOMETRY interpolates to the exact plane, so
+    no lateral SECTION_EPS/tan(theta) error at shallow face crossings."""
+    reg = Region()
+    for face in solid.cut_face(n, d, tol=off, fine=FINE):
+        reg = reg.union(_to_region(face, U, V, org))
+    return reg
+
+
+__all__ = ["intersect", "subtract", "union"]
+
+
+def _operands(a: Solid, more: tuple[Solid, ...], fn: str) -> None:
+    """Solids only, passed positionally -- a list slipping through the
+    identity shortcut would come back unchanged, silently."""
+    for x in (a, *more):
+        if not isinstance(x, Solid):
+            hint = ("; for a sequence, splat it: "
+                    f"{fn}(*parts, pid=...)") if isinstance(
+                        x, (list, tuple)) else ""
+            raise TypeError(f"{fn}() takes Solids positionally; got "
+                            f"{type(x).__name__}{hint}")
+
+
+def _empty(pid: str | None, kind: str | None, a: Solid) -> Solid:
+    return Solid((), pid=pid, kind=kind or a.kind)
+
+
+def _finish(out: Solid, operands: tuple[Solid, ...],
+            pid: str | None, kind: str | None) -> Solid:
+    """A boolean of two or more parts is ALWAYS a new part with a new id:
+    engine shortcut cases (disjoint subtract, A | A, ...) can hand back an
+    operand unchanged, and letting that leak would put two parts with one
+    pid in the model. Copy in that case; apply pid/kind overrides."""
+    if any(out is x for x in operands):
+        if len(operands) == 1:
+            # single operand: the rename/re-kind idiom -- union(s,
+            # kind=...) is s.replace(kind=...)'s functional twin, so
+            # the id survives unless pid= renames it (SPEC section 5)
+            out = out.replace(pid=pid, kind=kind)
+        else:
+            out = out.replace(
+                pid=pid if pid is not None else Solid._next_pid(),
+                kind=kind)
+    elif (pid is not None and out.id != pid) or (
+            kind is not None and out.kind != kind):
+        out = out.replace(pid=pid, kind=kind)
+    return out
+
+
+def union(a: Solid, *more: Solid, pid: str | None = None,
+          kind: str | None = None, tol: float = 1e-6) -> Solid:
+    """Union of all operands; ``union(a)`` is ``a`` itself (identity;
+    with ``pid=``/``kind=`` it is the renaming/re-kinding idiom).
+    With two or more operands the result is a new part with a new id
+    (``pid`` names it); ``kind=None`` inherits from ``a``.
+
+    >>> from polyhedral import make, union
+    >>> u = union(make.box((100, 100, 40)),
+    ...           make.box((100, 100, 60), center=(0, 0, 50)), pid="U")
+    >>> round(u.volume)
+    1000000
+    """
+    _operands(a, more, "union")
+    if not more and pid is None and kind is None:
+        return a
+    out = a
+    for b in more:
+        nxt = _bool(pid, out, b, "union", kind=kind or a.kind, tol=tol)
+        if nxt is None:
+            return _empty(pid, kind, a)
+        out = nxt
+    return _finish(out, (a, *more), pid, kind)
+
+
+def intersect(a: Solid, *more: Solid, pid: str | None = None,
+              kind: str | None = None,
+              tol: float = 1e-6) -> Solid:
+    """Common volume of all operands; ``intersect(a)`` is ``a``.
+    An empty Solid (falsy) when nothing is shared. Two or more
+    operands: a new part with a new id."""
+    _operands(a, more, "intersect")
+    if not more and pid is None and kind is None:
+        return a
+    out = a
+    for b in more:
+        nxt = _bool(pid, out, b, "intersect", kind=kind or a.kind, tol=tol)
+        if nxt is None:
+            return _empty(pid, kind, a)
+        out = nxt
+    return _finish(out, (a, *more), pid, kind)
+
+
+def subtract(a: Solid, *tools: Solid, pid: str | None = None,
+             kind: str | None = None,
+             tol: float = 1e-6) -> Solid:
+    """``a`` minus every tool; ``subtract(a)`` is ``a``. An empty Solid
+    (falsy) when nothing remains. With tools: a new part with a new id.
+    """
+    _operands(a, tools, "subtract")
+    if not tools and pid is None and kind is None:
+        return a
+    out = a
+    for b in tools:
+        nxt = _bool(pid, out, b, "subtract", kind=kind or a.kind, tol=tol)
+        if nxt is None:
+            return _empty(pid, kind, a)
+        out = nxt
+    return _finish(out, (a, *tools), pid, kind)
+
+
+def _same_geometry(A: Solid, B: Solid) -> bool:
+    """Exact structural equality: same faces, rings and vertex values in
+    the same order (a copy preserves order). Heuristics (volume + bbox +
+    face count) are NOT identity: a plate and its own 180-degree rotation
+    agree on all three yet are different parts."""
+    if A is B:
+        return True
+    if len(A.faces) != len(B.faces):
+        return False
+    for fa, fb in zip(A.faces, B.faces):
+        if len(fa) != len(fb):
+            return False
+        for ra, rb in zip(fa, fb):
+            if len(ra) != len(rb):
+                return False
+            if not all(float(p[0]) == float(q[0])
+                       and float(p[1]) == float(q[1])
+                       and float(p[2]) == float(q[2])
+                       for p, q in zip(ra, rb)):
+                return False
+    return True
+
+
+def _bool(pid: str | None, A: Solid, B: Solid,
+          op: Literal["union", "intersect", "subtract"],
+          kind: str | None = None, tol: float = 1e-6) -> Solid | None:
+    """One binary boolean; None means an empty result. The op decides
+    which side of each face-plane section is kept:
+    A's faces keep the side outside B (inside for intersect), B's faces
+    the side outside A (inside for intersect/subtract; flipped into
+    cavity walls for subtract)."""
+    keep_a_inside = op == "intersect"
+    keep_b_inside = op != "union"
+    flip_b = op == "subtract"
+    if A.is_empty or B.is_empty:
+        if op == "intersect":                      # intersect with empty
+            return None
+        if op == "subtract":
+            return None if A.is_empty else A
+        if A.is_empty and B.is_empty:              # union of nothing
+            return None
+        return B if A.is_empty else A              # union with empty
+    if _same_geometry(A, B):
+        # A & A = A and A | A = A; A - A is nothing
+        return None if op == "subtract" else A
+
+    # Separating-plane early-out only for a strict gap: touching solids
+    # must go through the full path so coincident faces get the ownership
+    # rules (a >= d - tol test would let a stacked union keep both
+    # interior walls).
+    PA = np.array([v for f in A.faces for r in f for v in r], float)
+    disjoint = False
+    if _is_convex(B, tol):
+        for face, n in zip(B.faces, B.normals()):
+            d = float(n @ np.asarray(face[0][0], float))
+            if float((PA @ n).min()) > d + WELD:
+                disjoint = True
+                break
+    if not disjoint and _is_convex(A, tol):
+        PB = np.array([v for f in B.faces for r in f for v in r], float)
+        for face, n in zip(A.faces, A.normals()):
+            d = float(n @ np.asarray(face[0][0], float))
+            if float((PB @ n).min()) > d + WELD:
+                disjoint = True
+                break
+    if disjoint:
+        if op == "union":
+            faces = [[[np.asarray(v, float) for v in r] for r in f]
+                     for f in list(A.faces) + list(B.faces)]
+            return Solid(faces, pid=pid, kind=kind or A.kind)
+        return None if op == "intersect" else A
+
+    faces = []
+
+    def _plane_d(f: Any, n: Any) -> float:
+        """Ring-averaged plane offset: a single quantized vertex drifts d by
+        up to ~5e-4 on rotated geometry, the mean is several times tighter."""
+        return float(np.mean([n @ np.asarray(p, float) for p in f[0]]))
+
+    aplanes = [(f, n, _plane_d(f, n)) for f, n in zip(A.faces, A.normals())]
+    bplanes = [(f, n, _plane_d(f, n)) for f, n in zip(B.faces, B.normals())]
+
+    def coincident(n: Any, d: float, planes: Any) -> Any:
+        """Faces of `planes` in the same plane as (n, d), by orientation.
+        Tolerant matching: quantized rotated geometry shifts normals ~1e-6
+        and plane offsets ~2e-4, which an exact dict key misses."""
+        same, anti = [], []
+        for f2, n2, d2 in planes:
+            dot = float(n @ n2)
+            if dot > 1.0 - 1e-8 and abs(d2 - d) <= COP:
+                same.append(f2)
+            elif dot < -1.0 + 1e-8 and abs(d2 + d) <= COP:
+                anti.append(f2)
+        return same, anti
+
+    for face, n in zip(A.faces, A.normals()):
+        org = np.asarray(face[0][0], float)
+        U, V, org = _frame(n, org)
+        d = _plane_d(face, n)
+        regA = _to_region(face, U, V, org)
+        # coincident B faces, split by orientation
+        b_same, b_anti = coincident(n, d, bplanes)
+        reg_same, reg_anti = Region(), Region()
+        for fb in b_same:
+            reg_same = reg_same.union(_to_region(fb, U, V, org))
+        for fb in b_anti:
+            reg_anti = reg_anti.union(_to_region(fb, U, V, org))
+        work = regA
+        if not reg_same.is_empty:
+            work = work.subtract(reg_same)
+        if not reg_anti.is_empty:
+            work = work.subtract(reg_anti)
+        # epsilon-shifted membership, never exactly at the face plane
+        off = -SECTION_EPS if keep_b_inside else SECTION_EPS
+        sec = _section_region(B, n, d, off, U, V, org)
+        if sec.is_empty:
+            out = Region() if keep_a_inside else work
+        else:
+            out = work.intersect(sec) if keep_a_inside else work.subtract(sec)
+        # ownership table: A keeps same-pairs for union/intersect,
+        # anti-pairs for subtract; B always drops (see module docstring)
+        if not flip_b and not reg_same.is_empty:
+            out = out.union(regA.intersect(reg_same))
+        if flip_b and not reg_anti.is_empty:
+            out = out.union(regA.intersect(reg_anti))
+        faces += _to_faces(out, U, V, org, n)
+
+    for face, n in zip(B.faces, B.normals()):
+        org = np.asarray(face[0][0], float)
+        U, V, org = _frame(n, org)
+        d = _plane_d(face, n)
+        work = _to_region(face, U, V, org)
+        a_same, a_anti = coincident(n, d, aplanes)
+        for fa in a_same + a_anti:      # B always drops coincident overlap
+            work = work.subtract(_to_region(fa, U, V, org))
+        off = -SECTION_EPS if keep_a_inside else SECTION_EPS
+        sec = _section_region(A, n, d, off, U, V, org)
+        if sec.is_empty:
+            if keep_b_inside:
+                continue
+        else:
+            work = work.intersect(sec) if keep_b_inside else work.subtract(sec)
+        faces += _to_faces(work, U, V, org, -n if flip_b else n)
+
+    if not faces:
+        return None
+    faces = _weld3d(faces, WELD)
+    faces = _fix_t(faces, WELD)
+    out = Solid(faces, pid=pid, kind=kind or A.kind)
+    # degenerate sliver faces are culled by Solid.__init__; a result with
+    # nothing left is "empty", and the contract for empty is None
+    return None if out.is_empty else out
+
+
+def _weld3d(faces: Any, tol: float) -> Any:
+    """Weld vertices closer than `tol` (grid hash + neighbour probe).
+    Distance-based welding, NOT grid rounding: no grid size is both
+    watertight and volume-accurate, because nearby points straddling a
+    grid boundary stay separate.
+    """
+    cell = max(tol, 1e-9) * 2.0
+    reps: list[Any] = []
+    buckets: dict[tuple[int, ...], list[int]] = {}
+
+    def rep(p: Any) -> Any:
+        c = tuple((p / cell).astype(int))
+        for dx in (-1, 0, 1):
+            for dy in (-1, 0, 1):
+                for dz in (-1, 0, 1):
+                    for k in buckets.get((c[0] + dx, c[1] + dy, c[2] + dz), ()):
+                        if float(np.linalg.norm(p - reps[k])) <= tol:
+                            return reps[k]
+        buckets.setdefault(c, []).append(len(reps))
+        reps.append(p)
+        return p
+
+    return [[[rep(np.asarray(v, float)) for v in ring] for ring in face]
+            for face in faces]
+
+
+def _fix_t(faces: Any, tol: float) -> Any:
+    """Insert vertices that land mid-edge of another face (T-vertex repair)
+    so shared edges match up and the surface closes.
+    """
+    pts = {tuple(v) for f in faces for r in f for v in r}
+    cell = 5.0
+    grid: dict[tuple[int, ...], list[Any]] = {}
+    for v in pts:
+        grid.setdefault(tuple(int(x // cell) for x in v), []).append(np.array(v))
+
+    def near_seg(a: Any, b: Any, L: float) -> Any:
+        """Candidate points from every grid cell the segment passes through
+        (sampling only the midpoint missed T-vertices on long edges)."""
+        steps = max(1, int(L // cell) + 1)
+        seen, out = set(), []
+        for i in range(steps + 1):
+            p = a + (b - a) * (i / steps)
+            c = tuple(int(x // cell) for x in p)
+            for dx in (-1, 0, 1):
+                for dy in (-1, 0, 1):
+                    for dz in (-1, 0, 1):
+                        cc = (c[0] + dx, c[1] + dy, c[2] + dz)
+                        if cc not in seen:
+                            seen.add(cc)
+                            out += grid.get(cc, [])
+        return out
+
+    new = []
+    for face in faces:
+        rings = []
+        for ring in face:
+            out, m = [], len(ring)
+            for i in range(m):
+                a, b = np.asarray(ring[i]), np.asarray(ring[(i + 1) % m])
+                out.append(a)
+                dv = b - a
+                L = float(np.linalg.norm(dv))
+                if tol > L:
+                    continue
+                u = dv / L
+                on = []
+                for q in near_seg(a, b, L):
+                    w = q - a
+                    t = float(w @ u)
+                    if tol < t < L - tol and float(np.linalg.norm(w - t * u)) <= tol:
+                        on.append((t, q))
+                on.sort(key=lambda x: x[0])
+                for _, q in on:
+                    out.append(q)
+            rings.append(out)
+        new.append(rings)
+    return new