three-cad-viewer 5.0.7 → 5.1.1

package/dist/core/picking-controller.d.ts

@@ -62,6 +62,23 @@ export declare class PickingController {
     private onIdHoverMove;
     /** Cursor left the canvas → clear any hover highlight. */
     private onIdHoverLeave;
+    /**
+     * Pick the visible component under the cursor with the current topo filter, or
+     * `null` when the cursor is off the canvas or over background.
+     */
+    private pickUnderCursor;
+    /**
+     * World-space point on the visible component under the cursor (same pick as the
+     * hover), or `null` when there is none or the GPU lacks the position attachment.
+     */
+    pointUnderCursor(): THREE.Vector3 | null;
+    /**
+     * Tree-row hover: HOVER the faces of the tree node at `path` (leaf or group), or
+     * clear when `null`. Drops the canvas hover target first — otherwise the next
+     * render's {@link handleIdHover} (cursor outside the canvas) would release that
+     * stale target and wipe the tree hover with it.
+     */
+    setTreeHover(path: string | null): void;
     /**
      * Whether hover preselection (highlight + status line) is active. Disabled for GDS:
      * dense, stacked, instance-unrolled layout data where per-pixel hover flickers

package/dist/core/types.d.ts

@@ -136,6 +136,8 @@ export interface ChangeNotification {
     clip_normal_1?: StateChange<Vector3Tuple | null>;
     clip_normal_2?: StateChange<Vector3Tuple | null>;
     lastPick?: StateChange<PickInfo | null>;
+    /** Point copied with Ctrl/Cmd-C (event, sent on every copy; `old` is always null). */
+    copiedPoint?: StateChange<Vector3Tuple>;
     [key: string]: StateChange<unknown> | undefined;
 }
 /** Callback for notifications */

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;
@@ -206,6 +213,12 @@ declare class Viewer {
     private _suppressUpdate;
     private _zebraSettingsApplied;
     idPicker: IdPicker | null;
+    /** Outline of the clip caps; created on first use, kept across renders. */
+    private _capOutline;
+    /** Camera world + projection matrix of the previous outline frame (motion test). */
+    private _capOutlineCamera;
+    /** Pending redraw that adds the outline once the camera has settled. */
+    private _capOutlineSettle;
     pickingController: PickingController;
     private _studioManager;
     /** Environment manager — proxied from StudioManager for display.ts access. */
@@ -213,6 +226,8 @@ 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). */
+    private _animationStarted;
     clipNormal0: Vector3Tuple | null;
     clipNormal1: Vector3Tuple | null;
     clipNormal2: Vector3Tuple | null;
@@ -338,7 +353,38 @@ 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
+     * while the camera moves (drag, wheel, damping, preset views): the outline pass
+     * renders faces and caps a second time, so it is drawn once the camera has been
+     * still for {@link CAP_OUTLINE_SETTLE_MS}.
+     */
+    private _renderCapOutline;
+    /** Whether the camera's world or projection matrix changed since the last call. */
+    private _cameraMovedSinceLastOutline;
+    /** Redraw once the camera has settled, so the skipped outline appears. */
+    private _scheduleCapOutline;
+    /** Cancel a pending outline redraw. */
+    private _cancelCapOutline;
     /**
      * Remove all assets and event handlers. Call when done with the viewer.
      *
@@ -540,6 +586,17 @@ declare class Viewer {
     get lastObject(): PickedComponent | null;
     /** Last committed selection. */
     get lastSelection(): PickedComponent | null;
+    /** Tree-row hover: highlight the faces of the node at `path`, or clear on `null`. */
+    handleTreeHover: (path: string | null) => void;
+    /**
+     * 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.
+     * @returns true when a point was copied (the caller then consumes the key event).
+     */
+    copyPointUnderCursor(): boolean;
     /** Enable/disable the double-click pick handler (on when no tool is active). */
     setPickHandler(flag: boolean): void;
     /** Enable/disable click+key selection input (on while a select/measure tool is active). */

package/dist/rendering/cap-outline.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Screen-space outline of the clip caps (CAD mode).
+ *
+ * The caps carry no geometry of their own outline, and the faces next to a cut may
+ * face away from the camera or belong to a touching solid, so the outline is found
+ * in screen space instead:
+ *
+ * 1. Id pass into an offscreen target (color + depth + stencil):
+ *    - visible faces as black occluders (face pick layer + override material), so a
+ *      cap hidden behind another part gets no outline; face pixels within the line
+ *      width of a clip plane write {@link CUT_EDGE_ID} instead, which draws the cut
+ *      contour on the faces themselves (needed when the caps are behind the faces),
+ *    - the stencil meshes and caps (on {@link CAP_LAYER}) with each cap writing its
+ *      own id instead of its shaded color — the same stencil sequence as the main
+ *      render, since three orders them identically (material creation order).
+ * 2. Composite over the canvas: a pixel is drawn in the edge color when its id is
+ *    larger than a neighbour's id, which yields a line on one side of every boundary
+ *    cap↔cap, cap↔surface and cap↔background. Cut-edge pixels are the largest id, so
+ *    where they meet a cap only they are drawn — one line, not two.
+ */
+import * as THREE from "three";
+/** Render layer of the clip stencil meshes and cap quads (pick layers use 1-3). */
+export declare const CAP_LAYER = 4;
+/** Id of face pixels on the cut contour (larger than any cap id). */
+export declare const CUT_EDGE_ID = 16777215;
+/** Encode a cap id (1..2^24-1) as an exact 8-bit RGB color (0 = no cap). */
+export declare function capIdColor(id: number): THREE.Vector3;
+/** Per-frame inputs of {@link CapOutlinePass.render}. */
+export interface CapOutlineOptions {
+    /** Clip planes and mode of the face materials (for the occluders). */
+    planes: THREE.Plane[];
+    intersection: boolean;
+    /** Draw faces as occluders (off in transparent mode: caps show through faces). */
+    occlude: boolean;
+    /** Outline color (sRGB hex). */
+    color: number;
+    /** Switch the cap materials between shaded output and id output. */
+    setCapIdPass: (flag: boolean) => void;
+}
+export declare class CapOutlinePass {
+    private target;
+    private readonly occluder;
+    /** Width of the cut contour on the faces, in device pixels (= outline width). */
+    private readonly cutWidth;
+    private readonly composite;
+    private readonly quadScene;
+    private readonly quadCamera;
+    private readonly quad;
+    private readonly size;
+    private readonly savedClearColor;
+    private readonly savedViewport;
+    constructor();
+    private ensureTarget;
+    /**
+     * Render the id pass and draw the outline over the current (canvas) framebuffer.
+     * Call right after the main scene render.
+     */
+    render(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera, options: CapOutlineOptions): void;
+    dispose(): void;
+}

package/dist/rendering/clip-style.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Section hatching for clip caps (CAD mode, shader-only). The per-solid cap quads
+ * draw hatch lines anchored to the plane (stable while rotating/panning) whose
+ * spacing is kept at a constant pixel distance by a per-frame world-per-pixel
+ * uniform. The outline of the caps is drawn separately (see cap-outline.ts); for its
+ * id pass the same cap shader can output the cap's id instead of its color.
+ *
+ * All shared uniforms are plain `{ value }` objects held by reference, so a single
+ * write (e.g. the per-frame hatch spacing) updates every patched material without a
+ * recompile.
+ */
+import * as THREE from "three";
+/** Distance between hatch lines in pixels. */
+export declare const HATCH_SPACING_PX = 8;
+/** Width of a hatch line in pixels. */
+export declare const HATCH_LINE_WIDTH_PX = 1;
+/** Uniforms shared by all hatch patched cap materials of one clipping setup. */
+export interface HatchUniforms {
+    /** World units between hatch lines (before the per-solid scale); set per frame. */
+    uHatchSpacing: {
+        value: number;
+    };
+    /** Half the cap quad size: maps the quad's [-1, 1] geometry to plane units. */
+    uCapHalfSize: {
+        value: number;
+    };
+    uHatchLineWidth: {
+        value: number;
+    };
+    uHatchOn: {
+        value: number;
+    };
+    /** 1 while the cap outline id pass renders: caps output their id, not a color. */
+    uCapIdPass: {
+        value: number;
+    };
+}
+export declare function createHatchUniforms(capHalfSize: number): HatchUniforms;
+/**
+ * World units covered by one screen pixel at the given point (exact for an
+ * orthographic camera; at the point's distance for a perspective camera).
+ */
+export declare function worldPerPixel(camera: THREE.Camera, point: THREE.Vector3, height: number): number;
+/**
+ * Patch a cap quad material to draw section hatching. `index` is the solid's index
+ * among the caps of its plane; it selects the hatch direction and spacing. `capId`
+ * is the cap's unique id color for the outline id pass (see `capIdColor`).
+ */
+export declare function patchHatchMaterial(material: THREE.Material, uniforms: HatchUniforms, index: number, capId: THREE.Vector3): void;

package/dist/rendering/highlight.d.ts

@@ -146,6 +146,11 @@ export declare class HighlightController {
      * when `null`. Mirrors {@link selectSolid} for the transient hover state.
      */
     setHoverSolid(solidPath: string | null): void;
+    /**
+     * HOVER every FACE at or below the tree path `prefix` (a leaf or a whole group),
+     * or clear hover when `null`. Drives the tree-row hover highlight.
+     */
+    setHoverPath(prefix: string | null): void;
     /** Set or clear the SELECTED flag for a single component id. */
     setSelected(id: number, flag: boolean): void;
     /** Whether a component currently carries the SELECTED flag. */

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/scene/clipping.d.ts

@@ -117,6 +117,9 @@ declare class Clipping extends THREE.Group {
     private _planeMeshGroup;
     /** Per-solid stencil/cap units, the unit of screen-size culling. */
     private _capUnits;
+    /** Shared uniforms of the section hatching on all cap quads. */
+    private _hatchUniforms;
+    private _hatchCenter;
     /**
      * Whether {@link cull} last ran with clipping active. Lets the inactive path
      * gate stencils/caps off exactly once, then early-return on later still frames.
@@ -191,6 +194,10 @@ declare class Clipping extends THREE.Group {
      * @param flag - True to show, false to hide.
      */
     setVisible: (flag: boolean) => void;
+    /** Whether any solid has clip caps (the cap outline pass has work to do). */
+    get hasCaps(): boolean;
+    /** Switch all cap materials between shaded output and outline id output. */
+    setCapIdPass: (flag: boolean) => void;
     /**
      * Bound the per-frame stencil/cap draw work to keep large assemblies from
      * overrunning the GPU watchdog on clip+rotate (see {@link CAP_CULL_MIN_PX}).