@chocozhang/three-model-render 1.0.6 → 2.0.1

package/dist/ui/index.d.ts

@@ -3,45 +3,205 @@ import * as THREE from 'three';
 /**
  * @file modelsLabel.ts
  * @description
- * Creates interactive 2D labels (DOM elements) attached to 3D objects with connecting lines.
+ * Creates interactive 2D labels (DOM elements) attached to 3D objects.
+ * unified tool replacing the old labelManager.ts and modelsLabel.ts.
  *
  * @best-practice
  * - Use `createModelsLabel` to annotate parts of a model.
- * - Supports fading endpoints, pulsing dots, and custom styling.
- * - Performance optimized with caching and RAF throttling.
+ * - set `style: 'line'` (default) for labels with connecting lines and pulsing dots.
+ * - set `style: 'simple'` for simple overhead labels (like the old labelManager).
  */
 
+/**
+ * Configuration options for the labeling system.
+ */
 interface LabelOptions {
+    /**
+     * Label style:
+     * - 'simple': Traditional overhead text label.
+     * - 'line': Modern callout with a connecting line and pulsing status dot.
+     */
+    style?: 'simple' | 'line';
+    /** Font size for the label text. Default is '12px'. */
     fontSize?: string;
+    /** Text color. Default is '#ffffff'. */
     color?: string;
+    /** Background color of the label. Supports CSS color strings. */
     background?: string;
+    /** CSS padding for the label. Default is '6px 10px'. */
     padding?: string;
+    /** CSS border radius for the label. Default is '6px'. */
     borderRadius?: string;
+    /**
+     * Vertical lift amount in pixels.
+     * For 'line' style, this determines the length of the callout line.
+     */
     lift?: number;
+    /** Diameter of the status dot in pixels (for 'line' style). */
     dotSize?: number;
+    /** Spacing between the status dot and the label text. */
     dotSpacing?: number;
+    /** Color of the connecting line. */
     lineColor?: string;
+    /** Width of the connecting line in pixels. */
     lineWidth?: number;
+    /** Throttling interval for position updates in milliseconds. 0 is per-frame. */
     updateInterval?: number;
+    /** Duration of the fade-in animation in milliseconds. */
     fadeInDuration?: number;
+    /** Number of frames to skip between occlusion checks. Increase to improve performance. */
+    occlusionCheckInterval?: number;
+    /** Whether to enable raycasting-based occlusion detection. Default is true. */
+    enableOcclusionDetection?: boolean;
+    /** Threshold for camera movement to trigger an update. Higher values reduce CPU usage. */
+    cameraMoveThreshold?: number;
+    /** Maximum distance from camera at which labels are visible. */
+    maxDistance?: number;
 }
+/**
+ * Interface for controlling the label system instance.
+ */
 interface LabelManager {
+    /** Rebuilds labels for a different model. */
     updateModel: (model: THREE.Object3D) => void;
+    /** Updates the mapping of mesh names to label text. */
     updateLabelsMap: (map: Record<string, string>) => void;
+    /** Temporarily stops position updates and occlusion checks. */
     pause: () => void;
+    /** Resumes position updates. */
     resume: () => void;
+    /** Completely removes all labels and cleans up resources. */
     dispose: () => void;
+    /** Returns the current running state. */
+    isRunning: () => boolean;
 }
 /**
- * Create Model Labels (with connecting lines and pulsing dots) - Optimized
+ * Initializes the unified labeling system for a specific model.
+ *
+ * Performance:
+ * - Uses Object Pooling for all Vector3/Box3 operations to minimize GC.
+ * - Throttles updates based on camera movement and configurable intervals.
+ * - Optimized occlusion detection with frame-skipping.
  *
- * Features:
- * - Supports pause/resume
- * - Configurable update interval
- * - Fade in/out effects
- * - Cached bounding box calculation
- * - RAF management optimization
+ * @param {THREE.Camera} camera - The active camera used for projection.
+ * @param {THREE.WebGLRenderer} renderer - The renderer used for dimension calculations.
+ * @param {THREE.Object3D} parentModel - The model to search for meshes to label.
+ * @param {Record<string, string>} modelLabelsMap - Mapping of part name substrings to label text.
+ * @param {LabelOptions} [options] - Configuration for styles and performance.
+ * @returns {LabelManager} Controls to manage the lifecycle of the labels.
  */
 declare function createModelsLabel(camera: THREE.Camera, renderer: THREE.WebGLRenderer, parentModel: THREE.Object3D, modelLabelsMap: Record<string, string>, options?: LabelOptions): LabelManager;
 
-export { createModelsLabel };
+/**
+ * @file performanceStats.ts
+ * @description
+ * Real-time performance monitoring overlay for Three.js applications.
+ * Displays FPS, memory usage, draw calls, and performance warnings.
+ *
+ * @best-practice
+ * - Create once during initialization
+ * - Call update() in your animation loop
+ * - Use minimal styling for low performance impact
+ *
+ * @performance
+ * - Uses requestAnimationFrame for efficient updates
+ * - DOM updates are batched and throttled
+ * - Minimal memory footprint
+ */
+
+/**
+ * Options for configuring the performance monitoring overlay.
+ */
+interface PerformanceStatsOptions {
+    /** Position of the stats overlay on the screen. Default is 'top-left'. */
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /** Refresh interval for DOM updates in milliseconds. Default is 500ms. */
+    updateInterval?: number;
+    /** Whether to track and display JS heap memory usage. Default is true. */
+    enableMemoryTracking?: boolean;
+    /** Whether to show visual warnings when performance drops. Default is true. */
+    enableWarnings?: boolean;
+    /** Optional WebGLRenderer to track draw calls and triangle counts. */
+    renderer?: THREE.WebGLRenderer | null;
+    /** FPS threshold below which a warning is triggered. Default is 30. */
+    fpsWarningThreshold?: number;
+    /** Memory usage threshold (in MB) above which a warning is triggered. Default is 200. */
+    memoryWarningThreshold?: number;
+}
+/**
+ * Performance Stats Monitor
+ * Lightweight FPS and memory monitoring overlay
+ */
+declare class PerformanceStats {
+    private container;
+    private fpsElement;
+    private memoryElement;
+    private drawCallsElement;
+    private trianglesElement;
+    private warningsContainer;
+    private frames;
+    private lastTime;
+    private fps;
+    private fpsHistory;
+    private maxHistoryLength;
+    private updateInterval;
+    private lastUpdateTime;
+    private warnings;
+    private maxWarnings;
+    private enabled;
+    private isVisible;
+    private options;
+    constructor(options?: PerformanceStatsOptions);
+    private setPosition;
+    private injectStyles;
+    /**
+     * Updates the performance statistics. This method must be called within the application's animation loop.
+     */
+    update(): void;
+    private formatNumber;
+    private addWarning;
+    private updateWarningsDisplay;
+    /**
+     * Gets the current frames per second (FPS).
+     * @returns {number} The current FPS.
+     */
+    getFPS(): number;
+    /**
+     * Gets the average FPS over the recent history period.
+     * @returns {number} The average FPS.
+     */
+    getAverageFPS(): number;
+    /**
+     * Returns a snapshot of all tracked performance metrics.
+     * @returns {object} Current performance statistics.
+     */
+    getStats(): any;
+    /**
+     * Toggles the visibility of the performance stats overlay.
+     */
+    toggle(): void;
+    /**
+     * Shows the performance stats overlay.
+     */
+    show(): void;
+    /**
+     * Hides the performance stats overlay.
+     */
+    hide(): void;
+    /**
+     * Enables or disables performance statistics collection.
+     * @param {boolean} enabled - Whether collection should be enabled.
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Disposes of the performance monitor and removes its DOM elements.
+     */
+    dispose(): void;
+}
+/**
+ * Helper function to create performance monitor
+ */
+declare function createPerformanceMonitor(options?: PerformanceStatsOptions): PerformanceStats;
+
+export { PerformanceStats, createModelsLabel, createPerformanceMonitor };
+export type { PerformanceStatsOptions };