@meimu/mutracer 0.1.0 → 0.1.2

package/lib/util/fromTHREE.d.ts

@@ -42,8 +42,12 @@ export interface THREEControls {
     removeEventListener(type: 'start' | 'end', listener: () => void): void;
     target?: THREE.Vector3;
     enableDamping?: boolean;
+    /** Damping per 60 Hz frame; synchronization adjusts it for elapsed time. Default undefined uses the control's own timing. */
+    dampingFactor?: number;
     autoRotate?: boolean;
     enabled?: boolean;
+    /** Optional OrbitControls polar-angle accessor. Default undefined. */ getPolarAngle?(): number;
+    /** Optional OrbitControls azimuthal-angle accessor. Default undefined. */ getAzimuthalAngle?(): number;
 }
 /** Three.js sources synchronized on each tick. */
 export interface THREESyncOptions extends FromTHREESceneOptions {
@@ -69,8 +73,10 @@ export declare class THREESync extends Sync {
     private _store;
     private _disposed;
     private _started;
+    private _gestureChanged;
     private _cameraState;
     private _lastUpdate?;
+    private _idleControlsState?;
     private _start;
     private _end;
     /** Subscribes to controls without converting sources or modifying the engine. */

package/lib/util/fromTHREE.js

@@ -139,13 +139,19 @@ function convertMaterial(threeMaterial, textureCache) {
     material.emissiveMap = convertTexture(standardMaterial.emissiveMap, textureCache);
     material.normalMap = convertTexture(standardMaterial.normalMap, textureCache);
     material.displacementMap = convertTexture(standardMaterial.displacementMap, textureCache);
+    const displacementBias = Number(standardMaterial.displacementBias);
+    if (Number.isFinite(displacementBias))
+        material.displacementBias = displacementBias;
     const displacementScale = Number(standardMaterial.displacementScale);
-    material.displacementScale = Number.isFinite(displacementScale)
+    // Three.js stores 1 even without a height map. Do not turn that inactive
+    // default into MuTracer's height when a texture is added after conversion.
+    material.displacementScale = Number.isFinite(displacementScale) &&
+        (standardMaterial.displacementMap != null || displacementScale !== 1)
         ? displacementScale
         : material.displacementScale;
     const displacementStepSize = Number(standardMaterial.userData.mutracerDisplacementStepSize);
     if (Number.isFinite(displacementStepSize)) {
-        material.displacementStepSize = Math.max(0.000001, displacementStepSize);
+        material.displacementStepSize = Math.max(0, displacementStepSize);
     }
     const uvProjection = standardMaterial.userData
         .mutracerDisplacementUvProjection;
@@ -255,6 +261,12 @@ function convertMaterial(threeMaterial, textureCache) {
             : fallback;
     };
     if (openPbr) {
+        for (const key of ['displacementScale', 'displacementBias', 'displacementStepSize']) {
+            const value = openPbr[key];
+            if (typeof value === 'number' && Number.isFinite(value)) {
+                material[key] = key === 'displacementStepSize' ? Math.max(0, value) : value;
+            }
+        }
         if (openPbr.specularAnisotropyModel !== undefined) {
             specularAnisotropyModelIndex(openPbr.specularAnisotropyModel);
             material.specularAnisotropyModel = openPbr.specularAnisotropyModel;
@@ -936,6 +948,25 @@ function convertScene(scene, options, store) {
         lights
     };
 }
+/** Inputs that can wake an idle OrbitControls instance, without inspecting its private inertia. */
+function orbitControlsState(camera, controls) {
+    if (!camera || !controls.getPolarAngle || !controls.getAzimuthalAngle)
+        return;
+    camera.parent?.updateWorldMatrix(true, false);
+    const state = [camera, controls.update, camera.parent, ...camera.position.toArray(), ...camera.quaternion.toArray(),
+        ...camera.scale.toArray(), ...camera.up.toArray(), camera.zoom, ...(camera.parent?.matrixWorld.elements ?? [])];
+    for (const [key, value] of Object.entries(controls)) {
+        // Pointer-down changes the gesture state without changing the view.
+        if (key.startsWith('_') || key === 'state')
+            continue;
+        const vector = value;
+        if (vector?.isVector3)
+            state.push(key, ...vector.toArray());
+        else if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'string')
+            state.push(key, value);
+    }
+    return state;
+}
 /**
  * Keeps one MuTracer scene in sync with a Three.js scene, reusing unchanged objects.
  * Skinning/morph targets run on the CPU with per-source-mesh dynamic geometry.
@@ -953,9 +984,11 @@ export class THREESync extends Sync {
     _store = createConversionStore();
     _disposed = false;
     _started = false;
+    _gestureChanged = false;
     _cameraState = [];
     _lastUpdate;
-    _start = () => { this._started = true; this.setActive(true); };
+    _idleControlsState;
+    _start = () => { this._started = true; this._gestureChanged = false; };
     _end = () => { this._started = false; };
     /** Subscribes to controls without converting sources or modifying the engine. */
     constructor(engine, _options = {}) {
@@ -971,25 +1004,55 @@ export class THREESync extends Sync {
         if (this._disposed)
             throw new Error('THREESync has been disposed');
         const now = performance.now(), controls = this._options.controls, sourceCamera = this._options.camera;
-        const dt = this._lastUpdate === undefined ? 0 : Math.min(.1, Math.max(0, (now - this._lastUpdate) / 1000));
+        const elapsed = this._lastUpdate === undefined ? 0 : Math.max(0, (now - this._lastUpdate) / 1000);
+        const dt = Math.min(.1, elapsed);
         this._lastUpdate = now;
         let moving = false, settled = false;
         if (controls && this._options.updateControls !== false) {
-            const position = sourceCamera?.position.clone(), zoom = sourceCamera?.zoom;
-            moving = !!controls.update(dt);
-            if (moving && !this._started && !controls.autoRotate && controls.enableDamping && position && sourceCamera && controls.target) {
-                const step = position.distanceTo(sourceCamera.position);
-                const zoomStep = Math.abs(Math.log(sourceCamera.zoom / zoom));
-                if (step < 5e-4 * sourceCamera.position.distanceTo(controls.target) && zoomStep < 5e-4) {
-                    controls.enableDamping = false;
-                    try {
-                        controls.update(0);
-                    }
-                    finally {
-                        controls.enableDamping = true;
+            const orbitInputs = orbitControlsState(sourceCamera, controls);
+            // OrbitControls applies pointer movement before synchronization. Keep a
+            // settled camera untouched on pointer-down until its inputs actually change.
+            const idle = (!this._started || !this._gestureChanged) && !controls.autoRotate && orbitInputs && this._idleControlsState && snapshotsEqual(orbitInputs, this._idleControlsState);
+            if (!idle) {
+                this._idleControlsState = undefined;
+                const position = sourceCamera?.position.clone(), rotation = sourceCamera?.quaternion.clone(), zoom = sourceCamera?.zoom;
+                const target = controls.target?.clone(), damping = controls.dampingFactor;
+                const frameDamping = controls.enableDamping && damping !== undefined && damping >= 0 && damping <= 1
+                    ? 1 - Math.pow(1 - damping, elapsed * 60) : undefined;
+                if (frameDamping !== undefined)
+                    controls.dampingFactor = frameDamping;
+                try {
+                    moving = !!controls.update(dt);
+                }
+                finally {
+                    if (frameDamping !== undefined)
+                        controls.dampingFactor = damping;
+                }
+                if (!this._started && !controls.autoRotate && controls.enableDamping && position && sourceCamera && controls.target) {
+                    const referenceScale = frameDamping ? damping / frameDamping : 1;
+                    const step = position.distanceTo(sourceCamera.position) * referenceScale;
+                    const zoomStep = Math.abs(Math.log(sourceCamera.zoom / zoom)) * referenceScale;
+                    const poseChanged = step > 0 || sourceCamera.zoom !== zoom || !!(orbitInputs && (!rotation.equals(sourceCamera.quaternion) || !target.equals(controls.target)));
+                    // End the remaining inertia once its 60 Hz movement is imperceptible.
+                    // update() can return false before that tail has actually stopped.
+                    if ((moving || poseChanged) && step < 5e-4 * sourceCamera.position.distanceTo(controls.target) && zoomStep < 5e-4) {
+                        controls.enableDamping = false;
+                        try {
+                            controls.update(0);
+                        }
+                        finally {
+                            controls.enableDamping = true;
+                        }
+                        moving = false;
+                        settled = true;
                     }
-                    moving = false;
-                    settled = true;
+                    // Once stopped, no more spherical/cartesian round trips occur until
+                    // a gesture, source pose, parent transform or public control option changes.
+                    if (orbitInputs && (settled || (!moving && !poseChanged)))
+                        this._idleControlsState = orbitControlsState(sourceCamera, controls);
+                }
+                else if (orbitInputs && !this._started && !controls.autoRotate && !moving) {
+                    this._idleControlsState = orbitControlsState(sourceCamera, controls);
                 }
             }
         }
@@ -1016,7 +1079,9 @@ export class THREESync extends Sync {
                 this._camera.copy(next);
             this.engine.camera = this._camera;
         }
-        this.setActive(this._started || moving || this._store.poseChanged || (cameraChanged && !settled));
+        if (this._started && (moving || cameraChanged))
+            this._gestureChanged = true;
+        this.setActive((this._started && this._gestureChanged) || moving || this._store.poseChanged || (cameraChanged && !settled));
     }
     /** Removes control subscriptions and caches. The last converted objects remain usable. */
     dispose() {
@@ -1025,6 +1090,7 @@ export class THREESync extends Sync {
         this._options.controls?.removeEventListener('start', this._start);
         this._options.controls?.removeEventListener('end', this._end);
         this._store = createConversionStore();
+        this._idleControlsState = undefined;
         this._disposed = true;
         super.dispose();
     }