@woosh/meep-engine 2.79.0 → 2.80.1

package/src/core/geom/packing/max-rect/{MaxRectangles.js → MaxRectanglesPacker.js}

@@ -1,15 +1,19 @@
-import BinaryHeap from "../../../collection/heap/FastBinaryHeap.js";
 import { assert } from "../../../assert.js";
+import BinaryHeap from "../../../collection/heap/FastBinaryHeap.js";
+import AABB2 from "../../2d/aabb/AABB2.js";
 import { QuadTreeDatum } from "../../2d/quad-tree/QuadTreeDatum.js";
 import { QuadTreeNode } from "../../2d/quad-tree/QuadTreeNode.js";
-import AABB2 from "../../2d/aabb/AABB2.js";
 import Vector2 from "../../Vector2.js";
-import { removeRedundantBoxes } from "./removeRedundantBoxes.js";
 import { costByRemainingArea } from "./cost/costByRemainingArea.js";
 import { findBestContainer } from "./findBestContainer.js";
 import { packOneBox } from "./packOneBox.js";
+import { removeRedundantBoxes } from "./removeRedundantBoxes.js";
 
-
+/**
+ * Packs rectangles into a finite area, packer is incremental and supports both insertions and removals of rectangles
+ * Implementation of "max rectangles" packing algorithm.
+ * Useful for packing texture atlases
+ */
 export class MaxRectanglesPacker {
     /**
      *
@@ -24,6 +28,8 @@ export class MaxRectanglesPacker {
          * @type {QuadTreeNode}
          */
         this.free = new QuadTreeNode(0, 0, width, height);
+
+        // initialize a with a free space occupying the entire area
         this.free.add(null, 0, 0, width, height);
 
         /**
@@ -98,7 +104,8 @@ export class MaxRectanglesPacker {
     }
 
     /**
-     *
+     * Tests whether a rectangle of given dimensions can be packed into remaining space
+     * Essentially, if this method succeeds - insertion will succeed as well, and if it fails - insertion will fail too
      * @param {number} w
      * @param {number} h
      * @return {boolean}
@@ -184,9 +191,10 @@ export class MaxRectanglesPacker {
     }
 
     /**
-     * Resize the packer canvas
+     * Resize the packer canvas, may trigger repacking if new dimensions are smaller than the existing ones
      * @param {number} width
      * @param {number} height
+     * @returns {boolean} false if packing fails after resize, true otherwise
      */
     resize(width, height) {
 
@@ -199,18 +207,20 @@ export class MaxRectanglesPacker {
 
         if (oldWidth > width || oldHeight > height) {
             //canvas was made smaller in at least one dimension, re-pack is required
-            this.repack();
-        } else {
-            //canvas was enlarged, we can simply add new free areas
-            if (width > oldWidth) {
-                this.free.insertDatum(new QuadTreeDatum(oldWidth, 0, width, height));
-            }
-            if (height > oldHeight) {
-                this.free.insertDatum(new QuadTreeDatum(0, oldHeight, width, height))
-            }
+            return this.repack();
+        }
+
+        //canvas was enlarged, we can simply add new free areas
+        if (width > oldWidth) {
+            this.free.insertDatum(new QuadTreeDatum(oldWidth, 0, width, height));
+        }
+        if (height > oldHeight) {
+            this.free.insertDatum(new QuadTreeDatum(0, oldHeight, width, height))
         }
 
         // assert.ok(this.validate());
+
+        return true;
     }
 
     validate() {
@@ -239,20 +249,3 @@ export class MaxRectanglesPacker {
 }
 
 
-/**
- * Packs {@link AABB2} boxes into defined bounds
- *
- * Based on paper "A Thousand Ways to Pack the Bin - A Practical Approach to Two-Dimensional Rectangle Bin Packing" 2010 Jukka Jylänki
- * Method presented called Maximal Rectangles
- *
- * @param {number} width
- * @param {number} height
- * @param {AABB2[]} boxes
- * @returns {boolean} true if packing was successful, false otherwise
- */
-export function packMaxRectangles(width, height, boxes) {
-
-    const packer = new MaxRectanglesPacker(width, height);
-
-    return packer.addMany(boxes);
-}

package/src/core/geom/packing/max-rect/MaxRectanglesPacker.spec.js

@@ -0,0 +1,60 @@
+import AABB2 from "../../2d/aabb/AABB2.js";
+import { MaxRectanglesPacker } from "./MaxRectanglesPacker.js";
+
+test("constructor does not throw", () => {
+    new MaxRectanglesPacker(1, 1)
+});
+
+test("pack 1 box that takes up entire available area", () => {
+    const packer = new MaxRectanglesPacker(1, 1);
+
+    const box = new AABB2(3, 5, 4, 6);
+
+    expect(packer.add(box)).toBe(true);
+
+    expect(box.x0).toBe(0);
+    expect(box.y0).toBe(0);
+});
+
+test("packing a box larger than available area", () => {
+
+    const packer = new MaxRectanglesPacker(1, 1);
+
+    const box = new AABB2(0, 0, 2, 1);
+
+    expect(packer.add(box)).toBe(false);
+
+    box.set(0, 0, 1, 2);
+
+    expect(packer.add(box)).toBe(false);
+
+    box.set(0, 0, 2, 2)
+
+    expect(packer.add(box)).toBe(false);
+});
+
+test("pack 4 squares that fit exactly", () => {
+
+    const packer = new MaxRectanglesPacker(2, 2);
+
+    const boxes = [
+        new AABB2(0, 0, 1, 1),
+        new AABB2(0, 0, 1, 1),
+        new AABB2(0, 0, 1, 1),
+        new AABB2(0, 0, 1, 1)
+    ];
+
+    for (let i = 0; i < boxes.length; i++) {
+        expect(packer.add(boxes[i])).toBe(true);
+    }
+
+    // validate overlap constraints
+    for (let i = 0; i < boxes.length; i++) {
+        const box_0 = boxes[i];
+        for (let j = i + 1; j < boxes.length; j++) {
+            const box_1 = boxes[j];
+
+            expect(box_0.overlapExists(box_1)).toBe(false);
+        }
+    }
+});

package/src/core/geom/packing/max-rect/packMaxRectangles.js

@@ -0,0 +1,19 @@
+import { MaxRectanglesPacker } from "./MaxRectanglesPacker.js";
+
+/**
+ * Packs {@link AABB2} boxes into defined bounds
+ *
+ * Based on paper "A Thousand Ways to Pack the Bin - A Practical Approach to Two-Dimensional Rectangle Bin Packing" 2010 Jukka Jylänki
+ * Method presented called Maximal Rectangles
+ *
+ * @param {number} width
+ * @param {number} height
+ * @param {AABB2[]} boxes
+ * @returns {boolean} true if packing was successful, false otherwise
+ */
+export function packMaxRectangles(width, height, boxes) {
+
+    const packer = new MaxRectanglesPacker(width, height);
+
+    return packer.addMany(boxes);
+}

package/src/core/graph/cluster_mesh_metis.js

@@ -12,12 +12,12 @@ const MAX_STEPS = 50;
  * @param {Uint32Array} result
  * @param {number} node_count
  * @param {Uint32Array} edge_addresses
- * @param {Uint32Array} adjecency_uint32
+ * @param {Uint32Array} adjacency_uint32
  * @param {Uint32Array} edge_weights_uint32
  * @param {number} patch_size
  * @returns {Promise<number>}
  */
-export async function metis_cluster_bs(result, node_count, edge_addresses, adjecency_uint32, edge_weights_uint32, patch_size) {
+export async function metis_cluster_bs(result, node_count, edge_addresses, adjacency_uint32, edge_weights_uint32, patch_size) {
 
     const metis = Metis.INSTANCE;
 
@@ -46,7 +46,7 @@ export async function metis_cluster_bs(result, node_count, edge_addresses, adjec
             node_count,
             partition_count,
             edge_addresses,
-            adjecency_uint32,
+            adjacency_uint32,
             edge_weights_uint32,
             metisOptions
         );

package/src/core/graph/metis/metis.js

@@ -1,5 +1,5 @@
-import WorkerBuilder from "../../process/worker/WorkerBuilder.js";
 import { OnDemandWorkerManager } from "../../process/worker/OnDemandWorkerManager.js";
+import WorkerBuilder from "../../process/worker/WorkerBuilder.js";
 
 
 export class Metis {
@@ -13,6 +13,16 @@ export class Metis {
         this.service = manager;
     }
 
+    /**
+     *
+     * @param {number} n_vertices
+     * @param {number} n_parts
+     * @param {Uint32Array} edge_addresses
+     * @param {Uint32Array} adjacency
+     * @param {Uint32Array} edge_weights
+     * @param {metis_options} options
+     * @returns {Promise<T>}
+     */
     partition(
         n_vertices,
         n_parts,
@@ -32,4 +42,9 @@ export class Metis {
     }
 }
 
+/**
+ * Singleton instance
+ * @readonly
+ * @type {Metis}
+ */
 Metis.INSTANCE = new Metis();

package/src/core/graph/metis/metis_options.js

@@ -1,33 +1,36 @@
+
+/**
+ * See metis.h for more details
+ * -1 is the used to signal absence of value, in which case a default will be used
+ */
 export class metis_options {
+    ptype = -1;
+    objtype = -1;
     /**
-     * See metis.h for more details
-     * -1 is the used to signal absence of value, in which case a default will be used
+     * Coarsening scheme
+     * 0 - METIS_CTYPE_RM
+     * 1 - METIS_CTYPE_SHEM
+     * @type {number}
      */
-    constructor() {
-        this.ptype = -1;
-        this.objtype = -1;
-        /**
-         * Coarsening scheme
-         * 0 - METIS_CTYPE_RM
-         * 1 - METIS_CTYPE_SHEM
-         * @type {number}
-         */
-        this.ctype = -1;
-        this.iptype = -1;
-        this.rtype = -1;
-        this.dbglvl = -1;
-        this.niter = -1;
-        this.ncuts = -1;
-        this.seed = -1;
-        this.no2hop = -1;
-        this.minconn = -1;
-        this.contig = -1;
-        this.compress - 1;
-        this.ccorder = -1;
-        this.pfactor = -1;
-        this.nseps = -1;
-        this.ufactor = -1;
-        this.numbering = -1;
-
-    }
+    ctype = -1;
+    iptype = -1;
+    rtype = -1;
+    dbglvl = -1;
+    niter = -1;
+    ncuts = -1;
+    /**
+     * Random seed
+     * Integer
+     * @type {number}
+     */
+    seed = -1;
+    no2hop = -1;
+    minconn = -1;
+    contig = -1;
+    ccorder = -1;
+    pfactor = -1;
+    nseps = -1;
+    ufactor = -1;
+    numbering = -1;
+    compress = - 1;
 }

package/src/core/math/bell_membership_function.js

@@ -3,7 +3,7 @@
  * @see "dbellmf" function from Matlab
  * @see https://codecrucks.com/what-is-fuzzy-membership-function-complete-guide/
  * @see https://researchhubs.com/post/maths/fundamentals/bell-shaped-function.html
- * @param {number} v
+ * @param {number} v value to be filtered (have membership adjustment applied to)
  * @param {number} a Controls window, larger value = larger window. Function will return exactly 0.5 at this distance away from center
  * @param {number} b Slope, larger slope makes function's tails sharper, meaning that values fall off faster away from center
  * @param {number} c Controls center of the bell curve

package/src/core/math/computeIsoscelesTriangleApexAngle.js

@@ -1,8 +1,8 @@
 /**
- *
+ * Compute apex angle of an isosceles triangle (triangle with two equal sides)
  * @param {number} side length of the side
  * @param {number} base length of the base
- * @returns {number}
+ * @returns {number} Apex angle in radians
  */
 export function computeIsoscelesTriangleApexAngle(side, base) {
     const b2 = base * base;

package/src/core/math/computeIsoscelesTriangleApexAngle.spec.js

@@ -0,0 +1,6 @@
+import { computeIsoscelesTriangleApexAngle } from "./computeIsoscelesTriangleApexAngle.js";
+
+test("sanity", () => {
+    // right-angle triangle
+    expect(computeIsoscelesTriangleApexAngle(1, Math.SQRT2)).toBeCloseTo(Math.PI / 2);
+});

package/src/core/math/interval/overlap1D.js

@@ -12,8 +12,15 @@ import { assert } from "../../assert.js";
 export function overlap1D(a0, a1, b0, b1) {
     assert.isNumber(a0, "a0");
     assert.isNumber(a1, "a1");
+
     assert.isNumber(b0, "b0");
     assert.isNumber(b1, "b1");
 
+    assert.notNaN(a0, 'a0');
+    assert.notNaN(a1, 'a1');
+
+    assert.notNaN(b0, 'b0');
+    assert.notNaN(b1, 'b1');
+
     return a1 > b0 && b1 > a0;
 }

package/src/core/math/noise/create_simplex_noise_2d.js

@@ -73,6 +73,10 @@ export function create_simplex_noise_2d(random = Math.random) {
         permMod12[i] = (perm[i] % 12) * 2;
     }
 
+    /**
+     * @param {number} x
+     * @param {number} y
+     */
     return function noise2D(x, y) {
         // if(!isFinite(x) || !isFinite(y)) return 0;
         let n0 = 0; // Noise contributions from the three corners

package/src/core/math/spline/computeCatmullRomSplineUniformDistance.js

@@ -30,9 +30,9 @@ const p2 = [];
 const p3 = [];
 
 /**
- * Takes distances between points into account and samples at equal intervals along linear distance along the point sequence. Computationally slightly more expensive, but produces very predictable and sable results
- * @param {number[]} result
- * @param {number[]} input
+ * Takes distances between points into account and samples at equal intervals along linear distance along the point sequence. Computationally slightly more expensive, but produces very predictable and stable results
+ * @param {number[]|Float32Array} result
+ * @param {number[]|Float32Array} input
  * @param {number} input_length number of points in the input
  * @param {number} dimensions number of dimensions per vertex
  * @param {number} sample_count number of discrete points to be generated

package/src/core/math/spline/v3_computeCatmullRomSplineUniformDistance.js

@@ -0,0 +1,42 @@
+import Vector3 from "../../geom/Vector3.js";
+import { computeCatmullRomSplineUniformDistance } from "./computeCatmullRomSplineUniformDistance.js";
+
+/**
+ *
+ * @param {Vector3[]} inputs
+ * @param {number} samples
+ * @returns {Vector3[]}
+ */
+export function v3_computeCatmullRomSplineUniformDistance(
+    inputs, samples
+) {
+
+    const input_count = inputs.length;
+
+    const inputs_array = new Float32Array(3 * input_count);
+    const result_array = new Float32Array(3 * samples);
+
+    for (let i = 0; i < input_count; i++) {
+        const v3 = inputs[i];
+
+        v3.writeToArray(inputs_array, i * 3);
+    }
+
+    computeCatmullRomSplineUniformDistance(
+        result_array, inputs_array, input_count, 3, samples
+    );
+
+    // convert numeric result to array of Vector3 objects
+    const result = [];
+
+    for (let i = 0; i < samples; i++) {
+        const v3 = new Vector3();
+
+        v3.readFromArray(result_array, i * 3);
+
+        result[i] = v3;
+
+    }
+
+    return result;
+}

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

@@ -10,15 +10,21 @@ import { number_compare_ascending } from "../../primitives/numbers/number_compar
  */
 export function computeStatisticalPartialMedian(values, start, end) {
     assert.isArrayLike(values, 'values');
+    assert.isNumber(start, 'start');
+    assert.greaterThanOrEqual(start, 0);
+
+    assert.isNumber(end, 'end');
     assert.lessThan(end, values.length);
 
+    assert.lessThanOrEqual(start, end);
+
     const copy = values.slice();
 
     copy.sort(number_compare_ascending);
 
     const range = end - start;
 
-    const position = (start + range) >> 1;
+    const position = start + (range >> 1);
 
     return copy[position];
 }

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

@@ -1,14 +1,23 @@
-import { computeStatisticalPartialMedian } from "./computeStatisticalPartialMedian.js";
+import { assert } from "../../assert.js";
 import { clamp } from "../clamp.js";
+import { computeStatisticalPartialMedian } from "./computeStatisticalPartialMedian.js";
 
 /**
  *
  * @param {number[]} values
- * @param {number} percentile_low
- * @param {number} percentile_high
+ * @param {number} percentile_low 0..1
+ * @param {number} percentile_high 0..1
  * @returns {number}
  */
 export function computeStatisticalPercentile(values, percentile_low, percentile_high) {
+    assert.isNumber(percentile_low, 'percentile_low');
+    assert.notNaN(percentile_low, 'percentile_low');
+
+    assert.isNumber(percentile_high, 'percentile_high');
+    assert.notNaN(percentile_high, 'percentile_high');
+
+    assert.greaterThanOrEqual(percentile_high, percentile_low);
+
     const n = values.length;
 
     const start = clamp(Math.floor(n * percentile_low), 0, n - 1);

package/src/core/math/statistics/computeStatisticalPercentile.spec.js

@@ -0,0 +1,11 @@
+import { computeStatisticalPercentile } from "./computeStatisticalPercentile.js";
+
+test("half", () => {
+    expect(computeStatisticalPercentile([
+        0, 1, 2, 3, 4, 5, 6, 7, 8, 9
+    ], 0, 0.5)).toBeCloseTo(2);
+
+    expect(computeStatisticalPercentile([
+        0, 1, 2, 3, 4, 5, 6, 7, 8, 9
+    ], 0.5, 1)).toBeCloseTo(7);
+});

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

@@ -0,0 +1,12 @@
+import { computeStatisticalVariance } from "./computeStatisticalVariance.js";
+
+/**
+ *
+ * @param {number[]} sample
+ * @returns {number}
+ */
+export function computeStatisticalStandardDeviation(sample) {
+    const variance = computeStatisticalVariance(sample);
+
+    return Math.sqrt(variance);
+}

package/src/core/math/statistics/{computeSampleStandardDeviation.js → computeStatisticalVariance.js}

@@ -1,11 +1,11 @@
 import { computeStatisticalMean } from "./computeStatisticalMean.js";
 
 /**
- *
+ * Compute statistical variance for a given sample of numbers
  * @param {number[]} sample
  * @returns {number}
  */
-export function computeSampleStandardDeviation(sample) {
+export function computeStatisticalVariance(sample) {
     //compute sample mean
     const mean = computeStatisticalMean(sample);
 
@@ -22,7 +22,5 @@ export function computeSampleStandardDeviation(sample) {
         SUM += delta2;
     }
 
-    const variance = SUM / (N - 1);
-
-    return Math.sqrt(variance);
-}
+    return SUM / N;
+}

package/src/core/math/statistics/computeStatisticalVariance.spec.js

@@ -0,0 +1,10 @@
+import { computeStatisticalVariance } from "./computeStatisticalVariance.js";
+
+test("sanity", () => {
+
+    expect(computeStatisticalVariance([
+        1, 2, 3, 4, 5, 6
+    ]))
+        .toBeCloseTo(2.92);
+
+});

package/src/core/model/node-graph/Connection.js

@@ -1,7 +1,7 @@
-import {assert} from "../../assert.js";
-import {noop} from "../../function/Functions.js";
-import {objectKeyByValue} from "../object/objectKeyByValue.js";
-import {PortDirection} from "./node/PortDirection.js";
+import { assert } from "../../assert.js";
+import { noop } from "../../function/Functions.js";
+import { objectKeyByValue } from "../object/objectKeyByValue.js";
+import { PortDirection } from "./node/PortDirection.js";
 
 /**
  *
@@ -102,7 +102,8 @@ export class Connection {
         assert.isNumber(id, 'id');
         assert.isInteger(id, 'id');
 
-        return this.source.instance.id === id || this.target.instance.id === id;
+        return this.source?.instance?.id === id
+            || this.target?.instance?.id === id;
     }
 
     /**

package/src/core/model/node-graph/Connection.spec.js

@@ -19,3 +19,15 @@ test("equality on self", () => {
 
     expect(thing.equals(thing)).toBe(true);
 });
+
+test("isAttachedToNode", () => {
+    const connection = new Connection();
+
+    expect(connection.isAttachedToNode(0)).toBe(false);
+});
+
+test("toString", () => {
+    const ut = new Connection();
+
+    expect(typeof ut.toString()).toBe("string");
+});

package/src/core/model/node-graph/DataType.spec.js

@@ -26,3 +26,22 @@ test('equals', () => {
 
     expect(c.equals(d)).toBe(false);
 });
+
+test("hash", () => {
+
+    const a = DataType.from(7, 'kitty');
+    const b = DataType.from(7, 'kitty');
+
+    expect(a.hash()).toEqual(a.hash()); //stability
+    expect(typeof a.hash()).toBe("number");
+    expect(Number.isInteger(a.hash())).toBe(true);
+
+
+    expect(a.hash()).toEqual(b.hash());
+});
+
+test("toString", () => {
+    const type = DataType.from(7, 'kitty');
+
+    expect(typeof type.toString()).toBe("string");
+});

package/src/core/model/node-graph/node/NodeDescription.js

@@ -1,16 +1,17 @@
-import {assert} from "../../../assert.js";
-import {isArrayEqual} from "../../../collection/array/isArrayEqual.js";
+import { assert } from "../../../assert.js";
+import { isArrayEqual } from "../../../collection/array/isArrayEqual.js";
 import Signal from "../../../events/signal/Signal.js";
-import {invokeObjectToJSON} from "../../object/invokeObjectToJSON.js";
-import {NodeParameterDataType} from "./parameter/NodeParameterDataType.js";
-import {NodeParameterDescription} from "./parameter/NodeParameterDescription.js";
-import {Port} from "./Port.js";
-import {PortDirection} from "./PortDirection.js";
+import { invokeObjectToJSON } from "../../object/invokeObjectToJSON.js";
+import { NodeParameterDataType } from "./parameter/NodeParameterDataType.js";
+import { NodeParameterDescription } from "./parameter/NodeParameterDescription.js";
+import { Port } from "./Port.js";
+import { PortDirection } from "./PortDirection.js";
 
 
 /**
+ * @template T
  * @private
- * @param {{id:number}[]} things
+ * @param {T[]} things
  * @returns {number}
  */
 function pickNewSetId(things) {
@@ -181,7 +182,7 @@ export class NodeDescription {
 
     /**
      *
-     * @param {BinaryDataType} type
+     * @param {DataType} type
      * @param {String} name
      * @param {PortDirection} direction
      */
@@ -338,6 +339,7 @@ export class NodeDescription {
             }
         }
 
+        // port not found
         return undefined;
     }
 
@@ -380,7 +382,7 @@ export class NodeDescription {
      * @param name
      * @param {NodeRegistry} registry
      */
-    fromJSON({ports, id, name}, registry) {
+    fromJSON({ ports, id, name }, registry) {
         this.id = id;
         this.name = name;
         this.ports = ports.map(p => Port.fromJSON(p, registry));