@sachitv/safe-math-ts 0.1.0

package/esm/src/geometry3d/matrix4.js

@@ -0,0 +1,975 @@
+import { dimensionlessUnit, } from '../units.js';
+import { quatNormalize, quatNormalizeUnsafe } from './quaternion.js';
+/**
+ * Casts a raw number into a branded quantity.
+ *
+ * @param value Raw numeric scalar.
+ * @returns Branded quantity.
+ */
+const asQuantity = (value) => value;
+/**
+ * Casts 16 numeric values into a branded affine matrix.
+ *
+ * @param values Matrix coefficients in column-major order.
+ * @returns Branded affine matrix.
+ */
+const asMat4 = (values) => values;
+/**
+ * Narrows a dimensionless affine matrix to a linear matrix type.
+ *
+ * @param value Affine matrix with dimensionless translation slot.
+ * @returns Branded linear matrix.
+ */
+const asLinearMat4 = (value) => value;
+/**
+ * Casts 16 numeric values into a branded projection matrix.
+ *
+ * @param values Matrix coefficients in column-major order.
+ * @returns Branded projection matrix.
+ */
+const asProjectionMat4 = (values) => values;
+/**
+ * Casts xyz components to a branded displacement tuple.
+ *
+ * @param x X component.
+ * @param y Y component.
+ * @param z Z component.
+ * @returns Branded displacement.
+ */
+const asDelta3 = (x, y, z) => [x, y, z];
+/**
+ * Casts xyz components to a branded point tuple.
+ *
+ * @param x X component.
+ * @param y Y component.
+ * @param z Z component.
+ * @returns Branded point.
+ */
+const asPoint3 = (x, y, z) => [x, y, z];
+/**
+ * Creates a typed 4x4 matrix from 16 column-major values.
+ *
+ * `toFrameTag`, `fromFrameTag`, and `translationUnitTag` enforce explicit
+ * frame/unit declaration at construction.
+ * Values follow column-major layout and translation lives in indices 12/13/14.
+ * Unsafe variant: slices to 16 values without length validation.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param translationUnitTag Translation unit token.
+ * @param values Matrix coefficients in column-major order.
+ * @returns Typed affine matrix.
+ */
+export const mat4Unsafe = (toFrameTag, fromFrameTag, translationUnitTag, values) => {
+    void toFrameTag;
+    void fromFrameTag;
+    void translationUnitTag;
+    return asMat4(values.slice(0, 16));
+};
+/**
+ * Creates a typed 4x4 matrix from 16 column-major values.
+ *
+ * `toFrameTag`, `fromFrameTag`, and `translationUnitTag` enforce explicit
+ * frame/unit declaration at construction.
+ * Values follow column-major layout and translation lives in indices 12/13/14.
+ * Throws when `values.length !== 16`.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param translationUnitTag Translation unit token.
+ * @param values Matrix coefficients in column-major order.
+ * @returns Typed affine matrix.
+ * @throws {Error} When `values` does not contain exactly 16 entries.
+ */
+export const mat4 = (toFrameTag, fromFrameTag, translationUnitTag, values) => {
+    void toFrameTag;
+    void fromFrameTag;
+    void translationUnitTag;
+    if (values.length !== 16) {
+        throw new Error(`Mat4 expects 16 values, received ${values.length}`);
+    }
+    return mat4Unsafe(toFrameTag, fromFrameTag, translationUnitTag, values);
+};
+/**
+ * Creates an identity linear transform for a frame.
+ *
+ * @param frameTag Frame token.
+ * @param dimensionlessUnitTag Dimensionless unit token.
+ * @returns Identity linear transform.
+ */
+export const mat4Identity = (frameTag, dimensionlessUnitTag) => {
+    void frameTag;
+    return asLinearMat4(mat4(frameTag, frameTag, dimensionlessUnitTag, [
+        1,
+        0,
+        0,
+        0,
+        0,
+        1,
+        0,
+        0,
+        0,
+        0,
+        1,
+        0,
+        0,
+        0,
+        0,
+        1,
+    ]));
+};
+/**
+ * Creates a pure translation matrix in a frame.
+ *
+ * @param frameTag Frame token.
+ * @param translation Translation displacement.
+ * @returns Affine translation matrix.
+ */
+export const mat4FromTranslation = (frameTag, translation) => (void frameTag,
+    asMat4([
+        1,
+        0,
+        0,
+        0,
+        0,
+        1,
+        0,
+        0,
+        0,
+        0,
+        1,
+        0,
+        translation[0],
+        translation[1],
+        translation[2],
+        1,
+    ]));
+/**
+ * Creates a non-uniform scale matrix in a frame.
+ *
+ * @param frameTag Frame token.
+ * @param dimensionlessUnitTag Dimensionless unit token.
+ * @param xScale X axis scale.
+ * @param yScale Y axis scale.
+ * @param zScale Z axis scale.
+ * @returns Linear scale matrix.
+ */
+export const mat4FromScale = (frameTag, dimensionlessUnitTag, xScale, yScale, zScale) => {
+    void frameTag;
+    void dimensionlessUnitTag;
+    return asLinearMat4(asMat4([
+        xScale,
+        0,
+        0,
+        0,
+        0,
+        yScale,
+        0,
+        0,
+        0,
+        0,
+        zScale,
+        0,
+        0,
+        0,
+        0,
+        1,
+    ]));
+};
+/**
+ * Creates a rotation matrix from a quaternion.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param dimensionlessUnitTag Dimensionless unit token.
+ * @param rotation Input quaternion.
+ * @returns Linear rotation matrix.
+ */
+export const mat4FromQuaternionUnsafe = (toFrameTag, fromFrameTag, dimensionlessUnitTag, rotation) => {
+    void toFrameTag;
+    void fromFrameTag;
+    void dimensionlessUnitTag;
+    const [x, y, z, w] = quatNormalizeUnsafe(rotation);
+    const xx = x * x;
+    const yy = y * y;
+    const zz = z * z;
+    const xy = x * y;
+    const xz = x * z;
+    const yz = y * z;
+    const wx = w * x;
+    const wy = w * y;
+    const wz = w * z;
+    return asLinearMat4(asMat4([
+        1 - 2 * (yy + zz),
+        2 * (xy + wz),
+        2 * (xz - wy),
+        0,
+        2 * (xy - wz),
+        1 - 2 * (xx + zz),
+        2 * (yz + wx),
+        0,
+        2 * (xz + wy),
+        2 * (yz - wx),
+        1 - 2 * (xx + yy),
+        0,
+        0,
+        0,
+        0,
+        1,
+    ]));
+};
+/**
+ * Creates a rotation matrix from a quaternion.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param dimensionlessUnitTag Dimensionless unit token.
+ * @param rotation Input quaternion.
+ * @returns Linear rotation matrix.
+ * @throws {Error} When `rotation` is near zero length.
+ */
+export const mat4FromQuaternion = (toFrameTag, fromFrameTag, dimensionlessUnitTag, rotation) => {
+    quatNormalize(rotation);
+    return mat4FromQuaternionUnsafe(toFrameTag, fromFrameTag, dimensionlessUnitTag, rotation);
+};
+/**
+ * Builds rigid transform matrix from rotation and translation.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param rotation Rotation quaternion.
+ * @param translation Translation expressed in `toFrameTag`.
+ * @returns Affine rigid transform matrix.
+ */
+export const mat4FromRigidTransform = (toFrameTag, fromFrameTag, rotation, translation) => {
+    void toFrameTag;
+    void fromFrameTag;
+    const rotationMatrix = mat4FromQuaternion(toFrameTag, fromFrameTag, dimensionlessUnit, rotation);
+    return asMat4([
+        rotationMatrix[0],
+        rotationMatrix[1],
+        rotationMatrix[2],
+        rotationMatrix[3],
+        rotationMatrix[4],
+        rotationMatrix[5],
+        rotationMatrix[6],
+        rotationMatrix[7],
+        rotationMatrix[8],
+        rotationMatrix[9],
+        rotationMatrix[10],
+        rotationMatrix[11],
+        translation[0],
+        translation[1],
+        translation[2],
+        1,
+    ]);
+};
+/**
+ * Builds an affine transform from translation, rotation, and non-uniform scale.
+ *
+ * Order: scale in `FromFrame`, then rotate `FromFrame -> ToFrame`, then translate
+ * in `ToFrame`.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param translation Translation expressed in `toFrameTag`.
+ * @param rotation Rotation from `fromFrameTag` into `toFrameTag`.
+ * @param scale Non-uniform scale in `fromFrameTag`.
+ * @returns Affine TRS matrix.
+ */
+export const mat4FromTRSUnsafe = (toFrameTag, fromFrameTag, translation, rotation, scale) => {
+    void toFrameTag;
+    void fromFrameTag;
+    const [x, y, z, w] = quatNormalizeUnsafe(rotation);
+    const xx = x * x;
+    const yy = y * y;
+    const zz = z * z;
+    const xy = x * y;
+    const xz = x * z;
+    const yz = y * z;
+    const wx = w * x;
+    const wy = w * y;
+    const wz = w * z;
+    const sx = scale[0];
+    const sy = scale[1];
+    const sz = scale[2];
+    return asMat4([
+        (1 - 2 * (yy + zz)) * sx,
+        (2 * (xy + wz)) * sx,
+        (2 * (xz - wy)) * sx,
+        0,
+        (2 * (xy - wz)) * sy,
+        (1 - 2 * (xx + zz)) * sy,
+        (2 * (yz + wx)) * sy,
+        0,
+        (2 * (xz + wy)) * sz,
+        (2 * (yz - wx)) * sz,
+        (1 - 2 * (xx + yy)) * sz,
+        0,
+        translation[0],
+        translation[1],
+        translation[2],
+        1,
+    ]);
+};
+/**
+ * Builds an affine transform from translation, rotation, and non-uniform scale.
+ *
+ * Order: scale in `FromFrame`, then rotate `FromFrame -> ToFrame`, then translate
+ * in `ToFrame`.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param translation Translation expressed in `toFrameTag`.
+ * @param rotation Rotation from `fromFrameTag` into `toFrameTag`.
+ * @param scale Non-uniform scale in `fromFrameTag`.
+ * @returns Affine TRS matrix.
+ * @throws {Error} When `rotation` is near zero length.
+ */
+export const mat4FromTRS = (toFrameTag, fromFrameTag, translation, rotation, scale) => {
+    quatNormalize(rotation);
+    return mat4FromTRSUnsafe(toFrameTag, fromFrameTag, translation, rotation, scale);
+};
+/**
+ * Creates a cache for TRS matrix construction.
+ *
+ * Returns a closure that reuses the previous matrix instance when all inputs are
+ * numerically unchanged.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param translationUnitTag Translation unit token.
+ * @returns Memoized TRS builder.
+ */
+export const createTrsMat4Cache = (toFrameTag, fromFrameTag, translationUnitTag) => {
+    void translationUnitTag;
+    let hasCached = false;
+    let cached = asMat4([
+        1,
+        0,
+        0,
+        0,
+        0,
+        1,
+        0,
+        0,
+        0,
+        0,
+        1,
+        0,
+        0,
+        0,
+        0,
+        1,
+    ]);
+    let tx = 0;
+    let ty = 0;
+    let tz = 0;
+    let qx = 0;
+    let qy = 0;
+    let qz = 0;
+    let qw = 1;
+    let sx = 1;
+    let sy = 1;
+    let sz = 1;
+    return (translation, rotation, scale) => {
+        const nextTx = translation[0];
+        const nextTy = translation[1];
+        const nextTz = translation[2];
+        const nextQx = rotation[0];
+        const nextQy = rotation[1];
+        const nextQz = rotation[2];
+        const nextQw = rotation[3];
+        const nextSx = scale[0];
+        const nextSy = scale[1];
+        const nextSz = scale[2];
+        if (hasCached &&
+            nextTx === tx &&
+            nextTy === ty &&
+            nextTz === tz &&
+            nextQx === qx &&
+            nextQy === qy &&
+            nextQz === qz &&
+            nextQw === qw &&
+            nextSx === sx &&
+            nextSy === sy &&
+            nextSz === sz) {
+            return cached;
+        }
+        cached = mat4FromTRS(toFrameTag, fromFrameTag, translation, rotation, scale);
+        hasCached = true;
+        tx = nextTx;
+        ty = nextTy;
+        tz = nextTz;
+        qx = nextQx;
+        qy = nextQy;
+        qz = nextQz;
+        qw = nextQw;
+        sx = nextSx;
+        sy = nextSy;
+        sz = nextSz;
+        return cached;
+    };
+};
+/**
+ * Builds a right-handed perspective projection matrix.
+ *
+ * Returns a matrix intended for `projectPoint3` (includes perspective divide).
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param fieldOfViewYRadians Vertical field of view in radians.
+ * @param aspect Width/height aspect ratio.
+ * @param near Near clipping plane distance.
+ * @param far Far clipping plane distance.
+ * @returns Projection matrix.
+ */
+export const mat4PerspectiveUnsafe = (toFrameTag, fromFrameTag, fieldOfViewYRadians, aspect, near, far) => {
+    void toFrameTag;
+    void fromFrameTag;
+    const f = 1 / Math.tan(fieldOfViewYRadians * 0.5);
+    const rangeInverse = 1 / (near - far);
+    return asProjectionMat4([
+        f / aspect,
+        0,
+        0,
+        0,
+        0,
+        f,
+        0,
+        0,
+        0,
+        0,
+        (far + near) * rangeInverse,
+        -1,
+        0,
+        0,
+        (2 * far * near) * rangeInverse,
+        0,
+    ]);
+};
+/**
+ * Builds a right-handed perspective projection matrix.
+ *
+ * Returns a matrix intended for `projectPoint3` (includes perspective divide).
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param fieldOfViewYRadians Vertical field of view in radians.
+ * @param aspect Width/height aspect ratio.
+ * @param near Near clipping plane distance.
+ * @param far Far clipping plane distance.
+ * @returns Projection matrix.
+ * @throws {Error} When FOV/aspect/near/far inputs are invalid.
+ */
+export const mat4Perspective = (toFrameTag, fromFrameTag, fieldOfViewYRadians, aspect, near, far) => {
+    void toFrameTag;
+    void fromFrameTag;
+    if (!(fieldOfViewYRadians > 0 && fieldOfViewYRadians < Math.PI)) {
+        throw new Error('fieldOfViewYRadians must be in (0, PI)');
+    }
+    if (!(aspect > 0)) {
+        throw new Error('aspect must be > 0');
+    }
+    if (!(near > 0 && far > 0 && near < far)) {
+        throw new Error('near and far must satisfy 0 < near < far');
+    }
+    return mat4PerspectiveUnsafe(toFrameTag, fromFrameTag, fieldOfViewYRadians, aspect, near, far);
+};
+/**
+ * Builds a right-handed orthographic projection matrix.
+ *
+ * Maps the view volume [left,right]×[bottom,top]×[-near,-far] to NDC
+ * [-1,1]×[-1,1]×[-1,1]. The w component of transformed points is always 1,
+ * so `projectPoint3` performs a trivial divide by 1.
+ *
+ * Unsafe variant: performs no input validation.
+ * Degenerate inputs (e.g. left === right) produce a singular matrix.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param left Left clipping plane distance.
+ * @param right Right clipping plane distance.
+ * @param bottom Bottom clipping plane distance.
+ * @param top Top clipping plane distance.
+ * @param near Near clipping plane distance.
+ * @param far Far clipping plane distance.
+ * @returns Orthographic projection matrix.
+ */
+export const mat4OrthoUnsafe = (toFrameTag, fromFrameTag, left, right, bottom, top, near, far) => {
+    void toFrameTag;
+    void fromFrameTag;
+    const rl = 1 / (right - left);
+    const tb = 1 / (top - bottom);
+    const rangeInverse = 1 / (near - far);
+    return asProjectionMat4([
+        2 * rl,
+        0,
+        0,
+        0,
+        0,
+        2 * tb,
+        0,
+        0,
+        0,
+        0,
+        2 * rangeInverse,
+        0,
+        -(right + left) * rl,
+        -(top + bottom) * tb,
+        (far + near) * rangeInverse,
+        1,
+    ]);
+};
+/**
+ * Builds a right-handed orthographic projection matrix.
+ *
+ * Maps the view volume [left,right]×[bottom,top]×[-near,-far] to NDC
+ * [-1,1]×[-1,1]×[-1,1]. The w component of transformed points is always 1,
+ * so `projectPoint3` performs a trivial divide by 1.
+ *
+ * Safe variant: validates that left < right, bottom < top, and 0 < near < far.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param left Left clipping plane distance.
+ * @param right Right clipping plane distance.
+ * @param bottom Bottom clipping plane distance.
+ * @param top Top clipping plane distance.
+ * @param near Near clipping plane distance.
+ * @param far Far clipping plane distance.
+ * @returns Orthographic projection matrix.
+ * @throws {Error} When the clipping volume is degenerate.
+ */
+export const mat4Ortho = (toFrameTag, fromFrameTag, left, right, bottom, top, near, far) => {
+    void toFrameTag;
+    void fromFrameTag;
+    if (!(right > left)) {
+        throw new Error('right must be > left');
+    }
+    if (!(top > bottom)) {
+        throw new Error('top must be > bottom');
+    }
+    if (!(near > 0 && far > 0 && near < far)) {
+        throw new Error('near and far must satisfy 0 < near < far');
+    }
+    return mat4OrthoUnsafe(toFrameTag, fromFrameTag, left, right, bottom, top, near, far);
+};
+/**
+ * Projects a point with a perspective matrix and performs perspective divide.
+ *
+ * Unsafe variant: performs no `w === 0` guard.
+ * Degenerate inputs can yield `NaN`/`Infinity`.
+ *
+ * @param projection Projection matrix.
+ * @param point Input point in projection source frame.
+ * @returns Point in normalized device coordinates.
+ */
+export const projectPoint3Unsafe = (projection, point) => {
+    const x = point[0];
+    const y = point[1];
+    const z = point[2];
+    const clipX = projection[0] * x +
+        projection[4] * y +
+        projection[8] * z +
+        projection[12];
+    const clipY = projection[1] * x +
+        projection[5] * y +
+        projection[9] * z +
+        projection[13];
+    const clipZ = projection[2] * x +
+        projection[6] * y +
+        projection[10] * z +
+        projection[14];
+    const clipW = projection[3] * x +
+        projection[7] * y +
+        projection[11] * z +
+        projection[15];
+    const invW = 1 / clipW;
+    return asPoint3(asQuantity(clipX * invW), asQuantity(clipY * invW), asQuantity(clipZ * invW));
+};
+/**
+ * Projects a point with a perspective matrix and performs perspective divide.
+ *
+ * Throws when homogeneous `w` is zero.
+ *
+ * @param projection Projection matrix.
+ * @param point Input point in projection source frame.
+ * @returns Point in normalized device coordinates.
+ * @throws {Error} When homogeneous `w` equals zero.
+ */
+export const projectPoint3 = (projection, point) => {
+    const clipW = projection[3] * point[0] +
+        projection[7] * point[1] +
+        projection[11] * point[2] +
+        projection[15];
+    if (Math.abs(clipW) < 1e-10) {
+        throw new Error('Perspective divide is undefined for w ≈ 0');
+    }
+    return projectPoint3Unsafe(projection, point);
+};
+/**
+ * Builds a world-to-view pose matrix from eye, target, and up direction.
+ *
+ * Unsafe variant: performs no degeneracy checks on eye/target/up.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param point_eye_from Camera eye position.
+ * @param point_target_from Camera target position.
+ * @param dir_up_from Up direction.
+ * @returns View matrix.
+ */
+export const mat4LookAtUnsafe = (toFrameTag, fromFrameTag, point_eye_from, point_target_from, dir_up_from) => {
+    void toFrameTag;
+    void fromFrameTag;
+    const forwardX = point_target_from[0] - point_eye_from[0];
+    const forwardY = point_target_from[1] - point_eye_from[1];
+    const forwardZ = point_target_from[2] - point_eye_from[2];
+    const forwardLength = Math.hypot(forwardX, forwardY, forwardZ);
+    const dir_forward_x = forwardX / forwardLength;
+    const dir_forward_y = forwardY / forwardLength;
+    const dir_forward_z = forwardZ / forwardLength;
+    const upLength = Math.hypot(dir_up_from[0], dir_up_from[1], dir_up_from[2]);
+    const upX = dir_up_from[0] / upLength;
+    const upY = dir_up_from[1] / upLength;
+    const upZ = dir_up_from[2] / upLength;
+    const rightX = dir_forward_y * upZ - dir_forward_z * upY;
+    const rightY = dir_forward_z * upX - dir_forward_x * upZ;
+    const rightZ = dir_forward_x * upY - dir_forward_y * upX;
+    const rightLength = Math.hypot(rightX, rightY, rightZ);
+    const dir_right_x = rightX / rightLength;
+    const dir_right_y = rightY / rightLength;
+    const dir_right_z = rightZ / rightLength;
+    const dir_up_orthogonal_x = dir_right_y * dir_forward_z -
+        dir_right_z * dir_forward_y;
+    const dir_up_orthogonal_y = dir_right_z * dir_forward_x -
+        dir_right_x * dir_forward_z;
+    const dir_up_orthogonal_z = dir_right_x * dir_forward_y -
+        dir_right_y * dir_forward_x;
+    const tx = -(dir_right_x * point_eye_from[0] +
+        dir_right_y * point_eye_from[1] +
+        dir_right_z * point_eye_from[2]);
+    const ty = -(dir_up_orthogonal_x * point_eye_from[0] +
+        dir_up_orthogonal_y * point_eye_from[1] +
+        dir_up_orthogonal_z * point_eye_from[2]);
+    const tz = dir_forward_x * point_eye_from[0] +
+        dir_forward_y * point_eye_from[1] +
+        dir_forward_z * point_eye_from[2];
+    return asMat4([
+        dir_right_x,
+        dir_up_orthogonal_x,
+        -dir_forward_x,
+        0,
+        dir_right_y,
+        dir_up_orthogonal_y,
+        -dir_forward_y,
+        0,
+        dir_right_z,
+        dir_up_orthogonal_z,
+        -dir_forward_z,
+        0,
+        asQuantity(tx),
+        asQuantity(ty),
+        asQuantity(tz),
+        1,
+    ]);
+};
+/**
+ * Builds a world-to-view pose matrix from eye, target, and up direction.
+ *
+ * `upDirection` must be dimensionless and non-zero.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param point_eye_from Camera eye position.
+ * @param point_target_from Camera target position.
+ * @param dir_up_from Up direction.
+ * @returns View matrix.
+ * @throws {Error} When eye/target/up vectors form a degenerate basis.
+ */
+export const mat4LookAt = (toFrameTag, fromFrameTag, point_eye_from, point_target_from, dir_up_from) => {
+    void toFrameTag;
+    void fromFrameTag;
+    const forwardX = point_target_from[0] - point_eye_from[0];
+    const forwardY = point_target_from[1] - point_eye_from[1];
+    const forwardZ = point_target_from[2] - point_eye_from[2];
+    const forwardLength = Math.hypot(forwardX, forwardY, forwardZ);
+    if (forwardLength === 0) {
+        throw new Error('LookAt requires eye and target to be distinct');
+    }
+    const dir_forward_x = forwardX / forwardLength;
+    const dir_forward_y = forwardY / forwardLength;
+    const dir_forward_z = forwardZ / forwardLength;
+    const upLength = Math.hypot(dir_up_from[0], dir_up_from[1], dir_up_from[2]);
+    if (upLength === 0) {
+        throw new Error('LookAt requires a non-zero up direction');
+    }
+    const upX = dir_up_from[0] / upLength;
+    const upY = dir_up_from[1] / upLength;
+    const upZ = dir_up_from[2] / upLength;
+    const rightX = dir_forward_y * upZ - dir_forward_z * upY;
+    const rightY = dir_forward_z * upX - dir_forward_x * upZ;
+    const rightZ = dir_forward_x * upY - dir_forward_y * upX;
+    const rightLength = Math.hypot(rightX, rightY, rightZ);
+    if (rightLength === 0) {
+        throw new Error('LookAt up direction cannot be parallel to forward');
+    }
+    return mat4LookAtUnsafe(toFrameTag, fromFrameTag, point_eye_from, point_target_from, dir_up_from);
+};
+export function transposeMat4(value) {
+    return asMat4([
+        value[0],
+        value[4],
+        value[8],
+        value[12],
+        value[1],
+        value[5],
+        value[9],
+        value[13],
+        value[2],
+        value[6],
+        value[10],
+        value[14],
+        value[3],
+        value[7],
+        value[11],
+        value[15],
+    ]);
+}
+/**
+ * Multiplies two raw 4x4 matrices in column-major order.
+ *
+ * @param left Left matrix values.
+ * @param right Right matrix values.
+ * @returns Product matrix values.
+ */
+const multiplyRaw = (left, right) => {
+    const output = new Array(16);
+    for (let column = 0; column < 4; column += 1) {
+        const columnOffset = column * 4;
+        for (let row = 0; row < 4; row += 1) {
+            output[columnOffset + row] = left[row] * right[columnOffset] +
+                left[row + 4] * right[columnOffset + 1] +
+                left[row + 8] * right[columnOffset + 2] +
+                left[row + 12] * right[columnOffset + 3];
+        }
+    }
+    return output;
+};
+/**
+ * Composes affine transforms with different translation units in chain order.
+ *
+ * Result translation unit is widened to `UnitExpr`.
+ * `composeMat4(outer, inner)` returns `outer * inner`, so `inner` is applied
+ * first.
+ *
+ * @param outer Outer transform.
+ * @param inner Inner transform.
+ * @returns Composed transform with widened translation unit.
+ */
+export function composeMat4(outer, inner) {
+    return asMat4(multiplyRaw(outer, inner));
+}
+/**
+ * Checks whether two scalar values are within epsilon tolerance.
+ *
+ * @param actual Computed value.
+ * @param expected Reference value.
+ * @param epsilon Absolute tolerance.
+ * @returns `true` when values are close enough.
+ */
+const isApproximately = (actual, expected, epsilon) => Math.abs(actual - expected) <= epsilon;
+/**
+ * Validates that a matrix represents a rigid transform.
+ *
+ * @param value Raw matrix values.
+ * @param epsilon Absolute tolerance for orthonormal checks.
+ * @throws {Error} When the matrix is not rigid.
+ */
+const assertRigidTransform = (value, epsilon) => {
+    const col0x = value[0];
+    const col0y = value[1];
+    const col0z = value[2];
+    const col1x = value[4];
+    const col1y = value[5];
+    const col1z = value[6];
+    const col2x = value[8];
+    const col2y = value[9];
+    const col2z = value[10];
+    const norm0 = col0x * col0x + col0y * col0y + col0z * col0z;
+    const norm1 = col1x * col1x + col1y * col1y + col1z * col1z;
+    const norm2 = col2x * col2x + col2y * col2y + col2z * col2z;
+    const dot01 = col0x * col1x + col0y * col1y + col0z * col1z;
+    const dot02 = col0x * col2x + col0y * col2y + col0z * col2z;
+    const dot12 = col1x * col2x + col1y * col2y + col1z * col2z;
+    const hasFiniteNorms = Number.isFinite(norm0) &&
+        Number.isFinite(norm1) &&
+        Number.isFinite(norm2);
+    const hasUnitLengthRows = isApproximately(norm0, 1, epsilon) &&
+        isApproximately(norm1, 1, epsilon) &&
+        isApproximately(norm2, 1, epsilon);
+    const hasOrthogonalRows = isApproximately(dot01, 0, epsilon) &&
+        isApproximately(dot02, 0, epsilon) &&
+        isApproximately(dot12, 0, epsilon);
+    const hasAffineBottomRow = isApproximately(value[3], 0, epsilon) &&
+        isApproximately(value[7], 0, epsilon) &&
+        isApproximately(value[11], 0, epsilon) &&
+        isApproximately(value[15], 1, epsilon);
+    const isRigid = hasFiniteNorms &&
+        hasUnitLengthRows &&
+        hasOrthogonalRows &&
+        hasAffineBottomRow;
+    if (!isRigid) {
+        throw new Error('Matrix is not a rigid transform');
+    }
+};
+export function invertRigidMat4Unsafe(value) {
+    const r00 = value[0];
+    const r10 = value[1];
+    const r20 = value[2];
+    const r01 = value[4];
+    const r11 = value[5];
+    const r21 = value[6];
+    const r02 = value[8];
+    const r12 = value[9];
+    const r22 = value[10];
+    const tx = value[12];
+    const ty = value[13];
+    const tz = value[14];
+    const inverseTx = -(r00 * tx + r10 * ty + r20 * tz);
+    const inverseTy = -(r01 * tx + r11 * ty + r21 * tz);
+    const inverseTz = -(r02 * tx + r12 * ty + r22 * tz);
+    return asMat4([
+        r00,
+        r01,
+        r02,
+        0,
+        r10,
+        r11,
+        r12,
+        0,
+        r20,
+        r21,
+        r22,
+        0,
+        inverseTx,
+        inverseTy,
+        inverseTz,
+        1,
+    ]);
+}
+export function invertRigidMat4(value) {
+    assertRigidTransform(value, 1e-10);
+    return invertRigidMat4Unsafe(value);
+}
+/**
+ * Builds a normal matrix (inverse-transpose of upper-left 3x3 linear part).
+ *
+ * Unsafe variant: performs no singularity guard.
+ * Degenerate inputs can yield `NaN`/`Infinity`.
+ *
+ * @param value Input affine transform.
+ * @returns Normal matrix as a linear transform.
+ */
+export const normalMatrixFromMat4Unsafe = (value) => {
+    const a = value[0];
+    const b = value[4];
+    const c = value[8];
+    const d = value[1];
+    const e = value[5];
+    const f = value[9];
+    const g = value[2];
+    const h = value[6];
+    const i = value[10];
+    const co00 = e * i - f * h;
+    const co01 = c * h - b * i;
+    const co02 = b * f - c * e;
+    const co10 = f * g - d * i;
+    const co11 = a * i - c * g;
+    const co12 = c * d - a * f;
+    const co20 = d * h - e * g;
+    const co21 = b * g - a * h;
+    const co22 = a * e - b * d;
+    const determinant = a * co00 + b * co10 + c * co20;
+    const inverseDeterminant = 1 / determinant;
+    return asLinearMat4(asMat4([
+        co00 * inverseDeterminant,
+        co01 * inverseDeterminant,
+        co02 * inverseDeterminant,
+        0,
+        co10 * inverseDeterminant,
+        co11 * inverseDeterminant,
+        co12 * inverseDeterminant,
+        0,
+        co20 * inverseDeterminant,
+        co21 * inverseDeterminant,
+        co22 * inverseDeterminant,
+        0,
+        0,
+        0,
+        0,
+        1,
+    ]));
+};
+/**
+ * Builds a normal matrix (inverse-transpose of upper-left 3x3 linear part).
+ *
+ * Throws when the linear part is singular.
+ *
+ * @param value Input affine transform.
+ * @returns Normal matrix as a linear transform.
+ * @throws {Error} When the upper-left 3x3 block is singular.
+ */
+export const normalMatrixFromMat4 = (value) => {
+    const a = value[0];
+    const b = value[4];
+    const c = value[8];
+    const d = value[1];
+    const e = value[5];
+    const f = value[9];
+    const g = value[2];
+    const h = value[6];
+    const i = value[10];
+    const co00 = e * i - f * h;
+    const co10 = f * g - d * i;
+    const co20 = d * h - e * g;
+    const determinant = a * co00 + b * co10 + c * co20;
+    if (Math.abs(determinant) < 1e-10) {
+        throw new Error('Cannot build a normal matrix from a singular transform');
+    }
+    return normalMatrixFromMat4Unsafe(value);
+};
+export function transformPoint3(matrix, point) {
+    const x = point[0];
+    const y = point[1];
+    const z = point[2];
+    const transformedX = matrix[0] * x +
+        matrix[4] * y +
+        matrix[8] * z +
+        matrix[12];
+    const transformedY = matrix[1] * x +
+        matrix[5] * y +
+        matrix[9] * z +
+        matrix[13];
+    const transformedZ = matrix[2] * x +
+        matrix[6] * y +
+        matrix[10] * z +
+        matrix[14];
+    return asPoint3(asQuantity(transformedX), asQuantity(transformedY), asQuantity(transformedZ));
+}
+export function transformDirection3(matrix, direction) {
+    const x = direction[0];
+    const y = direction[1];
+    const z = direction[2];
+    const transformedX = matrix[0] * x +
+        matrix[4] * y +
+        matrix[8] * z;
+    const transformedY = matrix[1] * x +
+        matrix[5] * y +
+        matrix[9] * z;
+    const transformedZ = matrix[2] * x +
+        matrix[6] * y +
+        matrix[10] * z;
+    return asDelta3(asQuantity(transformedX), asQuantity(transformedY), asQuantity(transformedZ));
+}