okgeometry-api 1.1.1 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okgeometry-api",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Geometry engine API for AEC applications — NURBS, meshes, booleans, intersections. Powered by Rust/WASM.",
   "type": "module",
   "main": "dist/index.js",

package/src/Mesh.ts

@@ -47,23 +47,77 @@ export interface PlanarCircle {
   radius: number;
 }
 
-export interface PlanarArc {
-  points: Point[];
-  center: Point;
-  radius: number;
-  startAngle: number;
-  endAngle: number;
-  sweepAngle: number;
-}
-
-interface RawMeshBounds {
-  minX: number;
-  minY: number;
-  minZ: number;
-  maxX: number;
-  maxY: number;
-  maxZ: number;
-}
+export interface PlanarArc {
+  points: Point[];
+  center: Point;
+  radius: number;
+  startAngle: number;
+  endAngle: number;
+  sweepAngle: number;
+}
+
+interface RawMeshBounds {
+  minX: number;
+  minY: number;
+  minZ: number;
+  maxX: number;
+  maxY: number;
+  maxZ: number;
+}
+
+export type MeshBooleanOperation = "union" | "subtraction" | "intersection";
+
+export interface MeshDebugBounds {
+  min: Point;
+  max: Point;
+  center: Point;
+  size: Vec3;
+  diagonal: number;
+}
+
+export interface MeshDebugSummary {
+  vertexCount: number;
+  faceCount: number;
+  trustedBooleanInput: boolean;
+  isClosedVolume: boolean;
+  topology: {
+    boundaryEdges: number;
+    nonManifoldEdges: number;
+  };
+  bounds: MeshDebugBounds;
+}
+
+export interface MeshDebugRayHit {
+  point: Point;
+  normal: Vec3;
+  faceIndex: number;
+  distance: number;
+}
+
+export interface MeshBooleanDebugProbe {
+  label: string;
+  origin: Point;
+  direction: Vec3;
+  maxDistance: number;
+  inputAHits: MeshDebugRayHit[];
+  inputBHits: MeshDebugRayHit[];
+  resultHits: MeshDebugRayHit[];
+}
+
+export interface MeshBooleanDebugOptions {
+  rayPaddingScale?: number;
+  maxRayHits?: number;
+  probes?: Array<"posX" | "negX" | "posY" | "negY" | "posZ" | "negZ">;
+}
+
+export interface MeshBooleanDebugReport {
+  operation: MeshBooleanOperation;
+  inputA: MeshDebugSummary;
+  inputB: MeshDebugSummary;
+  result: Mesh;
+  resultSummary: MeshDebugSummary;
+  probes: MeshBooleanDebugProbe[];
+}
 
 /**
  * Buffer-backed triangle mesh with GPU-ready accessors.
@@ -71,10 +125,13 @@ interface RawMeshBounds {
  *
  * Buffer format: [vertexCount, x1,y1,z1, ..., i1,i2,i3, ...]
  */
-export class Mesh {
-  private _buffer: Float64Array;
-  private _vertexCount: number;
-  private _trustedBooleanInput: boolean;
+export class Mesh {
+  private _buffer: Float64Array;
+  private _vertexCount: number;
+  private _trustedBooleanInput: boolean;
+  private static readonly DEFAULT_BOOLEAN_DEBUG_PROBES: Array<
+    "posX" | "negX" | "posY" | "negY" | "posZ" | "negZ"
+  > = ["posX", "negX", "posY", "negY", "posZ", "negZ"];
 
   private static readonly DEFAULT_BOOLEAN_LIMITS: MeshBooleanLimits = {
     maxInputFacesPerMesh: 120_000,
@@ -177,10 +234,191 @@ export class Mesh {
     return Number.isFinite(diag) && diag > 0 ? diag : 1;
   }
 
-  private static booleanContactTolerance(a: RawMeshBounds | null, b: RawMeshBounds | null): number {
-    const scale = Math.max(Mesh.boundsDiag(a), Mesh.boundsDiag(b));
-    return Math.min(1e-4, Math.max(1e-9, scale * 1e-6));
-  }
+  private static booleanContactTolerance(a: RawMeshBounds | null, b: RawMeshBounds | null): number {
+    const scale = Math.max(Mesh.boundsDiag(a), Mesh.boundsDiag(b));
+    return Math.min(1e-4, Math.max(1e-9, scale * 1e-6));
+  }
+
+  private static toDebugBounds(bounds: { min: Point; max: Point }): MeshDebugBounds {
+    const size = new Vec3(
+      bounds.max.x - bounds.min.x,
+      bounds.max.y - bounds.min.y,
+      bounds.max.z - bounds.min.z,
+    );
+    return {
+      min: bounds.min,
+      max: bounds.max,
+      center: new Point(
+        (bounds.min.x + bounds.max.x) * 0.5,
+        (bounds.min.y + bounds.max.y) * 0.5,
+        (bounds.min.z + bounds.max.z) * 0.5,
+      ),
+      size,
+      diagonal: Math.hypot(size.x, size.y, size.z),
+    };
+  }
+
+  private static clampDebugHitCount(count?: number): number {
+    if (!Number.isFinite(count)) return 4;
+    return Math.max(1, Math.min(32, Math.floor(count ?? 4)));
+  }
+
+  private static collectDebugHits(
+    mesh: Mesh,
+    origin: Point,
+    direction: Vec3,
+    maxDistance: number,
+    maxHits: number,
+  ): MeshDebugRayHit[] {
+    return mesh.raycastAll(origin, direction, maxDistance).slice(0, maxHits).map((hit) => ({
+      point: hit.point,
+      normal: hit.normal,
+      faceIndex: hit.faceIndex,
+      distance: hit.distance,
+    }));
+  }
+
+  private static buildBooleanDebugProbes(
+    inputA: Mesh,
+    inputB: Mesh,
+    result: Mesh,
+    options?: MeshBooleanDebugOptions,
+  ): MeshBooleanDebugProbe[] {
+    const boundsA = Mesh.toDebugBounds(inputA.getBounds());
+    const boundsB = Mesh.toDebugBounds(inputB.getBounds());
+    const resultBounds = Mesh.toDebugBounds(result.getBounds());
+    const min = new Point(
+      Math.min(boundsA.min.x, boundsB.min.x, resultBounds.min.x),
+      Math.min(boundsA.min.y, boundsB.min.y, resultBounds.min.y),
+      Math.min(boundsA.min.z, boundsB.min.z, resultBounds.min.z),
+    );
+    const max = new Point(
+      Math.max(boundsA.max.x, boundsB.max.x, resultBounds.max.x),
+      Math.max(boundsA.max.y, boundsB.max.y, resultBounds.max.y),
+      Math.max(boundsA.max.z, boundsB.max.z, resultBounds.max.z),
+    );
+    const center = new Point(
+      (min.x + max.x) * 0.5,
+      (min.y + max.y) * 0.5,
+      (min.z + max.z) * 0.5,
+    );
+    const diag = Math.max(
+      1e-6,
+      Math.hypot(max.x - min.x, max.y - min.y, max.z - min.z),
+    );
+    const padScale = Number.isFinite(options?.rayPaddingScale)
+      ? Math.max(0.01, options?.rayPaddingScale ?? 0.25)
+      : 0.25;
+    const pad = Math.max(1e-3, diag * padScale);
+    const maxHits = Mesh.clampDebugHitCount(options?.maxRayHits);
+    const probeIds = options?.probes?.length
+      ? options.probes
+      : Mesh.DEFAULT_BOOLEAN_DEBUG_PROBES;
+    const probeSpecs: Record<
+      "posX" | "negX" | "posY" | "negY" | "posZ" | "negZ",
+      { origin: Point; direction: Vec3 }
+    > = {
+      posX: {
+        origin: new Point(max.x + pad, center.y, center.z),
+        direction: new Vec3(-1, 0, 0),
+      },
+      negX: {
+        origin: new Point(min.x - pad, center.y, center.z),
+        direction: new Vec3(1, 0, 0),
+      },
+      posY: {
+        origin: new Point(center.x, max.y + pad, center.z),
+        direction: new Vec3(0, -1, 0),
+      },
+      negY: {
+        origin: new Point(center.x, min.y - pad, center.z),
+        direction: new Vec3(0, 1, 0),
+      },
+      posZ: {
+        origin: new Point(center.x, center.y, max.z + pad),
+        direction: new Vec3(0, 0, -1),
+      },
+      negZ: {
+        origin: new Point(center.x, center.y, min.z - pad),
+        direction: new Vec3(0, 0, 1),
+      },
+    };
+    const maxDistance = diag + pad * 2;
+
+    return probeIds.map((id) => {
+      const spec = probeSpecs[id];
+      return {
+        label: id,
+        origin: spec.origin,
+        direction: spec.direction,
+        maxDistance,
+        inputAHits: Mesh.collectDebugHits(inputA, spec.origin, spec.direction, maxDistance, maxHits),
+        inputBHits: Mesh.collectDebugHits(inputB, spec.origin, spec.direction, maxDistance, maxHits),
+        resultHits: Mesh.collectDebugHits(result, spec.origin, spec.direction, maxDistance, maxHits),
+      };
+    });
+  }
+
+  private static createBooleanDebugReport(
+    inputA: Mesh,
+    inputB: Mesh,
+    result: Mesh,
+    operation: MeshBooleanOperation,
+    debugOptions?: MeshBooleanDebugOptions,
+  ): MeshBooleanDebugReport {
+    return {
+      operation,
+      inputA: inputA.debugSummary(),
+      inputB: inputB.debugSummary(),
+      result,
+      resultSummary: result.debugSummary(),
+      probes: Mesh.buildBooleanDebugProbes(inputA, inputB, result, debugOptions),
+    };
+  }
+
+  private static logSubtractDebugSuccess(
+    inputA: Mesh,
+    inputB: Mesh,
+    result: Mesh,
+    options?: MeshBooleanOptions,
+  ): void {
+    try {
+      const report = Mesh.createBooleanDebugReport(
+        inputA,
+        inputB,
+        result,
+        "subtraction",
+        { maxRayHits: 2, probes: ["posX", "negX", "posY"] },
+      );
+      console.log("[okgeometry-api] Mesh.subtract debug", {
+        options: options ?? null,
+        inputA: report.inputA,
+        inputB: report.inputB,
+        result: report.resultSummary,
+        probes: report.probes,
+      });
+    } catch (debugError) {
+      console.error("[okgeometry-api] Mesh.subtract debug logging failed", debugError);
+    }
+  }
+
+  private static logSubtractDebugFailure(
+    inputA: Mesh,
+    inputB: Mesh,
+    options: MeshBooleanOptions | undefined,
+    error: unknown,
+  ): void {
+    try {
+      console.error("[okgeometry-api] Mesh.subtract failed", {
+        options: options ?? null,
+        inputA: inputA.debugSummary(),
+        inputB: inputB.debugSummary(),
+        error,
+      });
+    } catch (debugError) {
+      console.error("[okgeometry-api] Mesh.subtract failure logging failed", debugError);
+    }
+  }
 
   private static cloneMesh(mesh: Mesh): Mesh {
     return Mesh.fromBuffer(new Float64Array(mesh._buffer), {
@@ -295,9 +533,22 @@ export class Mesh {
     return new Mesh(buffer, true);
   }
 
-  get trustedBooleanInput(): boolean {
-    return this._trustedBooleanInput;
-  }
+  get trustedBooleanInput(): boolean {
+    return this._trustedBooleanInput;
+  }
+
+  debugSummary(): MeshDebugSummary {
+    const bounds = Mesh.toDebugBounds(this.getBounds());
+    const topology = this.topologyMetrics();
+    return {
+      vertexCount: this.vertexCount,
+      faceCount: this.faceCount,
+      trustedBooleanInput: this._trustedBooleanInput,
+      isClosedVolume: this.isClosedVolume(),
+      topology,
+      bounds,
+    };
+  }
 
   /**
    * Build an axis-aligned rectangle on a plane basis from opposite corners.
@@ -1054,12 +1305,12 @@ export class Mesh {
     return Mesh.fromTrustedBuffer(result);
   }
 
-  static encodeBooleanOperationToken(
-    operation: "union" | "subtraction" | "intersection",
-    a: Mesh,
-    b: Mesh,
-    options?: MeshBooleanOptions,
-  ): string {
+  static encodeBooleanOperationToken(
+    operation: MeshBooleanOperation,
+    a: Mesh,
+    b: Mesh,
+    options?: MeshBooleanOptions,
+  ): string {
     const tokens: string[] = [operation];
     if (a._trustedBooleanInput && b._trustedBooleanInput) {
       tokens.push("trustedInput");
@@ -1101,22 +1352,29 @@ export class Mesh {
    * @param options - Optional safety overrides
    * @returns New mesh with other's volume removed from this
    */
-  subtract(other: Mesh, options?: MeshBooleanOptions): Mesh {
-    ensureInit();
-    const operationToken = Mesh.encodeBooleanOperationToken("subtraction", this, other, options);
-    return this.runBoolean(
-      other,
-      "subtraction",
-      () => wasm.mesh_boolean_operation(
-        this._vertexCount,
-        this._buffer,
-        other._vertexCount,
-        other._buffer,
-        operationToken,
-      ),
-      options,
-    );
-  }
+  subtract(other: Mesh, options?: MeshBooleanOptions): Mesh {
+    ensureInit();
+    const operationToken = Mesh.encodeBooleanOperationToken("subtraction", this, other, options);
+    try {
+      const result = this.runBoolean(
+        other,
+        "subtraction",
+        () => wasm.mesh_boolean_operation(
+          this._vertexCount,
+          this._buffer,
+          other._vertexCount,
+          other._buffer,
+          operationToken,
+        ),
+        options,
+      );
+      Mesh.logSubtractDebugSuccess(this, other, result, options);
+      return result;
+    } catch (error) {
+      Mesh.logSubtractDebugFailure(this, other, options, error);
+      throw error;
+    }
+  }
 
   /**
    * Compute boolean intersection with another mesh.
@@ -1124,9 +1382,9 @@ export class Mesh {
    * @param options - Optional safety overrides
    * @returns New mesh containing only the overlapping volume
    */
-  intersect(other: Mesh, options?: MeshBooleanOptions): Mesh {
-    ensureInit();
-    const operationToken = Mesh.encodeBooleanOperationToken("intersection", this, other, options);
+  intersect(other: Mesh, options?: MeshBooleanOptions): Mesh {
+    ensureInit();
+    const operationToken = Mesh.encodeBooleanOperationToken("intersection", this, other, options);
     return this.runBoolean(
       other,
       "intersection",
@@ -1137,9 +1395,48 @@ export class Mesh {
         other._buffer,
         operationToken,
       ),
-      options,
-    );
-  }
+      options,
+    );
+  }
+
+  debugBoolean(
+    other: Mesh,
+    operation: MeshBooleanOperation,
+    options?: MeshBooleanOptions,
+    debugOptions?: MeshBooleanDebugOptions,
+  ): MeshBooleanDebugReport {
+    const result = operation === "union"
+      ? this.union(other, options)
+      : operation === "subtraction"
+        ? this.subtract(other, options)
+        : this.intersect(other, options);
+
+    return Mesh.createBooleanDebugReport(this, other, result, operation, debugOptions);
+  }
+
+  debugUnion(
+    other: Mesh,
+    options?: MeshBooleanOptions,
+    debugOptions?: MeshBooleanDebugOptions,
+  ): MeshBooleanDebugReport {
+    return this.debugBoolean(other, "union", options, debugOptions);
+  }
+
+  debugSubtract(
+    other: Mesh,
+    options?: MeshBooleanOptions,
+    debugOptions?: MeshBooleanDebugOptions,
+  ): MeshBooleanDebugReport {
+    return this.debugBoolean(other, "subtraction", options, debugOptions);
+  }
+
+  debugIntersect(
+    other: Mesh,
+    options?: MeshBooleanOptions,
+    debugOptions?: MeshBooleanDebugOptions,
+  ): MeshBooleanDebugReport {
+    return this.debugBoolean(other, "intersection", options, debugOptions);
+  }
 
   /**
    * Compute boolean union in a dedicated Web Worker (non-blocking).

package/src/index.ts

@@ -35,6 +35,13 @@ export { NurbsSurface } from "./NurbsSurface.js";
 // Mesh and operations
 export { Mesh, MeshBooleanExecutionError } from "./Mesh.js";
 export type {
+  MeshBooleanOperation,
+  MeshBooleanDebugOptions,
+  MeshBooleanDebugProbe,
+  MeshBooleanDebugReport,
+  MeshDebugBounds,
+  MeshDebugRayHit,
+  MeshDebugSummary,
   MeshBooleanLimits,
   MeshBooleanOptions,
   MeshBooleanAsyncOptions,