three-cad-viewer 5.1.0 → 5.1.2

package/dist/core/viewer.d.ts

@@ -27,6 +27,11 @@ import { ViewerState } from "./viewer-state.js";
 import type { Display } from "../ui/display.js";
 import type { Vector3Tuple, QuaternionTuple } from "three";
 import { CollapseState, type ZebraColorScheme, type ZebraMappingMode, type StudioToneMapping, type StudioTextureMapping, type StudioBackground, type NotificationCallback, type RenderOptions, type ViewerOptions, type Shapes, type VisibilityState, type ActiveTab, type Axis, type ClipIndex, type ThemeInput, type BoundingBoxFlat, type Keymap } from "./types.js";
+/**
+ * Why the viewer renders continuously (see {@link Viewer.setLoopReason}): an
+ * animation is playing, a measure/select tool is active, or a screenshot is taken.
+ */
+export type LoopReason = "animation" | "tool" | "capture";
 /**
  * Material settings for the viewer.
  */
@@ -187,6 +192,8 @@ declare class Viewer {
     hasAnimationLoop: boolean;
     mixer: THREE.AnimationMixer | null;
     continueAnimation: boolean;
+    /** Reasons for continuous rendering; the render loop runs while any is set. */
+    private _loopReasons;
     clipAction: THREE.AnimationAction | null;
     shapeRenderer: ShapeRenderer | null;
     camera_distance: number;
@@ -219,7 +226,7 @@ declare class Viewer {
     /** True while the Studio (presentation) tab owns the render. PickHost member. */
     get studioActive(): boolean;
     zScale: number;
-    /** Whether the attached animation has moved parts (Play pressed or time slider moved). */
+    /** Whether the attached animation has moved parts (Play or time slider, not stopped since). */
     private _animationStarted;
     clipNormal0: Vector3Tuple | null;
     clipNormal1: Vector3Tuple | null;
@@ -346,6 +353,24 @@ declare class Viewer {
      * Start the animation loop
      */
     animate: () => void;
+    /**
+     * Add or remove a reason for continuous rendering. The render loop runs while at
+     * least one reason is set; otherwise the viewer renders on demand (camera changes
+     * and explicit updates), so an idle viewer costs no CPU/GPU time.
+     * @param reason - why continuous rendering is needed.
+     * @param flag - whether the reason applies.
+     */
+    setLoopReason(reason: LoopReason, flag: boolean): void;
+    /**
+     * Run the render loop only while the animation plays. When it stops (pause,
+     * stop, slider), render once so the final pose is shown.
+     */
+    private _setAnimationPlaying;
+    /**
+     * Start or stop the render loop directly. Prefer {@link setLoopReason}, which keeps
+     * the loop running while any other reason still needs it.
+     * @param flag - whether the render loop should run.
+     */
     toggleAnimationLoop(flag: boolean): void;
     /**
      * Draw the outline of the clip caps over the frame (Clip tab active only). Skipped
@@ -567,8 +592,9 @@ declare class Viewer {
      * Copy the world-space point under the cursor as `"x, y, z"` to the clipboard and
      * send it to the host as a `copiedPoint` notification (for hosts that block the
      * browser clipboard). Does nothing while parts may be displaced from their model
-     * positions — explode mode, an animation once started (Play or time slider), a
-     * z-scale other than 1 — or when no visible component is under the cursor.
+     * positions — explode mode, an animation that was played or scrubbed and not
+     * stopped since (Stop puts the parts back), a z-scale other than 1 — or when no
+     * visible component is under the cursor.
      * @returns true when a point was copied (the caller then consumes the key event).
      */
     copyPointUnderCursor(): boolean;

package/dist/scene/animation.d.ts

@@ -116,6 +116,16 @@ declare class Animation {
      * Dispose of animation resources.
      */
     dispose(): void;
+    /**
+     * Apply the current animation time to the objects without advancing it, so a
+     * single on-demand render shows the pose (e.g. after {@link setRelativeTime}).
+     */
+    apply(): void;
+    /**
+     * Restart the frame-time measurement, so resuming playback after a pause does
+     * not advance the animation by the whole pause.
+     */
+    resetClock(): void;
     /**
      * Update the animation mixer (call each frame when animating).
      */

package/dist/three-cad-viewer.esm.js

@@ -92263,6 +92263,20 @@ class Animation {
         this.tracks = [];
         this.root = null;
     }
+    /**
+     * Apply the current animation time to the objects without advancing it, so a
+     * single on-demand render shows the pose (e.g. after {@link setRelativeTime}).
+     */
+    apply() {
+        this.mixer?.update(0);
+    }
+    /**
+     * Restart the frame-time measurement, so resuming playback after a pause does
+     * not advance the animation by the whole pause.
+     */
+    resetClock() {
+        this.clock.reset();
+    }
     /**
      * Update the animation mixer (call each frame when animating).
      */
@@ -97834,7 +97848,7 @@ class Tools {
     }
 }
 
-const version = "5.1.0";
+const version = "5.1.2";
 
 /**
  * `PickedComponent` over a GPU id-pick result. Drives the shader
@@ -109429,6 +109443,8 @@ class Viewer {
      * @param updateMarker - enforce to redraw orientation marker after every ui activity
      */
     constructor(display, options, notifyCallback, pinAsPngCallback = null, updateMarker = true) {
+        /** Reasons for continuous rendering; the render loop runs while any is set. */
+        this._loopReasons = new Set();
         // Hide-undo stack: each meta-double-click hide pushes the leaf id + its pre-hide
         // state; meta-double-click on empty space pops and restores the last one. Lets a
         // hidden object be brought back without the tree (e.g. in Studio, where it's hidden).
@@ -109455,7 +109471,7 @@ class Viewer {
         this._capOutlineCamera = [];
         /** Pending redraw that adds the outline once the camera has settled. */
         this._capOutlineSettle = null;
-        /** Whether the attached animation has moved parts (Play pressed or time slider moved). */
+        /** Whether the attached animation has moved parts (Play or time slider, not stopped since). */
         this._animationStarted = false;
         // ---------------------------------------------------------------------------
         // Render Loop & Scene Updates
@@ -109864,12 +109880,19 @@ class Viewer {
                         this.clipAction.paused = false;
                     }
                     this.clipAction.play();
+                    this._setAnimationPlaying(true);
                     break;
                 case "pause":
                     this.clipAction.paused = !this.clipAction.paused;
+                    this._setAnimationPlaying(!this.clipAction.paused && this.clipAction.isRunning());
                     break;
                 case "stop":
                     this.clipAction.stop();
+                    // stop() restores the parts' original transforms (three.js
+                    // AnimationMixer._deactivateAction -> restoreOriginalState), so they are
+                    // at their model positions again and points can be copied.
+                    this._animationStarted = false;
+                    this._setAnimationPlaying(false);
                     break;
             }
         };
@@ -110759,10 +110782,7 @@ class Viewer {
                 return Promise.resolve({ task: taskId, dataUrl: null });
             }
             // canvas.toBlob can be very slow when animation loop is off!
-            const animationLoop = this.hasAnimationLoop;
-            if (!animationLoop) {
-                this.toggleAnimationLoop(true);
-            }
+            this.setLoopReason("capture", true);
             this.rendered.orientationMarker.setVisible(false);
             this.update(true);
             return this.display.captureCanvas({
@@ -110780,10 +110800,8 @@ class Viewer {
                     }
                 },
                 onComplete: () => {
-                    // Restore animation loop to original state
-                    if (!animationLoop) {
-                        this.toggleAnimationLoop(false);
-                    }
+                    // Restore the loop to what the other reasons need
+                    this.setLoopReason("capture", false);
                     this.rendered.orientationMarker.setVisible(true);
                     this.update(true);
                 },
@@ -111181,14 +111199,13 @@ class Viewer {
             return;
         }
         logger.debug("Animation initialized");
-        if (!this.hasAnimationLoop) {
-            this.toggleAnimationLoop(true);
-        }
         this.state.set("animationMode", label === "E" ? "explode" : "animation");
         this._animationStarted = false;
         this.clipAction = this.animation.animate(this.rendered.nestedGroup.rootGroup, duration, speed, repeat);
         // Reset animation slider to start
         this.state.set("animationSliderValue", 0);
+        // Not playing yet: render on demand only (the loop starts with Play).
+        this._setAnimationPlaying(false);
     }
     /**
      * Check whether animation object exists
@@ -111205,7 +111222,7 @@ class Viewer {
         }
         this.state.set("animationMode", "none");
         this._animationStarted = false;
-        this.toggleAnimationLoop(false);
+        this.setLoopReason("animation", false);
     }
     /**
      * Set the animation to a specific relative time (0-1).
@@ -111217,6 +111234,8 @@ class Viewer {
             this._animationStarted = true;
         this.animation.setRelativeTime(fraction);
         this.state.set("animationSliderValue", fraction * 1000);
+        // Setting a time pauses the animation: stop the loop and show the new pose.
+        this._setAnimationPlaying(false);
     }
     /**
      * Get the current relative animation time (0-1).
@@ -111225,6 +111244,44 @@ class Viewer {
     getRelativeTime() {
         return this.animation.getRelativeTime();
     }
+    /**
+     * Add or remove a reason for continuous rendering. The render loop runs while at
+     * least one reason is set; otherwise the viewer renders on demand (camera changes
+     * and explicit updates), so an idle viewer costs no CPU/GPU time.
+     * @param reason - why continuous rendering is needed.
+     * @param flag - whether the reason applies.
+     */
+    setLoopReason(reason, flag) {
+        if (flag) {
+            this._loopReasons.add(reason);
+        }
+        else {
+            this._loopReasons.delete(reason);
+        }
+        const run = this._loopReasons.size > 0;
+        if (run !== this.hasAnimationLoop)
+            this.toggleAnimationLoop(run);
+    }
+    /**
+     * Run the render loop only while the animation plays. When it stops (pause,
+     * stop, slider), render once so the final pose is shown.
+     */
+    _setAnimationPlaying(playing) {
+        if (playing) {
+            // Resume without jumping ahead by the time spent paused.
+            this.animation.resetClock();
+        }
+        this.setLoopReason("animation", playing);
+        if (!playing && this._rendered !== null) {
+            this.animation.apply();
+            this.update(true, false);
+        }
+    }
+    /**
+     * Start or stop the render loop directly. Prefer {@link setLoopReason}, which keeps
+     * the loop running while any other reason still needs it.
+     * @param flag - whether the render loop should run.
+     */
     toggleAnimationLoop(flag) {
         if (flag) {
             this.continueAnimation = true;
@@ -111375,6 +111432,7 @@ class Viewer {
             // Hide the topo filter (+ detach its shortcuts) for a clean cleared canvas.
             this.display.shapeFilterDropDownMenu.show(false);
             // stop animation
+            this._loopReasons.clear();
             this.hasAnimationLoop = false;
             this.continueAnimation = false;
             // remove change listener if exists
@@ -111957,8 +112015,9 @@ class Viewer {
      * Copy the world-space point under the cursor as `"x, y, z"` to the clipboard and
      * send it to the host as a `copiedPoint` notification (for hosts that block the
      * browser clipboard). Does nothing while parts may be displaced from their model
-     * positions — explode mode, an animation once started (Play or time slider), a
-     * z-scale other than 1 — or when no visible component is under the cursor.
+     * positions — explode mode, an animation that was played or scrubbed and not
+     * stopped since (Stop puts the parts back), a z-scale other than 1 — or when no
+     * visible component is under the cursor.
      * @returns true when a point was copied (the caller then consumes the key event).
      */
     copyPointUnderCursor() {
@@ -114069,7 +114128,7 @@ class Display {
             if (flag && this.viewer.isStudioActive) {
                 return;
             }
-            this.viewer.toggleAnimationLoop(flag);
+            this.viewer.setLoopReason("tool", flag);
             if (flag) {
                 // Delegate state mutations to Viewer
                 this.viewer.activateTool(name, true);