@absolutejs/geometry 0.2.0 → 0.4.0

package/README.md

@@ -131,3 +131,70 @@ 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.
+
+## Exclusive material partition (0.4.0)
+
+`partitionSolidMaterials(meshes, kernel, maximumOperations = 126)` implements
+ordered solid ownership. Cell i is input i minus the union of earlier inputs.
+The caller explicitly chooses the order; this library does not invent a material
+priority. Inputs must be valid oriented solid boundaries, including cavity walls.
+
+Supply `{create(mesh), subtract(a,b), union(a,b), mesh(solid)}`. Native handles
+implement `volume()` and `delete()`; every construction/operation returns a fresh
+handle, and failures inside the adapter must clean up allocations not returned.
+`mesh` returns Float64 positions and Uint32 indices in the supplied local frame.
+Return a valid closed boundary, or two empty arrays for an empty solid. The
+package copies all borrowed arrays and releases native handles on success/failure.
+At most three native handles are retained at once, including the output of the
+current operation; previous union/intermediate geometry is promptly released.
+
+Results include:
+- `cells`: one entry per input, with stable `source` index, mesh and volume.
+  A fully covered source remains an explicitly empty cell.
+- `exterior`: the separate whole-union boundary and volume.
+- `inputVolumes`, `authoredVolume`, `materialVolume`, `volumeDifference`,
+  `maximumVolumeError` and `operations`. The signed volume difference is not
+  clamped; insignificant negative roundoff can remain.
+
+Cell walls include internal material interfaces. **Do not render every cell wall
+as exposed material or infer that two touching cells are detached.** Exterior face
+provenance, adjacency, strength, density, fracture surfaces and extraction/physics
+acceptance remain host concerns. In particular this does not turn an existing
+positive-overlap attachment graph into a surface-interface graph.
+
+Limits: 1–64 inputs, 100,000 input vertices/200,000 input triangles, up to 126
+Boolean operations, and 200,000 exported vertices/400,000 exported triangles
+across all cells plus exterior. Native input/output volume and total conservation
+errors above 1e-5 reject. These are acceptance budgets, not certified geometric
+error bounds or a proof against a faulty Boolean backend. Topology checks do not
+detect all geometric self-intersections. Use a cancellable worker: a synchronous
+backend call cannot be interrupted by an operation counter.
+
+The implementation uses the set identity
+`C_i = S_i ∖ (S_0 ∪ … ∪ S_(i−1))`; its tests use Manifold only as a development
+dependency. [Manifold's documentation](https://manifoldcad.org/docs/jsuser/classes/Manifold.html)
+describes the native Boolean/volume contract. No Boolean engine is bundled.

package/dist/index.d.ts

@@ -3,3 +3,5 @@ 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';
+export { partitionSolidMaterials, type MaterialPartitionKernel, type SolidMaterialPartition } from './materialPartition.js';

package/dist/index.js

@@ -3,3 +3,5 @@ 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';
+export { partitionSolidMaterials } from './materialPartition.js';

package/dist/materialPartition.d.ts

@@ -0,0 +1,39 @@
+import type { OverlapMesh, OverlapSolid } from './overlap.js';
+export type MaterialPartitionKernel<S extends OverlapSolid> = {
+    create(mesh: OverlapMesh): S;
+    subtract(a: S, b: S): S;
+    union(a: S, b: S): S;
+    mesh(solid: S): OverlapMesh;
+};
+/**
+ * Ordered CSG material ownership: cell i = input i minus all earlier inputs.
+ * Input order is the host's explicit policy. The separate union mesh is the
+ * exterior; cell boundaries include INTERNAL partition walls and must not be
+ * blindly rendered or interpreted as fractures. No attachment/strength inference.
+ *
+ * The host must supply correct Boolean operations and fresh disposable handles.
+ * Meshes are valid, consistently oriented, non-self-intersecting solid boundaries;
+ * closedComponents checks topology, not geometric self-intersection. All input
+ * geometry is copied/rebased before the host sees it. Returned meshes are copied.
+ * Native work is bounded by input/output sizes and operation count, not wall time.
+ * Run in a cancellable worker for a wall-clock deadline.
+ */
+export declare function partitionSolidMaterials<S extends OverlapSolid>(meshes: readonly OverlapMesh[], kernel: MaterialPartitionKernel<S>, maximumOperations?: number): {
+    cells: ({
+        source: number;
+    } & OverlapMesh & {
+        volume: number;
+    })[];
+    exterior: {
+        positions: Float64Array<ArrayBuffer>;
+        indices: Uint32Array<ArrayBuffer>;
+        volume: number;
+    };
+    inputVolumes: number[];
+    authoredVolume: number;
+    materialVolume: number;
+    volumeDifference: number;
+    maximumVolumeError: number;
+    operations: number;
+};
+export type SolidMaterialPartition = ReturnType<typeof partitionSolidMaterials>;

package/dist/materialPartition.js

@@ -0,0 +1,117 @@
+import { closedComponents } from './closedComponents.js';
+import { signedVolume } from './signedVolume.js';
+/**
+ * Ordered CSG material ownership: cell i = input i minus all earlier inputs.
+ * Input order is the host's explicit policy. The separate union mesh is the
+ * exterior; cell boundaries include INTERNAL partition walls and must not be
+ * blindly rendered or interpreted as fractures. No attachment/strength inference.
+ *
+ * The host must supply correct Boolean operations and fresh disposable handles.
+ * Meshes are valid, consistently oriented, non-self-intersecting solid boundaries;
+ * closedComponents checks topology, not geometric self-intersection. All input
+ * geometry is copied/rebased before the host sees it. Returned meshes are copied.
+ * Native work is bounded by input/output sizes and operation count, not wall time.
+ * Run in a cancellable worker for a wall-clock deadline.
+ */
+export function partitionSolidMaterials(meshes, kernel, maximumOperations = 126) {
+    if (!Array.isArray(meshes) || !meshes.length || meshes.length > 64 ||
+        !kernel || !['create', 'subtract', 'union', 'mesh'].every(k => typeof kernel[k] === 'function') ||
+        !Number.isSafeInteger(maximumOperations) || maximumOperations < 0 || maximumOperations > 126 ||
+        2 * (meshes.length - 1) > maximumOperations ||
+        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 material partition budget');
+    const inputs = meshes;
+    const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+    const volumes = inputs.map(m => {
+        if (!(m.positions instanceof Float64Array) || !(m.indices instanceof Uint32Array) || !m.indices.length)
+            throw Error('Invalid material partition mesh');
+        closedComponents(m.positions, m.indices);
+        const v = signedVolume(m.positions, m.indices);
+        if (!Number.isFinite(v) || v <= 0)
+            throw Error('Invalid material input volume');
+        m.positions.forEach((p, i) => { min[i % 3] = Math.min(min[i % 3], p); max[i % 3] = Math.max(max[i % 3], p); });
+        return v;
+    });
+    const origin = min.map((v, k) => v / 2 + max[k] / 2);
+    const handles = new Set(), seen = new Set();
+    const own = (s) => {
+        if (seen.has(s))
+            throw Error('Material kernel must return fresh handles');
+        seen.add(s);
+        handles.add(s);
+        return s;
+    };
+    const release = (s) => { handles.delete(s); s.delete(); };
+    let maximumVolumeError = 0, outputVertices = 0, outputIndices = 0, operations = 0;
+    const checkVolume = (actual, expected) => {
+        const error = Math.abs(actual / expected - 1);
+        if (!Number.isFinite(error) || error > 1e-5)
+            throw Error('Material volume precision budget exceeded');
+        maximumVolumeError = Math.max(maximumVolumeError, error);
+    };
+    const read = (s) => {
+        const volume = s.volume();
+        if (!Number.isFinite(volume) || volume < 0)
+            throw Error('Invalid partition output volume');
+        const raw = kernel.mesh(s);
+        if (!(raw?.positions instanceof Float64Array) || !(raw?.indices instanceof Uint32Array) ||
+            (outputVertices += raw.positions.length / 3) > 200000 ||
+            (outputIndices += raw.indices.length) > 1200000)
+            throw Error('Material output budget exceeded');
+        const positions = raw.positions.slice(), indices = raw.indices.slice();
+        if (!indices.length) {
+            if (positions.length || volume !== 0)
+                throw Error('Invalid empty material cell');
+            return { positions, indices, volume };
+        }
+        closedComponents(positions, indices);
+        checkVolume(signedVolume(positions, indices), volume);
+        for (let i = 0; i < positions.length; i++)
+            positions[i] = positions[i] + origin[i % 3];
+        // Re-check precision after restoring the requested coordinate frame.
+        checkVolume(signedVolume(positions, indices), volume);
+        return { positions, indices, volume };
+    };
+    try {
+        const cells = [];
+        let combined;
+        for (let i = 0; i < inputs.length; i++) {
+            const m = inputs[i];
+            const input = own(kernel.create({
+                positions: Float64Array.from(m.positions, (v, j) => v - origin[j % 3]),
+                indices: m.indices.slice(),
+            }));
+            checkVolume(input.volume(), volumes[i]);
+            const exclusive = combined ? own(kernel.subtract(input, combined)) : input;
+            if (combined)
+                operations++;
+            if (exclusive.volume() > input.volume() * 1.00001)
+                throw Error('Partition subtraction enlarged material');
+            cells.push({ source: i, ...read(exclusive) });
+            if (combined) {
+                release(exclusive);
+                const previous = combined;
+                combined = own(kernel.union(previous, input));
+                operations++;
+                release(previous);
+                release(input);
+            }
+            else
+                combined = input;
+        }
+        const exterior = read(combined);
+        const materialVolume = cells.reduce((n, c) => n + c.volume, 0);
+        checkVolume(materialVolume, exterior.volume);
+        const authoredVolume = volumes.reduce((n, v) => n + v, 0);
+        if (exterior.volume > authoredVolume * 1.00001)
+            throw Error('Partition union enlarged material');
+        return { cells, exterior, inputVolumes: volumes, authoredVolume,
+            materialVolume: exterior.volume, volumeDifference: authoredVolume - exterior.volume,
+            maximumVolumeError, operations };
+    }
+    finally {
+        for (const h of [...handles].reverse())
+            h.delete();
+    }
+}

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.4.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"
   }
 }