@d5techs/3dgs-lib 1.1.0 → 1.1.1

package/dist/App.d.ts

@@ -17,11 +17,12 @@ import { MeshRenderer } from "./mesh/MeshRenderer";
 import { Mesh } from "./mesh/Mesh";
 import { GSSplatRenderer } from "./gs/GSSplatRenderer";
 import { GSSplatRendererMobile } from "./gs/GSSplatRendererMobile";
-import type { BoundingBox } from "./types";
-import { SplatTransformProxy, MeshGroupProxy, SplatBoundingBoxProvider } from "./interaction/GizmoManager";
-import { TransformableObject, GizmoMode } from "./core/gizmo/TransformGizmoV2";
-import { BoundingBoxProvider } from "./core/BoundingBoxRenderer";
-export { SplatTransformProxy, MeshGroupProxy, SplatBoundingBoxProvider };
+import type { BoundingBox, SimpleBoundingBox } from "./types";
+import { HotspotManager } from "./interaction/HotspotManager";
+import type { HotspotInfo } from "./interaction/HotspotManager";
+import { SplatTransformProxy, MeshGroupProxy, SplatBoundingBoxProvider } from "./scene/proxies";
+import { TransformableObject, GizmoMode } from "./core/gizmo/TransformGizmo";
+import type { BoundingBoxProvider } from "./types";
 /**
  * 统一进度回调类型
  * @param progress 进度值 0-100
@@ -41,6 +42,7 @@ export declare class App {
     private objLoader;
     private sceneManager;
     private gizmoManager;
+    private hotspotManager;
     private isRunning;
     private animationId;
     private useMobileRenderer;
@@ -66,6 +68,10 @@ export declare class App {
      * 加载 Splat 文件
      */
     addSplat(urlOrBuffer: string | ArrayBuffer, onProgress?: ProgressCallback, isLocalFile?: boolean): Promise<number>;
+    /**
+     * 加载 SOG 文件 (Spatially Ordered Gaussians)
+     */
+    addSOG(urlOrBuffer: string | ArrayBuffer, onProgress?: ProgressCallback, isLocalFile?: boolean): Promise<number>;
     /**
      * 添加测试立方体
      */
@@ -105,13 +111,18 @@ export declare class App {
     getMeshColor(index: number): [number, number, number, number] | null;
     setMeshColor(index: number, r: number, g: number, b: number, a?: number): boolean;
     setMeshRangeColor(startIndex: number, count: number, r: number, g: number, b: number, a?: number): number;
+    getOverlayMeshCount(): number;
+    removeOverlayMeshByIndex(index: number): boolean;
+    getOverlayMeshColor(index: number): [number, number, number, number] | null;
+    setOverlayMeshRangeColor(startIndex: number, count: number, r: number, g: number, b: number, a?: number): number;
+    createOverlayMeshGroupProxy(startIndex: number, count: number): MeshGroupProxy | null;
     frameCurrentModel(animate?: boolean): boolean;
-    getTransformGizmo(): import(".").TransformGizmoV2;
+    getTransformGizmo(): import(".").TransformGizmo;
     getViewportGizmo(): import(".").ViewportGizmo;
     getBoundingBoxRenderer(): import(".").BoundingBoxRenderer;
     setGizmoMode(mode: GizmoMode): void;
     setGizmoTarget(object: TransformableObject | null): void;
-    setSelectionBoundingBox(box: BoundingBox | null): void;
+    setSelectionBoundingBox(box: SimpleBoundingBox | null): void;
     setSelectionBoundingBoxProvider(provider: BoundingBoxProvider | null): void;
     clearSelectionBoundingBox(): void;
     /**
@@ -133,6 +144,16 @@ export declare class App {
     getGSRenderer(): GSSplatRenderer | undefined;
     getGSRendererMobile(): GSSplatRendererMobile | undefined;
     isUsingMobileRenderer(): boolean;
+    getHotspotManager(): HotspotManager;
+    enterHotspotMode(objUrl: string): void;
+    exitHotspotMode(): void;
+    isHotspotModeActive(): boolean;
+    getHotspots(): HotspotInfo[];
+    setHotspotBillboard(hotspotIndex: number, enabled: boolean): boolean;
+    getHotspotBillboard(hotspotIndex: number): boolean;
+    getHotspotCount(): number;
+    findHotspotIndexByMeshStart(overlayMeshStartIndex: number): number;
+    getOverlayMeshByIndex(index: number): import("./mesh/Mesh").Mesh | null;
     private fetchWithProgress;
     private parsePLYBuffer;
     /**

package/dist/core/BoundingBoxRenderer.d.ts

@@ -1,8 +1,6 @@
 import { Renderer } from "./Renderer";
 import { Camera } from "./Camera";
 import type { SimpleBoundingBox, BoundingBoxProvider } from "../types";
-export type { BoundingBoxProvider };
-export type BoundingBox = SimpleBoundingBox;
 /**
  * BoundingBoxRenderer - 包围盒线框渲染器
  * 用于显示选中对象的包围盒，支持动态跟随
@@ -35,7 +33,7 @@ export declare class BoundingBoxRenderer {
     /**
      * 设置静态包围盒（不会自动更新）
      */
-    setBoundingBox(box: BoundingBox | null): void;
+    setBoundingBox(box: SimpleBoundingBox | null): void;
     /**
      * 清除包围盒
      */

package/dist/core/OrbitControls.d.ts

@@ -1,7 +1,7 @@
 import { Camera } from "./Camera";
 /**
  * OrbitControls - 轨道控制器
- * 只负责鼠标/触摸输入控制相机
+ * 支持阻尼惯性、屏幕空间平移、中键拖拽、指数缩放
  */
 export declare class OrbitControls {
     private camera;
@@ -18,9 +18,17 @@ export declare class OrbitControls {
     panSpeed: number;
     touchZoomSpeed: number;
     touchPanSpeed: number;
+    enableDamping: boolean;
+    dampingFactor: number;
     private isDragging;
     private lastX;
     private lastY;
+    private velocityTheta;
+    private velocityPhi;
+    private velocityDistance;
+    private velocityPanX;
+    private velocityPanY;
+    private velocityPanZ;
     private touchMode;
     private lastTouchDistance;
     private lastTouchCenter;
@@ -34,18 +42,17 @@ export declare class OrbitControls {
     private boundOnTouchEnd;
     private boundOnContextMenu;
     constructor(camera: Camera, canvas: HTMLCanvasElement);
-    /**
-     * 设置事件监听
-     */
     private setupEventListeners;
+    private removeEventListeners;
+    destroy(): void;
     /**
-     * 移除事件监听
+     * 从视图矩阵提取相机的 right 和 up 向量，用于屏幕空间平移
      */
-    private removeEventListeners;
+    private getCameraAxes;
     /**
-     * 销毁控制器
+     * 屏幕空间平移：将屏幕 delta 映射到相机 right/up 方向
      */
-    destroy(): void;
+    private panByScreenDelta;
     private onMouseDown;
     private onMouseMove;
     private onMouseUp;
@@ -53,49 +60,22 @@ export declare class OrbitControls {
     private onTouchStart;
     private onTouchMove;
     private onTouchEnd;
-    /**
-     * 计算双指之间的距离
-     */
     private getTouchDistance;
-    /**
-     * 计算双指的中心点
-     */
     private getTouchCenter;
     /**
-     * 根据球坐标更新相机位置
+     * 将球坐标写入相机位置（内部方法，不处理阻尼）
      */
-    update(): void;
+    private applySpherical;
     /**
-     * 切换到标准视图
-     * @param axis 轴 'X' | 'Y' | 'Z'
-     * @param positive 是否正向
-     * @param animate 是否动画过渡
+     * 每帧调用：应用阻尼衰减并更新相机
+     * 在渲染循环中调用此方法以获得平滑惯性效果
      */
+    update(): void;
     setViewAxis(axis: string, positive: boolean, animate?: boolean): void;
-    /**
-     * 动画过渡到目标视图
-     */
     private animateToView;
-    /**
-     * 设置相机目标点（控制器旋转中心）
-     * @param x X 坐标
-     * @param y Y 坐标
-     * @param z Z 坐标
-     */
     setTarget(x: number, y: number, z: number): void;
-    /**
-     * 获取当前目标点
-     */
     getTarget(): [number, number, number];
-    /**
-     * 根据模型参数自动调整相机位置和参数
-     * @param center 模型中心点
-     * @param radius 模型包围球半径
-     * @param animate 是否使用动画过渡
-     */
     frameModel(center: [number, number, number], radius: number, animate?: boolean): void;
-    /**
-     * 动画过渡到目标帧（包含目标点和距离）
-     */
     private animateToFrame;
+    clearVelocity(): void;
 }

package/dist/core/gizmo/{TransformGizmoV2.d.ts → TransformGizmo.d.ts}

@@ -65,10 +65,10 @@ export interface TransformGizmoConfig {
     snapIncrement?: number;
 }
 /**
- * TransformGizmoV2 - 重构后的变换 Gizmo
+ * TransformGizmo - 变换 Gizmo
  * 参考 PlayCanvas 引擎的 TransformGizmo 实现
  */
-export declare class TransformGizmoV2 {
+export declare class TransformGizmo {
     private renderer;
     private camera;
     private canvas;

package/dist/core/{ViewportGizmo.d.ts → gizmo/ViewportGizmo.d.ts}

@@ -1,5 +1,5 @@
-import { Camera } from "./Camera";
-import { Renderer } from "./Renderer";
+import { Camera } from "../Camera";
+import { Renderer } from "../Renderer";
 /**
  * ViewportGizmo - 视口坐标轴指示器
  * 在画布右上角显示当前相机朝向

package/dist/core/gizmo/index.d.ts

@@ -10,5 +10,6 @@ export { ArcShape } from "./ArcShape";
 export type { ArcShapeConfig, ArcDisplayMode } from "./ArcShape";
 export { BoxLineShape } from "./BoxLineShape";
 export type { BoxLineShapeConfig } from "./BoxLineShape";
-export { TransformGizmoV2, GizmoMode } from "./TransformGizmoV2";
-export type { TransformGizmoConfig, TransformableObject, GizmoSpace, GizmoDragMode, GizmoTheme, } from "./TransformGizmoV2";
+export { ViewportGizmo } from "./ViewportGizmo";
+export { TransformGizmo, GizmoMode } from "./TransformGizmo";
+export type { TransformGizmoConfig, TransformableObject, GizmoSpace, GizmoDragMode, GizmoTheme, } from "./TransformGizmo";

package/dist/core/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Core 模块统一导出
+ */
+export { Renderer } from './Renderer';
+export { Camera } from './Camera';
+export { OrbitControls } from './OrbitControls';
+export { BoundingBoxRenderer } from './BoundingBoxRenderer';

package/dist/gs/GSSplatRenderer.d.ts

@@ -15,8 +15,6 @@ import { CompactSplatData } from "./PLYLoaderMobile";
 import type { BoundingBox, Vec3Tuple } from "../types";
 import { SHMode, RendererCapabilities } from "../types";
 import type { IGSSplatRendererWithCapabilities } from "./IGSSplatRenderer";
-export { SHMode };
-export type { BoundingBox };
 /**
  * GSSplatRendererV2 - 优化的渲染器
  */
@@ -32,15 +30,37 @@ export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities
     private sorter;
     private shMode;
     private boundingBox;
+    private cpuPositions;
     private position;
     private rotation;
     private scale;
     private pivot;
     private modelMatrix;
     private pixelCullThreshold;
+    private maxVisibleSplats;
+    private lastSortViewMatrix;
+    private lastSortProjMatrix;
+    private lastSortModelMatrix;
+    private lastSortWidth;
+    private lastSortHeight;
+    private lastSortPixelThreshold;
+    private lastSortMaxVisible;
+    private sortStateInitialized;
+    private sortFrequency;
+    private frameCounter;
+    private depthNormalPipeline;
+    private depthRT;
+    private depthRTView;
+    private normalRT;
+    private normalRTView;
+    private dnRTWidth;
+    private dnRTHeight;
+    private dnResult;
     constructor(renderer: Renderer, camera: Camera);
     private createPipeline;
     private createUniformBuffer;
+    private createDepthNormalPipeline;
+    private ensureDepthNormalTextures;
     setPosition(x: number, y: number, z: number): void;
     getPosition(): Vec3Tuple;
     setRotation(x: number, y: number, z: number): void;
@@ -54,13 +74,39 @@ export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities
     setSHMode(mode: SHMode): void;
     getSHMode(): SHMode;
     setPixelCullThreshold(threshold: number): void;
+    /**
+     * 设置最大可见 splat 数量
+     * 排序后只保留距离最近的 N 个 splat，远处被遮挡的 splat 被丢弃
+     * 0 = 不限制
+     */
+    setMaxVisibleSplats(count: number): void;
+    getMaxVisibleSplats(): number;
+    /**
+     * 设置排序频率
+     * 1 = 每帧排序（默认），2 = 每 2 帧排序一次，以此类推
+     * 相机静止时自动跳过排序，不受此参数影响
+     */
+    setSortFrequency(frequency: number): void;
+    getSortFrequency(): number;
+    private needsSort;
+    private saveSortState;
     setData(splats: SplatCPU[]): void;
     setCompactData(compactData: CompactSplatData): void;
     render(pass: GPURenderPassEncoder): void;
     getSplatCount(): number;
     getBoundingBox(): BoundingBox | null;
+    getCPUPositions(): Float32Array | null;
     private computeBoundingBox;
     private computeBoundingBoxFromCompact;
+    prepareDepthNormalPass(px?: number, py?: number): void;
+    private static half2Float;
+    private static _f32;
+    private static _u32;
+    getDepthNormal(): {
+        depth: number;
+        normal: Vec3Tuple;
+        worldPos: Vec3Tuple;
+    } | null;
     supportsSHMode(mode: SHMode): boolean;
     getCapabilities(): RendererCapabilities;
     destroy(): void;

package/dist/gs/GSSplatRendererMobile.d.ts

@@ -13,7 +13,6 @@ import { CompactSplatData } from "./PLYLoaderMobile";
 import type { BoundingBox, Vec3Tuple } from "../types";
 import { SHMode, RendererCapabilities } from "../types";
 import type { IGSSplatRendererWithCapabilities } from "./IGSSplatRenderer";
-export type { BoundingBox };
 /**
  * GSSplatRendererMobile - 移动端优化渲染器
  * 实现 IGSSplatRenderer 接口
@@ -32,6 +31,7 @@ export declare class GSSplatRendererMobile implements IGSSplatRendererWithCapabi
     private sorter;
     private positionsBuffer;
     private boundingBox;
+    private cpuPositions;
     private frameCount;
     private sortEveryNFrames;
     private position;
@@ -117,6 +117,7 @@ export declare class GSSplatRendererMobile implements IGSSplatRendererWithCapabi
      * 获取 bounding box
      */
     getBoundingBox(): BoundingBox | null;
+    getCPUPositions(): Float32Array | null;
     /**
      * 设置排序频率
      * @param n 每 n 帧排序一次

package/dist/gs/GSSplatSorter.d.ts

@@ -23,6 +23,8 @@ export interface CullingOptions {
     farPlane: number;
     pixelThreshold: number;
     frustumDilation?: number;
+    /** 最大可见 splat 数量（排序后截断），0 = 不限制 */
+    maxVisibleCount?: number;
 }
 /**
  * 排序器配置选项
@@ -50,6 +52,7 @@ export declare class GSSplatSorter {
     private sortedIndicesBuffer;
     private initIndirectPipeline;
     private projectCullPipeline;
+    private clampDrawCountPipeline;
     private cullingBindGroupLayout;
     private cullingBindGroup;
     private upsweepPipeline;

package/dist/gs/IGSSplatRenderer.d.ts

@@ -7,8 +7,6 @@ import type { CompactSplatData } from "./PLYLoaderMobile";
 import type { SplatCPU } from "./PLYLoader";
 import type { BoundingBox, Vec3Tuple } from "../types";
 import { SHMode, RendererCapabilities } from "../types";
-export type { BoundingBox, Vec3Tuple, RendererCapabilities };
-export { SHMode };
 /**
  * 3D Gaussian Splatting 渲染器接口
  */
@@ -70,6 +68,11 @@ export interface IGSSplatRenderer {
      * 获取 bounding box
      */
     getBoundingBox(): BoundingBox | null;
+    /**
+     * 获取 CPU 端 splat 位置数据（用于射线拾取等交互）
+     * 返回 Float32Array，每 3 个值为一个点的 x, y, z
+     */
+    getCPUPositions(): Float32Array | null;
     /**
      * 设置 SH 模式
      * 移动端可能只支持 L0
@@ -83,6 +86,32 @@ export interface IGSSplatRenderer {
      * 是否支持指定的 SH 模式
      */
     supportsSHMode?(mode: SHMode): boolean;
+    /**
+     * 设置排序频率
+     * 1 = 每帧排序（默认），N = 每 N 帧排序一次
+     * 降低排序频率可显著提升中距离场景的帧率，代价是移动时短暂的排序瑕疵
+     */
+    setSortFrequency?(frequency: number): void;
+    /**
+     * 获取排序频率
+     */
+    getSortFrequency?(): number;
+    /**
+     * 渲染深度+法线到 offscreen RT，并将指定像素 copy 到 staging buffer 发起异步回读。
+     * 在主 render 之后每帧调用，复用排序结果。
+     * @param px 像素 x 坐标（-1 表示不回读）
+     * @param py 像素 y 坐标（-1 表示不回读）
+     */
+    prepareDepthNormalPass?(px: number, py: number): void;
+    /**
+     * 同步读取上一帧 prepareDepthNormalPass 回读完成的结果。
+     * @returns null 表示上一帧无命中、回读未完成、或未请求过回读
+     */
+    getDepthNormal?(): {
+        depth: number;
+        normal: Vec3Tuple;
+        worldPos: Vec3Tuple;
+    } | null;
     /**
      * 销毁资源
      */

package/dist/gs/SOGLoader.d.ts

@@ -0,0 +1,25 @@
+/**
+ * SOGLoader - 加载 SOG (Spatially Ordered Gaussians) 格式的 3DGS 文件
+ *
+ * SOG 是 PlayCanvas 开源的压缩容器格式，约 15-20x 压缩比 (vs PLY)
+ * .sog 文件本质是 ZIP 包，内含 meta.json + 多个无损 WebP 图像
+ *
+ * 支持:
+ * - 完整位置解码（16-bit 对称对数量化）
+ * - Codebook 缩放解码
+ * - Smallest-three 四元数解码 (26-bit)
+ * - DC 颜色 + 透明度 (SH L0)
+ * - 高阶球谐系数 L1-L3（palette + codebook）
+ *
+ * 规范 v2: https://developer.playcanvas.com/user-manual/gaussian-splatting/formats/sog/
+ */
+import type { CompactSplatData } from './PLYLoaderMobile';
+export type SOGProgressCallback = (progress: number, stage: 'download' | 'parse' | 'upload') => void;
+/**
+ * 从 URL 加载 .sog 文件
+ */
+export declare function loadSOG(url: string, onProgress?: SOGProgressCallback): Promise<CompactSplatData>;
+/**
+ * 从 ArrayBuffer 解析 SOG 数据
+ */
+export declare function deserializeSOG(data: ArrayBuffer, onProgress?: SOGProgressCallback): Promise<CompactSplatData>;

package/dist/index.d.ts

@@ -8,11 +8,9 @@ export { isMobileDevice, getRecommendedDPR, isWebGPUSupported, computeBoundingBo
 export { Renderer } from './core/Renderer';
 export { Camera } from './core/Camera';
 export { OrbitControls } from './core/OrbitControls';
-export { ViewportGizmo } from './core/ViewportGizmo';
+export { ViewportGizmo } from './core/gizmo/ViewportGizmo';
 export { BoundingBoxRenderer } from './core/BoundingBoxRenderer';
-export type { BoundingBox as SelectionBoundingBox, BoundingBoxProvider } from './core/BoundingBoxRenderer';
 export { Mesh } from './mesh/Mesh';
-export type { MeshBoundingBox } from './mesh/Mesh';
 export { MeshRenderer } from './mesh/MeshRenderer';
 export { GLBLoader } from './loaders/GLBLoader';
 export type { LoadedMesh } from './loaders/GLBLoader';
@@ -27,8 +25,9 @@ export type { SplatCPU } from './gs/PLYLoader';
 export { loadPLYMobile, parsePLYBuffer, compactDataToGPUBuffer } from './gs/PLYLoaderMobile';
 export type { MobileLoadOptions, CompactSplatData } from './gs/PLYLoaderMobile';
 export { loadSplat, deserializeSplat } from './gs/SplatLoader';
-export { GSSplatRenderer, SHMode as GSSHMode } from './gs/GSSplatRenderer';
-export type { BoundingBox as GSSplatBoundingBox } from './gs/GSSplatRenderer';
+export { loadSOG, deserializeSOG } from './gs/SOGLoader';
+export type { SOGProgressCallback } from './gs/SOGLoader';
+export { GSSplatRenderer } from './gs/GSSplatRenderer';
 export { GSSplatSorter } from './gs/GSSplatSorter';
 export type { SorterOptions, CullingOptions, ScreenInfo } from './gs/GSSplatSorter';
 export { GSSplatRendererMobile } from './gs/GSSplatRendererMobile';
@@ -39,9 +38,11 @@ export type { CompressedSplatTextures } from './gs/TextureCompressor';
 export { SceneManager } from './scene/SceneManager';
 export type { SceneObjectType, SceneObjectInfo } from './scene/SceneManager';
 export { SplatTransformProxy, MeshGroupProxy, SplatBoundingBoxProvider, } from './scene/proxies';
-export { GizmoManager, SplatTransformProxy as GizmoSplatTransformProxy, MeshGroupProxy as GizmoMeshGroupProxy, SplatBoundingBoxProvider as GizmoSplatBoundingBoxProvider } from './interaction/GizmoManager';
+export { GizmoManager } from './interaction/GizmoManager';
+export { HotspotManager } from './interaction/HotspotManager';
+export type { HotspotInfo } from './interaction/HotspotManager';
+export type { TransformableObject } from './core/gizmo/TransformGizmo';
+export { TransformGizmo, GizmoMode } from './core/gizmo/TransformGizmo';
+export type { GizmoTheme, TransformGizmoConfig, GizmoSpace } from './core/gizmo/TransformGizmo';
 export { App } from './App';
 export type { ProgressCallback } from './App';
-export type { TransformableObject } from './core/gizmo/TransformGizmoV2';
-export { TransformGizmoV2, GizmoMode } from './core/gizmo/TransformGizmoV2';
-export type { GizmoTheme, TransformGizmoConfig, GizmoSpace } from './core/gizmo/TransformGizmoV2';

package/dist/interaction/GizmoManager.d.ts

@@ -9,13 +9,13 @@
 import { Renderer } from "../core/Renderer";
 import { Camera } from "../core/Camera";
 import { OrbitControls } from "../core/OrbitControls";
-import { ViewportGizmo } from "../core/ViewportGizmo";
-import { TransformGizmoV2, TransformableObject, GizmoMode } from "../core/gizmo/TransformGizmoV2";
-import { BoundingBoxRenderer, BoundingBox as RendererBoundingBox, BoundingBoxProvider } from "../core/BoundingBoxRenderer";
+import { ViewportGizmo } from "../core/gizmo/ViewportGizmo";
+import { TransformGizmo, TransformableObject, GizmoMode } from "../core/gizmo/TransformGizmo";
+import { BoundingBoxRenderer } from "../core/BoundingBoxRenderer";
+import type { SimpleBoundingBox, BoundingBoxProvider } from "../types";
 import type { IGSSplatRenderer } from "../gs/IGSSplatRenderer";
 import type { Mesh } from "../mesh/Mesh";
 import { SplatTransformProxy, MeshGroupProxy, SplatBoundingBoxProvider } from "../scene/proxies";
-export { SplatTransformProxy, MeshGroupProxy, SplatBoundingBoxProvider };
 /**
  * GizmoManager - Gizmo 交互管理器
  */
@@ -47,7 +47,7 @@ export declare class GizmoManager {
     /**
      * 获取变换 Gizmo
      */
-    getTransformGizmo(): TransformGizmoV2;
+    getTransformGizmo(): TransformGizmo;
     /**
      * 设置 Gizmo 模式
      */
@@ -67,7 +67,7 @@ export declare class GizmoManager {
     /**
      * 设置选中对象的包围盒（静态模式）
      */
-    setSelectionBoundingBox(box: RendererBoundingBox | null): void;
+    setSelectionBoundingBox(box: SimpleBoundingBox | null): void;
     /**
      * 设置选中对象的包围盒提供者（动态模式）
      */

package/dist/interaction/HotspotManager.d.ts

@@ -0,0 +1,142 @@
+/**
+ * HotspotManager - 热点放置管理器
+ *
+ * 在 3DGS 场景中通过射线拾取表面点，计算法线，
+ * 显示吸附圆圈指示器，并放置 OBJ 模型热点。
+ */
+import { Camera } from "../core/Camera";
+import { Renderer } from "../core/Renderer";
+import { OrbitControls } from "../core/OrbitControls";
+import { MeshRenderer } from "../mesh/MeshRenderer";
+import type { IGSSplatRenderer } from "../gs/IGSSplatRenderer";
+import type { Vec3Tuple } from "../types";
+/** 热点信息 */
+export interface HotspotInfo {
+    position: Vec3Tuple;
+    normal: Vec3Tuple;
+    meshStartIndex: number;
+    meshCount: number;
+    /** 是否始终面向屏幕（billboard 模式），默认 false */
+    billboard: boolean;
+    /** 放置时的缩放值（billboard 旋转时需要保持） */
+    placedScale: number;
+    /** 放置时的法线偏移量 */
+    placedNormalOffset: number;
+    /** 放置时的本地中心偏移 (本地空间) */
+    placedLocalCenter: Vec3Tuple;
+}
+/**
+ * HotspotManager
+ */
+export declare class HotspotManager {
+    private camera;
+    private renderer;
+    private controls;
+    private meshRenderer;
+    private objLoader;
+    private canvas;
+    private active;
+    private gsRenderer;
+    private indicatorMesh;
+    private indicatorAdded;
+    private hotspots;
+    private currentHit;
+    private indicatorTransform;
+    private hotspotOBJUrl;
+    private boundOnMouseMove;
+    private boundOnMouseDown;
+    private boundOnMouseUp;
+    private boundOnKeyDown;
+    private mouseDownPos;
+    private isDragging;
+    private readonly DRAG_THRESHOLD;
+    private pendingMouseX;
+    private pendingMouseY;
+    private hasPendingMove;
+    private rafId;
+    private lastHitIdx;
+    private lastNormal;
+    private indicatorBaseRadius;
+    private pickRadiusPx;
+    private onHotspotPlaced;
+    private onModeChanged;
+    constructor(renderer: Renderer, camera: Camera, canvas: HTMLCanvasElement, controls: OrbitControls, meshRenderer: MeshRenderer);
+    setGSRenderer(gsRenderer: IGSSplatRenderer | null): void;
+    setHotspotOBJUrl(url: string): void;
+    enter(): void;
+    exit(): void;
+    isActive(): boolean;
+    getHotspots(): HotspotInfo[];
+    setOnHotspotPlaced(cb: ((info: HotspotInfo) => void) | null): void;
+    setOnModeChanged(cb: ((active: boolean) => void) | null): void;
+    private pickPixelX;
+    private pickPixelY;
+    private lastClientX;
+    private lastClientY;
+    private pickDirty;
+    /**
+     * Returns the current pick pixel coordinates in device pixels.
+     * Called by the render loop to pass to prepareDepthNormalPass.
+     * Returns [-1, -1] when no pick is needed.
+     */
+    getPickPixel(): [number, number];
+    private onMouseMove;
+    private processMouseMove;
+    /**
+     * 读取上一帧的深度法线GPU回读结果，更新指示器
+     * 每帧在App.Render()中调用
+     * 如果GPU没有回读结果，则使用CPU拾取
+     */
+    consumeGPUResult(): void;
+    private onMouseDown;
+    private onMouseUp;
+    private onKeyDown;
+    private raycastSplatsCPU;
+    private estimateNormal;
+    /**
+     * 距离加权 PCA：离中心越近的点权重越高
+     */
+    private weightedPCA;
+    /**
+     * 求 3x3 对称矩阵最小特征值对应的特征向量（偏移幂迭代）
+     */
+    private smallestEigenvector;
+    private createIndicatorMesh;
+    private showIndicator;
+    private hideIndicator;
+    private updateIndicator;
+    private placeHotspot;
+    /**
+     * 将 OBJ mesh 的变换设置为与指示器完全一致的大小、位置、朝向。
+     *
+     * 使用指示器缓存的基向量 (right, forward, normal) 和 visualDiameter，
+     * 将 OBJ 缩放到与指示器圆圈等大，居中放置在相同位置。
+     */
+    private applyIndicatorTransform;
+    /**
+     * 从 modelMatrix 反向提取 position / rotation / scale，
+     * 使 Mesh 的分离属性与矩阵保持同步（Gizmo 需要）。
+     */
+    private decomposeModelMatrix;
+    /**
+     * 设置指定热点的 billboard 模式
+     * @param hotspotIndex 热点索引（在 hotspots 数组中的位置）
+     * @param enabled 是否启用 billboard
+     */
+    setHotspotBillboard(hotspotIndex: number, enabled: boolean): boolean;
+    getHotspotBillboard(hotspotIndex: number): boolean;
+    getHotspotCount(): number;
+    /**
+     * 通过 overlay mesh 起始索引找到对应的热点索引
+     */
+    findHotspotIndexByMeshStart(overlayMeshStartIndex: number): number;
+    /**
+     * 每帧调用：更新所有 billboard 热点朝向相机
+     */
+    updateBillboards(): void;
+    /**
+     * 关闭 billboard 时恢复到放置时的法线朝向
+     */
+    private restoreHotspotOrientation;
+    destroy(): void;
+}