@woosh/meep-engine 3.52.0 → 3.54.0

package/src/generation/foliage/skeleton/TreeSkeleton.js

@@ -0,0 +1,1100 @@
+import { assert } from "../../../core/assert.js";
+import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
+import { EdgeDirectionType } from "../../../core/graph/Edge.js";
+import { Graph } from "../../../core/graph/v2/Graph.js";
+import { spline3_hermite } from "../../../core/math/spline/spline3_hermite.js";
+import { spline3_hermite_derivative } from "../../../core/math/spline/spline3_hermite_derivative.js";
+import { t64_look_rotation } from "../../../engine/ecs/transform/t64_look_rotation.js";
+import {
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_SCALE_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET,
+    Transform64
+} from "../../../engine/ecs/transform/Transform64.js";
+import { Attribute } from "../../../shade/renderer/geometry/Attribute.js";
+
+const INITIAL_NODE_CAPACITY = 128;
+const INITIAL_SEGMENT_CAPACITY = 128;
+const INITIAL_BRANCH_CAPACITY = 64;
+
+const SCRATCH_VEC3 = new Float32Array(3);
+
+/**
+ * Helper to grow the typed array backing an {@link Attribute} while preserving existing items.
+ *
+ * @template {Int32Array|Float32Array|Uint16Array|Uint8Array} T
+ * @param {Attribute} attr
+ * @param {number} new_capacity_items
+ * @returns {T}
+ */
+function grow_attribute_capacity(attr, new_capacity_items) {
+    const item_size = attr.spec.itemSize;
+    const old_data = /** @type {T} */ (attr.data);
+    const ArrayCtor = /** @type {new (len: number) => T} */ (old_data.constructor);
+    const next_data = new ArrayCtor(new_capacity_items * item_size);
+    next_data.set(old_data);
+    attr.data = next_data;
+    return next_data;
+}
+
+/**
+ * Directed botanical tree skeleton backed by Meep's {@link Graph}, {@link Transform64}, and {@link Attribute}s.
+ *
+ * - **Topology (`this.graph: Graph<number>`)**:
+ *   A single connected directed tree (`EdgeDirectionType.Forward`) of skeleton node IDs `0 .. node_count - 1`.
+ *   Intra-branch edges represent Cubic Hermite spine segments; inter-branch edges connect each lateral branch's
+ *   root node to its parent attachment node on the supporting branch.
+ * - **Spatial Frame & Radius (`this.node_transforms: Transform64[]`)**:
+ *   Each node `v` owns a {@link Transform64} storing:
+ *   - `translation` (`[12..14]`): 3D position $\mathbf{p}_v = (x, y, z)$ in tree space ($+Y$ up).
+ *   - `rotation` (`[16..19]`): Orthonormal Rotation-Minimizing Frame (RMF) quaternion where
+ *     local $+X$ (`right`) $= \mathbf{R}_v$, local $+Y$ (`up`) $= \mathbf{S}_v = \mathbf{T}_v \times \mathbf{R}_v$,
+ *     and local $+Z$ (`forward`) $= \mathbf{T}_v$ (unit spine tangent).
+ *   - `scale` (`[20..22]`): Uniform cross-sectional radius $R_v$.
+ * - **Node & Segment Data (`Attribute`)**:
+ *   Per-node and per-segment attributes are packed into typed {@link Attribute} buffers.
+ */
+export class TreeSkeleton {
+    /**
+     * Directed topological graph of node IDs (`0 .. node_count - 1`).
+     * @type {Graph<number>}
+     */
+    graph = new Graph();
+
+    /**
+     * Per-node 3D transforms (translation = position, rotation = RMF basis `[R, S, T]`, scale = radius).
+     * @type {Transform64[]}
+     */
+    node_transforms = [];
+
+    /**
+     * Number of active skeleton nodes.
+     * @type {number}
+     */
+    node_count = 0;
+
+    /**
+     * Number of active Cubic Hermite spine segments.
+     * @type {number}
+     */
+    segment_count = 0;
+
+    /**
+     * Number of active branches.
+     * @type {number}
+     */
+    branch_count = 0;
+
+    /**
+     * @type {number}
+     */
+    #node_capacity = INITIAL_NODE_CAPACITY;
+
+    /**
+     * @type {number}
+     */
+    #segment_capacity = INITIAL_SEGMENT_CAPACITY;
+
+    /**
+     * @type {number}
+     */
+    #branch_capacity = INITIAL_BRANCH_CAPACITY;
+
+    /**
+     * Int32x4 per node: `[branch_id, level, parent_branch_id, in_segment_id]`
+     * @type {Attribute}
+     */
+    attr_node_branch_info = Attribute.from(new Int32Array(INITIAL_NODE_CAPACITY * 4), 4, "node_branch_info");
+
+    /**
+     * Float32x3 per node: `[t_norm, arc_s, phase_hash]`
+     * @type {Attribute}
+     */
+    attr_node_spine_param = Attribute.from(new Float32Array(INITIAL_NODE_CAPACITY * 3), 3, "node_spine_param");
+
+    /**
+     * Uint16x2 per node: `[primary_joint_index, parent_joint_index]`
+     * @type {Attribute}
+     */
+    attr_node_joint = Attribute.from(new Uint16Array(INITIAL_NODE_CAPACITY * 2), 2, "node_joint");
+
+    /**
+     * Int32x2 per Cubic Hermite segment: `[v0, v1]`
+     * @type {Attribute}
+     */
+    attr_segment_endpoints = Attribute.from(new Int32Array(INITIAL_SEGMENT_CAPACITY * 2), 2, "segment_endpoints");
+
+    /**
+     * Float32x3 per Cubic Hermite segment: `[m0x, m0y, m0z]` (outgoing tangent at `v0`)
+     * @type {Attribute}
+     */
+    attr_segment_hermite_m0 = Attribute.from(new Float32Array(INITIAL_SEGMENT_CAPACITY * 3), 3, "segment_hermite_m0");
+
+    /**
+     * Float32x3 per Cubic Hermite segment: `[m1x, m1y, m1z]` (incoming tangent at `v1`)
+     * @type {Attribute}
+     */
+    attr_segment_hermite_m1 = Attribute.from(new Float32Array(INITIAL_SEGMENT_CAPACITY * 3), 3, "segment_hermite_m1");
+
+    /**
+     * Float32x2 per Cubic Hermite segment: `[length, parent_attach_t]`
+     * @type {Attribute}
+     */
+    attr_segment_metrics = Attribute.from(new Float32Array(INITIAL_SEGMENT_CAPACITY * 2), 2, "segment_metrics");
+
+    /**
+     * Root node ID of each branch.
+     * @type {Int32Array}
+     */
+    branch_root_vertex = new Int32Array(INITIAL_BRANCH_CAPACITY);
+
+    /**
+     * Terminal tip node ID of each branch.
+     * @type {Int32Array}
+     */
+    branch_tip_vertex = new Int32Array(INITIAL_BRANCH_CAPACITY);
+
+    /**
+     * Recursion level of each branch (0 = trunk).
+     * @type {Uint8Array}
+     */
+    branch_level = new Uint8Array(INITIAL_BRANCH_CAPACITY);
+
+    /**
+     * Parent branch ID (-1 for trunk).
+     * @type {Int32Array}
+     */
+    branch_parent = new Int32Array(INITIAL_BRANCH_CAPACITY);
+
+    /**
+     * Parent Hermite segment ID where this branch attaches (-1 for trunk).
+     * @type {Int32Array}
+     */
+    branch_parent_edge = new Int32Array(INITIAL_BRANCH_CAPACITY);
+
+    /**
+     * Normalized position t in [0, 1] along the parent branch where this branch attaches.
+     * @type {Float32Array}
+     */
+    branch_parent_attach_t = new Float32Array(INITIAL_BRANCH_CAPACITY);
+
+    /**
+     * Total arc length of each branch in meters.
+     * @type {Float32Array}
+     */
+    branch_length = new Float32Array(INITIAL_BRANCH_CAPACITY);
+
+    /**
+     * Base radius of each branch in meters.
+     * @type {Float32Array}
+     */
+    branch_base_radius = new Float32Array(INITIAL_BRANCH_CAPACITY);
+
+    /**
+     * Per-branch random phase hash in [0, 1).
+     * @type {Float32Array}
+     */
+    branch_phase_hash = new Float32Array(INITIAL_BRANCH_CAPACITY);
+
+    /**
+     * Crown center `[cx, cy, cz]` in tree local space (Y-up).
+     * @type {Float32Array}
+     */
+    crown_center = new Float32Array([0, 6, 0]);
+
+    /**
+     * Crown ellipsoid semi-axes `[rx, ry, rz]`.
+     * @type {Float32Array}
+     */
+    crown_radii = new Float32Array([4.5, 5.0, 4.5]);
+
+    constructor() {
+        this.attr_node_branch_info.count = 0;
+        this.attr_node_spine_param.count = 0;
+        this.attr_node_joint.count = 0;
+        this.attr_segment_endpoints.count = 0;
+        this.attr_segment_hermite_m0.count = 0;
+        this.attr_segment_hermite_m1.count = 0;
+        this.attr_segment_metrics.count = 0;
+    }
+
+    /**
+     * Resets the skeleton to empty state while retaining allocated attribute buffers and `Transform64` instances.
+     */
+    clear() {
+        this.graph.clear();
+        this.node_count = 0;
+        this.segment_count = 0;
+        this.branch_count = 0;
+        this.attr_node_branch_info.count = 0;
+        this.attr_node_spine_param.count = 0;
+        this.attr_node_joint.count = 0;
+        this.attr_segment_endpoints.count = 0;
+        this.attr_segment_hermite_m0.count = 0;
+        this.attr_segment_hermite_m1.count = 0;
+        this.attr_segment_metrics.count = 0;
+    }
+
+    /**
+     * @param {number} required_count
+     */
+    #ensure_node_capacity(required_count) {
+        if (required_count <= this.#node_capacity) {
+            return;
+        }
+        let next_cap = this.#node_capacity * 2;
+        while (next_cap < required_count) {
+            next_cap *= 2;
+        }
+        grow_attribute_capacity(this.attr_node_branch_info, next_cap);
+        grow_attribute_capacity(this.attr_node_spine_param, next_cap);
+        grow_attribute_capacity(this.attr_node_joint, next_cap);
+        this.#node_capacity = next_cap;
+    }
+
+    /**
+     * @param {number} required_count
+     */
+    #ensure_segment_capacity(required_count) {
+        if (required_count <= this.#segment_capacity) {
+            return;
+        }
+        let next_cap = this.#segment_capacity * 2;
+        while (next_cap < required_count) {
+            next_cap *= 2;
+        }
+        grow_attribute_capacity(this.attr_segment_endpoints, next_cap);
+        grow_attribute_capacity(this.attr_segment_hermite_m0, next_cap);
+        grow_attribute_capacity(this.attr_segment_hermite_m1, next_cap);
+        grow_attribute_capacity(this.attr_segment_metrics, next_cap);
+        this.#segment_capacity = next_cap;
+    }
+
+    /**
+     * @param {number} required_count
+     */
+    #ensure_branch_capacity(required_count) {
+        if (required_count <= this.#branch_capacity) {
+            return;
+        }
+        let next_cap = this.#branch_capacity * 2;
+        while (next_cap < required_count) {
+            next_cap *= 2;
+        }
+
+        const grow_i32 = (old) => {
+            const arr = new Int32Array(next_cap);
+            arr.set(old);
+            return arr;
+        };
+        const grow_u8 = (old) => {
+            const arr = new Uint8Array(next_cap);
+            arr.set(old);
+            return arr;
+        };
+        const grow_f32 = (old) => {
+            const arr = new Float32Array(next_cap);
+            arr.set(old);
+            return arr;
+        };
+
+        this.branch_root_vertex = grow_i32(this.branch_root_vertex);
+        this.branch_tip_vertex = grow_i32(this.branch_tip_vertex);
+        this.branch_level = grow_u8(this.branch_level);
+        this.branch_parent = grow_i32(this.branch_parent);
+        this.branch_parent_edge = grow_i32(this.branch_parent_edge);
+        this.branch_parent_attach_t = grow_f32(this.branch_parent_attach_t);
+        this.branch_length = grow_f32(this.branch_length);
+        this.branch_base_radius = grow_f32(this.branch_base_radius);
+        this.branch_phase_hash = grow_f32(this.branch_phase_hash);
+        this.#branch_capacity = next_cap;
+    }
+
+    /**
+     * Registers a new branch in the branch table and returns its `branch_id`.
+     *
+     * @param {number} root_vertex
+     * @param {number} level
+     * @param {number} parent_branch_id
+     * @param {number} parent_edge_id
+     * @param {number} parent_attach_t
+     * @param {number} length
+     * @param {number} base_radius
+     * @param {number} [phase_hash=0]
+     * @returns {number} branch_id
+     */
+    add_branch(
+        root_vertex,
+        level,
+        parent_branch_id,
+        parent_edge_id,
+        parent_attach_t,
+        length,
+        base_radius,
+        phase_hash = 0
+    ) {
+        const id = this.branch_count;
+        this.#ensure_branch_capacity(id + 1);
+        this.branch_count = id + 1;
+
+        this.branch_root_vertex[id] = root_vertex;
+        this.branch_tip_vertex[id] = root_vertex;
+        this.branch_level[id] = level;
+        this.branch_parent[id] = parent_branch_id;
+        this.branch_parent_edge[id] = parent_edge_id;
+        this.branch_parent_attach_t[id] = parent_attach_t;
+        this.branch_length[id] = length;
+        this.branch_base_radius[id] = base_radius;
+        this.branch_phase_hash[id] = phase_hash;
+
+        return id;
+    }
+
+    /**
+     * Allocates and initializes a new skeleton node in `this.graph`, storing its 3D position,
+     * orthonormal RMF basis `[R, S, T]`, and radius in a {@link Transform64}, and its metadata in {@link Attribute}s.
+     *
+     * @param {number} px
+     * @param {number} py
+     * @param {number} pz
+     * @param {number} tx unit spine tangent X
+     * @param {number} ty unit spine tangent Y
+     * @param {number} tz unit spine tangent Z
+     * @param {number} rx unit radial normal X
+     * @param {number} ry unit radial normal Y
+     * @param {number} rz unit radial normal Z
+     * @param {number} radius cross-sectional radius
+     * @param {number} branch_id
+     * @param {number} level
+     * @param {number} parent_branch_id
+     * @param {number} t_norm
+     * @param {number} arc_s
+     * @param {number} phase_hash
+     * @returns {number} node ID
+     */
+    add_node(
+        px, py, pz,
+        tx, ty, tz,
+        rx, ry, rz,
+        radius,
+        branch_id,
+        level,
+        parent_branch_id,
+        t_norm,
+        arc_s,
+        phase_hash
+    ) {
+        const v = this.node_count;
+        this.#ensure_node_capacity(v + 1);
+        this.node_count = v + 1;
+
+        this.attr_node_branch_info.count = this.node_count;
+        this.attr_node_spine_param.count = this.node_count;
+        this.attr_node_joint.count = this.node_count;
+
+        this.graph.addNode(v);
+
+        let t64 = this.node_transforms[v];
+        if (t64 === undefined) {
+            t64 = new Transform64();
+            this.node_transforms[v] = t64;
+        }
+
+        // Binormal S = T x R so (R = S x T, S, T) maps to local (+X, +Y, +Z) via t64_look_rotation(t64, T, S)
+        const sx = ty * rz - tz * ry;
+        const sy = tz * rx - tx * rz;
+        const sz = tx * ry - ty * rx;
+
+        t64.setTranslation(px, py, pz);
+        t64_look_rotation(t64, tx, ty, tz, sx, sy, sz);
+        t64.setScaleScalar(radius);
+        t64.updateMatrix();
+
+        const b_info = /** @type {Int32Array} */ (this.attr_node_branch_info.data);
+        const b_off = v * 4;
+        b_info[b_off] = branch_id;
+        b_info[b_off + 1] = level;
+        b_info[b_off + 2] = parent_branch_id;
+        b_info[b_off + 3] = -1;
+
+        const s_param = /** @type {Float32Array} */ (this.attr_node_spine_param.data);
+        const s_off = v * 3;
+        s_param[s_off] = t_norm;
+        s_param[s_off + 1] = arc_s;
+        s_param[s_off + 2] = phase_hash;
+
+        const j_data = /** @type {Uint16Array} */ (this.attr_node_joint.data);
+        const j_off = v * 2;
+        j_data[j_off] = 0;
+        j_data[j_off + 1] = 0;
+
+        return v;
+    }
+
+    /**
+     * Connects `parent_v -> child_v` with a directed `EdgeDirectionType.Forward` edge in `this.graph`
+     * if not already connected. Used both by `add_segment` and to link lateral branch root nodes to their
+     * parent attachment node so `this.graph` forms a single connected arborescence.
+     *
+     * @param {number} parent_v
+     * @param {number} child_v
+     */
+    connect_nodes(parent_v, child_v) {
+        if (parent_v >= 0 && child_v >= 0 && parent_v !== child_v) {
+            if (!this.graph.edgeExistsBetween(parent_v, child_v)) {
+                this.graph.createEdge(parent_v, child_v, EdgeDirectionType.Forward);
+            }
+        }
+    }
+
+    /**
+     * Creates a directed Cubic Hermite spine segment `(v0 -> v1)` and adds the corresponding
+     * `EdgeDirectionType.Forward` edge to `this.graph`.
+     *
+     * @param {number} v0 parent node ID
+     * @param {number} v1 child node ID
+     * @param {number} m0x outgoing tangent X at v0
+     * @param {number} m0y outgoing tangent Y at v0
+     * @param {number} m0z outgoing tangent Z at v0
+     * @param {number} m1x incoming tangent X at v1
+     * @param {number} m1y incoming tangent Y at v1
+     * @param {number} m1z incoming tangent Z at v1
+     * @param {number} length chord/arc length of the segment
+     * @param {number} [parent_attach_t=0] normalized position along parent branch
+     * @returns {number} segment ID
+     */
+    add_segment(v0, v1, m0x, m0y, m0z, m1x, m1y, m1z, length, parent_attach_t = 0) {
+        const e = this.segment_count;
+        this.#ensure_segment_capacity(e + 1);
+        this.segment_count = e + 1;
+
+        this.attr_segment_endpoints.count = this.segment_count;
+        this.attr_segment_hermite_m0.count = this.segment_count;
+        this.attr_segment_hermite_m1.count = this.segment_count;
+        this.attr_segment_metrics.count = this.segment_count;
+
+        this.connect_nodes(v0, v1);
+
+        const endpoints = /** @type {Int32Array} */ (this.attr_segment_endpoints.data);
+        endpoints[e * 2] = v0;
+        endpoints[e * 2 + 1] = v1;
+
+        const m0 = /** @type {Float32Array} */ (this.attr_segment_hermite_m0.data);
+        const e3 = e * 3;
+        m0[e3] = m0x;
+        m0[e3 + 1] = m0y;
+        m0[e3 + 2] = m0z;
+
+        const m1 = /** @type {Float32Array} */ (this.attr_segment_hermite_m1.data);
+        m1[e3] = m1x;
+        m1[e3 + 1] = m1y;
+        m1[e3 + 2] = m1z;
+
+        const metrics = /** @type {Float32Array} */ (this.attr_segment_metrics.data);
+        metrics[e * 2] = length;
+        metrics[e * 2 + 1] = parent_attach_t;
+
+        // Record incoming Hermite segment on v1 if v1 belongs to the same branch or has no segment yet
+        const b_info = /** @type {Int32Array} */ (this.attr_node_branch_info.data);
+        if (b_info[v1 * 4 + 3] < 0 || b_info[v0 * 4] === b_info[v1 * 4]) {
+            b_info[v1 * 4 + 3] = e;
+        }
+
+        return e;
+    }
+
+    /**
+     * Reads node `v`'s 3D position from its {@link Transform64}.
+     *
+     * @param {number[]|Float32Array|Float64Array} out
+     * @param {number} out_offset
+     * @param {number} v
+     */
+    node_read_position(out, out_offset, v) {
+        const t64 = this.node_transforms[v];
+        out[out_offset] = t64[TRANSFORM64_TRANSLATION_OFFSET];
+        out[out_offset + 1] = t64[TRANSFORM64_TRANSLATION_OFFSET + 1];
+        out[out_offset + 2] = t64[TRANSFORM64_TRANSLATION_OFFSET + 2];
+    }
+
+    /**
+     * Writes node `v`'s 3D position into its {@link Transform64}.
+     *
+     * @param {number} v
+     * @param {number} px
+     * @param {number} py
+     * @param {number} pz
+     */
+    node_write_position(v, px, py, pz) {
+        this.node_transforms[v].setTranslation(px, py, pz);
+    }
+
+    /**
+     * Reads node `v`'s unit spine tangent $\mathbf{T}_v$ (local $+Z$ of its {@link Transform64}).
+     *
+     * @param {number[]|Float32Array|Float64Array} out
+     * @param {number} out_offset
+     * @param {number} v
+     */
+    node_read_tangent(out, out_offset, v) {
+        const t64 = this.node_transforms[v];
+        v3_quaternion_apply(
+            out, out_offset,
+            0, 0, 1,
+            t64[TRANSFORM64_ROTATION_OFFSET],
+            t64[TRANSFORM64_ROTATION_OFFSET + 1],
+            t64[TRANSFORM64_ROTATION_OFFSET + 2],
+            t64[TRANSFORM64_ROTATION_OFFSET + 3]
+        );
+    }
+
+    /**
+     * Reads node `v`'s unit RMF radial normal $\mathbf{R}_v$ (local $+X$ of its {@link Transform64}).
+     *
+     * @param {number[]|Float32Array|Float64Array} out
+     * @param {number} out_offset
+     * @param {number} v
+     */
+    node_read_frame_r(out, out_offset, v) {
+        const t64 = this.node_transforms[v];
+        v3_quaternion_apply(
+            out, out_offset,
+            1, 0, 0,
+            t64[TRANSFORM64_ROTATION_OFFSET],
+            t64[TRANSFORM64_ROTATION_OFFSET + 1],
+            t64[TRANSFORM64_ROTATION_OFFSET + 2],
+            t64[TRANSFORM64_ROTATION_OFFSET + 3]
+        );
+    }
+
+    /**
+     * Reads node `v`'s unit RMF binormal $\mathbf{S}_v = \mathbf{T}_v \times \mathbf{R}_v$ (local $+Y$ of its {@link Transform64}).
+     *
+     * @param {number[]|Float32Array|Float64Array} out
+     * @param {number} out_offset
+     * @param {number} v
+     */
+    node_read_frame_s(out, out_offset, v) {
+        const t64 = this.node_transforms[v];
+        v3_quaternion_apply(
+            out, out_offset,
+            0, 1, 0,
+            t64[TRANSFORM64_ROTATION_OFFSET],
+            t64[TRANSFORM64_ROTATION_OFFSET + 1],
+            t64[TRANSFORM64_ROTATION_OFFSET + 2],
+            t64[TRANSFORM64_ROTATION_OFFSET + 3]
+        );
+    }
+
+    /**
+     * Updates node `v`'s {@link Transform64} rotation from tangent $\mathbf{T}$ and radial vector $\mathbf{R}$.
+     *
+     * @param {number} v
+     * @param {number} tx
+     * @param {number} ty
+     * @param {number} tz
+     * @param {number} rx
+     * @param {number} ry
+     * @param {number} rz
+     */
+    node_write_frame(v, tx, ty, tz, rx, ry, rz) {
+        const t64 = this.node_transforms[v];
+        const sx = ty * rz - tz * ry;
+        const sy = tz * rx - tx * rz;
+        const sz = tx * ry - ty * rx;
+        t64_look_rotation(t64, tx, ty, tz, sx, sy, sz);
+        t64.updateMatrix();
+    }
+
+    /**
+     * Updates node `v`'s tangent $\mathbf{T}_v$ while orthogonalizing its existing radial vector $\mathbf{R}_v$.
+     *
+     * @param {number} v
+     * @param {number} tx
+     * @param {number} ty
+     * @param {number} tz
+     */
+    node_write_tangent(v, tx, ty, tz) {
+        this.node_read_frame_r(SCRATCH_VEC3, 0, v);
+        let rx = SCRATCH_VEC3[0];
+        let ry = SCRATCH_VEC3[1];
+        let rz = SCRATCH_VEC3[2];
+        const dot = rx * tx + ry * ty + rz * tz;
+        rx -= dot * tx;
+        ry -= dot * ty;
+        rz -= dot * tz;
+        const r_len = Math.sqrt(rx * rx + ry * ry + rz * rz);
+        if (r_len > 1e-8) {
+            rx /= r_len;
+            ry /= r_len;
+            rz /= r_len;
+        } else {
+            rx = Math.abs(ty) < 0.9 ? 0.0 : 1.0;
+            ry = Math.abs(ty) < 0.9 ? 1.0 : 0.0;
+            rz = 0.0;
+        }
+        this.node_write_frame(v, tx, ty, tz, rx, ry, rz);
+    }
+
+    /**
+     * Returns node `v`'s cross-sectional radius stored in its {@link Transform64} scale.
+     *
+     * @param {number} v
+     * @returns {number}
+     */
+    node_read_radius(v) {
+        return this.node_transforms[v][TRANSFORM64_SCALE_OFFSET];
+    }
+
+    /**
+     * Writes node `v`'s cross-sectional radius into its {@link Transform64} scale.
+     *
+     * @param {number} v
+     * @param {number} radius
+     */
+    node_write_radius(v, radius) {
+        const t64 = this.node_transforms[v];
+        t64.setScaleScalar(radius);
+        t64.updateMatrix();
+    }
+
+    /**
+     * @param {number} v
+     * @returns {number}
+     */
+    node_branch_id(v) {
+        return /** @type {Int32Array} */ (this.attr_node_branch_info.data)[v * 4];
+    }
+
+    /**
+     * @param {number} v
+     * @returns {number}
+     */
+    node_level(v) {
+        return /** @type {Int32Array} */ (this.attr_node_branch_info.data)[v * 4 + 1];
+    }
+
+    /**
+     * @param {number} v
+     * @returns {number}
+     */
+    node_parent_branch_id(v) {
+        return /** @type {Int32Array} */ (this.attr_node_branch_info.data)[v * 4 + 2];
+    }
+
+    /**
+     * @param {number} v
+     * @returns {number} incoming Hermite segment ID, or -1 if none
+     */
+    node_in_segment(v) {
+        return /** @type {Int32Array} */ (this.attr_node_branch_info.data)[v * 4 + 3];
+    }
+
+    /**
+     * Reads `[t_norm, arc_s, phase_hash]` for node `v`.
+     *
+     * @param {number[]|Float32Array} out
+     * @param {number} out_offset
+     * @param {number} v
+     */
+    node_read_spine_param(out, out_offset, v) {
+        const data = /** @type {Float32Array} */ (this.attr_node_spine_param.data);
+        const off = v * 3;
+        out[out_offset] = data[off];
+        out[out_offset + 1] = data[off + 1];
+        out[out_offset + 2] = data[off + 2];
+    }
+
+    /**
+     * @param {number} v
+     * @returns {number}
+     */
+    node_t_norm(v) {
+        return /** @type {Float32Array} */ (this.attr_node_spine_param.data)[v * 3];
+    }
+
+    /**
+     * @param {number} v
+     * @returns {number}
+     */
+    node_arc_s(v) {
+        return /** @type {Float32Array} */ (this.attr_node_spine_param.data)[v * 3 + 1];
+    }
+
+    /**
+     * @param {number} v
+     * @returns {number}
+     */
+    node_phase_hash(v) {
+        return /** @type {Float32Array} */ (this.attr_node_spine_param.data)[v * 3 + 2];
+    }
+
+    /**
+     * @param {number} v
+     * @param {number} component 0 for primary joint, 1 for parent joint
+     * @returns {number}
+     */
+    node_read_joint(v, component) {
+        return /** @type {Uint16Array} */ (this.attr_node_joint.data)[v * 2 + component];
+    }
+
+    /**
+     * @param {number} v
+     * @param {number} primary_joint
+     * @param {number} parent_joint
+     */
+    node_write_joint(v, primary_joint, parent_joint) {
+        const data = /** @type {Uint16Array} */ (this.attr_node_joint.data);
+        const off = v * 2;
+        data[off] = primary_joint;
+        data[off + 1] = parent_joint;
+    }
+
+    /**
+     * Queries `this.graph` for the parent node of `v` along its incoming directed edge (`EdgeDirectionType.Forward`).
+     * Returns `-1` if `v` is a root node.
+     *
+     * @param {number} v
+     * @returns {number}
+     */
+    node_parent_vertex(v) {
+        const container = this.graph.getNodeContainer(v);
+        if (container === undefined) {
+            return -1;
+        }
+        const edges = container.getEdges();
+        for (let i = 0; i < edges.length; i++) {
+            const edge = edges[i];
+            if (edge.isDirectedTowards(v)) {
+                return edge.other(v);
+            }
+        }
+        return -1;
+    }
+
+    /**
+     * @param {number} edge_id
+     * @returns {number}
+     */
+    segment_v0(edge_id) {
+        return /** @type {Int32Array} */ (this.attr_segment_endpoints.data)[edge_id * 2];
+    }
+
+    /**
+     * @param {number} edge_id
+     * @returns {number}
+     */
+    segment_v1(edge_id) {
+        return /** @type {Int32Array} */ (this.attr_segment_endpoints.data)[edge_id * 2 + 1];
+    }
+
+    /**
+     * @param {number} edge_id
+     * @returns {number}
+     */
+    segment_length(edge_id) {
+        return /** @type {Float32Array} */ (this.attr_segment_metrics.data)[edge_id * 2];
+    }
+
+    /**
+     * @param {number} edge_id
+     * @returns {number}
+     */
+    segment_parent_attach_t(edge_id) {
+        return /** @type {Float32Array} */ (this.attr_segment_metrics.data)[edge_id * 2 + 1];
+    }
+
+    /**
+     * @param {number[]|Float32Array} out
+     * @param {number} out_offset
+     * @param {number} edge_id
+     */
+    segment_read_m0(out, out_offset, edge_id) {
+        const m0 = /** @type {Float32Array} */ (this.attr_segment_hermite_m0.data);
+        const off = edge_id * 3;
+        out[out_offset] = m0[off];
+        out[out_offset + 1] = m0[off + 1];
+        out[out_offset + 2] = m0[off + 2];
+    }
+
+    /**
+     * @param {number} edge_id
+     * @param {number} mx
+     * @param {number} my
+     * @param {number} mz
+     */
+    segment_write_m0(edge_id, mx, my, mz) {
+        const m0 = /** @type {Float32Array} */ (this.attr_segment_hermite_m0.data);
+        const off = edge_id * 3;
+        m0[off] = mx;
+        m0[off + 1] = my;
+        m0[off + 2] = mz;
+    }
+
+    /**
+     * @param {number[]|Float32Array} out
+     * @param {number} out_offset
+     * @param {number} edge_id
+     */
+    segment_read_m1(out, out_offset, edge_id) {
+        const m1 = /** @type {Float32Array} */ (this.attr_segment_hermite_m1.data);
+        const off = edge_id * 3;
+        out[out_offset] = m1[off];
+        out[out_offset + 1] = m1[off + 1];
+        out[out_offset + 2] = m1[off + 2];
+    }
+
+    /**
+     * @param {number} edge_id
+     * @param {number} mx
+     * @param {number} my
+     * @param {number} mz
+     */
+    segment_write_m1(edge_id, mx, my, mz) {
+        const m1 = /** @type {Float32Array} */ (this.attr_segment_hermite_m1.data);
+        const off = edge_id * 3;
+        m1[off] = mx;
+        m1[off + 1] = my;
+        m1[off + 2] = mz;
+    }
+
+    /**
+     * Evaluates the 3D position along Cubic Hermite segment `edge_id` at parameter `u` in `[0, 1]`.
+     *
+     * @param {number[]|Float32Array} out
+     * @param {number} out_offset
+     * @param {number} edge_id
+     * @param {number} u
+     */
+    evaluate_segment_position(out, out_offset, edge_id, u) {
+        const endpoints = /** @type {Int32Array} */ (this.attr_segment_endpoints.data);
+        const v0 = endpoints[edge_id * 2];
+        const v1 = endpoints[edge_id * 2 + 1];
+
+        const t0 = this.node_transforms[v0];
+        const t1 = this.node_transforms[v1];
+        const m0 = /** @type {Float32Array} */ (this.attr_segment_hermite_m0.data);
+        const m1 = /** @type {Float32Array} */ (this.attr_segment_hermite_m1.data);
+        const e3 = edge_id * 3;
+
+        out[out_offset] = spline3_hermite(
+            u,
+            t0[TRANSFORM64_TRANSLATION_OFFSET],
+            t1[TRANSFORM64_TRANSLATION_OFFSET],
+            m0[e3],
+            m1[e3]
+        );
+        out[out_offset + 1] = spline3_hermite(
+            u,
+            t0[TRANSFORM64_TRANSLATION_OFFSET + 1],
+            t1[TRANSFORM64_TRANSLATION_OFFSET + 1],
+            m0[e3 + 1],
+            m1[e3 + 1]
+        );
+        out[out_offset + 2] = spline3_hermite(
+            u,
+            t0[TRANSFORM64_TRANSLATION_OFFSET + 2],
+            t1[TRANSFORM64_TRANSLATION_OFFSET + 2],
+            m0[e3 + 2],
+            m1[e3 + 2]
+        );
+    }
+
+    /**
+     * Evaluates the unnormalized 3D derivative along Cubic Hermite segment `edge_id` at parameter `u` in `[0, 1]`.
+     *
+     * @param {number[]|Float32Array} out
+     * @param {number} out_offset
+     * @param {number} edge_id
+     * @param {number} u
+     */
+    evaluate_segment_derivative(out, out_offset, edge_id, u) {
+        const endpoints = /** @type {Int32Array} */ (this.attr_segment_endpoints.data);
+        const v0 = endpoints[edge_id * 2];
+        const v1 = endpoints[edge_id * 2 + 1];
+
+        const t0 = this.node_transforms[v0];
+        const t1 = this.node_transforms[v1];
+        const m0 = /** @type {Float32Array} */ (this.attr_segment_hermite_m0.data);
+        const m1 = /** @type {Float32Array} */ (this.attr_segment_hermite_m1.data);
+        const e3 = edge_id * 3;
+
+        out[out_offset] = spline3_hermite_derivative(
+            u,
+            t0[TRANSFORM64_TRANSLATION_OFFSET],
+            t1[TRANSFORM64_TRANSLATION_OFFSET],
+            m0[e3],
+            m1[e3]
+        );
+        out[out_offset + 1] = spline3_hermite_derivative(
+            u,
+            t0[TRANSFORM64_TRANSLATION_OFFSET + 1],
+            t1[TRANSFORM64_TRANSLATION_OFFSET + 1],
+            m0[e3 + 1],
+            m1[e3 + 1]
+        );
+        out[out_offset + 2] = spline3_hermite_derivative(
+            u,
+            t0[TRANSFORM64_TRANSLATION_OFFSET + 2],
+            t1[TRANSFORM64_TRANSLATION_OFFSET + 2],
+            m0[e3 + 2],
+            m1[e3 + 2]
+        );
+    }
+
+    /**
+     * Evaluates the unit 3D tangent vector along Cubic Hermite segment `edge_id` at parameter `u` in `[0, 1]`.
+     *
+     * @param {number[]|Float32Array} out
+     * @param {number} out_offset
+     * @param {number} edge_id
+     * @param {number} u
+     */
+    evaluate_segment_tangent(out, out_offset, edge_id, u) {
+        this.evaluate_segment_derivative(out, out_offset, edge_id, u);
+        const dx = out[out_offset];
+        const dy = out[out_offset + 1];
+        const dz = out[out_offset + 2];
+        const len_sq = dx * dx + dy * dy + dz * dz;
+        if (len_sq > 1e-12) {
+            const inv_len = 1.0 / Math.sqrt(len_sq);
+            out[out_offset] = dx * inv_len;
+            out[out_offset + 1] = dy * inv_len;
+            out[out_offset + 2] = dz * inv_len;
+        } else {
+            const v0 = this.segment_v0(edge_id);
+            this.node_read_tangent(out, out_offset, v0);
+        }
+    }
+
+    /**
+     * Collects the ordered node IDs and Hermite segment IDs along branch `branch_id` by traversing
+     * outgoing edges of `this.graph` that belong to `branch_id`.
+     *
+     * @param {number} branch_id
+     * @param {number[]} out_nodes
+     * @param {number[]} out_segments
+     */
+    collect_branch_chain(branch_id, out_nodes, out_segments) {
+        out_nodes.length = 0;
+        out_segments.length = 0;
+        if (branch_id < 0 || branch_id >= this.branch_count) {
+            return;
+        }
+        const root_v = this.branch_root_vertex[branch_id];
+        if (root_v < 0 || root_v >= this.node_count) {
+            return;
+        }
+        out_nodes.push(root_v);
+
+        let cur_v = root_v;
+        while (true) {
+            const container = this.graph.getNodeContainer(cur_v);
+            if (container === undefined) {
+                break;
+            }
+            const edges = container.getEdges();
+            let next_v = -1;
+            for (let i = 0; i < edges.length; i++) {
+                const edge = edges[i];
+                if (edge.isDirectedAwayFrom(cur_v)) {
+                    const cand_v = edge.other(cur_v);
+                    if (this.node_branch_id(cand_v) === branch_id) {
+                        next_v = cand_v;
+                        break;
+                    }
+                }
+            }
+            if (next_v < 0) {
+                break;
+            }
+            const seg_id = this.node_in_segment(next_v);
+            if (seg_id < 0) {
+                break;
+            }
+            out_nodes.push(next_v);
+            out_segments.push(seg_id);
+            cur_v = next_v;
+        }
+    }
+
+    /**
+     * Deep copies another `TreeSkeleton` into this instance (`Graph`, `Transform64[]`, and `Attribute`s).
+     *
+     * @param {TreeSkeleton} other
+     * @returns {this}
+     */
+    copy(other) {
+        assert.defined(other, 'other');
+        if (this === other) {
+            return this;
+        }
+
+        this.clear();
+
+        this.#ensure_node_capacity(other.node_count);
+        this.#ensure_segment_capacity(other.segment_count);
+        this.#ensure_branch_capacity(other.branch_count);
+
+        this.node_count = other.node_count;
+        this.segment_count = other.segment_count;
+        this.branch_count = other.branch_count;
+
+        for (let v = 0; v < other.node_count; v++) {
+            this.graph.addNode(v);
+            let t64 = this.node_transforms[v];
+            if (t64 === undefined) {
+                t64 = new Transform64();
+                this.node_transforms[v] = t64;
+            }
+            t64.copy(other.node_transforms[v]);
+        }
+
+        other.graph.traverseEdges((edge) => {
+            this.graph.createEdge(edge.first, edge.second, edge.direction);
+        });
+
+        this.attr_node_branch_info.copy(other.attr_node_branch_info);
+        this.attr_node_spine_param.copy(other.attr_node_spine_param);
+        this.attr_node_joint.copy(other.attr_node_joint);
+        this.#node_capacity = this.attr_node_branch_info.data.length / 4;
+
+        this.attr_segment_endpoints.copy(other.attr_segment_endpoints);
+        this.attr_segment_hermite_m0.copy(other.attr_segment_hermite_m0);
+        this.attr_segment_hermite_m1.copy(other.attr_segment_hermite_m1);
+        this.attr_segment_metrics.copy(other.attr_segment_metrics);
+        this.#segment_capacity = this.attr_segment_endpoints.data.length / 2;
+
+        for (let i = 0; i < other.branch_count; i++) {
+            this.branch_root_vertex[i] = other.branch_root_vertex[i];
+            this.branch_tip_vertex[i] = other.branch_tip_vertex[i];
+            this.branch_level[i] = other.branch_level[i];
+            this.branch_parent[i] = other.branch_parent[i];
+            this.branch_parent_edge[i] = other.branch_parent_edge[i];
+            this.branch_parent_attach_t[i] = other.branch_parent_attach_t[i];
+            this.branch_length[i] = other.branch_length[i];
+            this.branch_base_radius[i] = other.branch_base_radius[i];
+            this.branch_phase_hash[i] = other.branch_phase_hash[i];
+        }
+
+        this.crown_center.set(other.crown_center);
+        this.crown_radii.set(other.crown_radii);
+
+        return this;
+    }
+
+    /**
+     * @returns {TreeSkeleton}
+     */
+    clone() {
+        const r = new TreeSkeleton();
+        r.copy(this);
+        return r;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+TreeSkeleton.prototype.isTreeSkeleton = true;