@woosh/meep-engine 2.163.10 → 2.164.0

package/src/core/geom/3d/frustum/frustum3_slice_linear_to_points.js

@@ -0,0 +1,96 @@
+/**
+ * TODO compute slices to minimize world-space volume difference between clusters
+ * @param {number[]} input_frustum_corners corners of input frustum
+ * @param {number} tr_x slices in X axis
+ * @param {number} tr_y slices in Y axis
+ * @param {number} tr_z slices in Z axis
+ * @param {number[]} output_frustum_corners
+ */
+export function frustum3_slice_linear_to_points(
+    input_frustum_corners,
+    tr_x, tr_y, tr_z,
+    output_frustum_corners
+) {
+    // read out view frustum scratch_corners
+    const x_000 = input_frustum_corners[0];
+    const y_000 = input_frustum_corners[1];
+    const z_000 = input_frustum_corners[2];
+
+    const x_001 = input_frustum_corners[3];
+    const y_001 = input_frustum_corners[4];
+    const z_001 = input_frustum_corners[5];
+
+    const x_010 = input_frustum_corners[6];
+    const y_010 = input_frustum_corners[7];
+    const z_010 = input_frustum_corners[8];
+
+    const x_011 = input_frustum_corners[9];
+    const y_011 = input_frustum_corners[10];
+    const z_011 = input_frustum_corners[11];
+
+    const x_100 = input_frustum_corners[12];
+    const y_100 = input_frustum_corners[13];
+    const z_100 = input_frustum_corners[14];
+
+    const x_101 = input_frustum_corners[15];
+    const y_101 = input_frustum_corners[16];
+    const z_101 = input_frustum_corners[17];
+
+    const x_110 = input_frustum_corners[18];
+    const y_110 = input_frustum_corners[19];
+    const z_110 = input_frustum_corners[20];
+
+    const x_111 = input_frustum_corners[21];
+    const y_111 = input_frustum_corners[22];
+    const z_111 = input_frustum_corners[23];
+
+
+    const x_plane_count = tr_x + 1;
+    const y_plane_count = tr_y + 1;
+    const z_plane_count = tr_z + 1;
+
+    const z_slice_stride = x_plane_count * y_plane_count;
+
+    for (let i_z = 0; i_z < z_plane_count; i_z++) {
+        const r_0 = i_z / tr_z;
+        const r_1 = 1 - r_0;
+
+        const z_offset = i_z * z_slice_stride;
+
+        for (let i_y = 0; i_y < y_plane_count; i_y++) {
+
+            const v_0 = i_y / tr_y;
+            const v_1 = 1 - v_0;
+
+            const y_offset = z_offset + i_y * x_plane_count;
+
+            for (let i_x = 0; i_x < x_plane_count; i_x++) {
+                const u_0 = i_x / tr_x;
+                const u_1 = 1 - u_0;
+
+                const m_000 = u_1 * v_1 * r_1;
+                const m_001 = u_1 * v_1 * r_0;
+                const m_010 = u_1 * v_0 * r_1;
+                const m_011 = u_1 * v_0 * r_0;
+                const m_100 = u_0 * v_1 * r_1;
+                const m_101 = u_0 * v_1 * r_0;
+                const m_110 = u_0 * v_0 * r_1;
+                const m_111 = u_0 * v_0 * r_0;
+
+                // interpolate view frustum scratch_corners
+                const x = x_000 * m_000 + x_001 * m_001 + x_010 * m_010 + x_011 * m_011 + x_100 * m_100 + x_101 * m_101 + x_110 * m_110 + x_111 * m_111;
+                const y = y_000 * m_000 + y_001 * m_001 + y_010 * m_010 + y_011 * m_011 + y_100 * m_100 + y_101 * m_101 + y_110 * m_110 + y_111 * m_111;
+                const z = z_000 * m_000 + z_001 * m_001 + z_010 * m_010 + z_011 * m_011 + z_100 * m_100 + z_101 * m_101 + z_110 * m_110 + z_111 * m_111;
+
+                // write out cluster corner position
+                const index = y_offset + i_x
+                const address = index * 3;
+
+                output_frustum_corners[address] = x;
+                output_frustum_corners[address + 1] = y;
+                output_frustum_corners[address + 2] = z;
+            }
+
+        }
+    }
+}

package/src/core/geom/3d/frustum/frustum_compute_corners.js

@@ -1,5 +1,5 @@
 import { assert } from "../../../assert.js";
-import { plane3_compute_convex_3_plane_intersection } from "../plane/plane3_compute_convex_3_plane_intersection.js";
+import { plane3_compute_3_plane_intersection } from "../plane/plane3_compute_3_plane_intersection.js";
 
 /**
  * This function operates in 3D.
@@ -25,7 +25,7 @@ export function frustum_compute_corners(
     const o = frustum_offset;
 
     // plane_x0, plane_y0, plane_z0
-    plane3_compute_convex_3_plane_intersection(
+    plane3_compute_3_plane_intersection(
         output, output_offset,
         f[o], f[o + 1], f[o + 2], f[o + 3],
         f[o + 8], f[o + 9], f[o + 10], f[o + 11],
@@ -33,7 +33,7 @@ export function frustum_compute_corners(
     );
 
     // plane_x0, plane_y0, plane_z1
-    plane3_compute_convex_3_plane_intersection(
+    plane3_compute_3_plane_intersection(
         output, output_offset + 3,
         f[o], f[o + 1], f[o + 2], f[o + 3],
         f[o + 8], f[o + 9], f[o + 10], f[o + 11],
@@ -41,7 +41,7 @@ export function frustum_compute_corners(
     );
 
     // plane_x0, plane_y1, plane_z0
-    plane3_compute_convex_3_plane_intersection(
+    plane3_compute_3_plane_intersection(
         output, output_offset + 6,
         f[o], f[o + 1], f[o + 2], f[o + 3],
         f[o + 12], f[o + 13], f[o + 14], f[o + 15],
@@ -49,7 +49,7 @@ export function frustum_compute_corners(
     );
 
     // plane_x0, plane_y1, plane_z1
-    plane3_compute_convex_3_plane_intersection(
+    plane3_compute_3_plane_intersection(
         output, output_offset + 9,
         f[o], f[o + 1], f[o + 2], f[o + 3],
         f[o + 12], f[o + 13], f[o + 14], f[o + 15],
@@ -57,7 +57,7 @@ export function frustum_compute_corners(
     );
 
     // plane_x1, plane_y0, plane_z0
-    plane3_compute_convex_3_plane_intersection(
+    plane3_compute_3_plane_intersection(
         output, output_offset + 12,
         f[o + 4], f[o + 5], f[o + 6], f[o + 7],
         f[o + 8], f[o + 9], f[o + 10], f[o + 11],
@@ -65,7 +65,7 @@ export function frustum_compute_corners(
     );
 
     // plane_x1, plane_y0, plane_z1
-    plane3_compute_convex_3_plane_intersection(
+    plane3_compute_3_plane_intersection(
         output, output_offset + 15,
         f[o + 4], f[o + 5], f[o + 6], f[o + 7],
         f[o + 8], f[o + 9], f[o + 10], f[o + 11],
@@ -73,7 +73,7 @@ export function frustum_compute_corners(
     );
 
     // plane_x1, plane_y1, plane_z0
-    plane3_compute_convex_3_plane_intersection(
+    plane3_compute_3_plane_intersection(
         output, output_offset + 18,
         f[o + 4], f[o + 5], f[o + 6], f[o + 7],
         f[o + 12], f[o + 13], f[o + 14], f[o + 15],
@@ -81,7 +81,7 @@ export function frustum_compute_corners(
     );
 
     // plane_x1, plane_y1, plane_z1
-    plane3_compute_convex_3_plane_intersection(
+    plane3_compute_3_plane_intersection(
         output, output_offset + 21,
         f[o + 4], f[o + 5], f[o + 6], f[o + 7],
         f[o + 12], f[o + 13], f[o + 14], f[o + 15],

package/src/core/geom/3d/frustum/frustum_matrix4_project.d.ts

@@ -1,10 +1,7 @@
 /**
- * Perform affine transform on a given frustum
- * @param {number[]|Float32Array|Float64Array} output
- * @param {number} output_offset
- * @param {number[]|Float32Array|Float64Array} input
- * @param {number} input_offset
- * @param {number[]|Float32Array|Float64Array} matrix4
+ * @deprecated Renamed to {@link frustum3_matrix4_project}. This re-export is kept for backward
+ * compatibility (meep is a library; old names are public surface).
  */
-export function frustum_matrix4_project(output: number[] | Float32Array | Float64Array, output_offset: number, input: number[] | Float32Array | Float64Array, input_offset: number, matrix4: number[] | Float32Array | Float64Array): void;
+export const frustum_matrix4_project: typeof frustum3_matrix4_project;
+import { frustum3_matrix4_project } from "./frustum3_matrix4_project.js";
 //# sourceMappingURL=frustum_matrix4_project.d.ts.map

package/src/core/geom/3d/frustum/frustum_matrix4_project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frustum_matrix4_project.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/frustum_matrix4_project.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,gDANW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,gBAClC,MAAM,WACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,QAQ5C"}
+{"version":3,"file":"frustum_matrix4_project.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/frustum_matrix4_project.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,sEAAgE;yCANvB,+BAA+B"}

package/src/core/geom/3d/frustum/frustum_matrix4_project.js

@@ -1,18 +1,7 @@
-import { clipping_volume_matrix4_project } from "./clipping_volume_matrix4_project.js";
-
-
-/**
- * Perform affine transform on a given frustum
- * @param {number[]|Float32Array|Float64Array} output
- * @param {number} output_offset
- * @param {number[]|Float32Array|Float64Array} input
- * @param {number} input_offset
- * @param {number[]|Float32Array|Float64Array} matrix4
- */
-export function frustum_matrix4_project(
-    output, output_offset,
-    input, input_offset,
-    matrix4
-){
-    clipping_volume_matrix4_project(output, output_offset, input, input_offset, 6, matrix4);
-}
+import { frustum3_matrix4_project } from "./frustum3_matrix4_project.js";
+
+/**
+ * @deprecated Renamed to {@link frustum3_matrix4_project}. This re-export is kept for backward
+ * compatibility (meep is a library; old names are public surface).
+ */
+export const frustum_matrix4_project = frustum3_matrix4_project;

package/src/core/geom/3d/frustum/hexahedron_from_aabb.d.ts

@@ -1,19 +1,7 @@
 /**
- * Constructs an orthographic hexahedron from an Axis-Aligned Bounding Box.
- * The planes are stored as 4-tuples (nx, ny, nz, d).
- *
- * Normals are facing inwards, i.e., the volume of positive.
- *
- * This can also be used for an orthographic camera frustum.
- *
- * @param {Float32Array|number[]} output
- * @param {number} output_offset
- * @param {number} x0 - Minimum X
- * @param {number} y0 - Minimum Y
- * @param {number} z0 - Minimum Z
- * @param {number} x1 - Maximum X
- * @param {number} y1 - Maximum Y
- * @param {number} z1 - Maximum Z
+ * @deprecated Renamed to {@link frustum3_from_aabb}. This re-export is kept for backward
+ * compatibility (meep is a library; old names are public surface).
  */
-export function hexahedron_from_aabb(output: Float32Array | number[], output_offset: number, x0: number, y0: number, z0: number, x1: number, y1: number, z1: number): void;
+export const hexahedron_from_aabb: typeof frustum3_from_aabb;
+import { frustum3_from_aabb } from "./frustum3_from_aabb.js";
 //# sourceMappingURL=hexahedron_from_aabb.d.ts.map

package/src/core/geom/3d/frustum/hexahedron_from_aabb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hexahedron_from_aabb.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/hexahedron_from_aabb.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,6CATW,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QA4ChB"}
+{"version":3,"file":"hexahedron_from_aabb.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/hexahedron_from_aabb.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,6DAAuD;mCANpB,yBAAyB"}

package/src/core/geom/3d/frustum/hexahedron_from_aabb.js

@@ -1,60 +1,7 @@
-/**
- * Constructs an orthographic hexahedron from an Axis-Aligned Bounding Box.
- * The planes are stored as 4-tuples (nx, ny, nz, d).
- *
- * Normals are facing inwards, i.e., the volume of positive.
- *
- * This can also be used for an orthographic camera frustum.
- *
- * @param {Float32Array|number[]} output
- * @param {number} output_offset
- * @param {number} x0 - Minimum X
- * @param {number} y0 - Minimum Y
- * @param {number} z0 - Minimum Z
- * @param {number} x1 - Maximum X
- * @param {number} y1 - Maximum Y
- * @param {number} z1 - Maximum Z
- */
-export function hexahedron_from_aabb(
-    output,
-    output_offset,
-    x0, y0, z0,
-    x1, y1, z1
-){
-    
-    // Right plane (x = x1): Normal points -X
-    output[output_offset + 0] = -1;
-    output[output_offset + 1] = 0;
-    output[output_offset + 2] = 0;
-    output[output_offset + 3] = x1;
-
-    // Left plane (x = x0): Normal points +X
-    output[output_offset + 4] = 1;
-    output[output_offset + 5] = 0;
-    output[output_offset + 6] = 0;
-    output[output_offset + 7] = -x0;
-
-    // Top plane (y = y1): Normal points -Y
-    output[output_offset + 8] = 0;
-    output[output_offset + 9] = -1;
-    output[output_offset + 10] = 0;
-    output[output_offset + 11] = y1;
-
-    // Bottom plane (y = y0): Normal points +Y
-    output[output_offset + 12] = 0;
-    output[output_offset + 13] = 1;
-    output[output_offset + 14] = 0;
-    output[output_offset + 15] = -y0;
-
-    // Near plane (z = z0): Normal points +Z
-    output[output_offset + 16] = 0;
-    output[output_offset + 17] = 0;
-    output[output_offset + 18] = 1;
-    output[output_offset + 19] = -z0;
-
-    // Far plane (z = z1): Normal points -Z
-    output[output_offset + 20] = 0;
-    output[output_offset + 21] = 0;
-    output[output_offset + 22] = -1;
-    output[output_offset + 23] = z1;
-}
+import { frustum3_from_aabb } from "./frustum3_from_aabb.js";
+
+/**
+ * @deprecated Renamed to {@link frustum3_from_aabb}. This re-export is kept for backward
+ * compatibility (meep is a library; old names are public surface).
+ */
+export const hexahedron_from_aabb = frustum3_from_aabb;

package/src/core/geom/3d/frustum/read_three_planes_to_array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read_three_planes_to_array.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/read_three_planes_to_array.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,mDAHW,OAAO,SACP,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,QAoB9D"}
+{"version":3,"file":"read_three_planes_to_array.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/read_three_planes_to_array.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,mFAA6E;mDAN1B,yCAAyC"}

package/src/core/geom/3d/frustum/read_three_planes_to_array.js

@@ -1,26 +1,7 @@
-import { assert } from "../../../assert.js";
-
-/**
- *
- * @param {Plane[]} planes
- * @param {ArrayLike<number>|number[]|Float32Array|Float64Array} array
- */
-export function read_three_planes_to_array(planes, array) {
-    const plane_count = planes.length;
-
-    assert.greaterThanOrEqual(array.length, plane_count * 4, 'target array is too small');
-
-    for (let i = 0; i < plane_count; i++) {
-        const plane = planes[i];
-
-        const offset = i * 4;
-
-        const normal = plane.normal;
-
-        array[offset] = normal.x;
-        array[offset + 1] = normal.y;
-        array[offset + 2] = normal.z;
-
-        array[offset + 3] = plane.constant;
-    }
-}
+import { frustum3_planes_to_flat_from_three } from "./frustum3_planes_to_flat_from_three.js";
+
+/**
+ * @deprecated Renamed to {@link frustum3_planes_to_flat_from_three}. This re-export is kept for backward
+ * compatibility (meep is a library; old names are public surface).
+ */
+export const read_three_planes_to_array = frustum3_planes_to_flat_from_three;

package/src/core/geom/3d/frustum/slice_frustum_linear_to_points.d.ts

@@ -1,10 +1,7 @@
 /**
- * TODO compute slices to minimize world-space volume difference between clusters
- * @param {number[]} input_frustum_corners corners of input frustum
- * @param {number} tr_x slices in X axis
- * @param {number} tr_y slices in Y axis
- * @param {number} tr_z slices in Z axis
- * @param {number[]} output_frustum_corners
+ * @deprecated Renamed to {@link frustum3_slice_linear_to_points}. This re-export is kept for backward
+ * compatibility (meep is a library; old names are public surface).
  */
-export function slice_frustum_linear_to_points(input_frustum_corners: number[], tr_x: number, tr_y: number, tr_z: number, output_frustum_corners: number[]): void;
+export const slice_frustum_linear_to_points: typeof frustum3_slice_linear_to_points;
+import { frustum3_slice_linear_to_points } from "./frustum3_slice_linear_to_points.js";
 //# sourceMappingURL=slice_frustum_linear_to_points.d.ts.map

package/src/core/geom/3d/frustum/slice_frustum_linear_to_points.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slice_frustum_linear_to_points.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/slice_frustum_linear_to_points.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,sEANW,MAAM,EAAE,QACR,MAAM,QACN,MAAM,QACN,MAAM,0BACN,MAAM,EAAE,QAyFlB"}
+{"version":3,"file":"slice_frustum_linear_to_points.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/slice_frustum_linear_to_points.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,oFAA8E;gDAN9B,sCAAsC"}

package/src/core/geom/3d/frustum/slice_frustum_linear_to_points.js

@@ -1,96 +1,7 @@
-/**
- * TODO compute slices to minimize world-space volume difference between clusters
- * @param {number[]} input_frustum_corners corners of input frustum
- * @param {number} tr_x slices in X axis
- * @param {number} tr_y slices in Y axis
- * @param {number} tr_z slices in Z axis
- * @param {number[]} output_frustum_corners
- */
-export function slice_frustum_linear_to_points(
-    input_frustum_corners,
-    tr_x, tr_y, tr_z,
-    output_frustum_corners
-) {
-    // read out view frustum scratch_corners
-    const x_000 = input_frustum_corners[0];
-    const y_000 = input_frustum_corners[1];
-    const z_000 = input_frustum_corners[2];
-
-    const x_001 = input_frustum_corners[3];
-    const y_001 = input_frustum_corners[4];
-    const z_001 = input_frustum_corners[5];
-
-    const x_010 = input_frustum_corners[6];
-    const y_010 = input_frustum_corners[7];
-    const z_010 = input_frustum_corners[8];
-
-    const x_011 = input_frustum_corners[9];
-    const y_011 = input_frustum_corners[10];
-    const z_011 = input_frustum_corners[11];
-
-    const x_100 = input_frustum_corners[12];
-    const y_100 = input_frustum_corners[13];
-    const z_100 = input_frustum_corners[14];
-
-    const x_101 = input_frustum_corners[15];
-    const y_101 = input_frustum_corners[16];
-    const z_101 = input_frustum_corners[17];
-
-    const x_110 = input_frustum_corners[18];
-    const y_110 = input_frustum_corners[19];
-    const z_110 = input_frustum_corners[20];
-
-    const x_111 = input_frustum_corners[21];
-    const y_111 = input_frustum_corners[22];
-    const z_111 = input_frustum_corners[23];
-
-
-    const x_plane_count = tr_x + 1;
-    const y_plane_count = tr_y + 1;
-    const z_plane_count = tr_z + 1;
-
-    const z_slice_stride = x_plane_count * y_plane_count;
-
-    for (let i_z = 0; i_z < z_plane_count; i_z++) {
-        const r_0 = i_z / tr_z;
-        const r_1 = 1 - r_0;
-
-        const z_offset = i_z * z_slice_stride;
-
-        for (let i_y = 0; i_y < y_plane_count; i_y++) {
-
-            const v_0 = i_y / tr_y;
-            const v_1 = 1 - v_0;
-
-            const y_offset = z_offset + i_y * x_plane_count;
-
-            for (let i_x = 0; i_x < x_plane_count; i_x++) {
-                const u_0 = i_x / tr_x;
-                const u_1 = 1 - u_0;
-
-                const m_000 = u_1 * v_1 * r_1;
-                const m_001 = u_1 * v_1 * r_0;
-                const m_010 = u_1 * v_0 * r_1;
-                const m_011 = u_1 * v_0 * r_0;
-                const m_100 = u_0 * v_1 * r_1;
-                const m_101 = u_0 * v_1 * r_0;
-                const m_110 = u_0 * v_0 * r_1;
-                const m_111 = u_0 * v_0 * r_0;
-
-                // interpolate view frustum scratch_corners
-                const x = x_000 * m_000 + x_001 * m_001 + x_010 * m_010 + x_011 * m_011 + x_100 * m_100 + x_101 * m_101 + x_110 * m_110 + x_111 * m_111;
-                const y = y_000 * m_000 + y_001 * m_001 + y_010 * m_010 + y_011 * m_011 + y_100 * m_100 + y_101 * m_101 + y_110 * m_110 + y_111 * m_111;
-                const z = z_000 * m_000 + z_001 * m_001 + z_010 * m_010 + z_011 * m_011 + z_100 * m_100 + z_101 * m_101 + z_110 * m_110 + z_111 * m_111;
-
-                // write out cluster corner position
-                const index = y_offset + i_x
-                const address = index * 3;
-
-                output_frustum_corners[address] = x;
-                output_frustum_corners[address + 1] = y;
-                output_frustum_corners[address + 2] = z;
-            }
-
-        }
-    }
-}
+import { frustum3_slice_linear_to_points } from "./frustum3_slice_linear_to_points.js";
+
+/**
+ * @deprecated Renamed to {@link frustum3_slice_linear_to_points}. This re-export is kept for backward
+ * compatibility (meep is a library; old names are public surface).
+ */
+export const slice_frustum_linear_to_points = frustum3_slice_linear_to_points;

package/src/core/geom/3d/funnel_string_pull.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"funnel_string_pull.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/3d/funnel_string_pull.js"],"names":[],"mappings":"AAkGA;;;;;;;;;;;;GAYG;AACH,2CARW,WAAW,GAAC,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,iBACtC,MAAM,mBACN,WAAW,GAAC,WAAW,GAAC,UAAU,GAAC,MAAM,EAAE,kBAC3C,YAAY,GAAC,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,gBACvC,MAAM,eACN,YAAY,GAAC,MAAM,EAAE,UAoH/B"}

package/src/{engine/navigation/mesh → core/geom/3d}/funnel_string_pull.js

@@ -1,4 +1,4 @@
-import { assert } from "../../../core/assert.js";
+import { assert } from "../../assert.js";
 
 
 /**

package/src/core/geom/3d/gjk/GJK_REVIEW_NOTES.md

@@ -0,0 +1,146 @@
+# GJK review notes — Johnson distance subalgorithm & robustness
+
+Notes from a 2026-06-18 research pass (capsule-vs-AABB / segment-vs-box work) on
+how this engine's GJK family relates to the known GJK robustness literature —
+chiefly the **Johnson distance subalgorithm** and its 2017 **signed-volumes**
+replacement. See `NOTES.md` (same dir) for the raw reference links.
+
+**TL;DR:** the specific Johnson failure mode does **not** apply here, because this
+engine has **no distance-returning GJK** — nothing computes the Johnson
+sub-distance, so there is nothing to replace. The finding is *forward-looking*:
+it becomes relevant the day a closest-distance-between-separated-convexes query
+is added (speculative contacts, conservative-advancement CCD, proximity
+queries). The analogous simplex-degeneracy risk in our boolean/penetration GJK is
+real but already mitigated by explicit floating-point-dust guards.
+
+## What this engine actually has
+
+There are three Minkowski-difference routines here, and **none is a distance
+subalgorithm**:
+
+| File | Role | Simplex / sub-distance method |
+|---|---|---|
+| `gjk.js` | **Boolean** overlap test (used by `physics/queries/shape_cast.js`) | Voronoi-region simplex update via triple cross products (Kevin Moran adaptation). Returns a bool; never computes a closest point. |
+| `gjk_epa_penetration.js` | **Penetration** axis+depth (narrowphase convex / mesh / concave-per-triangle) | GJK builds a rank-4 origin-enclosing simplex (Voronoi-region updates), then EPA expands faces toward the closest one (Bullet `btGjkEpa2` structure). |
+| `mpr.js` | Penetration normal on **smooth** supports (sphere/capsule), where EPA stalls | Minkowski Portal Refinement — portal, not simplex sub-distance. |
+
+The thing the literature calls the *Johnson distance subalgorithm* — given a
+simplex of ≤4 points, find the closest point on it to the origin and the minimal
+sub-simplex (which Voronoi region the origin projects into), via recursively
+computed barycentric cofactors — is **absent**. Our GJK only ever asks "does the
+simplex enclose / has the support passed the origin?", never "what is the
+closest point on the simplex?". So there is no Johnson cofactor recursion and no
+Backup procedure in this codebase.
+
+## The Johnson subalgorithm and why it fails
+
+In a *distance* GJK (Gilbert–Johnson–Keerthi 1988), each iteration must solve the
+sub-distance problem: project the origin onto the current simplex and discard the
+vertices not contributing to the closest feature. Johnson's method expresses the
+barycentric weights as ratios of determinants (Δ cofactors) built from dot
+products of support-point *differences*.
+
+Failure mode (the part relevant to robustness reviews): for a **near-degenerate
+simplex** — points nearly coincident or nearly coplanar/collinear, which GJK
+*naturally drives toward* as it converges on a near-contact configuration — those
+determinants are differences of nearly-equal products and lose most of their
+significant digits to **subtractive cancellation**. The algorithm then either
+fails to find any valid sub-simplex (the historical "Backup procedure" brute-forces
+all subsets as a fallback) or, worse, selects the wrong Voronoi region and returns
+a **wrong closest point / distance**. Net effect in practice: the distance is
+*under-estimated just before contact* — i.e. under-detection, the same direction
+of error we found in the capsule-box alternating projection.
+
+## The 2017 fix — signed volumes (Montanari, Petrinic & Barbieri)
+
+*"Improving the GJK Algorithm for Faster and More Reliable Distance Queries
+Between Convex Objects"*, ACM TOG 36(3), 2017; reference impl **openGJK**
+(SoftwareX 2018). Both already cited in `NOTES.md`.
+
+It replaces Johnson's distance subalgorithm **and** the Backup procedure with a
+**signed-volumes** subalgorithm:
+
+- determines the Voronoi region by comparing **signed volumes** (determinants) of
+  the simplex and its sub-faces, projecting onto the lowest-dimensional one that
+  contains the origin's projection;
+- crucially **does not multiply together potentially small quantities**, so it is
+  *accurate to machine precision* and, per the paper, "cannot possibly generate
+  systems of linearly dependent equations" — **degenerate simplices are handled
+  naturally** (they collapse to a lower-dimensional projection instead of
+  triggering a fallback);
+- side benefit: ~10% faster on average, 15–30% in the contact-heavy regime.
+
+This is the single most relevant robustness upgrade for any GJK that returns a
+**distance**. It is *not* a drop-in change to a boolean or penetration GJK, which
+do not run a sub-distance step.
+
+## Applicability to this codebase
+
+1. **No live bug.** Nothing here runs the Johnson subalgorithm, so there is
+   nothing to "fix". Do not retrofit signed-volumes onto `gjk.js` /
+   `gjk_epa_penetration.js` — they have no sub-distance step to replace.
+
+2. **The analogous risk is the Voronoi-region update**, not Johnson cofactors.
+   `gjk.js` and the GJK phase of `gjk_epa_penetration.js` decide regions with
+   triple-cross-products and dot products, which suffer the *same class* of
+   cancellation on degenerate simplices. This is already mitigated deliberately:
+   - `gjk.js` `perpendicular_to_edge()` + the exact-zero direction checks are FP-dust
+     guards for exactly the collapsed-simplex case (see the comment block there —
+     a wedge dot rounding a hair above zero while the triple product rounds to
+     zero). Documented as off the hot path.
+   - `gjk_epa_penetration.js` carries `DIR_EPS`/`EPA_EPS` floors and pool-overflow
+     "use current best face" degradations.
+   These are spot mitigations, not a machine-precision guarantee — but they cover
+   the inputs the narrowphase actually feeds (the convex hulls / triangles), and
+   the penetration path is cross-checked by MPR on smooth shapes.
+
+3. **Signed-volumes becomes relevant when a distance query is added.** If/when the
+   engine grows speculative/“soft” contacts that need a *separation distance*, a
+   conservative-advancement CCD that needs closest-distance per step, or general
+   proximity queries, implement that as a **new** signed-volumes distance GJK
+   (port openGJK) rather than coaxing distance out of the boolean/penetration
+   routines. Capsule primitives should keep using the closed-form contacts
+   (`capsule_contacts.js`, now exact — see below), not GJK-with-margin.
+
+## Related robustness notes (same review)
+
+- **EPA precision wall on flat supports.** `Triangle3D`'s support is degenerate
+  along the face normal (all 3 vertices project equally), which stalls EPA and
+  yields noisy depths. The narrowphase already routes sphere/box/capsule-vs-
+  triangle through **closed-form** fast-paths in `narrowphase_step.js` for exactly
+  this reason, and `shape_cast.js` recovers the TOI normal with **MPR** rather
+  than EPA on smooth-vs-smooth. Good — keep new primitive pairs on closed forms.
+- **Capsule-as-segment-support-with-margin is intentionally NOT used here.** Jolt
+  and PhysX-PCM collide capsules as a segment support inflated by the radius
+  inside GJK/EPA (with bounded corner error from the shrink-margin model). This
+  engine instead uses exact closed-form capsule contacts. That is the more
+  accurate choice for these primitive pairs and should stay.
+- **Non-convergence policy.** Both `gjk.js` and `gjk_epa_penetration.js` cap at
+  `*_MAX_ITER = 64` and treat exhaustion as *no intersection*. For well-conditioned
+  convex inputs this is unreachable; it is a backstop against pathological input,
+  not a correctness lever.
+
+## Action items (low urgency — none is a known live defect)
+
+- [ ] If a separation-distance / proximity / conservative-advancement query is
+      ever needed, port **openGJK signed-volumes** as a dedicated distance GJK.
+      Do not extend the boolean/penetration routines for it.
+- [ ] (Optional, deeper) A focused robustness pass on
+      `gjk_epa_penetration.js`'s simplex phase — confirm the degenerate-simplex
+      guards hold under near-coplanar convex-hull inputs at scale. Out of scope
+      for this note; flagged only because it is the nearest analog to the Johnson
+      concern.
+
+## References
+
+- Gilbert, Johnson, Keerthi (1988), *A Fast Procedure for Computing the Distance
+  Between Complex Objects in Three-Dimensional Space*, IEEE J. Robotics &
+  Automation — the original GJK + Johnson distance subalgorithm.
+- Montanari, Petrinic, Barbieri (2017), *Improving the GJK Algorithm…*, ACM TOG
+  36(3), DOI 10.1145/3072959.3083724; openGJK reference impl
+  (github.com/MattiaMontanari/openGJK). Already in `NOTES.md`.
+- van den Bergen (1999), *A Fast and Robust GJK Implementation for Collision
+  Detection of Convex Objects* — the classic robustness treatment (error bounds,
+  the Backup procedure) that motivates the 2017 work.
+- Ericson, *Real-Time Collision Detection* (2005), §9.5 (GJK), Ch. 9 (EPA context).
+- `gjk.js` header — adapted from github.com/kevinmoran/GJK (boolean Voronoi GJK).