@absolutejs/geometry 0.1.0 → 0.2.0

package/README.md

@@ -75,3 +75,59 @@ Run `bun install --frozen-lockfile` and `bun run check:package`.
 and its development asset tooling; see docs/canopy-audit/README.md.
 
 Licensed under BSL-1.1; see LICENSE for the additional use grant and change date.
+
+## Worker-side alpha preparation (0.1.1)
+
+`alphaFromRgba(rgba, width, height)` copies one alpha byte per RGBA8 texel into an
+owned Uint8Array. It accepts Uint8Array or Uint8ClampedArray and validates the
+exact byte length and the same 4,194,304-texel budget before allocation.
+
+`alphaFromImageBitmap(bitmap)` reads an already decoded bitmap using a temporary
+OffscreenCanvas 2D context with `willReadFrequently: true`. Call it in a worker;
+it performs synchronous CPU readback wherever it is called. The temporary canvas
+is released afterward. It does not create a WebGL context, close the input bitmap,
+or detach any borrowed renderer resource. The caller owns bitmap cleanup.
+Unsupported runtimes, closed/invalid bitmaps and oversized images fail explicitly.
+There is no hidden main-thread fallback.
+
+ImageBitmap supports structured cloning as well as transfer. The browser-worker
+qualification checks exact alpha values and that closing a cloned worker image
+leaves its source usable. Transfer only owned copies if using a transfer list.
+See the [HTML ImageBitmap ownership contract](https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap)
+and [OffscreenCanvas](https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas).
+These helpers prepare raster inputs; they do not assign hydrologic meaning to alpha.
+
+## Oriented solid boundaries (0.2.0)
+
+`closedComponents(positions, indices)` splits index-connected closed oriented
+boundary shells. Coincident coordinates never weld distinct authored vertices.
+`solidPointMembership(positions, indices)` prepares a solid-angle classifier that
+returns `inside`, `outside`, or `boundary`; oriented cavity walls cancel their
+outer shell's winding inside a void.
+
+`solidComponents(positions, indices, faceOwners, maxTriangleTests?)` returns
+`{ components, shells, cavities, pointQueries, triangleTests }`. Each component
+contains positions, indices and original `sourceTriangles`. It preserves separate
+positive components of the same source, and assigns each inward cavity to the
+smallest enclosing positive shell **of its explicitly declared source**. It never
+infers source identity, takes absolute cavity mass, or uses a convex hull.
+
+Precondition: each owner's input must be a valid, nonintersecting oriented solid
+boundary, such as a validated Boolean kernel result. Shells must not touch.
+Topology checks and all-cavity-vertex containment checks are **not** a complete
+triangle-intersection validator; do not use this API to repair arbitrary soups.
+An outward material island inside an inward cavity remains a separate component.
+Deterministic order is positive-shell order, followed by each component's cavity
+shells; provenance follows that same face order (not globally sorted).
+
+Inputs are Float64 positions, Uint32 indices, and Int16/Uint16 per-face owners.
+Limits: 100,000 vertices, 200,000 triangles, 128 shells. Prepared point classifiers
+support up to 20,000 triangles; containment charges every tested outer triangle
+per cavity vertex, with 2 million tests by default (maximum 8 million). No GPU,
+Three.js, WASM, or runtime dependencies. All coordinates must share one local
+frame; point boundary tolerance is 1e-7 coordinate units, winding tolerance 1e-5.
+Near-degenerate faces, unresolved orientation, missing cavity parents, detected
+touching/crossing shells and exhausted budgets throw rather than guess.
+
+Sources: [Manifold's oriented boundary representation](https://manifoldcad.org/docs/jsuser/classes/Manifold.html)
+and [Jacobson et al.'s generalized winding numbers](https://igl.ethz.ch/projects/winding-number/robust-inside-outside-segmentation-using-generalized-winding-numbers-siggraph-2013-jacobson-et-al.pdf).

package/dist/alpha.d.ts

@@ -0,0 +1,5 @@
+/** Copy one alpha byte per row-major RGBA8 texel. Does not mutate borrowed pixels. */
+export declare function alphaFromRgba(rgba: Uint8Array | Uint8ClampedArray, width: number, height: number): Uint8Array;
+/** Worker/setup-time CPU readback. The caller owns and closes the bitmap.
+ * This never closes/detaches the caller's image and never creates a WebGL context. */
+export declare function alphaFromImageBitmap(bitmap: ImageBitmap): Uint8Array;

package/dist/alpha.js

@@ -0,0 +1,37 @@
+const MAX_TEXELS = 4_194_304;
+function validateSize(width, height) {
+    if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 1 || height < 1 || width * height > MAX_TEXELS)
+        throw Error('Invalid or oversized alpha source');
+}
+/** Copy one alpha byte per row-major RGBA8 texel. Does not mutate borrowed pixels. */
+export function alphaFromRgba(rgba, width, height) {
+    validateSize(width, height);
+    if (!(rgba instanceof Uint8Array || rgba instanceof Uint8ClampedArray) || rgba.length !== width * height * 4)
+        throw Error('Expected tightly packed RGBA8 alpha source');
+    const alpha = new Uint8Array(width * height);
+    for (let i = 0; i < alpha.length; i++)
+        alpha[i] = rgba[i * 4 + 3];
+    return alpha;
+}
+/** Worker/setup-time CPU readback. The caller owns and closes the bitmap.
+ * This never closes/detaches the caller's image and never creates a WebGL context. */
+export function alphaFromImageBitmap(bitmap) {
+    if (typeof ImageBitmap === 'undefined' || !(bitmap instanceof ImageBitmap))
+        throw Error('Expected an available ImageBitmap');
+    validateSize(bitmap.width, bitmap.height);
+    if (typeof OffscreenCanvas === 'undefined')
+        throw Error('OffscreenCanvas is unavailable for alpha readback');
+    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+    try {
+        const context = canvas.getContext('2d', { willReadFrequently: true });
+        if (!context)
+            throw Error('Canvas2D is unavailable for alpha readback');
+        context.drawImage(bitmap, 0, 0);
+        const pixels = context.getImageData(0, 0, bitmap.width, bitmap.height);
+        return alphaFromRgba(pixels.data, pixels.width, pixels.height);
+    }
+    finally {
+        canvas.width = 0;
+        canvas.height = 0;
+    }
+}

package/dist/closedComponents.d.ts

@@ -0,0 +1,7 @@
+/** Split welded closed components by index connectivity, never by spatial proximity.
+ * Coincident vertices in distinct authored solids deliberately remain distinct. */
+export declare function closedComponents(positions: Float64Array, indices: Uint32Array): {
+    positions: Float64Array<ArrayBuffer>;
+    indices: Uint32Array<ArrayBuffer>;
+    sourceTriangles: Uint32Array<ArrayBuffer>;
+}[];

package/dist/closedComponents.js

@@ -0,0 +1,76 @@
+/** Split welded closed components by index connectivity, never by spatial proximity.
+ * Coincident vertices in distinct authored solids deliberately remain distinct. */
+export function closedComponents(positions, indices) {
+    if (!(positions instanceof Float64Array) ||
+        positions.length % 3 ||
+        positions.length > 300000 ||
+        !positions.every(Number.isFinite) ||
+        !(indices instanceof Uint32Array) ||
+        indices.length % 3 ||
+        indices.length > 600000 ||
+        !indices.every((i) => i < positions.length / 3))
+        throw Error('Invalid component mesh');
+    const parent = Int32Array.from({ length: positions.length / 3 }, (_, i) => i), used = new Uint8Array(parent.length);
+    const find = (start) => {
+        let root = start;
+        while (parent[root] !== root)
+            root = parent[root];
+        while (start !== root) {
+            const next = parent[start];
+            parent[start] = root;
+            start = next;
+        }
+        return root;
+    };
+    const edgeCounts = new Map();
+    for (let i = 0; i < indices.length; i += 3)
+        for (let j = 0; j < 3; j++) {
+            const a = indices[i + j], b = indices[i + ((j + 1) % 3)];
+            if (a === b)
+                throw Error('Degenerate component triangle');
+            used[a] = used[b] = 1;
+            const ra = find(a), rb = find(b);
+            if (ra !== rb)
+                parent[Math.max(ra, rb)] = Math.min(ra, rb);
+            const key = a < b ? `${a}:${b}` : `${b}:${a}`, edge = edgeCounts.get(key);
+            if (edge) {
+                if (edge.count !== 1 || edge.a !== b || edge.b !== a)
+                    throw Error('Nonmanifold component mesh');
+                edge.count++;
+            }
+            else
+                edgeCounts.set(key, { a, b, count: 1 });
+        }
+    if ([...edgeCounts.values()].some((e) => e.count !== 2))
+        throw Error('Open component mesh');
+    const groups = new Map();
+    for (let i = 0; i < parent.length; i++)
+        if (used[i]) {
+            const root = find(i);
+            let group = groups.get(root);
+            if (!group) {
+                if (groups.size >= 128)
+                    throw Error('Component budget exceeded');
+                group = {
+                    positions: [],
+                    indices: [],
+                    sourceTriangles: [],
+                    map: new Map()
+                };
+                groups.set(root, group);
+            }
+            group.map.set(i, group.positions.length / 3);
+            group.positions.push(positions[i * 3], positions[i * 3 + 1], positions[i * 3 + 2]);
+        }
+    for (let t = 0; t < indices.length; t += 3) {
+        const group = groups.get(find(indices[t]));
+        for (let j = 0; j < 3; j++)
+            group.indices.push(group.map.get(indices[t + j]));
+        group.sourceTriangles.push(t / 3);
+    }
+    return [...groups.values()].map((g) => ({
+        positions: Float64Array.from(g.positions),
+        indices: Uint32Array.from(g.indices),
+        sourceTriangles: Uint32Array.from(g.sourceTriangles)
+    }));
+}

package/dist/index.d.ts

@@ -1 +1,5 @@
 export { projectAlphaCoverage, type AlphaProjectionInput, type AlphaProjection, } from "./projection.js";
+export { alphaFromRgba, alphaFromImageBitmap } from './alpha.js';
+export { closedComponents } from './closedComponents.js';
+export { solidPointMembership } from './solidPointMembership.js';
+export { solidComponents } from './solidComponents.js';

package/dist/index.js

@@ -1 +1,5 @@
 export { projectAlphaCoverage, } from "./projection.js";
+export { alphaFromRgba, alphaFromImageBitmap } from './alpha.js';
+export { closedComponents } from './closedComponents.js';
+export { solidPointMembership } from './solidPointMembership.js';
+export { solidComponents } from './solidComponents.js';

package/dist/solidComponents.d.ts

@@ -0,0 +1,16 @@
+/** Material components of a valid oriented Boolean boundary, restricted by explicit
+ * source identity. Input shells of each owner must not intersect or touch. This is
+ * not a triangle-soup repair or intersection validator. Positive islands remain
+ * separate; negative cavity walls attach to the smallest enclosing positive shell.
+ * All cavity vertices are checked, with a bounded winding-query budget. */
+export declare function solidComponents(positions: Float64Array, indices: Uint32Array, owners: Int16Array | Uint16Array, maxTriangleTests?: number): {
+    components: {
+        positions: Float64Array<ArrayBuffer>;
+        indices: Uint32Array<ArrayBuffer>;
+        sourceTriangles: Uint32Array<ArrayBuffer>;
+    }[];
+    shells: number;
+    cavities: number;
+    pointQueries: number;
+    triangleTests: number;
+};

package/dist/solidComponents.js

@@ -0,0 +1,94 @@
+import { closedComponents } from './closedComponents.js';
+import { solidPointMembership } from './solidPointMembership.js';
+/** Material components of a valid oriented Boolean boundary, restricted by explicit
+ * source identity. Input shells of each owner must not intersect or touch. This is
+ * not a triangle-soup repair or intersection validator. Positive islands remain
+ * separate; negative cavity walls attach to the smallest enclosing positive shell.
+ * All cavity vertices are checked, with a bounded winding-query budget. */
+export function solidComponents(positions, indices, owners, maxTriangleTests = 2_000_000) {
+    if (!(owners instanceof Int16Array || owners instanceof Uint16Array) ||
+        owners.length !== indices.length / 3 || !owners.every(v => v >= 0) ||
+        !Number.isSafeInteger(maxTriangleTests) || maxTriangleTests < 1 || maxTriangleTests > 8_000_000)
+        throw Error('Invalid material component input');
+    const shells = closedComponents(positions, indices).map(mesh => {
+        const owner = owners[mesh.sourceTriangles[0]];
+        if (mesh.sourceTriangles.some(t => owners[t] !== owner))
+            throw Error('Mixed shell ownership');
+        const volume = signedVolume(mesh.positions, mesh.indices);
+        if (!Number.isFinite(volume) || volume === 0)
+            throw Error('Unresolved shell volume');
+        const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+        mesh.positions.forEach((v, i) => { const k = i % 3; min[k] = Math.min(min[k], v); max[k] = Math.max(max[k], v); });
+        return { ...mesh, owner, volume, min, max };
+    });
+    const positive = shells.filter(s => s.volume > 0), holes = shells.filter(s => s.volume < 0), children = positive.map(() => []), classifiers = new Map();
+    let pointQueries = 0, triangleTests = 0;
+    for (const hole of holes) {
+        const enclosing = [];
+        for (const [id, outer] of positive.entries()) {
+            if (hole.owner !== outer.owner || hole.min.some((v, k) => v < outer.min[k] || hole.max[k] > outer.max[k]))
+                continue;
+            let classify = classifiers.get(id);
+            if (!classify) {
+                classify = solidPointMembership(outer.positions, outer.indices);
+                classifiers.set(id, classify);
+            }
+            let inside = 0, outside = 0;
+            for (let v = 0; v < hole.positions.length; v += 3) {
+                triangleTests += outer.indices.length / 3;
+                if (triangleTests > maxTriangleTests)
+                    throw Error('Material containment budget exceeded');
+                pointQueries++;
+                const membership = classify([hole.positions[v], hole.positions[v + 1], hole.positions[v + 2]]);
+                if (membership === 'boundary')
+                    throw Error('Touching material shells');
+                if (membership === 'inside')
+                    inside++;
+                else
+                    outside++;
+                if (inside && outside)
+                    throw Error('Crossing material shells');
+            }
+            if (inside)
+                enclosing.push(id);
+        }
+        enclosing.sort((a, b) => positive[a].volume - positive[b].volume);
+        if (!enclosing.length)
+            throw Error('Cavity has no enclosing source solid');
+        if (enclosing.length > 1 && positive[enclosing[0]].volume === positive[enclosing[1]].volume)
+            throw Error('Ambiguous cavity parent');
+        children[enclosing[0]].push(hole);
+    }
+    const components = positive.map((outer, id) => {
+        const parts = [outer, ...children[id]], p = [], i = [], triangles = [];
+        for (const part of parts) {
+            const offset = p.length / 3;
+            for (const v of part.positions)
+                p.push(v);
+            for (const v of part.indices)
+                i.push(v + offset);
+            for (const t of part.sourceTriangles)
+                triangles.push(t);
+        }
+        const mesh = { positions: Float64Array.from(p), indices: Uint32Array.from(i), sourceTriangles: Uint32Array.from(triangles) };
+        if (!(signedVolume(mesh.positions, mesh.indices) > 0))
+            throw Error('Nonpositive material component');
+        return mesh;
+    });
+    return { components, shells: shells.length, cavities: holes.length, pointQueries, triangleTests };
+}
+function signedVolume(p, i) {
+    const o = i[0] * 3, ox = p[o], oy = p[o + 1], oz = p[o + 2];
+    let sum = 0, error = 0;
+    for (let t = 0; t < i.length; t += 3) {
+        const a = i[t] * 3, b = i[t + 1] * 3, c = i[t + 2] * 3;
+        const ax = p[a] - ox, ay = p[a + 1] - oy, az = p[a + 2] - oz;
+        const bx = p[b] - ox, by = p[b + 1] - oy, bz = p[b + 2] - oz;
+        const cx = p[c] - ox, cy = p[c + 1] - oy, cz = p[c + 2] - oz;
+        const term = (ax * (by * cz - bz * cy) + ay * (bz * cx - bx * cz) + az * (bx * cy - by * cx)) / 6;
+        const increment = term - error, next = sum + increment;
+        error = next - sum - increment;
+        sum = next;
+    }
+    return sum;
+}

package/dist/solidPointMembership.d.ts

@@ -0,0 +1,6 @@
+type Point = readonly [number, number, number];
+/** Exact solid-angle sum for a closed oriented boundary, with explicit boundary
+ * classification. No convex hull, nearest-center assignment or sampled rays.
+ * Formula: Jacobson et al. 2013; see README sources and numerical limits. */
+export declare function solidPointMembership(positions: Float64Array, indices: Uint32Array): (point: Point) => "inside" | "outside" | "boundary";
+export {};

package/dist/solidPointMembership.js

@@ -0,0 +1,94 @@
+import { closedComponents } from './closedComponents.js';
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const cross = (a, b) => [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0]
+];
+const sub = (a, b) => [
+    a[0] - b[0],
+    a[1] - b[1],
+    a[2] - b[2]
+];
+/** Exact solid-angle sum for a closed oriented boundary, with explicit boundary
+ * classification. No convex hull, nearest-center assignment or sampled rays.
+ * Formula: Jacobson et al. 2013; see README sources and numerical limits. */
+export function solidPointMembership(positions, indices) {
+    if (!indices.length || indices.length > 60000)
+        throw Error('Solid point mesh budget exceeded');
+    closedComponents(positions, indices); // Require closed, consistently oriented topology.
+    const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+    const collapsedEdges = [];
+    const triangles = [];
+    for (let i = 0; i < indices.length; i += 3) {
+        const points = [0, 1, 2].map((k) => {
+            const id = indices[i + k] * 3;
+            return [
+                positions[id],
+                positions[id + 1],
+                positions[id + 2]
+            ];
+        });
+        const [a, b, c] = points, u = sub(b, a), v = sub(c, a), n = cross(u, v), area2 = dot(n, n);
+        for (const p of points)
+            for (let k = 0; k < 3; k++) {
+                min[k] = Math.min(min[k], p[k]);
+                max[k] = Math.max(max[k], p[k]);
+            }
+        // A clipping kernel may keep distinct topological vertices at identical
+        // coordinates. Such a face has exactly zero solid angle. Keep its edges
+        // for boundary queries without welding vertices or altering the mesh.
+        if (area2 === 0 &&
+            [u, v, sub(c, b)].some((edge) => edge.every((n) => n === 0))) {
+            collapsedEdges.push([a, b], [b, c], [c, a]);
+            continue;
+        }
+        if (!(area2 > 1e-30))
+            throw Error('Degenerate solid point face');
+        triangles.push({ a, b, c, u, v, n, area2 });
+    }
+    if (!triangles.length)
+        throw Error('Degenerate solid point mesh');
+    return (point) => {
+        if (point.length !== 3 || !point.every(Number.isFinite))
+            throw Error('Invalid solid query point');
+        const epsilon = 1e-7;
+        if (point.some((v, k) => v < min[k] - epsilon || v > max[k] + epsilon))
+            return 'outside';
+        for (const [a, b] of collapsedEdges) {
+            const edge = sub(b, a), delta = sub(point, a), length2 = dot(edge, edge);
+            const t = length2 === 0
+                ? 0
+                : Math.max(0, Math.min(1, dot(delta, edge) / length2));
+            if (Math.hypot(...delta.map((v, k) => v - t * edge[k])) <= epsilon)
+                return 'boundary';
+        }
+        let sum = 0, correction = 0;
+        for (const { a, b, c, u, v, n, area2 } of triangles) {
+            const delta = sub(point, a), distance = dot(delta, n);
+            if (distance * distance <= epsilon * epsilon * area2) {
+                // Barycentric coordinates of the orthogonal projection, using cross products
+                // instead of subtracting nearly equal Gram determinants on thin faces.
+                const s = dot(cross(delta, v), n) / area2, t = dot(cross(u, delta), n) / area2;
+                if (s >= -1e-10 && t >= -1e-10 && s + t <= 1 + 1e-10)
+                    return 'boundary';
+            }
+            const vectors = [a, b, c].map((p) => sub(p, point));
+            const lengths = vectors.map((p) => Math.hypot(...p));
+            if (lengths.some((l) => l <= epsilon))
+                return 'boundary';
+            const [x, y, z] = vectors.map((p, i) => p.map((v) => v / lengths[i]));
+            const angle = 2 *
+                Math.atan2(dot(x, cross(y, z)), 1 + dot(x, y) + dot(y, z) + dot(z, x));
+            const increment = angle - correction, next = sum + increment;
+            correction = next - sum - increment;
+            sum = next;
+        }
+        const winding = Math.abs(sum) / (4 * Math.PI);
+        if (winding < 1e-5)
+            return 'outside';
+        if (Math.abs(winding - 1) < 1e-5)
+            return 'inside';
+        throw Error('Ambiguous solid point membership');
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@absolutejs/geometry",
-  "version": "0.1.0",
-  "description": "Bounded alpha-aware geometry projection for worker-side asset measurement and web 3D tooling.",
+  "version": "0.2.0",
+  "description": "Bounded geometry projection, oriented material components and point membership for worker-side web 3D tooling.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",