@ume-group/contracts 0.2.1

package/dist/gausst.js

@@ -0,0 +1,307 @@
+/**
+ * Gausst Coordinate System Utilities
+ *
+ * Implements the coordinate system from Patent US8761580B2 and the
+ * legacy Gausst Maya plugin (gausstCamera.cpp).
+ *
+ * This system enables accurate camera matching between physical tracked
+ * cameras and virtual 3D scenes.
+ *
+ * Key features:
+ * - 35mm full-frame equivalent film gate (1.417" × 0.945")
+ * - FOV ↔ focal length conversion
+ * - Gausst rotation order: Tilt → Pan (negated) → Roll (negated)
+ * - Video plane sizing at distance
+ */
+// =============================================================================
+// Constants (from legacy gausstCamera.cpp)
+// =============================================================================
+export const GAUSST = {
+    // 35mm full-frame equivalent film gate
+    // From: MDistance(1.417, MDistance::uiUnit()) horizontal
+    // From: MDistance(.945, MDistance::uiUnit()) vertical
+    HORIZONTAL_APERTURE: 1.417, // inches (≈36mm)
+    VERTICAL_APERTURE: 0.945, // inches (≈24mm)
+    // Default values from legacy plugin
+    DEFAULT_FOCAL_LENGTH: 35, // mm
+    VIDEO_PLANE_DISTANCE: 500, // Maya units
+    DEFAULT_OVERSCAN: 1.3,
+    // Conversion constants
+    DEG_TO_RAD: Math.PI / 180,
+    RAD_TO_DEG: 180 / Math.PI,
+    MM_PER_INCH: 25.4,
+    // Default camera position (eye level, standing human)
+    DEFAULT_CAMERA_POSITION: [0, 1.6, 0],
+    DEFAULT_FOV: 60
+};
+// =============================================================================
+// FOV ↔ Focal Length Conversions
+// =============================================================================
+/**
+ * Convert field of view (degrees) to focal length (mm)
+ *
+ * Formula from legacy gausstCamera.h:
+ *   focalLength = ((aperture / 2) / tan(fieldOfView / 2)) * 25.4
+ *
+ * @param fovDegrees - Horizontal field of view in degrees
+ * @param apertureInches - Horizontal film aperture in inches (default: 35mm equivalent)
+ * @returns Focal length in millimeters
+ *
+ * @example
+ * fovToFocalLength(60) // ≈ 31mm
+ * fovToFocalLength(90) // ≈ 18mm
+ * fovToFocalLength(45) // ≈ 43mm
+ */
+export function fovToFocalLength(fovDegrees, apertureInches = GAUSST.HORIZONTAL_APERTURE) {
+    const fovRadians = fovDegrees * GAUSST.DEG_TO_RAD;
+    return ((apertureInches / 2) / Math.tan(fovRadians / 2)) * GAUSST.MM_PER_INCH;
+}
+/**
+ * Convert focal length (mm) to field of view (degrees)
+ *
+ * Inverse of fovToFocalLength
+ *
+ * @param focalLengthMM - Focal length in millimeters
+ * @param apertureInches - Horizontal film aperture in inches (default: 35mm equivalent)
+ * @returns Horizontal field of view in degrees
+ *
+ * @example
+ * focalLengthToFov(35) // ≈ 54.4°
+ * focalLengthToFov(50) // ≈ 39.6°
+ * focalLengthToFov(24) // ≈ 73.7°
+ */
+export function focalLengthToFov(focalLengthMM, apertureInches = GAUSST.HORIZONTAL_APERTURE) {
+    const fovRadians = 2 * Math.atan((apertureInches / 2 * GAUSST.MM_PER_INCH) / focalLengthMM);
+    return fovRadians * GAUSST.RAD_TO_DEG;
+}
+// =============================================================================
+// Rotation Utilities
+// =============================================================================
+/**
+ * Convert Gausst rotation (tilt, pan, roll) to Euler angles for Three.js
+ *
+ * From legacy gausstCamera.cpp moveTheCamera():
+ * - Maya rotation order: tilt, pan, roll
+ * - Pan and Roll are NEGATED before application
+ * - Three.js equivalent: 'YXZ' Euler order
+ *
+ * @param tiltDeg - Tilt (pitch) in degrees - rotation around X axis
+ * @param panDeg - Pan (yaw) in degrees - rotation around Y axis (will be negated)
+ * @param rollDeg - Roll in degrees - rotation around Z axis (will be negated)
+ * @returns Object with euler values and order for Three.js
+ *
+ * @example
+ * const { x, y, z, order } = gausst RotationToEuler(10, 20, 5);
+ * mesh.rotation.set(x, y, z);
+ * mesh.rotation.order = order;
+ */
+export function gausstRotationToEuler(tiltDeg, panDeg, rollDeg) {
+    return {
+        x: tiltDeg * GAUSST.DEG_TO_RAD, // Tilt (unchanged)
+        y: -panDeg * GAUSST.DEG_TO_RAD, // Pan (NEGATED)
+        z: -rollDeg * GAUSST.DEG_TO_RAD, // Roll (NEGATED)
+        order: 'YXZ'
+    };
+}
+/**
+ * Convert Three.js Euler angles back to Gausst rotation
+ *
+ * Inverse of gausst RotationToEuler - extracts tilt, pan, roll from Euler
+ * Assumes the object uses 'YXZ' rotation order
+ *
+ * @param x - Euler X rotation in radians
+ * @param y - Euler Y rotation in radians
+ * @param z - Euler Z rotation in radians
+ * @returns Gausst rotation as [tilt, pan, roll] in degrees
+ */
+export function eulerToGausstRotation(x, y, z) {
+    return [
+        x * GAUSST.RAD_TO_DEG, // Tilt
+        -y * GAUSST.RAD_TO_DEG, // Pan (negate back)
+        -z * GAUSST.RAD_TO_DEG // Roll (negate back)
+    ];
+}
+// =============================================================================
+// Video Plane Calculations
+// =============================================================================
+/**
+ * Calculate video plane dimensions at a given distance from camera
+ *
+ * From legacy gausstCamera.cpp draw():
+ *   horizontalSize = videoPolygonDistance * horizontalFilmApertureValue * 25.4f / focalLengthValue;
+ *   verticalSize = videoPolygonDistance * verticalFilmApertureValue * 25.4f / focalLengthValue;
+ *
+ * @param distance - Distance from camera in world units
+ * @param focalLengthMM - Focal length in millimeters
+ * @param horizontalAperture - Horizontal film aperture in inches
+ * @param verticalAperture - Vertical film aperture in inches
+ * @returns Width and height of video plane at that distance
+ *
+ * @example
+ * // Video plane at 10m with 35mm lens
+ * const { width, height } = getVideoPlaneSize(10, 35);
+ * // width ≈ 10.27m, height ≈ 6.85m
+ */
+export function getVideoPlaneSize(distance, focalLengthMM, horizontalAperture = GAUSST.HORIZONTAL_APERTURE, verticalAperture = GAUSST.VERTICAL_APERTURE) {
+    const width = (distance * horizontalAperture * GAUSST.MM_PER_INCH) / focalLengthMM;
+    const height = (distance * verticalAperture * GAUSST.MM_PER_INCH) / focalLengthMM;
+    return { width, height };
+}
+/**
+ * Calculate video plane dimensions using FOV instead of focal length
+ *
+ * @param distance - Distance from camera in world units
+ * @param fovDegrees - Horizontal field of view in degrees
+ * @returns Width and height of video plane at that distance
+ */
+export function getVideoPlaneSizeFromFov(distance, fovDegrees) {
+    const focalLength = fovToFocalLength(fovDegrees);
+    return getVideoPlaneSize(distance, focalLength);
+}
+// =============================================================================
+// Position Conversions
+// =============================================================================
+/**
+ * Convert tracking packet position to world coordinates
+ *
+ * From legacy gausstCamera.cpp moveTheCamera():
+ *   Xpos = convert4bytesToFloat(&theBuffer[6]) / 1000;
+ *   (Position comes as mm × 100, divide by 1000 to get meters)
+ *
+ * @param packetValue - Raw value from tracking packet (mm × 100)
+ * @returns Position in meters
+ */
+export function trackingPacketToMeters(packetValue) {
+    return packetValue / 100000; // mm×100 → meters
+}
+/**
+ * Convert meters to tracking packet format
+ *
+ * @param meters - Position in meters
+ * @returns Raw value for tracking packet (mm × 100)
+ */
+export function metersToTrackingPacket(meters) {
+    return Math.round(meters * 100000);
+}
+// =============================================================================
+// Aspect Ratio Utilities
+// =============================================================================
+/**
+ * Get the default aspect ratio from Gausst film gate
+ *
+ * @returns Aspect ratio (width / height)
+ */
+export function getGausstAspectRatio() {
+    return GAUSST.HORIZONTAL_APERTURE / GAUSST.VERTICAL_APERTURE;
+}
+/**
+ * Calculate vertical FOV from horizontal FOV using Gausst aspect ratio
+ *
+ * @param horizontalFovDeg - Horizontal field of view in degrees
+ * @returns Vertical field of view in degrees
+ */
+export function horizontalToVerticalFov(horizontalFovDeg) {
+    const aspectRatio = getGausstAspectRatio();
+    const hFovRad = horizontalFovDeg * GAUSST.DEG_TO_RAD;
+    const vFovRad = 2 * Math.atan(Math.tan(hFovRad / 2) / aspectRatio);
+    return vFovRad * GAUSST.RAD_TO_DEG;
+}
+/**
+ * Calculate horizontal FOV from vertical FOV using Gausst aspect ratio
+ *
+ * @param verticalFovDeg - Vertical field of view in degrees
+ * @returns Horizontal field of view in degrees
+ */
+export function verticalToHorizontalFov(verticalFovDeg) {
+    const aspectRatio = getGausstAspectRatio();
+    const vFovRad = verticalFovDeg * GAUSST.DEG_TO_RAD;
+    const hFovRad = 2 * Math.atan(Math.tan(vFovRad / 2) * aspectRatio);
+    return hFovRad * GAUSST.RAD_TO_DEG;
+}
+// =============================================================================
+// Three.js Integration Helpers
+// =============================================================================
+/**
+ * Apply Gausst rotation directly to a Three.js Object3D
+ *
+ * This is the primary function for setting rotation on 3D objects
+ * using the Gausst coordinate system.
+ *
+ * @param object - Three.js Object3D (mesh, camera, group, etc.)
+ * @param tiltDeg - Tilt (pitch) in degrees
+ * @param panDeg - Pan (yaw) in degrees
+ * @param rollDeg - Roll in degrees
+ *
+ * @example
+ * import * as THREE from 'three';
+ * const mesh = new THREE.Mesh(geometry, material);
+ * applyGausstRotation(mesh, 10, 45, 0); // 10° tilt, 45° pan
+ */
+export function applyGausstRotation(object, tiltDeg, panDeg, rollDeg) {
+    const euler = gausstRotationToEuler(tiltDeg, panDeg, rollDeg);
+    object.rotation.order = euler.order;
+    object.rotation.set(euler.x, euler.y, euler.z);
+}
+/**
+ * Configure a Three.js PerspectiveCamera with Gausst parameters
+ *
+ * @param camera - Three.js PerspectiveCamera
+ * @param fovDegrees - Horizontal field of view in degrees
+ * @param position - Camera position [x, y, z] in meters
+ * @param lookAt - Look-at target [x, y, z] in meters
+ *
+ * @example
+ * const camera = new THREE.PerspectiveCamera();
+ * configureGausstCamera(camera, 60, [0, 1.6, 0], [0, 1.6, -10]);
+ */
+export function configureGausstCamera(camera, fovDegrees, position, lookAt) {
+    // Note: Three.js PerspectiveCamera.fov is VERTICAL FOV
+    camera.fov = horizontalToVerticalFov(fovDegrees);
+    camera.position.set(...position);
+    camera.lookAt(...lookAt);
+    camera.updateProjectionMatrix();
+}
+// =============================================================================
+// Validation Utilities
+// =============================================================================
+/**
+ * Validate FOV is within reasonable bounds
+ *
+ * @param fovDegrees - Field of view to validate
+ * @returns true if valid, false otherwise
+ */
+export function isValidFov(fovDegrees) {
+    return fovDegrees > 1 && fovDegrees < 179;
+}
+/**
+ * Validate focal length is within reasonable bounds
+ *
+ * @param focalLengthMM - Focal length to validate
+ * @returns true if valid, false otherwise
+ */
+export function isValidFocalLength(focalLengthMM) {
+    return focalLengthMM > 1 && focalLengthMM < 1000;
+}
+/**
+ * Clamp FOV to valid range
+ *
+ * @param fovDegrees - FOV to clamp
+ * @returns Clamped FOV
+ */
+export function clampFov(fovDegrees) {
+    return Math.max(1, Math.min(179, fovDegrees));
+}
+/**
+ * Clamp rotation to reasonable range (-180 to 180)
+ *
+ * @param degrees - Rotation in degrees
+ * @returns Normalized rotation in -180 to 180 range
+ */
+export function normalizeRotation(degrees) {
+    let normalized = degrees % 360;
+    if (normalized > 180)
+        normalized -= 360;
+    if (normalized < -180)
+        normalized += 360;
+    return normalized;
+}

package/dist/gausst.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=gausst.test.d.ts.map

package/dist/gausst.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gausst.test.d.ts","sourceRoot":"","sources":["../src/gausst.test.ts"],"names":[],"mappings":""}

package/dist/gausst.test.js

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { GAUSST, fovToFocalLength, focalLengthToFov, gausstRotationToEuler, eulerToGausstRotation, normalizeRotation, isValidFov, clampFov, horizontalToVerticalFov, verticalToHorizontalFov } from './gausst';
+describe('fovToFocalLength', () => {
+    it('converts 60° FOV to ~31.19mm', () => {
+        const result = fovToFocalLength(60);
+        expect(result).toBeCloseTo(31.19, 1);
+    });
+});
+describe('fovToFocalLength / focalLengthToFov round-trip', () => {
+    it('recovers original FOV within 0.001°', () => {
+        const originalFov = 72.5;
+        const focal = fovToFocalLength(originalFov);
+        const recovered = focalLengthToFov(focal);
+        expect(recovered).toBeCloseTo(originalFov, 3);
+    });
+});
+describe('gausstRotationToEuler', () => {
+    it('negates pan and roll, keeps tilt', () => {
+        const tilt = 10;
+        const pan = 20;
+        const roll = 5;
+        const result = gausstRotationToEuler(tilt, pan, roll);
+        expect(result.x).toBeCloseTo(tilt * GAUSST.DEG_TO_RAD, 10);
+        expect(result.y).toBeCloseTo(-pan * GAUSST.DEG_TO_RAD, 10);
+        expect(result.z).toBeCloseTo(-roll * GAUSST.DEG_TO_RAD, 10);
+        expect(result.order).toBe('YXZ');
+    });
+});
+describe('gausstRotationToEuler / eulerToGausstRotation round-trip', () => {
+    it('recovers original tilt, pan, roll', () => {
+        const tilt = 15;
+        const pan = -30;
+        const roll = 7.5;
+        const euler = gausstRotationToEuler(tilt, pan, roll);
+        const [rTilt, rPan, rRoll] = eulerToGausstRotation(euler.x, euler.y, euler.z);
+        expect(rTilt).toBeCloseTo(tilt, 10);
+        expect(rPan).toBeCloseTo(pan, 10);
+        expect(rRoll).toBeCloseTo(roll, 10);
+    });
+});
+describe('normalizeRotation', () => {
+    it('normalizes boundary cases', () => {
+        expect(normalizeRotation(181)).toBeCloseTo(-179, 10);
+        expect(normalizeRotation(360)).toBeCloseTo(0, 10);
+        expect(normalizeRotation(-270)).toBeCloseTo(90, 10);
+    });
+});
+describe('isValidFov', () => {
+    it('rejects boundaries, accepts valid range', () => {
+        expect(isValidFov(1)).toBe(false);
+        expect(isValidFov(179)).toBe(false);
+        expect(isValidFov(60)).toBe(true);
+        expect(isValidFov(0)).toBe(false);
+    });
+});
+describe('clampFov', () => {
+    it('clamps to [1, 179]', () => {
+        expect(clampFov(200)).toBe(179);
+        expect(clampFov(0)).toBe(1);
+        expect(clampFov(-50)).toBe(1);
+        expect(clampFov(90)).toBe(90);
+    });
+});
+describe('horizontalToVerticalFov / verticalToHorizontalFov round-trip', () => {
+    it('recovers original horizontal FOV within 0.001°', () => {
+        const hFov = 65;
+        const vFov = horizontalToVerticalFov(hFov);
+        const recovered = verticalToHorizontalFov(vFov);
+        expect(recovered).toBeCloseTo(hFov, 3);
+    });
+});