@woosh/meep-engine 2.43.1 → 2.43.4

package/core/geom/3d/tetrahedra/TetrahedralMesh.js

@@ -0,0 +1,650 @@
+import { tetrahedron_contains_point } from "./tetrahedron_contains_point.js";
+import { typed_array_copy } from "../../../collection/array/typed/typed_array_copy.js";
+import { max3 } from "../../../math/max3.js";
+import { assert } from "../../../assert.js";
+import { array_copy } from "../../../collection/array/copyArray.js";
+import { array_quick_sort_by_comparator } from "../../../collection/array/arrayQuickSort.js";
+import { compareNumbersDescending } from "../../../function/Functions.js";
+import { BinaryBuffer } from "../../../binary/BinaryBuffer.js";
+import { Base64 } from "../../../binary/Base64.js";
+
+/**
+ * @readonly
+ * @type {number}
+ */
+const LAYOUT_TETRA_WORD_COUNT = 8;
+
+/**
+ * Size in bytes of a single tetrahedron record
+ * @readonly
+ * @type {number}
+ */
+export const LAYOUT_TETRA_BYTE_SIZE = LAYOUT_TETRA_WORD_COUNT * 4;
+
+/**
+ * @readonly
+ * @type {number}
+ */
+export const INVALID_NEIGHBOUR = 0xFFFFFFFF;
+
+/**
+ * @readonly
+ * @type {number}
+ */
+export const MAX_TET_INDEX = 0xFFFFFFFC;
+
+/**
+ * @readonly
+ * @type {number}
+ */
+const DEFAULT_INITIAL_SIZE = 128;
+
+/**
+ * @readonly
+ * @type {number}
+ */
+const CAPACITY_GROW_MULTIPLIER = 1.2;
+
+/**
+ * @readonly
+ * @type {number}
+ */
+const CAPACITY_GROW_MIN_STEP = 32;
+
+/**
+ * Only keeps track of tetrahedra, actual point coordinates are stored outside.
+ * For most useful operations point coordinates are passed in as an extra argument.
+ *
+ * Binary Layout:
+ *      vertex_id_a :: uint32
+ *      vertex_id_b :: uint32
+ *      vertex_id_c :: uint32
+ *      vertex_id_d :: uint32
+ *      neighbour_a :: uint32         - neighbour tetrahedron, opposite to vertex A
+ *      neighbour_b :: uint32         - neighbour tetrahedron, opposite to vertex B
+ *      neighbour_c :: uint32         - neighbour tetrahedron, opposite to vertex C
+ *      neighbour_d :: uint32         - neighbour tetrahedron, opposite to vertex D
+ * Layout is similar to [1], but is interleaved for better cache locality.
+ * Also note that sub-determinants are not included, these are only needed for building the mesh, we excluded them to keep structure clean and more compact.
+ *
+ * Neighbours are encoded in the following manner:
+ *      MSB -> [tet_id:30bit][opposite_corner_index:2bit] <- LSB
+ *      Code to get tet index: encoded >> 2
+ *      Code to get corner index: encoded & 3
+ *
+ * @see [1] 2018 "One machine, one minute, three billion tetrahedra" by Célestin Marot,  Jeanne Pellerin and Jean-François Remacle
+ * @see https://git.immc.ucl.ac.be/hextreme/hxt_seqdel (C source code for [1])
+ */
+export class TetrahedralMesh {
+    /**
+     *
+     * @param {number} [initial_size]
+     */
+    constructor(initial_size = DEFAULT_INITIAL_SIZE) {
+        assert.isNonNegativeInteger(initial_size, 'initial_size');
+
+        /**
+         *
+         * @type {ArrayBuffer}
+         * @private
+         */
+        this.__buffer = new ArrayBuffer(initial_size * LAYOUT_TETRA_BYTE_SIZE);
+
+        /**
+         *
+         * @type {Uint32Array}
+         * @private
+         */
+        this.__data_uint32 = new Uint32Array(this.__buffer);
+
+        /**
+         *
+         * @type {DataView}
+         * @private
+         */
+        this.__view = new DataView(this.__buffer);
+
+        /**
+         *
+         * @type {number}
+         * @private
+         */
+        this.__capacity = initial_size;
+
+        /**
+         *
+         * @type {number}
+         * @private
+         */
+        this.__used_end = 0;
+
+        /**
+         * Unused slots
+         * @type {number[]}
+         * @private
+         */
+        this.__free = [];
+
+        /**
+         *
+         * @type {number}
+         * @private
+         */
+        this.__free_pointer = 0;
+    }
+
+    /**
+     * Traverse tetrahedrons
+     * @param {(tet:number,mesh:TetrahedralMesh)=>*} visitor
+     * @param {*} [thisArg]
+     */
+    forEach(visitor, thisArg) {
+        for (let i = 0; i < this.__used_end; i++) {
+            if (!this.exists(i)) {
+                continue;
+            }
+
+            visitor.call(thisArg, i, this);
+        }
+    }
+
+    /**
+     *
+     * @param {number} capacity
+     */
+    setCapacity(capacity) {
+        assert.isNonNegativeInteger(capacity, 'capacity');
+
+        if (capacity === this.__capacity) {
+            // do nothing
+            return;
+        }
+
+        if (capacity < this.__capacity && capacity < this.__used_end) {
+            throw new Error('Reducing capacity would result in dropping information. This is an illegal operation. If you need to reduce capacity - either drop data or compact the layout first.');
+        }
+
+        // allocate new buffer
+        const new_buffer = new ArrayBuffer(capacity * LAYOUT_TETRA_BYTE_SIZE);
+
+        // move data across from old buffer to the new one
+        const destination_uint8 = new Uint8Array(new_buffer);
+        const source_uint8 = new Uint8Array(this.__buffer);
+
+        typed_array_copy(source_uint8, destination_uint8);
+
+        // set new buffer
+        this.__buffer = new_buffer;
+        this.__view = new DataView(new_buffer);
+        this.__data_uint32 = new Uint32Array(new_buffer);
+
+        // write new capacity
+        this.__capacity = capacity;
+    }
+
+    /**
+     *
+     * @return {number}
+     */
+    getCapacity() {
+        return this.__capacity;
+    }
+
+    /**
+     * How many tetrahedrons are contained in the mesh
+     * @return {number}
+     */
+    size() {
+        return this.__used_end;
+    }
+
+    /**
+     * Grow capacity to at least the specified size
+     * @param {number} capacity
+     */
+    growCapacity(capacity) {
+
+        const existing_capacity = this.__capacity;
+
+        const new_capacity = max3(
+            capacity,
+            Math.ceil(existing_capacity * CAPACITY_GROW_MULTIPLIER),
+            existing_capacity + CAPACITY_GROW_MIN_STEP
+        );
+
+        this.setCapacity(new_capacity);
+    }
+
+    /**
+     * NOTE: this method can be quite slow in cases of sparse allocation, please prefer not to use it
+     * @param {number} tet
+     * @return {boolean}
+     */
+    exists(tet) {
+
+        if (tet < 0 || tet >= this.__used_end) {
+            return false;
+        }
+
+        for (let i = 0; i < this.__free_pointer; i++) {
+            const free = this.__free[i];
+
+            if (tet === free) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * NOTE: the neighbour value must be encoded, see format specification for details
+     * @param {number} tetra_index
+     * @param {number} neighbour_index
+     * @returns {number} index of the neighbour encoded with the opposite corner
+     */
+    getNeighbour(tetra_index, neighbour_index) {
+        assert.isNonNegativeInteger(tetra_index, 'tetra_index');
+        assert.ok(this.exists(tetra_index), 'tetrahedron does not exist');
+
+        assert.isNonNegativeInteger(neighbour_index, 'neighbour_index');
+
+        assert.lessThan(neighbour_index, 4, 'neighbour_index');
+
+        const tetra_address = LAYOUT_TETRA_BYTE_SIZE * tetra_index;
+        return this.__view.getUint32(tetra_address + (4 + neighbour_index) * 4);
+    }
+
+    /**
+     * NOTE: the neighbour value must be encoded, see format specification for details
+     * @param {number} tetra_index
+     * @param {number} neighbour_index which neighbour to set (0..11)
+     * @param {number} neighbour index of the neighbour encoded with the opposite corner
+     */
+    setNeighbour(tetra_index, neighbour_index, neighbour) {
+
+        assert.isNonNegativeInteger(tetra_index, 'tetra_index');
+        assert.ok(this.exists(tetra_index), 'tetrahedron does not exist');
+
+        assert.isNonNegativeInteger(neighbour_index, 'neighbour_index');
+        assert.isNonNegativeInteger(neighbour, 'neighbour');
+
+        assert.lessThan(neighbour_index, 4, 'neighbour_index');
+
+        const tetra_address = LAYOUT_TETRA_BYTE_SIZE * tetra_index;
+        return this.__view.setUint32(tetra_address + (4 + neighbour_index) * 4, neighbour);
+    }
+
+
+    /**
+     *
+     * @param {number} tet_index
+     * @param {number} point_index should be an integer between 0 and 3
+     * @returns {number}
+     */
+    getVertexIndex(tet_index, point_index) {
+        assert.isNonNegativeInteger(tet_index, 'tet_index');
+        assert.lessThanOrEqual(tet_index, MAX_TET_INDEX, 'max index exceeded');
+        //assert.ok(this.exists(tet_index), 'tetrahedron does not exist');
+
+        assert.isNonNegativeInteger(point_index, 'point_index');
+        assert.lessThan(point_index, 4, 'point_index must be less than 4');
+
+
+        return this.__view.getUint32(tet_index * LAYOUT_TETRA_BYTE_SIZE + point_index * 4);
+    }
+
+    /**
+     *
+     * @param {number} tet_index
+     * @param {number} point_index
+     * @param {number} vertex
+     */
+    setVertexIndex(tet_index, point_index, vertex) {
+        assert.isNonNegativeInteger(tet_index, 'tet_index');
+        assert.lessThanOrEqual(tet_index, MAX_TET_INDEX, 'max index exceeded');
+        //assert.ok(this.exists(tet_index), 'tetrahedron does not exist');
+
+        assert.isNonNegativeInteger(point_index, 'point_index');
+        assert.lessThan(point_index, 4, 'point_index must be less than 4');
+
+        assert.isNonNegativeInteger(vertex, 'vertex');
+
+
+        return this.__view.setUint32(
+            tet_index * LAYOUT_TETRA_BYTE_SIZE + point_index * 4,
+            vertex
+        );
+    }
+
+    /**
+     * Whether a given tetrahedron contains vertex with a given index
+     * @param {number} tet
+     * @param {number} vertex
+     * @return {boolean}
+     */
+    tetContainsVertex(tet, vertex) {
+        for (let i = 0; i < 4; i++) {
+            if (this.getVertexIndex(tet, i) === vertex) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+
+    /**
+     * Allocate empty tet
+     * NOTE: the tet memory might be dirty, please make sure you set/clear it as necessary
+     * @return {number} index of allocated tetrahedron
+     */
+    allocate() {
+        if (this.__free_pointer > 0) {
+            this.__free_pointer--;
+            return this.__free[this.__free_pointer];
+        }
+
+        const tetra_index = this.__used_end;
+
+        this.__used_end++;
+
+        if (tetra_index >= this.__capacity) {
+            // needs to be increased in size
+            this.growCapacity(tetra_index);
+        }
+
+        // initialize neighbours
+        for (let i = 0; i < 4; i++) {
+            this.setNeighbour(tetra_index, i, INVALID_NEIGHBOUR);
+        }
+
+        //assert(this.validateLength());
+
+
+        // assert(this.validateLength());
+
+        return tetra_index;
+    }
+
+    /**
+     *
+     * @param {number[]|Float32Array} points
+     * @param {number} a
+     * @param {number} b
+     * @param {number} c
+     * @param {number} d
+     * @returns {number} index of the new tetrahedron
+     */
+    append(points, a, b, c, d) {
+        const tetra_index = this.allocate();
+
+        const address = tetra_index * LAYOUT_TETRA_BYTE_SIZE;
+
+        const view = this.__view;
+
+        view.setUint32(address, a);
+        view.setUint32(address + 4, b);
+        view.setUint32(address + 8, c);
+        view.setUint32(address + 12, d);
+
+        // set neighbours
+        view.setUint32(address + 16, INVALID_NEIGHBOUR);
+        view.setUint32(address + 20, INVALID_NEIGHBOUR);
+        view.setUint32(address + 24, INVALID_NEIGHBOUR);
+        view.setUint32(address + 28, INVALID_NEIGHBOUR);
+
+        return tetra_index;
+    }
+
+    /**
+     * Sets back-links on neighbours to this tet to INVALID_NEIGHBOUR basically making them into mesh surface
+     * This is a useful method for when you want to completely remove a given tet from the mesh to make sure that no dangling references will remain
+     * @param {number} tetra_index
+     */
+    disconnect(tetra_index) {
+        // find neighbours and remove reference to self
+        for (let i = 0; i < 4; i++) {
+            const neighbour_encoded = this.getNeighbour(tetra_index, i);
+
+            if (neighbour_encoded === INVALID_NEIGHBOUR) {
+                // no neighbour
+                continue;
+            }
+
+            // get tetrahedra index and point index
+            const neighbour_index = neighbour_encoded >> 2;
+            const neighbour_point = neighbour_encoded & 3;
+
+            // clear reference to self
+            this.setNeighbour(neighbour_index, neighbour_point, INVALID_NEIGHBOUR);
+        }
+    }
+
+    /**
+     * Remove tetrahedron
+     * Please note that if there are any dangling references in the mesh neighbourhood - you will need to take care of that separately
+     * @param {number} tetra_index
+     */
+    delete(tetra_index) {
+        assert.isNonNegativeInteger(tetra_index, 'tera_index');
+        assert.lessThan(tetra_index, this.__used_end, 'attempting to remove tet outside of valid region');
+        // assert.equal(this.__occupancy.get(tetra_index), true, 'tetrahedron does not exist');
+
+
+        if (tetra_index === this.__used_end - 1) {
+            // tet was at the end of the allocated space
+            this.__used_end--;
+        } else {
+            // mark as dead
+            this.__free[this.__free_pointer++] = tetra_index;
+        }
+
+        //assert(this.validateLength());
+
+        //assert(this.validateLength());
+    }
+
+    /**
+     * Used mainly to remove tetrahedrons whos points touch the "super-tetrahedron's" points that was inserted originally
+     * These points are identified by an offset + count parameters
+     * @param {number} range_start
+     * @param {number} range_end
+     */
+    removeTetrasConnectedToPoints(range_start, range_end) {
+
+        for (let i = this.__used_end - 1; i >= 0; i--) {
+
+            for (let j = 0; j < 4; j++) {
+                const point_index = this.getVertexIndex(i, j);
+
+                if (point_index >= range_start && point_index <= range_end) {
+
+                    if (!this.exists(i)) {
+                        // tet doesn't actually exist (deallocated)
+                        break;
+                    }
+
+                    // point index is in range, tetra should be removed
+                    this.disconnect(i);
+                    this.delete(i);
+                    break;
+                }
+            }
+        }
+
+    }
+
+    /**
+     *
+     * @param {number[]} points
+     * @param {number} index
+     * @returns {number} index of tetra or -1 if no containing tetra found
+     */
+    findTetraContainingPoint(points, index) {
+        const data_view = this.__view;
+
+        // TODO improve this
+        const n = this.__used_end;
+        for (let i = 0; i < n; i++) {
+
+            const tet_address = i * LAYOUT_TETRA_BYTE_SIZE;
+
+            const a = data_view.getUint32(tet_address);
+            const b = data_view.getUint32(tet_address + 4);
+            const c = data_view.getUint32(tet_address + 8);
+            const d = data_view.getUint32(tet_address + 12);
+
+            if (tetrahedron_contains_point(points, a, b, c, d, index)) {
+                return i;
+            }
+        }
+
+        return -1;
+    }
+
+
+    /**
+     * Relocate tetrahedron in memory, patches neighbourhood links as well
+     * NOTE: The destination slot will be overwritten. This is a dangerous method that can break the topology, make sure you fully understand what you are doing when using it
+     * @param {number} source_index index of source tetrahedron
+     * @param {number} destination_index new index, where the source tetrahedron is to be moved
+     */
+    relocate(source_index, destination_index) {
+        // validate_tetrahedron_neighbourhood(this, source_index, console.error);
+
+        // patch neighbours
+        for (let i = 0; i < 4; i++) {
+            const encoded_neighbour = this.getNeighbour(source_index, i);
+
+            if (encoded_neighbour === INVALID_NEIGHBOUR) {
+                // no neighbour
+                continue;
+            }
+
+            const neighbour_index = encoded_neighbour >> 2;
+            const neighbour_vertex = encoded_neighbour & 3;
+
+            const encoded_tet = (destination_index << 2) | (i & 3);
+
+            assert.equal(this.getNeighbour(neighbour_index, neighbour_vertex), (source_index << 2) | (i & 3), 'invalid source state');
+
+            this.setNeighbour(neighbour_index, neighbour_vertex, encoded_tet);
+        }
+
+
+        const layout_word_size = LAYOUT_TETRA_BYTE_SIZE >> 2;
+        array_copy(this.__data_uint32, source_index * layout_word_size, this.__data_uint32, destination_index * layout_word_size, layout_word_size);
+
+        // validate_tetrahedron_neighbourhood(this, destination_index, console.error);
+    }
+
+    /**
+     * Perform compaction, removing unused memory slots
+     * NOTE: existing tetrahedron indices can become invalidated as tets are moved into free slots
+     * @returns {number} number of relocated elements
+     */
+    compact() {
+        // sort free
+        array_quick_sort_by_comparator(this.__free, compareNumbersDescending, null, 0, this.__free_pointer - 1);
+
+        let relocation_count = 0;
+        let free_head_pointer = 0;
+
+        while (this.__free_pointer > free_head_pointer) {
+            const last_used = this.__used_end - 1;
+
+            if (this.__free[free_head_pointer] >= last_used) {
+                /*
+                 The slot is actually free.
+                 As we have sorted the free slots, it's expected to be at the start of the list
+                 Adjust pointers and continue onto the next slot
+                 */
+                free_head_pointer++
+                this.__used_end = last_used;
+                continue;
+            }
+
+            const free_slot = this.__free[this.__free_pointer - 1];
+
+            this.__free_pointer--;
+
+            if (last_used <= free_slot) {
+                continue;
+            }
+
+
+            this.relocate(last_used, free_slot);
+            relocation_count++;
+
+            this.__used_end--;
+
+        }
+
+        this.__free.splice(0, this.__free.length); // release memory
+        this.__free_pointer = 0;
+
+        return relocation_count;
+    }
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     */
+    serialize(buffer) {
+        buffer.writeUint32(1); // format version
+        buffer.writeUintVar(this.__used_end);
+        buffer.writeUintVar(this.__free_pointer);
+
+        // record main buffer
+        buffer.writeUint32Array(this.__data_uint32, 0, this.__used_end * LAYOUT_TETRA_WORD_COUNT);
+        buffer.writeUint32Array(this.__free, 0, this.__free_pointer);
+    }
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     */
+    deserialize(buffer) {
+        const version_number = buffer.readUint32();
+
+        if (version_number !== 1) {
+            throw new Error(`Unsupported version number, expected ${1}, instead got ${version_number}`);
+        }
+
+        this.__used_end = buffer.readUintVar();
+        this.__free_pointer = buffer.readUintVar();
+
+        this.growCapacity(this.__used_end);
+
+        buffer.readUint32Array(this.__data_uint32, 0, this.__used_end);
+
+        buffer.readUint32Array(this.__free, 0, this.__free_pointer);
+    }
+
+    /**
+     *
+     * @return {string}
+     */
+    serialize_base64() {
+        const buffer = new BinaryBuffer();
+
+        this.serialize(buffer);
+
+        buffer.trim();
+
+        return Base64.encode(buffer.data);
+    }
+
+    /**
+     *
+     * @param {string} str
+     */
+    deserialize_base64(str) {
+        const arrayBuffer = Base64.decode(str);
+
+        const binaryBuffer = BinaryBuffer.fromArrayBuffer(arrayBuffer);
+
+        this.deserialize(binaryBuffer);
+    }
+}