forgekernel 0.1.0__py3-none-any.whl

forgekernel/surfacing.py

@@ -0,0 +1,341 @@
+"""K6.0 — surfacing groundwork: Coons patches, exact curvature, G1.
+
+The exactness thesis extends into differential geometry:
+
+- **Gaussian curvature is exactly rational.** With the unnormalized
+  normal ``n = S_u × S_v``, the second-fundamental terms ``L' = S_uu·n``
+  etc. carry a factor |n| each, and
+
+      K = (L'·N' − M'²) / (EG − F²)²
+
+  — every |n| cancels, so K at a rational parameter of a polynomial
+  surface is an exact ``Fraction``. A float kernel evaluates the same
+  formula through several rounded square roots.
+- **Mean curvature needs one √** (the (EG−F²)^{3/2}) and comes back as
+  a certified interval (ADR-0019).
+- **G1 continuity is certified by polynomial identity.** Two patches
+  meet G1 along a shared boundary iff the cross product of their
+  transversal tangents with the boundary tangent vanishes identically —
+  a polynomial in the boundary parameter. Checking it at more sample
+  points than its degree bound is a PROOF (a nonzero polynomial of
+  degree d has at most d roots), not a heuristic.
+- **Coons patches** (bilinearly blended) from four Bézier boundaries:
+  ruled(u) + ruled(v) − bilinear, assembled exactly via Bézier degree
+  elevation and control-net arithmetic.
+"""
+
+from __future__ import annotations
+
+from fractions import Fraction
+
+from forgekernel.interval import CInterval
+from forgekernel.nurbs import BSplineSurface, bezier_surface, surface_partials2
+
+F = Fraction
+
+
+# -- Bézier net algebra --------------------------------------------------------
+
+def _elevate_row(row):
+    """Degree-elevate a Bézier control row by one (exact convex comb.)."""
+    p = len(row) - 1
+    out = [row[0]]
+    for i in range(1, p + 1):
+        a = F(i, p + 1)
+        out.append(tuple(a * row[i - 1][c] + (1 - a) * row[i][c]
+                         for c in range(3)))
+    out.append(row[-1])
+    return out
+
+
+def _elevate_u(net, times):
+    for _ in range(times):
+        cols = list(map(list, zip(*net)))
+        cols = [_elevate_row(c) for c in cols]
+        net = list(map(list, zip(*cols)))
+    return net
+
+
+def _elevate_v(net, times):
+    for _ in range(times):
+        net = [_elevate_row(r) for r in net]
+    return net
+
+
+def coons_patch(c0, c1, d0, d1) -> BSplineSurface:
+    """Bilinearly blended Coons patch from four Bézier boundary curves
+    (given as control-point lists): ``c0``/``c1`` run along u at v=0/1;
+    ``d0``/``d1`` run along v at u=0/1. Corners must agree exactly.
+
+    S = Ruled_v(c0,c1) + Ruled_u(d0,d1) − Bilinear(corners), assembled
+    as one exact Bézier net via degree elevation."""
+    c0 = [tuple(F(x) for x in pt) for pt in c0]
+    c1 = [tuple(F(x) for x in pt) for pt in c1]
+    d0 = [tuple(F(x) for x in pt) for pt in d0]
+    d1 = [tuple(F(x) for x in pt) for pt in d1]
+    if len(c0) != len(c1) or len(d0) != len(d1):
+        raise ValueError("opposite boundaries must share degree (K6.1)")
+    # corner compatibility, exact
+    if not (c0[0] == d0[0] and c0[-1] == d1[0]
+            and c1[0] == d0[-1] and c1[-1] == d1[-1]):
+        raise ValueError("Coons boundaries disagree at a corner")
+    p = len(c0) - 1                     # u-degree
+    q = len(d0) - 1                     # v-degree
+    # ruled between c0 and c1: net rows along u, 2 columns in v
+    ruled_v = [[c0[i], c1[i]] for i in range(p + 1)]          # (p+1)×2
+    ruled_u = [[d0[j] for j in range(q + 1)],
+               [d1[j] for j in range(q + 1)]]                 # 2×(q+1)
+    bilin = [[c0[0], c1[0]], [c0[-1], c1[-1]]]                # 2×2
+    # elevate all three to degree (p, q)
+    A = _elevate_v(ruled_v, q - 1)
+    B = _elevate_u(ruled_u, p - 1)
+    C = _elevate_u(_elevate_v(bilin, q - 1), p - 1)
+    net = [[tuple(A[i][j][c] + B[i][j][c] - C[i][j][c] for c in range(3))
+            for j in range(q + 1)] for i in range(p + 1)]
+    return bezier_surface(net)
+
+
+# -- curvature -----------------------------------------------------------------
+
+def _dot(a, b):
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+
+
+def _cross(a, b):
+    return (a[1] * b[2] - a[2] * b[1],
+            a[2] * b[0] - a[0] * b[2],
+            a[0] * b[1] - a[1] * b[0])
+
+
+def gaussian_curvature(surface: BSplineSurface, u, v) -> Fraction:
+    """K at (u, v) — an EXACT rational for a polynomial surface.
+    Every |n| in the classical formula cancels:
+    K = ((S_uu·n)(S_vv·n) − (S_uv·n)²) / (EG − F²)²  with n = S_u×S_v."""
+    _, su, sv, suu, suv, svv = surface_partials2(surface, u, v)
+    n = _cross(su, sv)
+    E, Ff, G = _dot(su, su), _dot(su, sv), _dot(sv, sv)
+    denom = (E * G - Ff * Ff) ** 2
+    if denom == 0:
+        raise ValueError("degenerate tangent plane (singular parameterization)")
+    return (_dot(suu, n) * _dot(svv, n) - _dot(suv, n) ** 2) / denom
+
+
+def mean_curvature(surface: BSplineSurface, u, v) -> CInterval:
+    """H at (u, v) — certified (one genuine √ in (EG−F²)^{3/2}).
+    H = (E·N' − 2F·M' + G·L') / (2 (EG−F²)^{3/2}) with primes · n̂|n|."""
+    _, su, sv, suu, suv, svv = surface_partials2(surface, u, v)
+    n = _cross(su, sv)
+    E, Ff, G = _dot(su, su), _dot(su, sv), _dot(sv, sv)
+    W = E * G - Ff * Ff                      # = |n|²
+    if W == 0:
+        raise ValueError("degenerate tangent plane")
+    num = E * _dot(svv, n) - 2 * Ff * _dot(suv, n) + G * _dot(suu, n)
+    w32 = (CInterval.exact(W) * CInterval.exact(W) * CInterval.exact(W)).sqrt()
+    lo, hi = F(num) / w32.hi / 2, F(num) / w32.lo / 2
+    return CInterval(min(lo, hi), max(lo, hi))
+
+
+# -- G1 continuity certification -----------------------------------------------
+
+def g1_certify(A: BSplineSurface, B: BSplineSurface, *,
+               a_edge: str = "u1", b_edge: str = "u0",
+               samples: int | None = None) -> bool:
+    """Certify G1 continuity along a shared boundary by polynomial
+    identity testing: tangent planes agree along the seam iff
+    (t_A × t_B) · anything vanishes — concretely, the normals of A and
+    B are parallel at every boundary point, i.e. n_A × n_B ≡ 0, a
+    vector polynomial in the seam parameter. Its degree is bounded by
+    4·(p+q); checking MORE sample points than the bound and finding
+    zero every time is a proof, not a heuristic."""
+    def at(surface, edge, t):
+        (u0d, u1d), (v0d, v1d) = surface.domain()
+        u0d, u1d = F(u0d), F(u1d)
+        v0d, v1d = F(v0d), F(v1d)
+        if edge == "u1":
+            return F(u1d), v0d + t * (v1d - v0d)
+        if edge == "u0":
+            return F(u0d), v0d + t * (v1d - v0d)
+        if edge == "v1":
+            return u0d + t * (u1d - u0d), F(v1d)
+        return u0d + t * (u1d - u0d), F(v0d)
+
+    bound = 4 * (A.p + A.q + B.p + B.q) + 1
+    n = samples or bound
+    for k in range(n + 1):
+        t = F(k, n)
+        ua, va = at(A, a_edge, t)
+        ub, vb = at(B, b_edge, t)
+        # positions must coincide exactly (G0 first)
+        if A.eval(ua, va) != B.eval(ub, vb):
+            return False
+        na = A.normal(ua, va)
+        nb = B.normal(ub, vb)
+        if _cross(na, nb) != (0, 0, 0):
+            return False
+    return True
+
+
+# -- K6.1: G2 certification + curvature combs ----------------------------------
+
+def g2_certify(A: BSplineSurface, B: BSplineSurface, *,
+               a_edge: str = "u1", b_edge: str = "u0",
+               samples: int | None = None) -> bool:
+    """Certify G2 (curvature continuity) along a shared seam, exactly.
+
+    Requires G1 first (checked). Then the transversal normal curvature
+    must agree at every seam point. With unnormalized normals the
+    comparison cross-multiplies into pure rationals:
+
+        κ_n = (S_tt·n̂)/|S_t'|²-ish terms → compare
+        (S_tt^A·n_A)²·W_B == (S_tt^B·n_B)²·W_A   and matching sign,
+
+    where W = |n|² = EG−F² is rational. Zero at more samples than the
+    polynomial degree bound ⇒ identically zero: a proof."""
+    from forgekernel.nurbs import surface_partials2
+
+    if not g1_certify(A, B, a_edge=a_edge, b_edge=b_edge, samples=samples):
+        return False
+
+    def at(surface, edge, t):
+        (u0d, u1d), (v0d, v1d) = surface.domain()
+        u0d, u1d, v0d, v1d = F(u0d), F(u1d), F(v0d), F(v1d)
+        if edge == "u1":
+            return F(u1d), v0d + t * (v1d - v0d)
+        if edge == "u0":
+            return F(u0d), v0d + t * (v1d - v0d)
+        if edge == "v1":
+            return u0d + t * (u1d - u0d), F(v1d)
+        return u0d + t * (u1d - u0d), F(v0d)
+
+    def transversal_kn(surface, edge, uu, vv):
+        """(S_tt·n, W) for the TRANSVERSAL parameter curve at the seam
+        (the u-direction for u-edges, v-direction for v-edges)."""
+        _, su, sv, suu, suv, svv = surface_partials2(surface, uu, vv)
+        n = _cross(su, sv)
+        W = _dot(n, n)
+        stt = suu if edge in ("u0", "u1") else svv
+        return _dot(stt, n), W, n
+
+    bound = 8 * (A.p + A.q + B.p + B.q) + 1
+    ns = samples or bound
+    for k in range(ns + 1):
+        t = F(k, ns)
+        ua, va = at(A, a_edge, t)
+        ub, vb = at(B, b_edge, t)
+        Xa, Wa, na = transversal_kn(A, a_edge, ua, va)
+        Xb, Wb, nb = transversal_kn(B, b_edge, ub, vb)
+        if Wa == 0 or Wb == 0:
+            return False
+        # sign of n_B relative to n_A (G1 already guarantees parallel)
+        s = 1 if _dot(na, nb) > 0 else -1
+        # κ_n^A == κ_n^B in A's orientation, cross-multiplied (exact):
+        if Xa * Xa * Wb != Xb * Xb * Wa:
+            return False
+        # signs must agree too (curvature bowing the same way)
+        if (Xa > 0) != (s * Xb > 0) and not (Xa == 0 and Xb == 0):
+            return False
+    return True
+
+
+def curve_curvature_comb(curve, n: int = 32, scale: float = 1.0):
+    """Curvature comb for a Bézier/B-spline curve — the visual surfacing
+    audit tool. Returns [(point, tip), ...] where tip = point + scale·κ·N̂.
+    κ = |c'×c''|/|c'|³ has one √ per sample: magnitudes are certified-
+    exact ratios evaluated to float only for the viewer."""
+    import math
+
+    from forgekernel.nurbs import _deboor4, _hodo_list
+
+    p, U = curve.p, curve.U
+    pts = [tuple(pt) for pt in curve.cp]
+    (t0, t1) = curve.domain()
+    out = []
+    p1, U1, D1 = _hodo_list(p, U, pts)
+    p2, U2, D2 = _hodo_list(p1, U1, D1) if p1 >= 1 else (-1, [], [])
+    for k in range(n + 1):
+        t = F(t0) + F(k, n) * (F(t1) - F(t0))
+        c = curve.eval(t)
+        d1 = _deboor4(p1, U1, D1, t) if D1 else (F(0),) * 3
+        d2 = _deboor4(p2, U2, D2, t) if p2 >= 0 and D2 else (F(0),) * 3
+        cx = _cross(d1, d2)
+        num2 = _dot(cx, cx)                    # |c'×c''|², exact
+        den2 = _dot(d1, d1)                    # |c'|², exact
+        if den2 == 0:
+            continue
+        kappa = math.sqrt(float(num2)) / float(den2) ** 1.5
+        # normal direction: component of c'' orthogonal to c'
+        proj = _dot(d2, d1)
+        nvec = tuple(float(d2[c]) - float(proj / den2) * float(d1[c])
+                     for c in range(3))
+        nlen = math.sqrt(sum(x * x for x in nvec)) or 1.0
+        pt = tuple(float(x) for x in c)
+        tip = tuple(pt[c] + scale * kappa * nvec[c] / nlen for c in range(3))
+        out.append((pt, tip))
+    return out
+
+
+# -- K6.2: G1 blend strip (fill between two patches, proven smooth) -----------
+
+def _edge_data(surface: BSplineSurface, edge: str):
+    """(boundary curve net, transversal derivative net) along an edge —
+    exact Bézier control rows extracted from the surface net.
+
+    For a Bézier patch the boundary curve is the edge row/column of the
+    control net, and the transversal derivative along that edge is
+    p·(row₁ − row₀) (a Bézier curve of the edge parameter)."""
+    net = surface.cp
+    p, q = surface.p, surface.q
+    if any(w != F(1) for row in surface.w for w in row):
+        raise ValueError("blend strip: polynomial patches only (K6.3)")
+    if edge == "u1":        # u = 1 edge, parameter runs along v
+        c = net[-1]
+        d = [tuple(F(p) * (net[-1][j][k] - net[-2][j][k]) for k in range(3))
+             for j in range(q + 1)]
+    elif edge == "u0":
+        c = net[0]
+        d = [tuple(F(p) * (net[1][j][k] - net[0][j][k]) for k in range(3))
+             for j in range(q + 1)]
+    elif edge == "v1":
+        c = [net[i][-1] for i in range(p + 1)]
+        d = [tuple(F(q) * (net[i][-1][k] - net[i][-2][k]) for k in range(3))
+             for i in range(p + 1)]
+    else:
+        c = [net[i][0] for i in range(p + 1)]
+        d = [tuple(F(q) * (net[i][1][k] - net[i][0][k]) for k in range(3))
+             for i in range(p + 1)]
+    return [tuple(x) for x in c], d
+
+
+def g1_blend_strip(A: BSplineSurface, B: BSplineSurface, *,
+                   a_edge: str = "u1", b_edge: str = "u0") -> BSplineSurface:
+    """Fill the gap between an edge of ``A`` and an edge of ``B`` with a
+    cubic Hermite strip that meets BOTH with G1 continuity — by
+    construction, and certifiable by :func:`g1_certify` afterwards.
+
+    The strip is cubic transversally: Hermite data (position + outward
+    transversal derivative) at each end, converted to an exact Bézier
+    net via the Hermite→Bézier map  [P0, P0+m0/3, P1−m1/3, P1]."""
+    ca, da = _edge_data(A, a_edge)
+    cb, db = _edge_data(B, b_edge)
+    if len(ca) != len(cb):
+        raise ValueError("blend strip: edges must share degree (K6.3)")
+    # outward direction: A's edge derivative points OUT of A when the
+    # edge is u1/v1, INTO A when u0/v0 (flip). Likewise B's must point
+    # INTO the strip (i.e. out of B flipped at u1/v1... B's edge faces
+    # the strip, so B's outward transversal at u0/v0 is already inward).
+    sa = 1 if a_edge in ("u1", "v1") else -1
+    sb = 1 if b_edge in ("u1", "v1") else -1
+    n = len(ca)
+    net = []
+    for i in range(n):
+        p0 = ca[i]
+        p1 = cb[i]
+        m0 = tuple(sa * da[i][k] for k in range(3))       # d/dv at strip v=0
+        m1 = tuple(-sb * db[i][k] for k in range(3))      # d/dv at strip v=1
+        net.append([
+            p0,
+            tuple(p0[k] + m0[k] / 3 for k in range(3)),
+            tuple(p1[k] - m1[k] / 3 for k in range(3)),
+            p1,
+        ])
+    return bezier_surface(net)

forgekernel/tess.py

@@ -0,0 +1,74 @@
+"""Tessellation of the analytic composites (K2.x) for the viewer.
+
+Curved solids are exact objects; a mesh is a bounded-error VIEW of them.
+``deflection`` is the max chord error (mm) at the boundary — the one
+documented place a float enters, and only for display. Segment count is
+derived so the chord error stays under deflection: for radius r,
+N = ceil(pi / arccos(1 - deflection/r)).
+"""
+
+from __future__ import annotations
+
+import math
+
+
+def _nseg(radius: float, deflection: float) -> int:
+    r = max(radius, 1e-9)
+    if deflection >= r:
+        return 8
+    return max(8, math.ceil(math.pi / math.acos(max(-1.0, 1 - deflection / r))))
+
+
+def lathe(profile_rz: list[tuple], deflection: float = 0.2,
+          cx: float = 0.0, cy: float = 0.0) -> dict:
+    """Mesh a surface of revolution from a closed (r, z) profile revolved
+    about the z axis through (cx, cy). Deterministic; returns
+    {vertices, triangles}."""
+    rmax = max(r for r, _ in profile_rz) or 1.0
+    n = _nseg(rmax, deflection)
+    verts: list[list[float]] = []
+    tris: list[list[int]] = []
+    ring_start: list[int] = []
+    for r, z in profile_rz:
+        base = len(verts)
+        ring_start.append(base)
+        if r == 0:
+            verts.append([cx, cy, float(z)])
+        else:
+            for k in range(n):
+                a = 2 * math.pi * k / n
+                verts.append([cx + r * math.cos(a), cy + r * math.sin(a),
+                              float(z)])
+    m = len(profile_rz)
+    for i in range(m):
+        j = (i + 1) % m
+        ra = profile_rz[i][0]
+        rb = profile_rz[j][0]
+        a0, b0 = ring_start[i], ring_start[j]
+        if ra == 0 and rb == 0:
+            continue
+        for k in range(n):
+            kn = (k + 1) % n
+            if ra == 0:
+                tris.append([a0, b0 + k, b0 + kn])
+            elif rb == 0:
+                tris.append([a0 + k, b0, a0 + kn])
+            else:
+                tris.append([a0 + k, b0 + k, b0 + kn])
+                tris.append([a0 + k, b0 + kn, a0 + kn])
+    return {"vertices": verts, "triangles": tris}
+
+
+def mesh_volume(mesh: dict) -> float:
+    """Signed volume of a triangle mesh (divergence theorem) — the test
+    hook proving the mesh approximates the exact solid."""
+    v = mesh["vertices"]
+    total = 0.0
+    for a, b, c in mesh["triangles"]:
+        ax, ay, az = v[a]
+        bx, by, bz = v[b]
+        cx, cy, cz = v[c]
+        total += (ax * (by * cz - bz * cy)
+                  - ay * (bx * cz - bz * cx)
+                  + az * (bx * cy - by * cx))
+    return abs(total) / 6.0

forgekernel/trim.py

@@ -0,0 +1,193 @@
+"""K7 — trimmed-patch topology: a surface patch plus parameter-space trim
+loops, with **exact** point-in-region classification.
+
+A boolean over freeform solids produces faces that are only *part* of a
+surface — the region bounded by intersection curves. We represent that as
+the untrimmed patch (any surface exposing ``domain()``/``eval()``) plus a
+set of trim loops in the patch's (u, v) parameter domain:
+
+    loops[0]  — the outer boundary
+    loops[1:] — holes punched out of it
+
+Trim-loop vertices carry exact rational (u, v) coordinates: they come from
+certified SSI points (:func:`forgekernel.ssi.ssi_curves`) and patch-corner
+vertices, both already in ℚ. So the point-in-region test — even-odd ray
+parity — is decided in ℚ with **no tolerance**. That exactness is the whole
+point: which side of a trim boundary a point lies on is a *topological*
+decision, and ADR-0019 forbids a float from making it. A point that lands
+exactly on the boundary is reported as ``"on"`` (also an exact predicate),
+never silently bucketed into "in" or "out".
+
+The even-odd rule classifies correctly regardless of each loop's winding
+(a point inside a hole crosses outer+inner = even ⇒ out); loop orientation
+matters only for the signed parameter-domain area, not for containment.
+
+Not modeled here (deliberately): the *surface* area/volume of the trimmed
+region. Its integrand is the surface Jacobian and the trim curve is only
+polyline-approximated in parameter space, so that measure is not exact —
+it belongs to the later Green's-over-trim-loops step, not this type.
+"""
+
+from __future__ import annotations
+
+from fractions import Fraction as F
+
+
+def _as_uv(pt):
+    return (F(pt[0]), F(pt[1]))
+
+
+def _orient(a, b, c):
+    """Sign of the cross product (b−a)×(c−a): +1 left, −1 right, 0 collinear.
+    Exact in ℚ."""
+    d = (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0])
+    return (d > 0) - (d < 0)
+
+
+def _segments_properly_cross(a, b, c, d) -> bool:
+    """Do open segments a→b and c→d cross at an interior point? Exact ℚ, and
+    strict: shared endpoints or collinear touching do NOT count (those are
+    legal hole-touches-outer contacts, not a boundary crossing)."""
+    o1, o2 = _orient(a, b, c), _orient(a, b, d)
+    o3, o4 = _orient(c, d, a), _orient(c, d, b)
+    return o1 != 0 and o2 != 0 and o3 != 0 and o4 != 0 \
+        and o1 != o2 and o3 != o4
+
+
+class TrimmedPatch:
+    """A surface restricted to the region its trim loops enclose.
+
+    ``surface`` is any object with ``domain()`` -> ((u0,u1),(v0,v1)) and
+    ``eval(u, v)``. ``loops`` is a list of loops, each an ordered list of
+    (u, v) vertices (the closing edge back to the first vertex is implicit);
+    ``loops[0]`` is the outer boundary and the rest are holes."""
+
+    def __init__(self, surface, loops) -> None:
+        self.surface = surface
+        self.loops = [[_as_uv(p) for p in loop] for loop in loops]
+        if not self.loops:
+            raise ValueError("trimmed patch needs at least an outer loop")
+        for i, loop in enumerate(self.loops):
+            if len(loop) < 3:
+                raise ValueError(f"loop {i}: a trim loop needs >= 3 vertices")
+
+    # -- exact predicates ------------------------------------------------------
+
+    @staticmethod
+    def _on_segment(u, v, a, b) -> bool:
+        """Is (u, v) exactly on the closed segment a→b? (exact in ℚ)."""
+        cross = (b[0] - a[0]) * (v - a[1]) - (b[1] - a[1]) * (u - a[0])
+        if cross != 0:
+            return False
+        # collinear — inside the segment's bounding box?
+        return (min(a[0], b[0]) <= u <= max(a[0], b[0])
+                and min(a[1], b[1]) <= v <= max(a[1], b[1]))
+
+    def classify(self, u, v) -> str:
+        """Exact point-in-region: ``"in"`` (strict interior), ``"on"`` (on a
+        trim edge), or ``"out"``. All decided in ℚ — no tolerance."""
+        u, v = F(u), F(v)
+        # boundary first: an on-edge point is neither in nor out
+        for loop in self.loops:
+            m = len(loop)
+            for k in range(m):
+                if self._on_segment(u, v, loop[k], loop[(k + 1) % m]):
+                    return "on"
+        # even-odd parity of a +u ray at height v, over every loop's edges
+        inside = False
+        for loop in self.loops:
+            m = len(loop)
+            for k in range(m):
+                a, b = loop[k], loop[(k + 1) % m]
+                if (a[1] > v) != (b[1] > v):
+                    # u of the edge's crossing with the horizontal line at v
+                    x_int = a[0] + (v - a[1]) * (b[0] - a[0]) / (b[1] - a[1])
+                    if u < x_int:
+                        inside = not inside
+        return "in" if inside else "out"
+
+    def contains(self, u, v) -> bool:
+        """True iff (u, v) is in the strict interior of the trimmed region."""
+        return self.classify(u, v) == "in"
+
+    # -- exact volume contribution (K7 flux over the trim loops) ---------------
+
+    def flux(self):
+        """This trimmed face's exact flux contribution
+        (1/3)∮∮_D S·(S_u×S_v) du dv to the enclosed solid volume, via Green's
+        theorem over the trim loops (:func:`forgekernel.bsolid.trimmed_patch_flux`).
+        Requires a polynomial surface. Loops are winding-normalized first so
+        the outer/hole orientation is correct. Summing ``flux`` over the
+        outward-oriented faces of a closed shell gives the solid volume."""
+        from forgekernel.bsolid import trimmed_patch_flux
+        n = self.normalized()
+        return trimmed_patch_flux(n.surface, n.loops)
+
+    # -- exact measures --------------------------------------------------------
+
+    @staticmethod
+    def _loop_signed_area(loop):
+        """Shoelace signed area (exact ℚ); CCW positive."""
+        m = len(loop)
+        s = F(0)
+        for k in range(m):
+            a, b = loop[k], loop[(k + 1) % m]
+            s += a[0] * b[1] - b[0] * a[1]
+        return s / 2
+
+    def signed_area(self):
+        """Exact signed parameter-domain area = outer + Σ holes, using each
+        loop's given winding (outer CCW +, holes CW −). This is the (u, v)
+        measure of the region, NOT the surface area — see the module note."""
+        return sum((self._loop_signed_area(loop) for loop in self.loops), F(0))
+
+    def area(self):
+        """Exact unsigned parameter-domain area: |outer| − Σ|holes|."""
+        loops = self.loops
+        outer = abs(self._loop_signed_area(loops[0]))
+        holes = sum(abs(self._loop_signed_area(h)) for h in loops[1:])
+        return outer - holes
+
+    # -- orientation / validation ---------------------------------------------
+
+    def is_ccw(self, index: int = 0) -> bool:
+        return self._loop_signed_area(self.loops[index]) > 0
+
+    def normalized(self) -> "TrimmedPatch":
+        """Return a copy with canonical winding: outer CCW, holes CW."""
+        out = []
+        for i, loop in enumerate(self.loops):
+            ccw = self._loop_signed_area(loop) > 0
+            want_ccw = (i == 0)
+            out.append(list(loop) if ccw == want_ccw else list(reversed(loop)))
+        return TrimmedPatch(self.surface, out)
+
+    def validate(self) -> None:
+        """Structural checks: every vertex inside the surface's parameter
+        domain, holes strictly inside the outer boundary."""
+        (u0, u1), (v0, v1) = self.surface.domain()
+        for i, loop in enumerate(self.loops):
+            for (u, v) in loop:
+                if not (u0 <= u <= u1 and v0 <= v <= v1):
+                    raise ValueError(
+                        f"loop {i}: vertex ({u},{v}) outside surface domain")
+        outer = TrimmedPatch(self.surface, [self.loops[0]])
+        outer_loop = self.loops[0]
+        no = len(outer_loop)
+        for i, hole in enumerate(self.loops[1:], start=1):
+            # WHOLE-polygon containment, not a single sample point: every hole
+            # vertex must be in-or-on the outer boundary AND no hole edge may
+            # properly cross an outer edge. Testing only the vertex average
+            # accepts holes that stick out through the boundary and rejects
+            # valid holes whose average lands in a concavity (reviewed 2026-07).
+            for (u, v) in hole:
+                if outer.classify(u, v) == "out":
+                    raise ValueError(f"hole {i} is not inside the outer boundary")
+            mh = len(hole)
+            for a in range(mh):
+                h0, h1 = hole[a], hole[(a + 1) % mh]
+                for b in range(no):
+                    o0, o1 = outer_loop[b], outer_loop[(b + 1) % no]
+                    if _segments_properly_cross(h0, h1, o0, o1):
+                        raise ValueError(
+                            f"hole {i} crosses the outer boundary")

forgekernel-0.1.0.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: forgekernel
+Version: 0.1.0
+Summary: Exact-arithmetic B-rep CAD kernel: topology decided in ℚ, never by floating-point epsilon
+Author-email: Dan Willis <danielcwillis@gmail.com>
+Maintainer-email: Dan Willis <danielcwillis@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/gitcad-xyz/forge
+Project-URL: Repository, https://github.com/gitcad-xyz/forge
+Project-URL: Issues, https://github.com/gitcad-xyz/forge/issues
+Project-URL: Design — ADR-0018, https://github.com/gitcad-xyz/gitcad/blob/main/docs/adr/0018-native-kernel.md
+Project-URL: Benchmarks vs OCCT, https://github.com/gitcad-xyz/gitcad/blob/main/bench/RUST-vs-OCCT.md
+Keywords: cad,b-rep,brep,geometry,kernel,nurbs,solid-modeling,computational-geometry,exact-arithmetic,rational-arithmetic,step,occt,opencascade
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: rust
+Requires-Dist: forgekernel_rs>=0.1.0; extra == "rust"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# forge — the gitcad-native B-rep kernel
+
+From-scratch, unencumbered (Apache-2.0), built to pass the bar OCCT
+sets and then raise it — the plan and the decision record live in
+gitcad ([ADR-0018](https://github.com/gitcad-xyz/gitcad/blob/main/docs/adr/0018-native-kernel.md),
+[coverage plan](https://github.com/gitcad-xyz/gitcad/blob/main/docs/research/kernel-coverage-plan.md)).
+
+## The three-oracle chain
+
+```
+forgekernel.ref   Python + exact rational arithmetic — the executable
+                  specification; topological decisions are EXACT, never
+                  epsilon-guarded
+      ⇅ differential
+OCCT              the 30-year-hardened independent oracle, driven from
+                  the gitcad benchmark corpus through the Kernel seam
+      ⇅ oracle
+forge (Rust)      the production port, added operator class by operator
+                  class once ref has proven the semantics
+```
+
+## How progress is measured
+
+Not vibes: the [benchmark trend](https://github.com/gitcad-xyz/gitcad/blob/main/bench/TREND.md)
+in the gitcad repo scores every backend on the shared corpus —
+capability %, torture-case pass rate, correctness deltas, wall time.
+Day-one baseline: OCCT scores 93.8%, failing `swept_channel`
+(sharp-cornered sweep → invalid geometry). Beating that number with
+exact arithmetic is the first milestone.
+
+## Roadmap (gates, not dates)
+
+- **K1** exact planar core: rational linear algebra, plane-based
+  polyhedral B-rep, epsilon-free booleans, divergence-theorem mass
+  properties, native lineage. Gate: planar corpus green vs OCCT.
+- **K2** quadrics + torus with closed-form intersectors — most of
+  real mech. Gate: ≥80% corpus green.
+- **K3** NURBS + branch-complete surface–surface intersection (the
+  crown jewel). **K4** procedural offsets/shell. **K5** G2 blends.
+  **K6** the surfacing suite — the SolidWorks-class end goal.
+
+## Layout
+
+- `src/forgekernel/` — the Python reference kernel (`ref`)
+- `rust/` — the forge port (arrives with K1 stability)
+- gitcad consumes both through its `Kernel` seam; nothing here depends
+  on gitcad