@woosh/meep-engine 2.133.5 → 2.134.1

package/src/core/graph/graph_compute_laplacian_matrix.js

@@ -12,7 +12,8 @@ import { graph_compute_degree_matrix } from "./graph_compute_degree_matrix.js";
  * @param {Map<T,number>} node_indices Map from graph nodes to matrix indices.
  */
 export function graph_compute_laplacian_matrix(graph, result, node_indices) {
-    const degree = new SquareMatrix(result.size, BinaryDataType.Uint8);
+    // Uint32 prevents silent overflow for high-degree or multi-edge graphs
+    const degree = new SquareMatrix(result.size, BinaryDataType.Uint32);
     const adjacency = new SquareMatrix(result.size, BinaryDataType.Uint8);
 
     graph_compute_degree_matrix(graph, degree, node_indices);

package/src/core/graph/graph_k_means_cluster.d.ts

@@ -2,14 +2,21 @@
  * @param {MultiNode<T>[]} node_array
  * @param {number} k
  * @param {number} random_seed
- * @param {number[]|Uint8Array|Uint16Array|Uint32Array} node_cluster_assignments
+ * @param {number[]|Uint32Array} node_cluster_assignments pre-filled with UNASSIGNED_CLUSTER
  * @param {Map<T, number>} node_index_map
  * @param {Graph<MultiNode<T>>} graph
  * @returns {number[][]}
  */
-export function graph_k_means_cluster_detailed(node_array: MultiNode<T>[], k: number, random_seed: number, node_cluster_assignments: number[] | Uint8Array | Uint16Array | Uint32Array, node_index_map: Map<T, number>, graph: Graph<MultiNode<T>>): number[][];
+export function graph_k_means_cluster_detailed(node_array: MultiNode<T>[], k: number, random_seed: number, node_cluster_assignments: number[] | Uint32Array, node_index_map: Map<T, number>, graph: Graph<MultiNode<T>>): number[][];
 /**
- * Partition graph into K parts using K-means algorithm
+ * Partition graph into K parts using K-medoids (graph K-means).
+ * Iteratively reassigns nodes to the nearest medoid, then recomputes medoids
+ * as the within-cluster node minimising the sum of distances to other members.
+ * Stops when medoids stabilise or MAX_ITERATIONS is reached.
+ *
+ * Distances are BFS-based and so treat all edges as unit-weight; see
+ * {@link graph_compute_distance_matrix}.
+ *
  * @template T
  * @param {Graph<T>} graph
  * @param {number} k number of desired parts

package/src/core/graph/graph_k_means_cluster.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_k_means_cluster.d.ts","sourceRoot":"","sources":["../../../../src/core/graph/graph_k_means_cluster.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH,2DARW,cAAc,KACd,MAAM,eACN,MAAM,4BACN,MAAM,EAAE,GAAC,UAAU,GAAC,WAAW,GAAC,WAAW,kBAC3C,OAAO,MAAM,CAAC,+BAEZ,MAAM,EAAE,EAAE,CA2EtB;AAED;;;;;;;GAOG;AACH,6DAJW,MAAM,eACN,MAAM,GACJ,MAAM,EAAE,EAAE,CA0BtB"}
+{"version":3,"file":"graph_k_means_cluster.d.ts","sourceRoot":"","sources":["../../../../src/core/graph/graph_k_means_cluster.js"],"names":[],"mappings":"AA0DA;;;;;;;;GAQG;AACH,2DARW,cAAc,KACd,MAAM,eACN,MAAM,4BACN,MAAM,EAAE,GAAC,WAAW,kBACpB,OAAO,MAAM,CAAC,+BAEZ,MAAM,EAAE,EAAE,CA+ItB;AAED;;;;;;;;;;;;;;GAcG;AACH,6DAJW,MAAM,eACN,MAAM,GACJ,MAAM,EAAE,EAAE,CA0BtB"}

package/src/core/graph/graph_k_means_cluster.js

@@ -1,123 +1,250 @@
-//
-import { randomIntegerBetween } from "../math/random/randomIntegerBetween.js";
-import { seededRandom } from "../math/random/seededRandom.js";
-import { graph_compute_distance_matrix } from "./graph_compute_distance_matrix.js";
-
-
-/**
- * @param {MultiNode<T>[]} node_array
- * @param {number} k
- * @param {number} random_seed
- * @param {number[]|Uint8Array|Uint16Array|Uint32Array} node_cluster_assignments
- * @param {Map<T, number>} node_index_map
- * @param {Graph<MultiNode<T>>} graph
- * @returns {number[][]}
- */
-export function graph_k_means_cluster_detailed(
-    node_array,
-    k,
-    random_seed,
-    node_cluster_assignments,
-    node_index_map,
-    graph
-) {
-    const total_node_count = node_array.length;
-
-    if (k > total_node_count) {
-        throw new Error(`Not enough nodes in the graph, K(=${k}) > |V| (=${total_node_count})`);
-    }
-
-    const random = seededRandom(random_seed);
-
-    //seeds
-    const clusters_seeds = [];
-
-    /**
-     *
-     * @type {number[][]}
-     */
-    const clusters = [];
-
-    const UNASSIGNED_CLUSTER = 255;
-
-    // seed clusters
-    for (let i = 0; i < k; i++) {
-        //
-        const node_index = randomIntegerBetween(random, 0, total_node_count);
-
-        if (node_cluster_assignments[node_index] !== UNASSIGNED_CLUSTER) {
-            // node taken, retry
-            i--;
-            continue;
-        }
-
-        node_cluster_assignments[node_index] = i;
-
-        clusters_seeds[i] = node_index;
-        clusters[i] = [node_index];
-    }
-
-    const m_distances = graph_compute_distance_matrix(graph, node_array, clusters_seeds, node_index_map);
-
-    for (let node_index = 0; node_index < total_node_count; node_index++) {
-
-        if (node_cluster_assignments[node_index] !== UNASSIGNED_CLUSTER) {
-            // already assigned
-            continue;
-        }
-
-        let closest_cluster = 0;
-        let closest_distance = Number.POSITIVE_INFINITY;
-
-        for (let cluster_index = 0; cluster_index < k; cluster_index++) {
-            const cluster_seed = clusters_seeds[cluster_index];
-
-            const distance = m_distances.getCellValue(cluster_seed, node_index);
-
-            if (distance < closest_distance) {
-                closest_distance = distance;
-                closest_cluster = cluster_index;
-            }
-        }
-
-        // assign node to closest cluster
-        node_cluster_assignments[node_index] = closest_cluster;
-        clusters[closest_cluster].push(node_index);
-    }
-
-    return clusters;
-}
-
-/**
- * Partition graph into K parts using K-means algorithm
- * @template T
- * @param {Graph<T>} graph
- * @param {number} k number of desired parts
- * @param {number} random_seed seed for random number generator, useful for restarting partitioning
- * @returns {number[][]}
- */
-export function graph_k_means_cluster(graph, k, random_seed) {
-
-    const node_array = Array.from(graph.getNodes());
-    const node_count = node_array.length;
-
-    /**
-     *
-     * @type {Uint8Array}
-     */
-    const node_cluster_assignments = new Uint8Array(node_count);
-    // fill with "UNASSIGNED" value
-    node_cluster_assignments.fill(255);
-
-    /**
-     * build node index
-     * @type {Map<T, number>}
-     */
-    const node_index_map = new Map();
-
-    for (let i = 0; i < node_count; i++) {
-        node_index_map.set(node_array[i], i);
-    }
-
-    return graph_k_means_cluster_detailed(node_array, k, random_seed, node_cluster_assignments, node_index_map, graph);
-}
+import { assert } from "../assert.js";
+import { randomIntegerBetween } from "../math/random/randomIntegerBetween.js";
+import { seededRandom } from "../math/random/seededRandom.js";
+import { graph_compute_distance_matrix } from "./graph_compute_distance_matrix.js";
+
+
+/**
+ * Sentinel value marking a node as not yet assigned to any cluster.
+ * Must be distinguishable from any valid cluster index 0..k-1, so k must
+ * stay strictly below this.
+ * @type {number}
+ */
+const UNASSIGNED_CLUSTER = 0xFFFFFFFF;
+
+/**
+ * Maximum number of refinement iterations before the algorithm stops even
+ * if medoids haven't stabilised. In practice convergence is reached within
+ * a handful of iterations on well-connected graphs.
+ * @type {number}
+ */
+const MAX_ITERATIONS = 32;
+
+
+/**
+ * Find the medoid of a set of nodes: the member with minimum sum of
+ * distances to every other member.
+ *
+ * @param {number[]} members cluster member node indices
+ * @param {SquareMatrix} m_distances matrix whose columns for each member index are filled
+ * @returns {number} node index of the medoid
+ */
+function find_cluster_medoid(members, m_distances) {
+    const n = members.length;
+
+    let best_member = members[0];
+    let best_sum = Number.POSITIVE_INFINITY;
+
+    for (let i = 0; i < n; i++) {
+        const candidate = members[i];
+
+        let sum = 0;
+        for (let j = 0; j < n; j++) {
+            if (i === j) {
+                continue;
+            }
+            sum += m_distances.getCellValue(candidate, members[j]);
+        }
+
+        if (sum < best_sum) {
+            best_sum = sum;
+            best_member = candidate;
+        }
+    }
+
+    return best_member;
+}
+
+
+/**
+ * @param {MultiNode<T>[]} node_array
+ * @param {number} k
+ * @param {number} random_seed
+ * @param {number[]|Uint32Array} node_cluster_assignments pre-filled with UNASSIGNED_CLUSTER
+ * @param {Map<T, number>} node_index_map
+ * @param {Graph<MultiNode<T>>} graph
+ * @returns {number[][]}
+ */
+export function graph_k_means_cluster_detailed(
+    node_array,
+    k,
+    random_seed,
+    node_cluster_assignments,
+    node_index_map,
+    graph
+) {
+    const total_node_count = node_array.length;
+
+    if (k > total_node_count) {
+        throw new Error(`Not enough nodes in the graph, K(=${k}) > |V| (=${total_node_count})`);
+    }
+
+    // Cluster indices are stored alongside UNASSIGNED_CLUSTER in the same array, so
+    // k must fit strictly below the sentinel to avoid collisions.
+    assert.lessThan(k, UNASSIGNED_CLUSTER, `k must be less than UNASSIGNED_CLUSTER(=${UNASSIGNED_CLUSTER})`);
+
+    if (k === 0) {
+        return [];
+    }
+
+    const random = seededRandom(random_seed);
+
+    /**
+     * Current medoid (centroid) node index for each cluster
+     * @type {number[]}
+     */
+    const seeds = [];
+
+    // Farthest-first seeding: pick the first seed uniformly at random, then each
+    // subsequent seed is the node whose minimum distance to any existing seed is
+    // largest. This reliably spreads seeds across disconnected components and
+    // avoids the common K-means failure mode where random initialisation puts
+    // every seed into the same component.
+    {
+        // randomIntegerBetween is inclusive on both ends, so the max index is count-1
+        const first_seed = randomIntegerBetween(random, 0, total_node_count - 1);
+        seeds[0] = first_seed;
+        node_cluster_assignments[first_seed] = 0;
+    }
+
+    for (let i = 1; i < k; i++) {
+        const m_partial = graph_compute_distance_matrix(graph, node_array, seeds, node_index_map);
+
+        let best_node = -1;
+        let best_min_dist = -1;
+
+        for (let node_index = 0; node_index < total_node_count; node_index++) {
+            if (node_cluster_assignments[node_index] !== UNASSIGNED_CLUSTER) {
+                // already a seed
+                continue;
+            }
+
+            let min_dist = Number.POSITIVE_INFINITY;
+            for (let j = 0; j < i; j++) {
+                const d = m_partial.getCellValue(node_index, seeds[j]);
+                if (d < min_dist) {
+                    min_dist = d;
+                }
+            }
+
+            if (min_dist > best_min_dist) {
+                best_min_dist = min_dist;
+                best_node = node_index;
+            }
+        }
+
+        seeds[i] = best_node;
+        node_cluster_assignments[best_node] = i;
+    }
+
+    /**
+     * Node indices belonging to each cluster. Rebuilt every iteration.
+     * @type {number[][]}
+     */
+    let cluster_members = [];
+
+    for (let iter = 0; iter < MAX_ITERATIONS; iter++) {
+        // 1. Compute distances from every current seed to every node (BFS from each seed)
+        const m_distances_from_seeds = graph_compute_distance_matrix(graph, node_array, seeds, node_index_map);
+
+        // 2. Assign every node to its nearest seed
+        for (let node_index = 0; node_index < total_node_count; node_index++) {
+
+            let closest_cluster = 0;
+            let closest_distance = Number.POSITIVE_INFINITY;
+
+            for (let cluster_index = 0; cluster_index < k; cluster_index++) {
+                const cluster_seed = seeds[cluster_index];
+
+                // Matrix columns are the seed (target) indices, rows are source nodes.
+                // We need the distance from node_index to the seed, so read m[node_index, seed].
+                const distance = m_distances_from_seeds.getCellValue(node_index, cluster_seed);
+
+                if (distance < closest_distance) {
+                    closest_distance = distance;
+                    closest_cluster = cluster_index;
+                }
+            }
+
+            node_cluster_assignments[node_index] = closest_cluster;
+        }
+
+        // 3. Rebuild cluster member lists
+        cluster_members = [];
+        for (let i = 0; i < k; i++) {
+            cluster_members[i] = [];
+        }
+        for (let node_index = 0; node_index < total_node_count; node_index++) {
+            cluster_members[node_cluster_assignments[node_index]].push(node_index);
+        }
+
+        // 4. Recompute each seed as the medoid of its cluster
+        let seeds_changed = false;
+
+        for (let cluster_index = 0; cluster_index < k; cluster_index++) {
+            const members = cluster_members[cluster_index];
+
+            if (members.length <= 1) {
+                // 0 or 1 member: medoid is trivially the current seed
+                continue;
+            }
+
+            // BFS from every member to compute within-cluster pairwise distances
+            const m_within = graph_compute_distance_matrix(graph, node_array, members, node_index_map);
+
+            const new_seed = find_cluster_medoid(members, m_within);
+
+            if (new_seed !== seeds[cluster_index]) {
+                seeds[cluster_index] = new_seed;
+                seeds_changed = true;
+            }
+        }
+
+        if (!seeds_changed) {
+            break;
+        }
+    }
+
+    return cluster_members;
+}
+
+/**
+ * Partition graph into K parts using K-medoids (graph K-means).
+ * Iteratively reassigns nodes to the nearest medoid, then recomputes medoids
+ * as the within-cluster node minimising the sum of distances to other members.
+ * Stops when medoids stabilise or MAX_ITERATIONS is reached.
+ *
+ * Distances are BFS-based and so treat all edges as unit-weight; see
+ * {@link graph_compute_distance_matrix}.
+ *
+ * @template T
+ * @param {Graph<T>} graph
+ * @param {number} k number of desired parts
+ * @param {number} random_seed seed for random number generator, useful for restarting partitioning
+ * @returns {number[][]}
+ */
+export function graph_k_means_cluster(graph, k, random_seed) {
+
+    const node_array = Array.from(graph.getNodes());
+    const node_count = node_array.length;
+
+    /**
+     * Uint32 so cluster indices and the UNASSIGNED_CLUSTER sentinel (0xFFFFFFFF) don't collide
+     * for any practical k
+     * @type {Uint32Array}
+     */
+    const node_cluster_assignments = new Uint32Array(node_count);
+    node_cluster_assignments.fill(UNASSIGNED_CLUSTER);
+
+    /**
+     * build node index
+     * @type {Map<T, number>}
+     */
+    const node_index_map = new Map();
+
+    for (let i = 0; i < node_count; i++) {
+        node_index_map.set(node_array[i], i);
+    }
+
+    return graph_k_means_cluster_detailed(node_array, k, random_seed, node_cluster_assignments, node_index_map, graph);
+}

package/src/core/graph/layout/CircleLayout.js

@@ -626,9 +626,9 @@ function circleOverlapsConnection(circle, edge) {
     const dX = x1 - x0;
     const dY = y1 - y0;
 
-    //Vector from center sphere to ray start
-    const fX = x1 - cX;
-    const fY = y1 - cY;
+    //Vector from ray start to circle center
+    const fX = x0 - cX;
+    const fY = y0 - cY;
 
     const a = dX * dX + dY * dY;
     const b = 2 * (fX * dX + fY * dY);
@@ -695,9 +695,9 @@ function resolveCircleLineOverlap(circle, c0, c1) {
     const dX = x1 - x0;
     const dY = y1 - y0;
 
-    //Vector from center sphere to ray start
-    const fX = x1 - cX;
-    const fY = y1 - cY;
+    //Vector from ray start to circle center
+    const fX = x0 - cX;
+    const fY = y0 - cY;
 
     const a = dX * dX + dY * dY;
     const b = 2 * (fX * dX + fY * dY);

package/src/core/graph/layout/Connection.js

@@ -22,7 +22,7 @@ export class Connection {
         if (numPoints > 1) {
             let p0 = points[0];
             for (let i = 1; i < numPoints; i++) {
-                let p1 = points[1];
+                let p1 = points[i];
 
                 result += p0.distanceTo(p1);
 

package/src/core/graph/layout/box/aabb2_force_into_container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aabb2_force_into_container.d.ts","sourceRoot":"","sources":["../../../../../../src/core/graph/layout/box/aabb2_force_into_container.js"],"names":[],"mappings":"AA4CA;;;;GAIG;AACH,+EAMC"}
+{"version":3,"file":"aabb2_force_into_container.d.ts","sourceRoot":"","sources":["../../../../../../src/core/graph/layout/box/aabb2_force_into_container.js"],"names":[],"mappings":"AA8CA;;;;GAIG;AACH,+EAMC"}

package/src/core/graph/layout/box/aabb2_force_into_container.js

@@ -27,14 +27,16 @@ function interval_force_into_bounds(
         }
 
     }else{
-        // too big to fit, pick the smallest displacement to occupy entire bounds
+        // too big to fit, shift so subject covers the entire bounds
 
         const a = subject_v0 - bounds_v0;
         const b = bounds_v1 - subject_v1;
 
-        if(a > 0 && a < b){
+        if(a > 0){
+            // subject left edge is inside bounds, shift left so it covers
             displacement = -a;
         }else if(b > 0){
+            // subject right edge is inside bounds, shift right so it covers
             displacement = b;
         }
     }

package/src/core/math/statistics/computeStatisticalMedian.js

@@ -6,5 +6,5 @@ import { computeStatisticalPartialMedian } from "./computeStatisticalPartialMedi
  * @returns {number}
  */
 export function computeStatisticalMedian(values) {
-    return computeStatisticalPartialMedian(values, 0, values.length);
+    return computeStatisticalPartialMedian(values, 0, values.length - 1);
 }

package/src/engine/navigation/mesh/NavigationMesh.d.ts

@@ -10,20 +10,22 @@ export class NavigationMesh {
      * @param {BinaryTopology} source
      * @param {number} [agent_radius]
      * @param {number} [agent_height]
-     * @param {number} [agent_max_climb] In radians, how steep of an angle can the agent go up by
+     * @param {number} [agent_max_climb_angle] In radians, how steep of an angle can the agent go up by
      * @param {Vector3} [up] Defines world's "UP" direction, this is what the agent will respect for climbing constraint
      */
-    build({ source, agent_radius, agent_height, agent_max_climb, up, }: BinaryTopology): void;
+    build({ source, agent_radius, agent_height, agent_max_climb_angle, up, }: BinaryTopology): void;
     /**
+     * Compute a walkable path between the two points.
+     * The result is a sequence of 3d points written into `output`. First point matches start, last point matches goal (snapped onto the mesh).
      *
-     * @param {Float32Array} output
+     * @param {Float32Array} output packed XYZ triples
      * @param {number} start_x
      * @param {number} start_y
      * @param {number} start_z
      * @param {number} goal_x
      * @param {number} goal_y
      * @param {number} goal_z
-     * @returns {number}
+     * @returns {number} number of 3d points written to `output` (0 if no path was found)
      */
     find_path(output: Float32Array, start_x: number, start_y: number, start_z: number, goal_x: number, goal_y: number, goal_z: number): number;
 }

package/src/engine/navigation/mesh/NavigationMesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NavigationMesh.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/NavigationMesh.js"],"names":[],"mappings":"AAmCA;IAEI,yBAAgC;IAEhC;;;OAGG;IACH,KAFU,GAAG,CAEG;IAEhB;;;;;;;OAOG;IACH,oEANW,cAAc,QAwBxB;IAGD;;;;;;;;;;OAUG;IACH,kBATW,YAAY,WACZ,MAAM,WACN,MAAM,WACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAwGlB;CAEJ;+BA3L4C,gEAAgE;oBAFzF,gCAAgC"}
+{"version":3,"file":"NavigationMesh.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/NavigationMesh.js"],"names":[],"mappings":"AAgCA;IAEI,yBAAgC;IAEhC;;;OAGG;IACH,KAFU,GAAG,CAEG;IAEhB;;;;;;;OAOG;IACH,0EANW,cAAc,QAwBxB;IAGD;;;;;;;;;;;;OAYG;IACH,kBATW,YAAY,WACZ,MAAM,WACN,MAAM,WACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CA+HlB;CAEJ;+BAlN4C,gEAAgE;oBADzF,gCAAgC"}