viral-viewer-2 7.2.4 → 7.2.6

package/dist/components/custom-objects/viral-batched-mesh.d.ts

@@ -2,6 +2,11 @@ import { Box3, BufferGeometry, type Color, type Material, Mesh, Vector3 } from "
 import { type LineMaterial } from "three/examples/jsm/Addons";
 import { type BufferElement } from "../..";
 import type { WorkerThreadPool } from "../worker/base/worker-pool";
+/**
+ * Special alpha value to mark selected vertices for fast outline detection.
+ * The AlphaSelectionOutlinePass detects this value with ZERO extra render passes.
+ */
+export declare const SELECTION_ALPHA = 0.99;
 export declare class ViralBatchedMesh extends Mesh {
     globalMaterialIndex: number;
     private workerPool;
@@ -110,6 +115,13 @@ export declare class ViralBatchedMesh extends Mesh {
         elementId: string;
     }[];
     unselect(): void;
+    /**
+     * Set alpha value for elements (used for selection marking)
+     * This is VERY fast - only updates alpha channel, no geometry copying
+     *
+     * When setting alpha to 1.0 (removing selection), respects hidden/isolated state
+     */
+    private _setSelectionAlpha;
     /**
      * Hide elements by setting their alpha to 0 (GPU-accelerated)
      * Hidden elements are discarded in fragment shader - no rendering cost

package/dist/components/custom-objects/viral-bim-world.d.ts

@@ -11,7 +11,6 @@ import { ViralInstancedMeshV2 } from "./viral-instanced-mesh-v2";
  */
 export declare class ViralBIMWorld extends Mesh {
     workerPool: WorkerThreadPool | null;
-    private _mergePositionsWorker;
     bimModels: ViralBIMModel[];
     constructor();
     private _initializeWorkerPool;
@@ -99,11 +98,6 @@ export declare class ViralBIMWorld extends Mesh {
      * @returns Float32Array of positions or null if no selection
      */
     getSelectedElementsPositions(): Float32Array | null;
-    /**
-     * Async version — offloads vertex merging to a Web Worker so the main thread stays unblocked.
-     * Automatically cancels any in-flight request when called again.
-     */
-    getSelectedElementsPositionsAsync(): Promise<Float32Array | null>;
     /**
      * Changes the color of multiple elements in the merged mesh.
      * Works with RGBA color buffer (preserves existing alpha values)

package/dist/components/custom-objects/viral-instanced-mesh-v2.d.ts

@@ -1,6 +1,11 @@
 import { Box3, BufferGeometry, Color, InstancedMesh, type Material, Matrix4, Object3D, Vector3 } from "three";
 import { type LineMaterial } from "three/examples/jsm/Addons";
 import { type BufferElement } from "../..";
+/**
+ * Special alpha value to mark selected instances for fast outline detection.
+ * Note: Instanced meshes use a separate instanceSelected attribute instead of alpha.
+ */
+export declare const SELECTION_ALPHA = 0.99;
 export declare class ViralInstancedMeshV2 extends Object3D {
     protected material?: Material | undefined;
     globalMaterialIndex: number;
@@ -51,6 +56,12 @@ export declare class ViralInstancedMeshV2 extends Object3D {
         };
     }[]): void;
     unselect(): void;
+    /**
+     * Set instance selection state for fast outline detection
+     * @param elements - Elements to set selection for
+     * @param selected - 1.0 = selected, 0.0 = not selected
+     */
+    private _setInstanceSelection;
     /**
      * Changes the color of multiple elements.
      * @param elements - An array of elements, each containing `modelId` and `elementId`.
@@ -163,7 +174,10 @@ export declare class ViralInstancedMeshV2 extends Object3D {
      */
     isElementVisible(modelId: string, elementId: string): boolean;
     /**
-     * Inject per-instance opacity shader into material
+     * Inject per-instance opacity and selection shader into material
+     * Enables:
+     * - Per-instance opacity (ghosting, hiding)
+     * - Selection alpha marker (for fast outline detection via AlphaSelectionOutlinePass)
      * Must be called after material is set and before rendering
      */
     injectOpacityShader(): void;
@@ -171,6 +185,11 @@ export declare class ViralInstancedMeshV2 extends Object3D {
      * Ensure all instanced meshes have opacity attribute
      */
     private _ensureOpacityAttributes;
+    /**
+     * Ensure all instanced meshes have selection attribute
+     * Used for fast outline detection via AlphaSelectionOutlinePass
+     */
+    private _ensureSelectionAttributes;
     /**
      * Update opacity for specific instances
      */

package/dist/components/post-processing/alpha-selection-outline-pass.d.ts

@@ -0,0 +1,49 @@
+import type { WebGLRenderer } from "three";
+import { Color, type Vector2, type WebGLRenderTarget } from "three";
+import { Pass } from "three/examples/jsm/postprocessing/Pass";
+/**
+ * Alpha-Based Selection Outline Pass (FASTEST)
+ *
+ * This is the FASTEST possible selection outline implementation because:
+ * - ZERO extra render passes for selection mask
+ * - ZERO geometry copying
+ * - O(pixels) cost - same for 1 or 10,000 selected elements
+ *
+ * How it works:
+ * 1. Selected elements have their alpha set to a special value (SELECTION_ALPHA = 0.99)
+ * 2. This pass detects edges where alpha equals SELECTION_ALPHA
+ * 3. Applies outline effect at those edges
+ *
+ * Requirements:
+ * - ViralBatchedMesh/ViralInstancedMesh must set alpha = 0.99 for selected vertices
+ * - Must run after main render pass but before tone mapping
+ */
+export interface AlphaSelectionOutlineOptions {
+    /** Outline color (default: accent color) */
+    outlineColor: Color;
+    /** Outline opacity 0-1 (default: 1.0) */
+    outlineOpacity: number;
+    /** Outline thickness in pixels (default: 2.0) */
+    outlineThickness: number;
+    /** Alpha value that indicates selection (default: 0.99) */
+    selectionAlpha: number;
+    /** Tolerance for alpha detection (default: 0.005) */
+    alphaTolerance: number;
+}
+export declare const SELECTION_ALPHA = 0.99;
+export declare class AlphaSelectionOutlinePass extends Pass {
+    private resolution;
+    private options;
+    private outlineMaterial;
+    private copyMaterial;
+    private fsQuad;
+    /** Fast bypass during camera movement */
+    bypass: boolean;
+    /** Whether there's any selection active */
+    hasSelection: boolean;
+    constructor(resolution: Vector2, options?: Partial<AlphaSelectionOutlineOptions>);
+    setOptions(options: Partial<AlphaSelectionOutlineOptions>): void;
+    render(renderer: WebGLRenderer, writeBuffer: WebGLRenderTarget, readBuffer: WebGLRenderTarget, _deltaTime?: number, _maskActive?: boolean): void;
+    setSize(width: number, height: number): void;
+    dispose(): void;
+}

package/dist/components/post-processing/post-processing-renderer.d.ts

@@ -6,6 +6,7 @@ import { ShaderPass } from "three/examples/jsm/postprocessing/ShaderPass";
 import { SMAAPass } from "three/examples/jsm/postprocessing/SMAAPass";
 import { type ViralViewerApi } from "../..";
 import { DevicePerformanceChecker } from "../../utils/device";
+import { AlphaSelectionOutlinePass } from "./alpha-selection-outline-pass";
 import { type ScreenSpaceEdgesOptions, ScreenSpaceEdgesPass } from "./screen-space-edges-pass";
 import { type SelectionOutlineOptions, SelectionOutlinePass } from "./selection-outline-pass";
 export declare class PostProcessingRenderer {
@@ -26,6 +27,7 @@ export declare class PostProcessingRenderer {
     outlinePass: OutlinePass | null;
     screenSpaceEdgesPass: ScreenSpaceEdgesPass | null;
     selectionOutlinePass: SelectionOutlinePass | null;
+    alphaSelectionOutlinePass: AlphaSelectionOutlinePass | null;
     n8aoPass: any;
     perfChecker: DevicePerformanceChecker;
     constructor(renderer: WebGLRenderer, viralViewerApi: ViralViewerApi);
@@ -127,6 +129,11 @@ export declare class PostProcessingRenderer {
      * @param positions - Merged Float32Array of selected element positions, or null to clear
      */
     updateSelectionOutline(positions: Float32Array | null): void;
+    /**
+     * Notify the outline pass whether elements are currently selected.
+     * The GPU reads selection state directly from vertex colors — no data transfer needed.
+     */
+    setSelectionOutlineActive(hasSelection: boolean): void;
     /**
      * Enable selection outline rendering
      */
@@ -158,4 +165,43 @@ export declare class PostProcessingRenderer {
      * Set selection outline thickness in pixels
      */
     setSelectionOutlineThickness(thickness: number): void;
+    /**
+     * Initialize alpha-based selection outline pass
+     * ZERO extra render passes - detects selection via alpha channel in main render
+     * Cost: 1 fullscreen pass only (no geometry re-render)
+     *
+     * This is MUCH faster than SelectionOutlinePass for large selections
+     * Works with both batched meshes (per-vertex alpha) and instanced meshes (per-instance alpha)
+     */
+    initAlphaSelectionOutlinePass(): void;
+    /**
+     * Enable alpha selection outline rendering
+     */
+    enableAlphaSelectionOutline(): void;
+    /**
+     * Disable alpha selection outline rendering
+     */
+    disableAlphaSelectionOutline(): void;
+    /**
+     * Bypass alpha selection outline (instant, zero cost)
+     */
+    bypassAlphaSelectionOutline(): void;
+    /**
+     * Resume alpha selection outline after bypassing
+     */
+    resumeAlphaSelectionOutline(): void;
+    /**
+     * Set alpha selection outline color
+     */
+    setAlphaSelectionOutlineColor(color: Color | number | string): void;
+    /**
+     * Set alpha selection outline thickness in pixels
+     */
+    setAlphaSelectionOutlineThickness(thickness: number): void;
+    /**
+     * Update alpha selection outline state
+     * Call this when selection changes
+     * @param hasSelection - Whether there's any selection active
+     */
+    updateAlphaSelectionOutline(hasSelection: boolean): void;
 }

package/dist/components/post-processing/selection-outline-pass.d.ts

@@ -1,14 +1,17 @@
-import type { Camera, WebGLRenderer } from "three";
-import { Color, Scene, type Vector2, WebGLRenderTarget } from "three";
+import type { Camera, Vector2, WebGLRenderer } from "three";
+import { Color, type Scene, WebGLRenderTarget } from "three";
 import { Pass } from "three/examples/jsm/postprocessing/Pass";
 /**
  * Selection Outline Pass
  *
- * Lightweight outline effect for selected elements in merged geometry.
- * Cost: 1 extra draw call (for mask) + 1 fullscreen Sobel pass
+ * GPU-based outline effect for selected elements.
+ * Renders the scene with a filter shader that outputs white only for
+ * fragments matching the selection color — zero CPU vertex work.
+ *
+ * Cost: 1-2 extra draw calls (mask render with overrideMaterial) + 1 fullscreen Sobel pass
  *
  * Process:
- * 1. Render selected geometry to mask texture (white on black)
+ * 1. Render entire scene with overrideMaterial that filters by SELECT_COLOR
  * 2. Sobel edge detection on mask
  * 3. Composite colored edges over scene
  */
@@ -25,32 +28,33 @@ export interface SelectionOutlineOptions {
     occludedOpacity: number;
 }
 export declare class SelectionOutlinePass extends Pass {
+    private scene;
     private camera;
     private resolution;
     private options;
     private maskRenderTarget;
     private maskDepthRenderTarget;
-    private maskMaterial;
+    private selectionFilterMaterial;
+    private selectionFilterMaterialDepth;
     private outlineMaterial;
     private copyMaterial;
-    private maskScene;
-    private selectionMesh;
-    private selectionGeometry;
-    private selectionBuffer;
-    private selectionAttribute;
     private fsQuad;
     private hasSelection;
     /**
-     * 🔧 FAST TOGGLE:
+     * FAST TOGGLE:
      * - `bypass = false`: Full outline rendering (normal mode)
      * - `bypass = true`: Pass runs but just copies input to output (very fast, no mask render)
      */
     bypass: boolean;
-    constructor(_scene: Scene, camera: Camera, resolution: Vector2, options?: Partial<SelectionOutlineOptions>);
+    constructor(scene: Scene, camera: Camera, resolution: Vector2, options?: Partial<SelectionOutlineOptions>);
+    /**
+     * Notify the pass whether there is an active selection.
+     * No data transfer needed — the GPU reads selection state from vertex colors.
+     */
+    setHasSelection(hasSelection: boolean): void;
     /**
-     * Update selection geometry from buffer elements
-     * Call this when selection changes
-     * @param positions - Merged Float32Array of all selected element positions
+     * Legacy method — kept for backward compatibility.
+     * With the GPU-based approach, this just toggles hasSelection.
      */
     updateSelectionGeometry(positions: Float32Array | null): void;
     /**
@@ -62,6 +66,7 @@ export declare class SelectionOutlinePass extends Pass {
      */
     setOptions(options: Partial<SelectionOutlineOptions>): void;
     render(renderer: WebGLRenderer, writeBuffer: WebGLRenderTarget, readBuffer: WebGLRenderTarget, _deltaTime?: number, _maskActive?: boolean): void;
+    private _renderCopyPass;
     setSize(width: number, height: number): void;
     dispose(): void;
 }

package/dist/components/post-processing/stencil-selection-outline-pass.d.ts

@@ -0,0 +1,54 @@
+import type { WebGLRenderer } from "three";
+import { Color, type Vector2, type WebGLRenderTarget } from "three";
+import { Pass } from "three/examples/jsm/postprocessing/Pass";
+/**
+ * Stencil-Based Selection Outline Pass (FAST)
+ *
+ * This is a MUCH faster alternative to geometry-based selection outline.
+ * Instead of copying vertex data, it reads from a selection mask texture
+ * that's been written to during the main render pass.
+ *
+ * Performance: O(pixels) instead of O(selected_vertices)
+ * - 1000 selected elements = same cost as 1 selected element
+ * - No geometry copying
+ * - No extra mesh rendering
+ *
+ * Requirements:
+ * - Selection mask must be written by ViralBatchedMesh/ViralInstancedMesh during render
+ * - Main renderer must call updateSelectionMask() before this pass runs
+ */
+export interface StencilSelectionOutlineOptions {
+    /** Outline color (default: accent color) */
+    outlineColor: Color;
+    /** Outline opacity 0-1 (default: 1.0) */
+    outlineOpacity: number;
+    /** Outline thickness in pixels (default: 2.0) */
+    outlineThickness: number;
+}
+export declare class StencilSelectionOutlinePass extends Pass {
+    private resolution;
+    private options;
+    private selectionMaskTarget;
+    private outlineMaterial;
+    private copyMaterial;
+    private fsQuad;
+    bypass: boolean;
+    private hasSelection;
+    constructor(resolution: Vector2, options?: Partial<StencilSelectionOutlineOptions>);
+    /**
+     * Set the selection mask render target
+     * This should be called by the renderer after writing selection mask
+     */
+    setSelectionMaskTarget(target: WebGLRenderTarget | null): void;
+    /**
+     * Set whether there's an active selection
+     */
+    setHasSelection(value: boolean): void;
+    /**
+     * Update outline options
+     */
+    setOptions(options: Partial<StencilSelectionOutlineOptions>): void;
+    render(renderer: WebGLRenderer, writeBuffer: WebGLRenderTarget, readBuffer: WebGLRenderTarget, _deltaTime?: number, _maskActive?: boolean): void;
+    setSize(width: number, height: number): void;
+    dispose(): void;
+}

package/dist/components/visibility-manager/viral-visibility-manager.d.ts

@@ -5,15 +5,13 @@ export declare class ViralVisibilityManager {
     private viralViewerApi;
     /** Whether selection outline is enabled (default: true) */
     private _selectionOutlineEnabled;
-    /** Whether an outline update is already scheduled for the next frame */
-    private _outlineUpdateScheduled;
     constructor(viralViewerApi: ViralViewerApi);
     /**
      * show all elements and reset back to normal visualization
      */
     showAll2(): void;
     /**
-     * hide all elements and reset back to normal visualization
+     * Hide all elements (sets all meshes invisible)
      */
     hideAllElements(): void;
     /**
@@ -170,11 +168,10 @@ export declare class ViralVisibilityManager {
      */
     updateSelectionOutline(): void;
     /**
-     * Schedule outline update for the next animation frame.
-     * Batches multiple rapid selection changes into a single update.
-     * Uses Web Worker to avoid blocking the main thread.
+     * Notify the outline pass whether there is an active selection.
+     * The GPU reads selection state directly from vertex colors — no CPU work needed.
      */
-    private scheduleOutlineUpdate;
+    private notifySelectionOutline;
     /**
      * Enable selection outline effect
      */
@@ -192,6 +189,40 @@ export declare class ViralVisibilityManager {
      * Get whether selection outline mode is enabled
      */
     get selectionOutlineEnabled(): boolean;
+    /** Whether alpha selection outline is enabled (default: false, as it requires opt-in) */
+    private _alphaSelectionOutlineEnabled;
+    /**
+     * Update alpha selection outline state
+     * This is MUCH faster than updateSelectionOutline() - no geometry copying needed
+     */
+    updateAlphaSelectionOutline(): void;
+    /**
+     * Enable alpha selection outline effect
+     * This is the FAST outline mode - constant cost regardless of selection size
+     */
+    enableAlphaSelectionOutline(): void;
+    /**
+     * Disable alpha selection outline effect
+     */
+    disableAlphaSelectionOutline(): void;
+    /**
+     * Set whether alpha selection outline mode is enabled
+     * This is the recommended mode for large selections (1000+ elements)
+     * @param enabled - true to enable, false to disable
+     */
+    setAlphaSelectionOutlineMode(enabled: boolean): void;
+    /**
+     * Get whether alpha selection outline mode is enabled
+     */
+    get alphaSelectionOutlineEnabled(): boolean;
+    /**
+     * Bypass alpha selection outline (fast, for camera movement)
+     */
+    bypassAlphaSelectionOutline(): void;
+    /**
+     * Resume alpha selection outline after bypass
+     */
+    resumeAlphaSelectionOutline(): void;
     enableNight(): void;
     disableNight(): void;
     enableSectionBox(): void;