@absolutejs/geometry 0.3.0 → 0.4.0

package/README.md

@@ -155,3 +155,46 @@ 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

@@ -4,3 +4,4 @@ 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

@@ -4,3 +4,4 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/geometry",
-  "version": "0.3.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",