@woosh/meep-engine 3.16.0 → 3.17.1

package/src/shade/renderer/particles/graph/groups/particle_groups_geometry.js

@@ -1,319 +1,294 @@
-import { ParticleGroupBuilder } from "../ParticleGroupBuilder.js";
-import {
-    PARTICLE_TYPE_F32,
-    PARTICLE_TYPE_VEC2,
-    PARTICLE_TYPE_VEC3,
-    PARTICLE_TYPE_VEC4,
-} from "../ParticleValueType.js";
-
-/**
- * Directions, angles and rotations: the groups an effect needs the moment it stops firing particles
- * straight up.
- *
- * ## What the VM has not got
- *
- * No inverse trigonometry. `acos` is the one this file needs, and what it uses instead is the
- * polynomial everybody uses — see {@link acos_approx}. No division-free reciprocal either, so where
- * a divisor could be zero the argument is floored to a tiny positive number rather than left to
- * produce an infinity: an `Inf` written into a particle's position takes the particle out of the
- * world, and one written into a quaternion takes it out of every frame after that too.
- */
-
-/** Turns, in radians. @type {number} */
-const TAU = Math.PI * 2;
-
-/**
- * Smallest value a divisor is allowed to be. Chosen to be far below anything a rotation produces and
- * far above the point where its reciprocal stops being finite.
- * @type {number}
- */
-const DIVISOR_FLOOR = 1e-8;
-
-/**
- * `acos`, to about five decimal places, in seven instructions.
- *
- * The VM has sin, cos and the algebra, and no inverse trigonometry at all — adding an opcode for
- * this would cost every effect the instruction-decode switch grows by, for a function two nodes in
- * the library want. This is the standard minimax polynomial for `acos` on `[0, 1]`, reflected for
- * negative inputs: `sqrt(1 - x)` times a cubic, plus `pi` on the negative half.
- *
- * Worst-case error is under 7e-5 radians, which is a hundredth of a degree — well inside what a
- * particle effect can see, and the reason no exact version is worth the opcode.
- *
- * @param {ParticleGroupBuilder} g
- * @param {{node: NodeInstance, port: Port}} x the cosine, expected in `[-1, 1]`
- * @returns {{node: NodeInstance, port: Port}} the angle, in radians
- */
-function acos_approx(g, x) {
-    const negative = g.op("compare", [x, 0], { op: "lt" });
-    const magnitude = g.abs(x);
-
-    let r = g.mad(g.f(-0.0187293), magnitude, 0.0742610);
-
-    r = g.mad(r, magnitude, -0.2121144);
-    r = g.mad(r, magnitude, 1.5707288);
-    r = g.mul(r, g.sqrt(g.max(g.sub(1, magnitude), 0)));
-
-    // reflect: acos(-t) = pi - acos(t)
-    r = g.sub(r, g.mul(g.mul(2, negative), r));
-
-    return g.mad(negative, g.f(Math.PI), r);
-}
-
-/**
- * A point on the unit sphere, from two numbers in `[0, 1)`.
- *
- * Uniform over the surface, which is what the `z` lane being taken straight from `u` buys: the area
- * of a band of the sphere between two heights depends only on the heights, so spreading `z` evenly
- * spreads the points evenly. Taking a latitude evenly instead — the obvious thing, and the wrong one
- * — piles them up at the poles.
- *
- * Feed it a two-lane `random` and it is an unbiased direction.
- *
- * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
- */
-export const PARTICLE_GROUP_SAMPLE_SPHERE_SURFACE = (() => {
-    const g = new ParticleGroupBuilder({
-        name: "sampleSphereSurface",
-        label: "Sample Sphere Surface",
-        icon: "M12 3a9 9 0 1 0 0 18a9 9 0 1 0 0-18 M3 12h18 M12 3c4 4 4 14 0 18 M12 3c-4 4-4 14 0 18",
-        help: "uv in [0,1) to a point on the unit sphere, uniformly",
-        inputs: [{ name: "uv", type: PARTICLE_TYPE_VEC2 }],
-        outputs: [{ name: "out", type: PARTICLE_TYPE_VEC3 }],
-    });
-
-    const z = g.mad(g.x(g.in.uv), 2, -1);
-
-    // the radius of the circle at that height; the max guards the rounding at the poles
-    const radius = g.sqrt(g.max(g.sub(1, g.mul(z, z)), 0));
-
-    const phi = g.mul(g.y(g.in.uv), g.f(TAU));
-
-    g.out("out", g.vec3(g.mul(radius, g.cos(phi)), g.mul(radius, g.sin(phi)), z));
-
-    return g.build();
-})();
-
-/**
- * A point inside the unit ball, from three numbers in `[0, 1)`.
- *
- * A direction from the first two and a radius from the third — and the radius is the cube root of it,
- * because the volume inside a radius grows as its cube. Using the number itself would put half the
- * points inside the half-radius sphere, which holds an eighth of the volume, and every effect built
- * on it would have a bright core it never asked for.
- *
- * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
- */
-export const PARTICLE_GROUP_SAMPLE_SPHERE_VOLUME = (() => {
-    const g = new ParticleGroupBuilder({
-        name: "sampleSphereVolume",
-        label: "Sample Sphere Volume",
-        icon: "M12 3a9 9 0 1 0 0 18a9 9 0 1 0 0-18 M12 12l5-3 M8 14l1.5-1",
-        help: "uvw in [0,1) to a point inside the unit sphere, uniformly",
-        inputs: [{ name: "uvw", type: PARTICLE_TYPE_VEC3 }],
-        outputs: [{ name: "out", type: PARTICLE_TYPE_VEC3 }],
-    });
-
-    const direction = g.call(PARTICLE_GROUP_SAMPLE_SPHERE_SURFACE, { uv: g.swz(g.in.uvw, "xy") });
-
-    const radius = g.pow(g.z(g.in.uvw), g.f(1 / 3));
-
-    g.out("out", g.scale(direction.out, radius));
-
-    return g.build();
-})();
-
-/**
- * The angle between two directions, in radians, in `[0, pi]`.
- *
- * `acos` of the cosine, and the cosine is the dot product of the two normalised. The clamp is not
- * decoration: a dot product of two unit vectors is arithmetically in `[-1, 1]` and in floating point
- * is occasionally a hair outside it, which is exactly where `acos` stops being defined.
- *
- * Two of them, one per shape, because there is no honest way to do this at "whatever width arrives"
- * — the answer for two lanes and the answer for three are different questions about different
- * things, and a node that took either would be a node whose result depended on what was plugged in.
- *
- * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup[]}
- */
-export const PARTICLE_GROUP_ANGLE_BETWEEN = [PARTICLE_TYPE_VEC2, PARTICLE_TYPE_VEC3].map(type => {
-    const g = new ParticleGroupBuilder({
-        name: `angleBetween${type.components}`,
-        label: `Angle Between (${type.name})`,
-        icon: "M5 19h14 M5 19L17 7 M11 19a8 8 0 0 0 2.5-5.6",
-        help: `the angle in radians between two ${type.name} directions`,
-        inputs: [{ name: "a", type }, { name: "b", type }],
-        outputs: [{ name: "radians", type: PARTICLE_TYPE_F32 }],
-    });
-
-    const cosine = g.clamp(g.dot(g.normalize(g.in.a), g.normalize(g.in.b)), -1, 1);
-
-    g.out("radians", acos_approx(g, cosine));
-
-    return g.build();
-});
-
-/**
- * A quaternion for a rotation of `angle` radians about `axis`.
- *
- * `(axis * sin(angle/2), cos(angle/2))`, with the axis normalised first so the result is a unit
- * quaternion whatever length the axis arrived at. A zero axis normalises to zero, which gives the
- * quaternion `(0, 0, 0, cos(angle/2))` — not a rotation, and not a crash either.
- *
- * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
- */
-export const PARTICLE_GROUP_QUAT_FROM_AXIS_ANGLE = (() => {
-    const g = new ParticleGroupBuilder({
-        name: "quatFromAxisAngle",
-        label: "Quaternion From Axis Angle",
-        icon: "M12 4v16 M6 14a8 8 0 0 0 12 0 M4 9l2 5 2-5",
-        help: "a rotation about an axis, as a quaternion",
-        inputs: [
-            { name: "axis", type: PARTICLE_TYPE_VEC3 },
-            { name: "angle", type: PARTICLE_TYPE_F32 },
-        ],
-        outputs: [{ name: "quat", type: PARTICLE_TYPE_VEC4 }],
-    });
-
-    const half = g.mul(g.in.angle, 0.5);
-
-    const vector = g.scale(g.normalize(g.in.axis), g.sin(half));
-
-    g.out("quat", g.vec4(g.x(vector), g.y(vector), g.z(vector), g.cos(half)));
-
-    return g.build();
-})();
-
-/**
- * Turn a vector by a quaternion.
- *
- * `v + 2w(q x v) + 2(q x (q x v))`, written the way it is usually written: one cross product, one
- * scale, one more cross product. Two cross products beat building a rotation matrix, and there is
- * no matrix type here to build one into anyway.
- *
- * The quaternion is expected to be a unit one. A longer one scales the result by the square of its
- * length, which is the identity behaving as it always has rather than anything this checks.
- *
- * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
- */
-export const PARTICLE_GROUP_QUAT_ROTATE = (() => {
-    const g = new ParticleGroupBuilder({
-        name: "quatRotate",
-        label: "Rotate By Quaternion",
-        icon: "M5 12a7 7 0 1 1 3 5.8 M5 8v4h4 M12 12l5-2",
-        help: "a vector turned by a quaternion",
-        inputs: [
-            { name: "quat", type: PARTICLE_TYPE_VEC4 },
-            { name: "v", type: PARTICLE_TYPE_VEC3 },
-        ],
-        outputs: [{ name: "out", type: PARTICLE_TYPE_VEC3 }],
-    });
-
-    const axis = g.swz(g.in.quat, "xyz");
-    const w = g.w(g.in.quat);
-
-    const t = g.scale(g.cross(axis, g.in.v), 2);
-
-    g.out("out", g.add(g.add(g.in.v, g.scale(t, w)), g.cross(axis, t)));
-
-    return g.build();
-})();
-
-/**
- * The rotation that points `forward` along +Z with `up` as near to +Y as it can be.
- *
- * The basis is built first — forward, then a right that is perpendicular to both, then the up that
- * completes it — and then read off as a quaternion by Shepperd's method: four expressions, one per
- * component of the quaternion being the largest, and the largest is picked because the other three
- * divide by something near zero.
- *
- * There are no branches, so all four are computed and one is chosen. That is what a VM with no
- * control flow costs, and the choice is a pair of comparisons rather than a jump. Each divisor is
- * floored at {@link DIVISOR_FLOOR} first, so the three expressions that are *not* chosen produce a
- * finite number rather than an infinity — the selection reads registers rather than blending them,
- * but a program that computes infinities is one bad edit away from writing one out.
- *
- * Degenerate input — `forward` and `up` parallel, or either of them zero — leaves the basis without a
- * right vector, and what comes back is finite and arbitrary. Feeding this an `up` that could line up
- * with `forward` is the caller's to avoid, exactly as it is in every engine that offers this.
- *
- * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
- */
-export const PARTICLE_GROUP_QUAT_LOOK_ROTATION = (() => {
-    const g = new ParticleGroupBuilder({
-        name: "quatLookRotation",
-        label: "Quaternion Look Rotation",
-        icon: "M12 12l7-4 M12 12v-8 M12 12L5 9 M12 12l3 8",
-        help: "the rotation that looks along forward, with up upright",
-        inputs: [
-            { name: "forward", type: PARTICLE_TYPE_VEC3 },
-            { name: "up", type: PARTICLE_TYPE_VEC3 },
-        ],
-        outputs: [{ name: "quat", type: PARTICLE_TYPE_VEC4 }],
-    });
-
-    const f = g.normalize(g.in.forward);
-    const r = g.normalize(g.cross(g.in.up, f));
-    const u = g.cross(f, r);
-
-    // The rotation matrix, by column: r, u, f. `m(row, column)`.
-    const lane = ["x", "y", "z"];
-    const column = [r, u, f];
-
-    const m = (row, col) => g.swz(column[col], lane[row]);
-
-    const m00 = m(0, 0), m01 = m(0, 1), m02 = m(0, 2);
-    const m10 = m(1, 0), m11 = m(1, 1), m12 = m(1, 2);
-    const m20 = m(2, 0), m21 = m(2, 1), m22 = m(2, 2);
-
-    const trace = g.add(g.add(m00, m11), m22);
-
-    /**
-     * One of the four expressions: `magnitude` is four times the square of the component this case
-     * is the largest of, and `parts` are the other three numerators in `x, y, z, w` order with that
-     * component's slot left for `magnitude` itself.
-     *
-     * @param {*} magnitude
-     * @param {function(*): Array} parts
-     * @returns {*} the quaternion for this case
-     */
-    const candidate = (magnitude, parts) => {
-        const safe = g.max(magnitude, g.f(DIVISOR_FLOOR));
-
-        // s = 2*sqrt(safe) is the classical scale; the component this case is largest of is
-        // 0.25*s, which is safe/s, so every lane of the vector below is a numerator over s.
-        const s = g.mul(g.sqrt(safe), 2);
-
-        return g.mul(g.vec4(...parts(safe)), g.div(1, s));
-    };
-
-    const q_trace = candidate(g.add(trace, 1), safe => [
-        g.sub(m21, m12), g.sub(m02, m20), g.sub(m10, m01), safe,
-    ]);
-
-    const q_x = candidate(g.sub(g.sub(g.add(1, m00), m11), m22), safe => [
-        safe, g.add(m01, m10), g.add(m02, m20), g.sub(m21, m12),
-    ]);
-
-    const q_y = candidate(g.sub(g.sub(g.add(1, m11), m00), m22), safe => [
-        g.add(m01, m10), safe, g.add(m12, m21), g.sub(m02, m20),
-    ]);
-
-    const q_z = candidate(g.sub(g.sub(g.add(1, m22), m00), m11), safe => [
-        g.add(m02, m20), g.add(m12, m21), safe, g.sub(m10, m01),
-    ]);
-
-    // Largest wins, checked from the bottom up: y over z, then x over both, then the trace over all.
-    const yz = g.select(q_z, q_y, g.op("compare", [m11, m22], { op: "ge" }));
-
-    const x_largest = g.mul(
-        g.op("compare", [m00, m11], { op: "ge" }),
-        g.op("compare", [m00, m22], { op: "ge" })
-    );
-
-    const xyz = g.select(yz, q_x, x_largest);
-
-    g.out("quat", g.select(xyz, q_trace, g.op("compare", [trace, 0], { op: "gt" })));
-
-    return g.build();
-})();
+import { ParticleGroupBuilder } from "../ParticleGroupBuilder.js";
+import {
+    PARTICLE_TYPE_F32,
+    PARTICLE_TYPE_VEC2,
+    PARTICLE_TYPE_VEC3,
+    PARTICLE_TYPE_VEC4,
+} from "../ParticleValueType.js";
+
+/**
+ * Directions, angles and rotations: the groups an effect needs the moment it stops firing particles
+ * straight up.
+ *
+ * ## Dividing by something that might be zero
+ *
+ * The VM has no guard for it, so where a divisor could be zero the argument is floored to a tiny
+ * positive number rather than left to produce an infinity: an `Inf` written into a particle's
+ * position takes the particle out of the world, and one written into a quaternion takes it out of
+ * every frame after that too.
+ *
+ * ## `acos` is an opcode now
+ *
+ * This file used to carry it as a seven-instruction minimax polynomial, good to 7e-5 radians,
+ * because the VM had no inverse trigonometry and the comment here argued that an opcode was not
+ * worth what the decode switch would grow by. The ISA has `ACOS`, so the group calls it, and the
+ * two `angleBetween` groups cost 10 instructions rather than 31.
+ */
+
+/** Turns, in radians. @type {number} */
+const TAU = Math.PI * 2;
+
+/**
+ * Smallest value a divisor is allowed to be. Chosen to be far below anything a rotation produces and
+ * far above the point where its reciprocal stops being finite.
+ * @type {number}
+ */
+const DIVISOR_FLOOR = 1e-8;
+
+/**
+ * A point on the unit sphere, from two numbers in `[0, 1)`.
+ *
+ * Uniform over the surface, which is what the `z` lane being taken straight from `u` buys: the area
+ * of a band of the sphere between two heights depends only on the heights, so spreading `z` evenly
+ * spreads the points evenly. Taking a latitude evenly instead — the obvious thing, and the wrong one
+ * — piles them up at the poles.
+ *
+ * Feed it a two-lane `random` and it is an unbiased direction.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_SAMPLE_SPHERE_SURFACE = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "sampleSphereSurface",
+        label: "Sample Sphere Surface",
+        icon: "M12 3a9 9 0 1 0 0 18a9 9 0 1 0 0-18 M3 12h18 M12 3c4 4 4 14 0 18 M12 3c-4 4-4 14 0 18",
+        help: "uv in [0,1) to a point on the unit sphere, uniformly",
+        inputs: [{ name: "uv", type: PARTICLE_TYPE_VEC2 }],
+        outputs: [{ name: "out", type: PARTICLE_TYPE_VEC3 }],
+    });
+
+    const z = g.mad(g.x(g.in.uv), 2, -1);
+
+    // the radius of the circle at that height; the max guards the rounding at the poles
+    const radius = g.sqrt(g.max(g.sub(1, g.mul(z, z)), 0));
+
+    const phi = g.mul(g.y(g.in.uv), g.f(TAU));
+
+    g.out("out", g.vec3(g.mul(radius, g.cos(phi)), g.mul(radius, g.sin(phi)), z));
+
+    return g.build();
+})();
+
+/**
+ * A point inside the unit ball, from three numbers in `[0, 1)`.
+ *
+ * A direction from the first two and a radius from the third — and the radius is the cube root of it,
+ * because the volume inside a radius grows as its cube. Using the number itself would put half the
+ * points inside the half-radius sphere, which holds an eighth of the volume, and every effect built
+ * on it would have a bright core it never asked for.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_SAMPLE_SPHERE_VOLUME = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "sampleSphereVolume",
+        label: "Sample Sphere Volume",
+        icon: "M12 3a9 9 0 1 0 0 18a9 9 0 1 0 0-18 M12 12l5-3 M8 14l1.5-1",
+        help: "uvw in [0,1) to a point inside the unit sphere, uniformly",
+        inputs: [{ name: "uvw", type: PARTICLE_TYPE_VEC3 }],
+        outputs: [{ name: "out", type: PARTICLE_TYPE_VEC3 }],
+    });
+
+    const direction = g.call(PARTICLE_GROUP_SAMPLE_SPHERE_SURFACE, { uv: g.swz(g.in.uvw, "xy") });
+
+    const radius = g.pow(g.z(g.in.uvw), g.f(1 / 3));
+
+    g.out("out", g.scale(direction.out, radius));
+
+    return g.build();
+})();
+
+/**
+ * The angle between two directions, in radians, in `[0, pi]`.
+ *
+ * `acos` of the cosine, and the cosine is the dot product of the two normalised. The clamp is not
+ * decoration: a dot product of two unit vectors is arithmetically in `[-1, 1]` and in floating point
+ * is occasionally a hair outside it, which is exactly where `acos` stops being defined.
+ *
+ * Two of them, one per shape, because there is no honest way to do this at "whatever width arrives"
+ * — the answer for two lanes and the answer for three are different questions about different
+ * things, and a node that took either would be a node whose result depended on what was plugged in.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup[]}
+ */
+export const PARTICLE_GROUP_ANGLE_BETWEEN = [PARTICLE_TYPE_VEC2, PARTICLE_TYPE_VEC3].map(type => {
+    const g = new ParticleGroupBuilder({
+        name: `angleBetween${type.components}`,
+        label: `Angle Between (${type.name})`,
+        icon: "M5 19h14 M5 19L17 7 M11 19a8 8 0 0 0 2.5-5.6",
+        help: `the angle in radians between two ${type.name} directions`,
+        inputs: [{ name: "a", type }, { name: "b", type }],
+        outputs: [{ name: "radians", type: PARTICLE_TYPE_F32 }],
+    });
+
+    const cosine = g.clamp(g.dot(g.normalize(g.in.a), g.normalize(g.in.b)), -1, 1);
+
+    g.out("radians", g.acos(cosine));
+
+    return g.build();
+});
+
+/**
+ * A quaternion for a rotation of `angle` radians about `axis`.
+ *
+ * `(axis * sin(angle/2), cos(angle/2))`, with the axis normalised first so the result is a unit
+ * quaternion whatever length the axis arrived at. A zero axis normalises to zero, which gives the
+ * quaternion `(0, 0, 0, cos(angle/2))` — not a rotation, and not a crash either.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_QUAT_FROM_AXIS_ANGLE = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "quatFromAxisAngle",
+        label: "Quaternion From Axis Angle",
+        icon: "M12 4v16 M6 14a8 8 0 0 0 12 0 M4 9l2 5 2-5",
+        help: "a rotation about an axis, as a quaternion",
+        inputs: [
+            { name: "axis", type: PARTICLE_TYPE_VEC3 },
+            { name: "angle", type: PARTICLE_TYPE_F32 },
+        ],
+        outputs: [{ name: "quat", type: PARTICLE_TYPE_VEC4 }],
+    });
+
+    const half = g.mul(g.in.angle, 0.5);
+
+    const vector = g.scale(g.normalize(g.in.axis), g.sin(half));
+
+    g.out("quat", g.vec4(g.x(vector), g.y(vector), g.z(vector), g.cos(half)));
+
+    return g.build();
+})();
+
+/**
+ * Turn a vector by a quaternion.
+ *
+ * `v + 2w(q x v) + 2(q x (q x v))`, written the way it is usually written: one cross product, one
+ * scale, one more cross product. Two cross products beat building a rotation matrix, and there is
+ * no matrix type here to build one into anyway.
+ *
+ * The quaternion is expected to be a unit one. A longer one scales the result by the square of its
+ * length, which is the identity behaving as it always has rather than anything this checks.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_QUAT_ROTATE = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "quatRotate",
+        label: "Rotate By Quaternion",
+        icon: "M5 12a7 7 0 1 1 3 5.8 M5 8v4h4 M12 12l5-2",
+        help: "a vector turned by a quaternion",
+        inputs: [
+            { name: "quat", type: PARTICLE_TYPE_VEC4 },
+            { name: "v", type: PARTICLE_TYPE_VEC3 },
+        ],
+        outputs: [{ name: "out", type: PARTICLE_TYPE_VEC3 }],
+    });
+
+    const axis = g.swz(g.in.quat, "xyz");
+    const w = g.w(g.in.quat);
+
+    const t = g.scale(g.cross(axis, g.in.v), 2);
+
+    g.out("out", g.add(g.add(g.in.v, g.scale(t, w)), g.cross(axis, t)));
+
+    return g.build();
+})();
+
+/**
+ * The rotation that points `forward` along +Z with `up` as near to +Y as it can be.
+ *
+ * The basis is built first — forward, then a right that is perpendicular to both, then the up that
+ * completes it — and then read off as a quaternion by Shepperd's method: four expressions, one per
+ * component of the quaternion being the largest, and the largest is picked because the other three
+ * divide by something near zero.
+ *
+ * There are no branches, so all four are computed and one is chosen. That is what a VM with no
+ * control flow costs, and the choice is a pair of comparisons rather than a jump. Each divisor is
+ * floored at {@link DIVISOR_FLOOR} first, so the three expressions that are *not* chosen produce a
+ * finite number rather than an infinity — the selection reads registers rather than blending them,
+ * but a program that computes infinities is one bad edit away from writing one out.
+ *
+ * Degenerate input — `forward` and `up` parallel, or either of them zero — leaves the basis without a
+ * right vector, and what comes back is finite and arbitrary. Feeding this an `up` that could line up
+ * with `forward` is the caller's to avoid, exactly as it is in every engine that offers this.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_QUAT_LOOK_ROTATION = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "quatLookRotation",
+        label: "Quaternion Look Rotation",
+        icon: "M12 12l7-4 M12 12v-8 M12 12L5 9 M12 12l3 8",
+        help: "the rotation that looks along forward, with up upright",
+        inputs: [
+            { name: "forward", type: PARTICLE_TYPE_VEC3 },
+            { name: "up", type: PARTICLE_TYPE_VEC3 },
+        ],
+        outputs: [{ name: "quat", type: PARTICLE_TYPE_VEC4 }],
+    });
+
+    const f = g.normalize(g.in.forward);
+    const r = g.normalize(g.cross(g.in.up, f));
+    const u = g.cross(f, r);
+
+    // The rotation matrix, by column: r, u, f. `m(row, column)`.
+    const lane = ["x", "y", "z"];
+    const column = [r, u, f];
+
+    const m = (row, col) => g.swz(column[col], lane[row]);
+
+    const m00 = m(0, 0), m01 = m(0, 1), m02 = m(0, 2);
+    const m10 = m(1, 0), m11 = m(1, 1), m12 = m(1, 2);
+    const m20 = m(2, 0), m21 = m(2, 1), m22 = m(2, 2);
+
+    const trace = g.add(g.add(m00, m11), m22);
+
+    /**
+     * One of the four expressions: `magnitude` is four times the square of the component this case
+     * is the largest of, and `parts` are the other three numerators in `x, y, z, w` order with that
+     * component's slot left for `magnitude` itself.
+     *
+     * @param {*} magnitude
+     * @param {function(*): Array} parts
+     * @returns {*} the quaternion for this case
+     */
+    const candidate = (magnitude, parts) => {
+        const safe = g.max(magnitude, g.f(DIVISOR_FLOOR));
+
+        // s = 2*sqrt(safe) is the classical scale; the component this case is largest of is
+        // 0.25*s, which is safe/s, so every lane of the vector below is a numerator over s.
+        const s = g.mul(g.sqrt(safe), 2);
+
+        return g.mul(g.vec4(...parts(safe)), g.div(1, s));
+    };
+
+    const q_trace = candidate(g.add(trace, 1), safe => [
+        g.sub(m21, m12), g.sub(m02, m20), g.sub(m10, m01), safe,
+    ]);
+
+    const q_x = candidate(g.sub(g.sub(g.add(1, m00), m11), m22), safe => [
+        safe, g.add(m01, m10), g.add(m02, m20), g.sub(m21, m12),
+    ]);
+
+    const q_y = candidate(g.sub(g.sub(g.add(1, m11), m00), m22), safe => [
+        g.add(m01, m10), safe, g.add(m12, m21), g.sub(m02, m20),
+    ]);
+
+    const q_z = candidate(g.sub(g.sub(g.add(1, m22), m00), m11), safe => [
+        g.add(m02, m20), g.add(m12, m21), safe, g.sub(m10, m01),
+    ]);
+
+    // Largest wins, checked from the bottom up: y over z, then x over both, then the trace over all.
+    const yz = g.select(q_z, q_y, g.op("compare", [m11, m22], { op: "ge" }));
+
+    const x_largest = g.mul(
+        g.op("compare", [m00, m11], { op: "ge" }),
+        g.op("compare", [m00, m22], { op: "ge" })
+    );
+
+    const xyz = g.select(yz, q_x, x_largest);
+
+    g.out("quat", g.select(xyz, q_trace, g.op("compare", [trace, 0], { op: "gt" })));
+
+    return g.build();
+})();