@woosh/meep-engine 2.33.24 → 2.33.28

package/core/geom/3d/shape/UnionShape3D.js

@@ -0,0 +1,255 @@
+import { AbstractShape3D } from "./AbstractShape3D.js";
+import { seededRandom } from "../../../math/random/seededRandom.js";
+import { binarySearchHighIndex } from "../../../collection/array/binarySearchHighIndex.js";
+import { compareNumbers } from "../../../primitives/numbers/compareNumbers.js";
+import { min2 } from "../../../math/min2.js";
+import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
+
+/**
+ * To avoid severe performance overhead, we limit number of possible rejections
+ * @type {number}
+ */
+const SAMPLE_REJECTION_ATTEMPT_MAX = 4;
+
+/**
+ * Number of samples taken to estimate overlap level
+ * @type {number}
+ */
+const VOLUME_OVERLAP_ESTIMATION_TAPS = 1024;
+const VOLUME_OVERLAP_ESTIMATION_SUB_TAPS = 4;
+
+const scratch_array = [];
+
+export class UnionShape3D extends AbstractShape3D {
+    constructor() {
+        super();
+
+        /**
+         *
+         * @type {AbstractShape3D[]}
+         */
+        this.children = [];
+
+        /**
+         * Estimator of how much volume is in overlap,
+         * expressed as fraction of volume occupied by overlapping region of 2 shapes over the sum of volume occupied by each child
+         * @type {number}
+         * @private
+         */
+        this.__volume_overlap_fraction = -1;
+
+        this.__volume_sum = -1;
+        this.__volume_sums = [];
+        this.__child_volumes = [];
+    }
+
+    /**
+     *
+     * @private
+     */
+    __compute_volume_variables() {
+        this.__volume_sum = 0;
+
+        const children = this.children;
+        const child_count = children.length;
+
+        const child_volumes = this.__child_volumes = new Float32Array(child_count);
+        const child_volume_sums = this.__volume_sums = new Float32Array(child_count);
+
+        for (let i = 0; i < child_count; i++) {
+            const child_volume = children[i].volume;
+
+            child_volumes[i] = child_volume;
+            this.__volume_sum += child_volume;
+
+            child_volume_sums[i] = this.__volume_sum;
+        }
+
+    }
+
+    /**
+     * Monte-carlo-style volume overlap estimation
+     * @private
+     */
+    __estimate_volume_overlap_fraction() {
+
+        if (this.__volume_sum === -1) {
+            this.__compute_volume_variables();
+        }
+
+        const children = this.children;
+        const child_count = children.length;
+
+        const random = seededRandom(1);
+
+        const child_volume_sums = this.__volume_sums;
+        const child_volume_sum = this.__volume_sum;
+
+        let i = 0, j = 0, k = 0, tap_overlaps = 0;
+
+        for (i = 0; i < VOLUME_OVERLAP_ESTIMATION_TAPS; i++) {
+
+            const target_weight = random() * child_volume_sum;
+
+            // weighted search for a sample candidate, preferring larger volumes, resulting in more uniform sample distribution
+            const target_child_index = binarySearchHighIndex(child_volume_sums, target_weight, compareNumbers, 0, child_count - 1);
+
+            const child_0 = children[target_child_index];
+
+            for (j = 0; j < VOLUME_OVERLAP_ESTIMATION_SUB_TAPS; j++, i++) {
+
+                child_0.sample_random_point_in_volume(scratch_array, 0, random);
+
+                for (k = 0; k < child_count; k++) {
+                    if (target_child_index === k) {
+                        // skip self
+                        continue;
+                    }
+
+                    const child_1 = children[k];
+
+                    if (child_1.contains_point(scratch_array)) {
+                        tap_overlaps++;
+                    }
+                }
+
+            }
+        }
+
+        this.__volume_overlap_fraction = tap_overlaps / (VOLUME_OVERLAP_ESTIMATION_TAPS);
+    }
+
+    static from(children) {
+        const r = new UnionShape3D();
+
+        r.children = children;
+
+        return r;
+    }
+
+    get volume() {
+        if (this.__volume_overlap_fraction < 0) {
+            this.__estimate_volume_overlap_fraction();
+        }
+
+        let volume_sum = 0;
+
+        const children = this.children;
+        const child_count = children.length;
+
+        for (let i = 0; i < child_count; i++) {
+            const child = children[i];
+
+            volume_sum += child.volume;
+        }
+
+        /**
+         * Unbias the volume by taking overlap into account
+         * @type {number}
+         */
+        const unbiased_volume = volume_sum / (this.__volume_overlap_fraction + 1);
+
+        return unbiased_volume;
+    }
+
+    get surface_area() {
+        let r = 0;
+
+        const children = this.children;
+        const child_count = children.length;
+        for (let i = 0; i < child_count; i++) {
+            const child = children[i];
+
+            r += child.surface_area;
+        }
+
+        return r;
+    }
+
+    signed_distance_gradient_at_point(result, point) {
+        return compute_signed_distance_gradient_by_sampling(result, this, point);
+    }
+
+    signed_distance_at_point(point) {
+        let r = Infinity;
+
+        const children = this.children;
+        const child_count = children.length;
+
+        for (let i = 0; i < child_count; i++) {
+            const child = children[i];
+
+            r = min2(child.signed_distance_at_point(point), r);
+        }
+
+        return r;
+    }
+
+    contains_point(point) {
+        const children = this.children;
+        const n = children.length;
+        for (let i = 0; i < n; i++) {
+            const child = children[i];
+
+            if (child.contains_point(point)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    sample_random_point_in_volume(result, result_offset, random) {
+        const children = this.children;
+        const child_count = children.length;
+
+
+        const target_weight = random() * this.__volume_sum;
+
+        // weighted search for a sample candidate, preferring larger volumes, resulting in more uniform sample distribution
+        const target_child_index = binarySearchHighIndex(this.__volume_sums, target_weight, compareNumbers, 0, child_count - 1);
+
+        const child = children[target_child_index];
+
+        let collision_count, i, j;
+
+        for (i = 0; i < SAMPLE_REJECTION_ATTEMPT_MAX; i++) {
+
+            // sample shape
+            child.sample_random_point_in_volume(result, result_offset, random);
+
+            /*
+            because underlying shapes can overlap and we wish to offer a union, just returning the sample would result in over-sampling in areas where shapes overlap
+            to avoid this oversampling, we reject samples in such areas with probability proportional to number of overlapping shapes at the sampled point
+             */
+            collision_count = 0;
+
+            for (j = 0; j < child_count; j++) {
+                const child_1 = children[j];
+
+                if (child_1 === child) {
+                    // exclude sampled child itself
+                    continue;
+                }
+
+                if (child_1.contains_point(result)) {
+                    collision_count++;
+                }
+            }
+
+            if (collision_count > 0) {
+                const rejection_chance = collision_count / (collision_count + 1);
+
+                const rejection_roll = random();
+
+                if (rejection_roll < rejection_chance) {
+                    //reject
+                    continue;
+                }
+            }
+
+            // no collisions, or survived rejection
+            break;
+        }
+    }
+}

package/core/geom/3d/shape/UnitCubeShape3D.js

@@ -1,5 +1,11 @@
 import { AbstractShape3D } from "./AbstractShape3D.js";
 import { randomPointInBox } from "../../random/randomPointInBox.js";
+import { v3_length } from "../../v3_length.js";
+import { max2 } from "../../../math/max2.js";
+import { max3 } from "../../../math/max3.js";
+import { min2 } from "../../../math/min2.js";
+import { clamp } from "../../../math/clamp.js";
+import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
 
 export class UnitCubeShape3D extends AbstractShape3D {
 
@@ -7,6 +13,88 @@ export class UnitCubeShape3D extends AbstractShape3D {
         return 1;
     }
 
+    nearest_point_on_surface(result, reference) {
+        const r_x = reference[0];
+        const r_y = reference[1];
+        const r_z = reference[2];
+
+        // figure out closest face to the reference point
+        const ar_x = Math.abs(r_x);
+        const ar_y = Math.abs(r_y);
+        const ar_z = Math.abs(r_z);
+
+        if (ar_x > ar_y && ar_x > ar_z) {
+            // X is smallest, project onto X axis
+            if (r_x <= 0) {
+                result[0] = -0.5;
+            } else {
+                result[0] = 0.5;
+            }
+
+            result[1] = clamp(r_y, -0.5, 0.5);
+            result[2] = clamp(r_z, -0.5, 0.5);
+        } else if (ar_y > ar_x && ar_y > ar_z) {
+            // Y is smallest, project onto X axis
+            if (r_y <= 0) {
+                result[1] = -0.5;
+            } else {
+                result[1] = 0.5;
+            }
+
+            result[0] = clamp(r_x, -0.5, 0.5);
+            result[2] = clamp(r_z, -0.5, 0.5);
+        } else {
+            // project onto Z axis
+
+            if (r_z <= 0) {
+                result[2] = -0.5;
+            } else {
+                result[2] = 0.5;
+            }
+
+            result[0] = clamp(r_x, -0.5, 0.5);
+            result[1] = clamp(r_y, -0.5, 0.5);
+        }
+    }
+
+    signed_distance_gradient_at_point(result, point) {
+        return compute_signed_distance_gradient_by_sampling(result,this, point);
+    }
+
+    signed_distance_at_point(point) {
+        /*
+        based on https://www.iquilezles.org/www/articles/distfunctions/distfunctions.htm
+        original shader code:
+            ------------
+            float sdBox( vec3 p, vec3 b )
+            {
+              vec3 q = abs(p) - b;
+              return length(max(q,0.0)) + min(max(q.x,max(q.y,q.z)),0.0);
+            }
+            ------------
+         */
+        const q_x = Math.abs(point[0]) - 0.5;
+        const q_y = Math.abs(point[1]) - 0.5;
+        const q_z = Math.abs(point[2]) - 0.5;
+
+        return v3_length(
+            max2(q_x, 0),
+            max2(q_y, 0),
+            max2(q_z, 0)
+        ) + min2(max3(q_x, q_y, q_z), 0);
+    }
+
+    contains_point(point) {
+        const x = point[0];
+        const y = point[1];
+        const z = point[2];
+
+        return x > -0.5 && x < 0.5
+            && y > -0.5 && y < 0.5
+            && z > -0.5 && z < 0.5
+            ;
+    }
+
     sample_random_point_in_volume(result, result_offset, random) {
         randomPointInBox(random, result, result_offset);
     }

package/core/geom/3d/shape/UnitCubeShape3D.spec.js

@@ -0,0 +1,42 @@
+import { UnitCubeShape3D } from "./UnitCubeShape3D.js";
+
+test('signed distance', () => {
+    const s = new UnitCubeShape3D();
+
+    expect(s.signed_distance_at_point([0, 0, 0])).toBeCloseTo(-0.5);
+
+    expect(s.signed_distance_at_point([0.5, 0, 0])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([0, 0.5, 0])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([0, 0, 0.5])).toBeCloseTo(0);
+
+    expect(s.signed_distance_at_point([-0.5, 0, 0])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([0, -0.5, 0])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([0, 0, -0.5])).toBeCloseTo(0);
+
+    expect(s.signed_distance_at_point([0.5, 0.5, 0])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([0, 0.5, 0.5])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([0.5, 0, 0.5])).toBeCloseTo(0);
+
+    expect(s.signed_distance_at_point([-0.5, 0.5, 0])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([0.5, -0.5, 0])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([-0.5, -0.5, 0])).toBeCloseTo(0);
+
+    expect(s.signed_distance_at_point([0, -0.5, 0.5])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([0, 0.5, -0.5])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([0, -0.5, -0.5])).toBeCloseTo(0);
+
+    expect(s.signed_distance_at_point([-0.5, 0, 0.5])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([0.5, 0, -0.5])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([-0.5, 0, -0.5])).toBeCloseTo(0);
+
+    expect(s.signed_distance_at_point([0.5, 0.5, 0.5])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([-0.5, 0.5, 0.5])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([0.5, -0.5, 0.5])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([0.5, 0.5, -0.5])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([-0.5, -0.5, 0.5])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([0.5, -0.5, -0.5])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([-0.5, 0.5, -0.5])).toBeCloseTo(0);
+    expect(s.signed_distance_at_point([-0.5, -0.5, -0.5])).toBeCloseTo(0);
+
+    expect(s.signed_distance_at_point([1, 0, 0])).toBeCloseTo(0.5);
+});

package/core/geom/3d/shape/UnitSphereShape3D.js

@@ -1,6 +1,11 @@
 import { AbstractShape3D } from "./AbstractShape3D.js";
 import { randomPointInSphere } from "../../random/randomPointInSphere.js";
+import { v3_length } from "../../v3_length.js";
+import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
 
+/**
+ * Sphere with diameter of 1 (radius = 0.5)
+ */
 export class UnitSphereShape3D extends AbstractShape3D {
     get volume() {
         return 0.523598776;
@@ -10,6 +15,40 @@ export class UnitSphereShape3D extends AbstractShape3D {
         return 3.14159265;
     }
 
+    nearest_point_on_surface(result, reference) {
+
+        const r_x = reference[0];
+        const r_y = reference[1];
+        const r_z = reference[2];
+
+        // normalize vector to 0.5 radius
+        const d = 0.5 / Math.hypot(r_x, r_y, r_z);
+
+        result[0] = r_x * d;
+        result[1] = r_y * d;
+        result[2] = r_z * d;
+    }
+
+    signed_distance_gradient_at_point(result, point) {
+        return compute_signed_distance_gradient_by_sampling(result,this, point);
+    }
+
+    signed_distance_at_point(point) {
+        return v3_length(
+            point[0],
+            point[1],
+            point[2]
+        ) - 0.5;
+    }
+
+    contains_point(point) {
+        const x = point[0];
+        const y = point[1];
+        const z = point[2];
+
+        return (x * x + y * y + z * z) < 0.25;
+    }
+
     sample_random_point_in_volume(result, result_offset, random) {
         randomPointInSphere(random, result, result_offset);
     }

package/core/geom/3d/shape/util/compute_signed_distance_gradient_by_sampling.js

@@ -0,0 +1,48 @@
+const scratch_v = [];
+
+/**
+ *
+ * @param {number[]} result
+ * @param {AbstractShape3D} shape
+ * @param {number[]} point
+ * @returns {number}
+ */
+export function compute_signed_distance_gradient_by_sampling(result, shape, point) {
+    const v0 = shape.signed_distance_at_point(point);
+
+    scratch_v[0] = point[0] + 1e-5;
+    scratch_v[1] = point[1];
+    scratch_v[2] = point[2];
+
+    const vx = shape.signed_distance_at_point(scratch_v);
+
+    scratch_v[0] = point[0];
+    scratch_v[1] = point[1] + 1e-5;
+    scratch_v[2] = point[2];
+
+    const vy = shape.signed_distance_at_point(point);
+
+    scratch_v[0] = point[0];
+    scratch_v[1] = point[1];
+    scratch_v[2] = point[2] + 1e-5;
+
+    const vz = shape.signed_distance_at_point(point);
+
+    // convert absolute sample values to relative
+    const rx = vx - v0;
+    const ry = vy - v0;
+    const rz = vz - v0;
+
+    // normalize by sampling distance
+    const d = 1e-5 / 1.73205080757;
+
+    const nx = rx * d;
+    const ny = ry * d;
+    const nz = rz * d;
+
+    result[0] = nx;
+    result[1] = ny;
+    result[2] = nz;
+
+    return v0;
+}

package/core/geom/3d/shape/util/shape_to_visual_entity.js

@@ -0,0 +1,159 @@
+import { UnionShape3D } from "../UnionShape3D.js";
+import { UnitCubeShape3D } from "../UnitCubeShape3D.js";
+import { UnitSphereShape3D } from "../UnitSphereShape3D.js";
+import { TransformedShape3D } from "../TransformedShape3D.js";
+import EntityBuilder from "../../../../../engine/ecs/EntityBuilder.js";
+import { Transform } from "../../../../../engine/ecs/transform/Transform.js";
+import { AttachmentSockets } from "../../../../../engine/ecs/sockets/AttachmentSockets.js";
+import { Attachment } from "../../../../../engine/ecs/attachment/Attachment.js";
+import { ShadedGeometry } from "../../../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { LineBasicMaterial } from "three";
+import { makeHelperSphereGeometry } from "../../../../../editor/process/symbolic/makeHelperSphereGeometry.js";
+import { DrawMode } from "../../../../../engine/graphics/ecs/mesh-v2/DrawMode.js";
+import { makeHelperBoxGeometry } from "../../../../../editor/process/symbolic/makeHelperBoxGeometry.js";
+import Tag from "../../../../../engine/ecs/components/Tag.js";
+
+const g_unit_sphere = makeHelperSphereGeometry(0.5, 32);
+const g_unit_cube = makeHelperBoxGeometry(1, 1, 1);
+
+const lineMaterial = new LineBasicMaterial({
+    depthTest: true,
+    depthWrite: false,
+    transparent: true,
+    linewidth: 1,
+    fog: false,
+    color: '#FFFFFF',
+    opacity: 1
+});
+
+export const SHAPE_VISUAL_ENTITY_TAG = 'util/vis/Shape3D';
+
+/**
+ *
+ * @param {UnionShape3D} shape
+ * @param {EntityComponentDataset} ecd
+ * @returns {EntityBuilder}
+ */
+function composite_shape_to_entity(shape, ecd) {
+
+    const parent = new EntityBuilder();
+    parent
+        .add(new Transform())
+        .add(AttachmentSockets.fromJSON({
+            elements: [
+                {
+                    type: 0,
+                    id: 0
+                }
+            ]
+        }))
+        .build(ecd);
+
+    shape.children.forEach(c => {
+
+        const child_entity = shape_to_visual_entity(c, ecd);
+
+        child_entity.add(Attachment.fromJSON({
+            socket: 0,
+            parent: parent.entity,
+            immediate: true
+        }));
+
+    })
+
+    return parent;
+}
+
+
+/**
+ *
+ * @param {UnitCubeShape3D} shape
+ * @param {EntityComponentDataset} ecd
+ * @returns {EntityBuilder}
+ */
+function cube_shape_to_entity(shape, ecd) {
+    const eb = new EntityBuilder();
+
+    eb.add(new Transform());
+    eb.add(Tag.fromOne(SHAPE_VISUAL_ENTITY_TAG));
+    eb.add(ShadedGeometry.from(g_unit_cube, lineMaterial, DrawMode.LineSegments));
+
+    eb.build(ecd);
+
+    return eb;
+}
+
+
+/**
+ *
+ * @param {UnitSphereShape3D} shape
+ * @param {EntityComponentDataset} ecd
+ * @returns {EntityBuilder}
+ */
+function sphere_shape_to_entity(shape, ecd) {
+    const eb = new EntityBuilder();
+
+    eb.add(new Transform());
+    eb.add(Tag.fromOne(SHAPE_VISUAL_ENTITY_TAG));
+    eb.add(ShadedGeometry.from(g_unit_sphere, lineMaterial, DrawMode.Lines));
+
+    eb.build(ecd);
+
+    return eb;
+
+}
+
+/**
+ *
+ * @param {TransformedShape3D} shape
+ * @param {EntityComponentDataset} ecd
+ * @returns {EntityBuilder}
+ */
+function transformed_shape_to_entity(shape, ecd) {
+    const subject = shape_to_visual_entity(shape.subject, ecd);
+
+    const parent = new EntityBuilder();
+    parent
+        .add(new Transform())
+        .add(AttachmentSockets.fromJSON({
+            elements: [
+                {
+                    type: 0,
+                    id: 0
+                }
+            ]
+        }))
+        .build(ecd);
+
+    const attachment = Attachment.fromJSON({
+        socket: 0,
+        parent: parent.entity,
+        immediate: true
+    });
+
+    attachment.transform.fromMatrix4(shape.transform);
+
+    subject.add(attachment);
+
+    return parent;
+}
+
+/**
+ *
+ * @param {AbstractShape3D} shape
+ * @param {EntityComponentDataset} ecd
+ * @returns {EntityBuilder}
+ */
+export function shape_to_visual_entity(shape, ecd) {
+    if (shape instanceof UnionShape3D) {
+        return composite_shape_to_entity(shape, ecd);
+    } else if (shape instanceof UnitCubeShape3D) {
+        return cube_shape_to_entity(shape, ecd);
+    } else if (shape instanceof UnitSphereShape3D) {
+        return sphere_shape_to_entity(shape, ecd);
+    } else if (shape instanceof TransformedShape3D) {
+        return transformed_shape_to_entity(shape, ecd);
+    } else {
+        throw new Error('Unsupported shape type');
+    }
+}

package/core/geom/random/randomPointInSphere.js

@@ -12,11 +12,12 @@ export function randomPointInSphere(random, result, result_offset) {
 
     const cosTheta = random() * 2 - 1;
 
-    const u = random() * 0.5;
+    const u = random();
 
     const theta = Math.acos(cosTheta);
 
-    const r = Math.cbrt(u);
+    // compute radius
+    const r = Math.cbrt(u) * 0.5;
 
     const sinTheta = Math.sin(theta);
 

package/core/json/resolvePathByArray.js

@@ -44,10 +44,10 @@ export function resolvePathByArray(object, parts, missingPropertyHandler) {
             } else {
                 const options = buildErrorSuggestions(current);
 
-                throw new Error(`failed to resolve path '${path}' at part ${i} [${part}]. Existing keys: ${options.join(", ")}`);
+                throw new Error(`failed to resolve path [${parts.join(',')}] at part ${i} [${part}]. Existing keys: ${options.join(", ")}`);
             }
         }
         current = current[part];
     }
     return current;
-}
+}

package/core/model/ObservedBoolean.d.ts

@@ -1,4 +1,6 @@
 export default class ObservedBoolean {
+    constructor(value: boolean)
+
     set(value: boolean): ObservedBoolean
 
     getValue(): boolean