@newgameplusinc/odyssey-audio-video-sdk-dev 1.0.258 → 1.0.260

package/dist/utils/smoothing/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Smoothing utilities - Re-exports all smoothing functions
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./pan-smoothing"), exports);
+__exportStar(require("./gain-smoothing"), exports);

package/dist/utils/smoothing/pan-smoothing.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pan Smoothing
+ *
+ * Classes and functions for smoothing stereo panning values
+ * to prevent audio jitter and rapid left/right jumping
+ */
+/**
+ * Pan smoother configuration
+ */
+export interface PanSmootherOptions {
+    smoothingFactor?: number;
+    changeThreshold?: number;
+    centerDeadZone?: number;
+}
+/**
+ * Default pan smoother options
+ */
+export declare const DEFAULT_PAN_SMOOTHER_OPTIONS: Required<PanSmootherOptions>;
+/**
+ * Pan smoother class
+ * Smooths pan values using EMA with dead-zone and threshold
+ */
+export declare class PanSmoother {
+    private smoothedValues;
+    private options;
+    constructor(options?: PanSmootherOptions);
+    /**
+     * Smooth a pan value for a participant
+     *
+     * @param participantId Participant ID
+     * @param newPanValue New pan value (-1 to +1)
+     * @returns Smoothed pan value
+     */
+    smooth(participantId: string, newPanValue: number): number;
+    /**
+     * Clear smoothed value for a participant
+     */
+    clear(participantId: string): void;
+    /**
+     * Clear all smoothed values
+     */
+    clearAll(): void;
+}

package/dist/utils/smoothing/pan-smoothing.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Pan Smoothing
+ *
+ * Classes and functions for smoothing stereo panning values
+ * to prevent audio jitter and rapid left/right jumping
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PanSmoother = exports.DEFAULT_PAN_SMOOTHER_OPTIONS = void 0;
+/**
+ * Default pan smoother options
+ */
+exports.DEFAULT_PAN_SMOOTHER_OPTIONS = {
+    smoothingFactor: 0.35,
+    changeThreshold: 0.02,
+    centerDeadZone: 0.03,
+};
+/**
+ * Pan smoother class
+ * Smooths pan values using EMA with dead-zone and threshold
+ */
+class PanSmoother {
+    constructor(options = {}) {
+        this.smoothedValues = new Map();
+        this.options = { ...exports.DEFAULT_PAN_SMOOTHER_OPTIONS, ...options };
+    }
+    /**
+     * Smooth a pan value for a participant
+     *
+     * @param participantId Participant ID
+     * @param newPanValue New pan value (-1 to +1)
+     * @returns Smoothed pan value
+     */
+    smooth(participantId, newPanValue) {
+        const previousPan = this.smoothedValues.get(participantId);
+        // DEAD-ZONE: If new pan is very close to center, snap to exactly 0
+        let targetPan = newPanValue;
+        if (Math.abs(newPanValue) < this.options.centerDeadZone) {
+            targetPan = 0;
+        }
+        // If no previous value, initialize with current value
+        if (previousPan === undefined) {
+            this.smoothedValues.set(participantId, targetPan);
+            return targetPan;
+        }
+        // Calculate the change from previous pan
+        const panChange = Math.abs(targetPan - previousPan);
+        // If change is below threshold, keep previous value (prevents micro-jitter)
+        if (panChange < this.options.changeThreshold) {
+            return previousPan;
+        }
+        // Determine effective smoothing factor based on change magnitude
+        let effectiveSmoothingFactor = 0.7; // High smoothing = slow but stable
+        const signFlipped = (previousPan > 0 && targetPan < 0) || (previousPan < 0 && targetPan > 0);
+        const bothNearCenter = Math.abs(previousPan) < 0.2 && Math.abs(targetPan) < 0.2;
+        if (bothNearCenter) {
+            // Near center - use moderate smoothing
+            effectiveSmoothingFactor = 0.5;
+        }
+        else if (signFlipped && panChange > 1.0) {
+            // Full flip - likely jitter, use HEAVY smoothing
+            effectiveSmoothingFactor = 0.85;
+        }
+        // Apply exponential moving average smoothing
+        const smoothedPan = previousPan * effectiveSmoothingFactor + targetPan * (1 - effectiveSmoothingFactor);
+        // Apply dead-zone to final smoothed value
+        const finalPan = Math.abs(smoothedPan) < this.options.centerDeadZone ? 0 : smoothedPan;
+        // Store for next update
+        this.smoothedValues.set(participantId, finalPan);
+        return finalPan;
+    }
+    /**
+     * Clear smoothed value for a participant
+     */
+    clear(participantId) {
+        this.smoothedValues.delete(participantId);
+    }
+    /**
+     * Clear all smoothed values
+     */
+    clearAll() {
+        this.smoothedValues.clear();
+    }
+}
+exports.PanSmoother = PanSmoother;

package/dist/utils/spatial/angle-calc.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Angle Calculations
+ *
+ * Functions for computing angles between positions
+ */
+import { Position } from '../../types/position';
+/**
+ * Compute azimuth angle from listener to source
+ *
+ * @param listener Listener position
+ * @param source Source position
+ * @returns Angle in degrees (0-360), where 0° = forward (+Z), 90° = right (+X)
+ */
+export declare function computeAzimuthFromPositions(listener: Position, source: Position): number;
+/**
+ * Calculate angle between listener and sound source in degrees
+ * Takes into account listener's forward direction
+ *
+ * @param listenerPos Listener position
+ * @param sourcePos Source position
+ * @param listenerForward Listener's forward direction vector
+ * @returns Angle in degrees (0-360): 0° = front, 90° = right, 180° = back, 270° = left
+ */
+export declare function calculateAngleToSource(listenerPos: Position, sourcePos: Position, listenerForward: Position): number;

package/dist/utils/spatial/angle-calc.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Angle Calculations
+ *
+ * Functions for computing angles between positions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeAzimuthFromPositions = computeAzimuthFromPositions;
+exports.calculateAngleToSource = calculateAngleToSource;
+/**
+ * Compute azimuth angle from listener to source
+ *
+ * @param listener Listener position
+ * @param source Source position
+ * @returns Angle in degrees (0-360), where 0° = forward (+Z), 90° = right (+X)
+ */
+function computeAzimuthFromPositions(listener, source) {
+    const vx = source.x - listener.x;
+    const vz = source.z - listener.z;
+    const angleRad = Math.atan2(vx, vz); // 0° = forward (Z+), 90° = right (X+)
+    const deg = (angleRad * 180) / Math.PI;
+    const normalized = (deg + 360) % 360;
+    return normalized;
+}
+/**
+ * Calculate angle between listener and sound source in degrees
+ * Takes into account listener's forward direction
+ *
+ * @param listenerPos Listener position
+ * @param sourcePos Source position
+ * @param listenerForward Listener's forward direction vector
+ * @returns Angle in degrees (0-360): 0° = front, 90° = right, 180° = back, 270° = left
+ */
+function calculateAngleToSource(listenerPos, sourcePos, listenerForward) {
+    // Use X/Z as the horizontal plane for 360° panning
+    const vx = sourcePos.x - listenerPos.x;
+    const vz = sourcePos.z - listenerPos.z;
+    // Project listener forward onto X/Z plane
+    let fx = listenerForward.x;
+    let fz = listenerForward.z;
+    const fLen = Math.hypot(fx, fz);
+    if (fLen < 1e-4) {
+        // Fallback: if forward is nearly vertical/invalid, assume world-forward
+        fx = 0;
+        fz = 1;
+    }
+    else {
+        fx /= fLen;
+        fz /= fLen;
+    }
+    const vLen = Math.hypot(vx, vz);
+    if (vLen < 1e-4) {
+        return 0;
+    }
+    const nx = vx / vLen;
+    const nz = vz / vLen;
+    // Signed angle from forward->source
+    const dot = fx * nx + fz * nz;
+    const cross = fx * nz - fz * nx;
+    let radians = Math.atan2(cross, dot);
+    // atan2 gives [-π, π]; map to [0, 2π)
+    if (radians < 0) {
+        radians += Math.PI * 2;
+    }
+    const degrees = (radians * 180) / Math.PI;
+    // Convert to convention where +90 is to the right
+    const angle = (360 - degrees) % 360;
+    return angle;
+}

package/dist/utils/spatial/distance-calc.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Distance Calculations
+ *
+ * Functions for calculating distances between positions in 3D space
+ */
+import { Position } from '../../types/position';
+/**
+ * Calculate 3D Euclidean distance between two positions
+ * distance = √(Δx² + Δy² + Δz²)
+ *
+ * @param a First position
+ * @param b Second position
+ * @returns Distance in the same units as input positions
+ */
+export declare function getDistanceBetween(a: Position, b: Position): number;
+/**
+ * Calculate horizontal distance (XZ plane only, ignoring Y/height)
+ * Useful for spatial audio where vertical distance matters less
+ *
+ * @param a First position
+ * @param b Second position
+ * @returns Horizontal distance
+ */
+export declare function getHorizontalDistance(a: Position, b: Position): number;
+/**
+ * Check if a position is within a certain range of another
+ *
+ * @param a First position
+ * @param b Second position
+ * @param maxDistance Maximum allowed distance
+ * @returns True if within range
+ */
+export declare function isWithinRange(a: Position, b: Position, maxDistance: number): boolean;

package/dist/utils/spatial/distance-calc.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Distance Calculations
+ *
+ * Functions for calculating distances between positions in 3D space
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDistanceBetween = getDistanceBetween;
+exports.getHorizontalDistance = getHorizontalDistance;
+exports.isWithinRange = isWithinRange;
+/**
+ * Calculate 3D Euclidean distance between two positions
+ * distance = √(Δx² + Δy² + Δz²)
+ *
+ * @param a First position
+ * @param b Second position
+ * @returns Distance in the same units as input positions
+ */
+function getDistanceBetween(a, b) {
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const dz = b.z - a.z;
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+/**
+ * Calculate horizontal distance (XZ plane only, ignoring Y/height)
+ * Useful for spatial audio where vertical distance matters less
+ *
+ * @param a First position
+ * @param b Second position
+ * @returns Horizontal distance
+ */
+function getHorizontalDistance(a, b) {
+    const dx = b.x - a.x;
+    const dz = b.z - a.z;
+    return Math.sqrt(dx * dx + dz * dz);
+}
+/**
+ * Check if a position is within a certain range of another
+ *
+ * @param a First position
+ * @param b Second position
+ * @param maxDistance Maximum allowed distance
+ * @returns True if within range
+ */
+function isWithinRange(a, b, maxDistance) {
+    return getDistanceBetween(a, b) <= maxDistance;
+}

package/dist/utils/spatial/gain-calc.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Gain Calculations
+ *
+ * Functions for calculating audio gain based on distance
+ */
+/**
+ * Gain calculation configuration
+ */
+export interface GainConfig {
+    minDistance?: number;
+    maxDistance?: number;
+    minGain?: number;
+    falloffRate?: number;
+}
+/**
+ * Default gain configuration
+ */
+export declare const DEFAULT_GAIN_CONFIG: Required<GainConfig>;
+/**
+ * Calculate gain based on distance using inverse-square law
+ *
+ * Uses inverse-square law (realistic sound propagation) with floor:
+ * Gain = 1 / (1 + k * distance²)
+ *
+ * Distance → Gain mapping (with defaults):
+ * - 0-1m → 100% (full volume, very close)
+ * - 2m → ~80%
+ * - 3m → ~55%
+ * - 5m → ~30%
+ * - 8m → ~15%
+ * - 10m+ → 5% (minimum, barely audible)
+ *
+ * @param distance Distance in meters
+ * @param config Optional gain configuration
+ * @returns Gain as percentage (0-100)
+ */
+export declare function calculateLogarithmicGain(distance: number, config?: GainConfig): number;

package/dist/utils/spatial/gain-calc.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Gain Calculations
+ *
+ * Functions for calculating audio gain based on distance
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GAIN_CONFIG = void 0;
+exports.calculateLogarithmicGain = calculateLogarithmicGain;
+/**
+ * Default gain configuration
+ */
+exports.DEFAULT_GAIN_CONFIG = {
+    minDistance: 1.0, // Full volume at 1m or closer
+    maxDistance: 15.0, // Cannot hear beyond 15m
+    minGain: 5, // Minimum 5% at far distances
+    falloffRate: 0.15, // Controls how fast volume drops
+};
+/**
+ * Calculate gain based on distance using inverse-square law
+ *
+ * Uses inverse-square law (realistic sound propagation) with floor:
+ * Gain = 1 / (1 + k * distance²)
+ *
+ * Distance → Gain mapping (with defaults):
+ * - 0-1m → 100% (full volume, very close)
+ * - 2m → ~80%
+ * - 3m → ~55%
+ * - 5m → ~30%
+ * - 8m → ~15%
+ * - 10m+ → 5% (minimum, barely audible)
+ *
+ * @param distance Distance in meters
+ * @param config Optional gain configuration
+ * @returns Gain as percentage (0-100)
+ */
+function calculateLogarithmicGain(distance, config = {}) {
+    const { minDistance, maxDistance, minGain, falloffRate, } = { ...exports.DEFAULT_GAIN_CONFIG, ...config };
+    // Beyond max distance = minimum gain
+    if (distance >= maxDistance)
+        return minGain;
+    // Full volume within minimum distance
+    if (distance <= minDistance)
+        return 100;
+    // Inverse square falloff: gain = 1 / (1 + k * d²)
+    // This models realistic sound propagation in air
+    const effectiveDistance = distance - minDistance;
+    const attenuation = 1 / (1 + falloffRate * effectiveDistance * effectiveDistance);
+    // Scale to percentage range: minGain to 100
+    const gain = minGain + attenuation * (100 - minGain);
+    return Math.round(gain);
+}

package/dist/utils/spatial/head-position.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Head Position Calculations
+ *
+ * Functions for computing head/mouth position from body position
+ */
+import { Position } from '../../types/position';
+/**
+ * Compute estimated head/mouth position from body position
+ * Body position is typically at feet/base - add head height offset
+ *
+ * @param bodyPosition Body position (typically feet/base)
+ * @param headHeight Height offset to add (default: 1.6m)
+ * @returns Estimated head position
+ */
+export declare function computeHeadPosition(bodyPosition: Position, headHeight?: number): Position;
+/**
+ * Parse body height string to meters
+ * Handles various formats: "170", "170cm", "1.7m", etc.
+ *
+ * @param bodyHeightStr Body height string from participant data
+ * @param fallback Fallback height in meters (default: 1.6)
+ * @returns Height in meters
+ */
+export declare function parseBodyHeight(bodyHeightStr?: string, fallback?: number): number;
+/**
+ * Get vector from listener to target position
+ *
+ * @param listenerPosition Listener position
+ * @param targetPosition Target position
+ * @returns Vector from listener to target
+ */
+export declare function getVectorFromListener(listenerPosition: Position, targetPosition: Position): Position;

package/dist/utils/spatial/head-position.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Head Position Calculations
+ *
+ * Functions for computing head/mouth position from body position
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeHeadPosition = computeHeadPosition;
+exports.parseBodyHeight = parseBodyHeight;
+exports.getVectorFromListener = getVectorFromListener;
+/**
+ * Default head height offset in meters
+ * Average human head height above body origin
+ */
+const DEFAULT_HEAD_HEIGHT = 1.6;
+/**
+ * Compute estimated head/mouth position from body position
+ * Body position is typically at feet/base - add head height offset
+ *
+ * @param bodyPosition Body position (typically feet/base)
+ * @param headHeight Height offset to add (default: 1.6m)
+ * @returns Estimated head position
+ */
+function computeHeadPosition(bodyPosition, headHeight = DEFAULT_HEAD_HEIGHT) {
+    return {
+        x: bodyPosition.x,
+        y: bodyPosition.y + headHeight,
+        z: bodyPosition.z,
+    };
+}
+/**
+ * Parse body height string to meters
+ * Handles various formats: "170", "170cm", "1.7m", etc.
+ *
+ * @param bodyHeightStr Body height string from participant data
+ * @param fallback Fallback height in meters (default: 1.6)
+ * @returns Height in meters
+ */
+function parseBodyHeight(bodyHeightStr, fallback = 1.6) {
+    if (!bodyHeightStr)
+        return fallback;
+    const str = bodyHeightStr.toLowerCase().trim();
+    // Try parsing as number with optional unit
+    const numMatch = str.match(/^([\d.]+)\s*(cm|m)?$/);
+    if (numMatch) {
+        const value = parseFloat(numMatch[1]);
+        const unit = numMatch[2];
+        if (isNaN(value))
+            return fallback;
+        if (unit === 'm') {
+            return value;
+        }
+        else if (unit === 'cm' || value > 10) {
+            // Assume centimeters if > 10 or explicitly cm
+            return value / 100;
+        }
+        else {
+            return value;
+        }
+    }
+    return fallback;
+}
+/**
+ * Get vector from listener to target position
+ *
+ * @param listenerPosition Listener position
+ * @param targetPosition Target position
+ * @returns Vector from listener to target
+ */
+function getVectorFromListener(listenerPosition, targetPosition) {
+    return {
+        x: targetPosition.x - listenerPosition.x,
+        y: targetPosition.y - listenerPosition.y,
+        z: targetPosition.z - listenerPosition.z,
+    };
+}

package/dist/utils/spatial/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Spatial utilities - Re-exports all spatial calculation functions
+ */
+export * from './distance-calc';
+export * from './gain-calc';
+export * from './pan-calc';
+export * from './head-position';
+export * from './listener-calc';
+export * from './angle-calc';

package/dist/utils/spatial/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Spatial utilities - Re-exports all spatial calculation functions
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./distance-calc"), exports);
+__exportStar(require("./gain-calc"), exports);
+__exportStar(require("./pan-calc"), exports);
+__exportStar(require("./head-position"), exports);
+__exportStar(require("./listener-calc"), exports);
+__exportStar(require("./angle-calc"), exports);

package/dist/utils/spatial/listener-calc.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Listener Orientation Calculations
+ *
+ * Functions for computing listener orientation vectors
+ */
+import { Position, ListenerRight, Rotation } from '../../types/position';
+/**
+ * Full listener orientation (forward and up vectors)
+ */
+export interface ListenerOrientation {
+    forward: Position;
+    up: Position;
+}
+/**
+ * Calculate listener's right-ear vector from rotation
+ *
+ * @param rot Rotation in degrees (pitch, yaw, roll)
+ * @returns Right-ear unit vector (XZ plane)
+ */
+export declare function getListenerRightFromRotation(rot?: Rotation): ListenerRight;
+/**
+ * Calculate full listener orientation from camera vectors
+ *
+ * @param cameraPos Camera position
+ * @param lookAtPos Look-at target position
+ * @returns Forward and up vectors for Web Audio API
+ */
+export declare function calculateListenerOrientation(cameraPos: Position, lookAtPos: Position): ListenerOrientation | null;

package/dist/utils/spatial/listener-calc.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Listener Orientation Calculations
+ *
+ * Functions for computing listener orientation vectors
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getListenerRightFromRotation = getListenerRightFromRotation;
+exports.calculateListenerOrientation = calculateListenerOrientation;
+/**
+ * Calculate listener's right-ear vector from rotation
+ *
+ * @param rot Rotation in degrees (pitch, yaw, roll)
+ * @returns Right-ear unit vector (XZ plane)
+ */
+function getListenerRightFromRotation(rot) {
+    if (rot && typeof rot.y === 'number') {
+        const yawRad = (rot.y * Math.PI) / 180;
+        // Right ear vector - CLOCKWISE rotation (standard game engine convention)
+        // At yaw=0: facing +Z, right ear at +X → (1, 0)
+        // At yaw=90: facing +X, right ear at -Z → (0, -1)
+        return {
+            x: Math.cos(yawRad),
+            z: -Math.sin(yawRad),
+        };
+    }
+    // Fallback: assume facing forward with right ear to +X
+    return { x: 1, z: 0 };
+}
+/**
+ * Calculate full listener orientation from camera vectors
+ *
+ * @param cameraPos Camera position
+ * @param lookAtPos Look-at target position
+ * @returns Forward and up vectors for Web Audio API
+ */
+function calculateListenerOrientation(cameraPos, lookAtPos) {
+    // Calculate forward vector (from camera to look-at point)
+    const forwardX = lookAtPos.x - cameraPos.x;
+    const forwardY = lookAtPos.y - cameraPos.y;
+    const forwardZ = lookAtPos.z - cameraPos.z;
+    // Normalize forward vector
+    const forwardLen = Math.sqrt(forwardX * forwardX + forwardY * forwardY + forwardZ * forwardZ);
+    if (forwardLen < 0.001) {
+        return null;
+    }
+    const fwdX = forwardX / forwardLen;
+    const fwdY = forwardY / forwardLen;
+    const fwdZ = forwardZ / forwardLen;
+    // Calculate right vector (cross product of world up and forward)
+    const worldUp = { x: 0, y: 1, z: 0 };
+    const rightX = worldUp.y * fwdZ - worldUp.z * fwdY;
+    const rightY = worldUp.z * fwdX - worldUp.x * fwdZ;
+    const rightZ = worldUp.x * fwdY - worldUp.y * fwdX;
+    const rightLen = Math.sqrt(rightX * rightX + rightY * rightY + rightZ * rightZ);
+    if (rightLen < 0.001) {
+        // Forward is parallel to world up, use fallback
+        return {
+            forward: { x: fwdX, y: fwdY, z: fwdZ },
+            up: { x: 0, y: 1, z: 0 },
+        };
+    }
+    const rX = rightX / rightLen;
+    const rY = rightY / rightLen;
+    const rZ = rightZ / rightLen;
+    // Calculate true up vector (cross product of forward and right)
+    const upX = fwdY * rZ - fwdZ * rY;
+    const upY = fwdZ * rX - fwdX * rZ;
+    const upZ = fwdX * rY - fwdY * rX;
+    return {
+        forward: { x: fwdX, y: fwdY, z: fwdZ },
+        up: { x: upX, y: upY, z: upZ },
+    };
+}