@absolutejs/geometry 0.2.0 → 0.3.0

package/README.md

@@ -131,3 +131,27 @@ 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).
+
+## Initial material overlap audit (0.3.0)
+
+`auditSolidOverlaps(meshes, kernel, maximumQueries = 256)` checks solid intersection
+volumes before physics publication. Supply `{create(mesh), intersect(a,b)}` using
+your Boolean backend. Handles implement `volume()` and `delete()`; each operation
+must return a new owned handle. A factory that throws must release any allocation
+it made before throwing. The audit releases all successfully returned handles on
+both success and failure, and passes private position/index copies to the kernel.
+No Boolean engine is bundled or required at runtime.
+
+The result includes per-mesh oriented volumes, pair indices/intersection volumes,
+fraction of the smaller solid, query count, bounds skips and maximum input volume
+round-trip error. Touching/disjoint bounds need no native intersection. Candidate
+pairs are rebased before construction. Native volume error above 1e-5 or impossible
+intersection volume rejects; tiny nonzero intersections are reported, not rounded
+away. The host chooses its material-resolution threshold explicitly.
+
+Use valid oriented material boundaries, including cavity walls. The API does not
+repair overlapping shells within one input mesh, assign source ownership, union
+models, predict extraction clearance or validate dynamic contact penetration.
+Bounds are not proof of overlap. Limits: 64 meshes, 100,000 total vertices,
+200,000 total triangles, and at most 1,024 requested pair queries. A host worker
+must impose its own lifetime bound on its injected native kernel.

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export { alphaFromRgba, alphaFromImageBitmap } from './alpha.js';
 export { closedComponents } from './closedComponents.js';
 export { solidPointMembership } from './solidPointMembership.js';
 export { solidComponents } from './solidComponents.js';
+export { auditSolidOverlaps, type OverlapMesh, type OverlapSolid, type SolidOverlapAudit } from './overlap.js';

package/dist/index.js

@@ -3,3 +3,4 @@ export { alphaFromRgba, alphaFromImageBitmap } from './alpha.js';
 export { closedComponents } from './closedComponents.js';
 export { solidPointMembership } from './solidPointMembership.js';
 export { solidComponents } from './solidComponents.js';
+export { auditSolidOverlaps } from './overlap.js';

package/dist/overlap.d.ts

@@ -0,0 +1,30 @@
+export type OverlapMesh = {
+    positions: Float64Array;
+    indices: Uint32Array;
+};
+/** The host injects its Boolean kernel; all returned handles must be disposable. */
+export type OverlapSolid = {
+    volume(): number;
+    delete(): void;
+};
+export type SolidOverlapAudit = ReturnType<typeof auditSolidOverlaps>;
+/** Audit initial material overlap, not dynamic contact depth. Inputs must be valid
+ * oriented solid boundaries in one frame. No ownership, de-duplication or repair
+ * is inferred. Bounds skip disjoint/touching pairs; candidate pairs are rebased
+ * before invoking the host's kernel. Every native handle is released. */
+export declare function auditSolidOverlaps<S extends OverlapSolid>(meshes: readonly OverlapMesh[], kernel: {
+    create(mesh: OverlapMesh): S;
+    intersect(a: S, b: S): S;
+}, maximumQueries?: number): {
+    meshes: number;
+    volumes: number[];
+    pairs: {
+        a: number;
+        b: number;
+        volume: number;
+        fractionOfSmaller: number;
+    }[];
+    queries: number;
+    boundsSkipped: number;
+    maximumInputVolumeError: number;
+};

package/dist/overlap.js

@@ -0,0 +1,61 @@
+import { closedComponents } from './closedComponents.js';
+import { signedVolume } from './signedVolume.js';
+/** Audit initial material overlap, not dynamic contact depth. Inputs must be valid
+ * oriented solid boundaries in one frame. No ownership, de-duplication or repair
+ * is inferred. Bounds skip disjoint/touching pairs; candidate pairs are rebased
+ * before invoking the host's kernel. Every native handle is released. */
+export function auditSolidOverlaps(meshes, kernel, maximumQueries = 256) {
+    if (!Array.isArray(meshes) || meshes.length > 64 || !kernel || typeof kernel.create !== 'function' || typeof kernel.intersect !== 'function' ||
+        !Number.isSafeInteger(maximumQueries) || maximumQueries < 1 || maximumQueries > 1024 ||
+        meshes.reduce((n, m) => n + (m?.positions?.length ?? Infinity), 0) > 300000 ||
+        meshes.reduce((n, m) => n + (m?.indices?.length ?? Infinity), 0) > 600000)
+        throw Error('Invalid overlap audit budget');
+    const records = meshes.map(mesh => {
+        if (!mesh.indices.length)
+            throw Error('Empty overlap solid');
+        closedComponents(mesh.positions, mesh.indices);
+        const volume = signedVolume(mesh.positions, mesh.indices);
+        if (!(volume > 0) || !Number.isFinite(volume))
+            throw Error('Invalid overlap solid volume');
+        const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+        mesh.positions.forEach((v, i) => { min[i % 3] = Math.min(min[i % 3], v); max[i % 3] = Math.max(max[i % 3], v); });
+        return { ...mesh, volume, min, max };
+    });
+    const pairs = [];
+    let queries = 0, boundsSkipped = 0, maximumInputVolumeError = 0;
+    for (let a = 0; a < records.length; a++)
+        for (let b = a + 1; b < records.length; b++) {
+            const one = records[a], two = records[b];
+            if (one.min.some((v, k) => v >= two.max[k] || one.max[k] <= two.min[k])) {
+                boundsSkipped++;
+                continue;
+            }
+            if (++queries > maximumQueries)
+                throw Error('Overlap query budget exceeded');
+            const origin = one.min.map((v, k) => (Math.min(v, two.min[k]) + Math.max(one.max[k], two.max[k])) / 2);
+            const handles = [];
+            try {
+                const solids = [one, two].map(record => {
+                    const local = Float64Array.from(record.positions, (v, i) => v - origin[i % 3]);
+                    const solid = kernel.create({ positions: local, indices: record.indices.slice() });
+                    handles.push(solid);
+                    const error = Math.abs(solid.volume() / record.volume - 1);
+                    if (!Number.isFinite(error) || error > 1e-5)
+                        throw Error('Overlap input precision budget exceeded');
+                    maximumInputVolumeError = Math.max(maximumInputVolumeError, error);
+                    return solid;
+                });
+                const intersection = kernel.intersect(solids[0], solids[1]);
+                handles.push(intersection);
+                const volume = intersection.volume(), fractionOfSmaller = volume / Math.min(one.volume, two.volume);
+                if (!Number.isFinite(volume) || volume < 0 || fractionOfSmaller > 1.00001)
+                    throw Error('Invalid overlap volume');
+                pairs.push({ a, b, volume, fractionOfSmaller });
+            }
+            finally {
+                for (const handle of handles.reverse())
+                    handle.delete();
+            }
+        }
+    return { meshes: records.length, volumes: records.map(r => r.volume), pairs, queries, boundsSkipped, maximumInputVolumeError };
+}

package/dist/signedVolume.d.ts

@@ -0,0 +1 @@
+export declare function signedVolume(p: Float64Array, i: Uint32Array): number;

package/dist/signedVolume.js

@@ -0,0 +1,15 @@
+export 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/solidComponents.js

@@ -1,3 +1,4 @@
+import { signedVolume } from './signedVolume.js';
 import { closedComponents } from './closedComponents.js';
 import { solidPointMembership } from './solidPointMembership.js';
 /** Material components of a valid oriented Boolean boundary, restricted by explicit
@@ -77,18 +78,3 @@ export function solidComponents(positions, indices, owners, maxTriangleTests = 2
     });
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/geometry",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Bounded geometry projection, oriented material components and point membership for worker-side web 3D tooling.",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,7 +33,8 @@
     "check:package": "bun run build && bun test ./tests"
   },
   "devDependencies": {
-    "typescript": "5.9.3",
-    "@types/bun": "1.4.2"
+    "@types/bun": "1.4.2",
+    "manifold-3d": "3.5.1",
+    "typescript": "5.9.3"
   }
 }