@d5techs/3dgs-lib 1.0.1 → 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 { BoundingBox } from "./gs/IGSSplatRenderer";
-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,19 +1,6 @@
 import { Renderer } from "./Renderer";
 import { Camera } from "./Camera";
-/**
- * BoundingBox 数据结构
- */
-export interface BoundingBox {
-    min: [number, number, number];
-    max: [number, number, number];
-}
-/**
- * BoundingBoxProvider - 包围盒数据提供者接口
- * 实现此接口的对象可以动态提供包围盒数据
- */
-export interface BoundingBoxProvider {
-    getBoundingBox(): BoundingBox | null;
-}
+import type { SimpleBoundingBox, BoundingBoxProvider } from "../types";
 /**
  * BoundingBoxRenderer - 包围盒线框渲染器
  * 用于显示选中对象的包围盒，支持动态跟随
@@ -46,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

@@ -1,217 +1,113 @@
+/**
+ * GSSplatRenderer - 优化的 3D Gaussian Splatting 渲染器
+ *
+ * 基于 rfs-gsplat-render 的实现进行优化:
+ * 1. GPU Radix Sort - O(n) 稳定排序
+ * 2. Normalized Gaussian - 消除边缘雾化
+ * 3. ClipCorner 优化 - 减少 overdraw
+ * 4. MipSplatting 抗锯齿
+ * 5. 改进的视锥剔除
+ */
 import { Renderer } from "../core/Renderer";
 import { Camera } from "../core/Camera";
 import { SplatCPU } from "./PLYLoader";
 import { CompactSplatData } from "./PLYLoaderMobile";
-import { BoundingBox as IBoundingBox, SHMode as ISHMode, RendererCapabilities, IGSSplatRendererWithCapabilities } from "./IGSSplatRenderer";
-/**
- * 性能等级
- */
-export declare enum PerformanceTier {
-    HIGH = "high",// 桌面高端 GPU
-    MEDIUM = "medium",// 桌面中端
-    LOW = "low"
-}
+import type { BoundingBox, Vec3Tuple } from "../types";
+import { SHMode, RendererCapabilities } from "../types";
+import type { IGSSplatRendererWithCapabilities } from "./IGSSplatRenderer";
 /**
- * 移动端优化配置
- */
-export interface MobileOptimizationConfig {
-    maxVisibleSplats: number;
-    enableSorting: boolean;
-    sortEveryNFrames: number;
-    useCompactFormat: boolean;
-    pixelCullThreshold: number;
-    defaultSHMode: SHMode;
-}
-/**
- * SH 模式枚举
- * @deprecated 使用 IGSSplatRenderer 中的 SHMode
- */
-export declare enum SHMode {
-    L0 = 0,// 仅 DC 颜色 (高性能)
-    L1 = 1,// DC + L1 SH
-    L2 = 2,// DC + L1 + L2 SH
-    L3 = 3
-}
-/**
- * Bounding Box 结构
- * @deprecated 使用 IGSSplatRenderer 中的 BoundingBox
- */
-export interface BoundingBox {
-    min: [number, number, number];
-    max: [number, number, number];
-    center: [number, number, number];
-    radius: number;
-}
-export type { IBoundingBox as GSBoundingBox };
-/**
- * GSSplatRenderer - 3D Gaussian Splatting 渲染器
- * 使用 instanced quad 方式渲染 splats
- * 实现 IGSSplatRenderer 接口
- *
- * 优化功能：
- * - GPU 可见性剔除 (视锥/近平面/屏幕尺寸)
- * - DrawIndirect 避免 CPU submit 开销
- * - 仅对可见 splat 排序
- * - 移动端自动优化（降低排序频率、使用紧凑格式）
+ * GSSplatRendererV2 - 优化的渲染器
  */
 export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities {
     private renderer;
     private camera;
-    private pipelineL0;
-    private pipelineL1;
-    private pipelineL2;
-    private pipelineL3;
-    private pipelineL0Compact;
+    private pipeline;
     private bindGroupLayout;
-    private bindGroupLayoutCompact;
     private uniformBuffer;
     private splatBuffer;
     private splatCount;
     private bindGroup;
     private sorter;
-    private useDrawIndirect;
-    private isMobile;
-    private pixelCullThreshold;
     private shMode;
     private boundingBox;
+    private cpuPositions;
     private position;
     private rotation;
     private scale;
     private pivot;
     private modelMatrix;
-    private performanceTier;
-    private optimizationConfig;
-    private frameCount;
-    private useCompactFormat;
+    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(): [number, number, number];
-    /**
-     * 设置旋转 (欧拉角, 弧度)
-     */
+    getPosition(): Vec3Tuple;
     setRotation(x: number, y: number, z: number): void;
-    /**
-     * 获取旋转
-     */
-    getRotation(): [number, number, number];
-    /**
-     * 设置缩放
-     */
+    getRotation(): Vec3Tuple;
     setScale(x: number, y: number, z: number): void;
-    /**
-     * 获取缩放
-     */
-    getScale(): [number, number, number];
-    /**
-     * 设置旋转/缩放中心点 (pivot)
-     */
+    getScale(): Vec3Tuple;
     setPivot(x: number, y: number, z: number): void;
-    /**
-     * 获取旋转/缩放中心点 (pivot)
-     */
-    getPivot(): [number, number, number];
-    /**
-     * 更新模型矩阵
-     * 变换顺序: T * Tp * R * S * Tp^-1
-     * 即: 先移到原点，缩放，旋转，再移回pivot，最后应用用户平移
-     */
+    getPivot(): Vec3Tuple;
     private updateModelMatrix;
-    /**
-     * 获取当前模型矩阵
-     */
     getModelMatrix(): Float32Array;
-    /**
-     * 获取当前性能等级
-     */
-    getPerformanceTier(): PerformanceTier;
-    /**
-     * 手动设置优化配置
-     */
-    setOptimizationConfig(config: Partial<MobileOptimizationConfig>): void;
-    /**
-     * 获取当前优化配置
-     */
-    getOptimizationConfig(): MobileOptimizationConfig;
-    /**
-     * 设置 SH 模式
-     * @param mode L0/L1/L2/L3
-     */
     setSHMode(mode: SHMode): void;
-    /**
-     * 获取当前 SH 模式
-     */
     getSHMode(): SHMode;
-    /**
-     * 设置是否启用 DrawIndirect (剔除优化)
-     * 启用后会在 GPU 上进行可见性剔除，仅绘制可见 splat
-     */
-    setUseDrawIndirect(enabled: boolean): void;
-    /**
-     * 设置像素剔除阈值
-     * 屏幕上小于此像素数的 splat 会被剔除
-     * @param threshold 像素阈值，默认 1.0
-     */
     setPixelCullThreshold(threshold: number): void;
     /**
-     * 创建渲染管线 (L0/L1/L2/L3 四个版本)
+     * 设置最大可见 splat 数量
+     * 排序后只保留距离最近的 N 个 splat，远处被遮挡的 splat 被丢弃
+     * 0 = 不限制
      */
-    private createPipelines;
+    setMaxVisibleSplats(count: number): void;
+    getMaxVisibleSplats(): number;
     /**
-     * 创建 uniform buffer
-     * 布局: view (64 bytes) + proj (64 bytes) + model (64 bytes) + cameraPos (12 bytes) + padding (4 bytes) + screenSize (8 bytes) + padding (8 bytes) = 224 bytes
-     */
-    private createUniformBuffer;
-    /**
-     * 设置 splat 数据
-     * @param splats CPU 端的 splat 数组
+     * 设置排序频率
+     * 1 = 每帧排序（默认），2 = 每 2 帧排序一次，以此类推
+     * 相机静止时自动跳过排序，不受此参数影响
      */
+    setSortFrequency(frequency: number): void;
+    getSortFrequency(): number;
+    private needsSort;
+    private saveSortState;
     setData(splats: SplatCPU[]): void;
-    /**
-     * 设置紧凑格式的 splat 数据（移动端优化）
-     * 直接接受 CompactSplatData，避免创建中间对象
-     * @param compactData 紧凑格式的 splat 数据
-     */
     setCompactData(compactData: CompactSplatData): void;
-    /**
-     * 从紧凑数据计算 bounding box
-     */
-    private computeBoundingBoxFromCompact;
-    /**
-     * 渲染 splats
-     * @param pass 渲染通道编码器
-     */
     render(pass: GPURenderPassEncoder): void;
-    /**
-     * 获取 splat 数量
-     */
     getSplatCount(): number;
-    /**
-     * 获取点云的 bounding box
-     * @returns BoundingBox 或 null（如果没有点云数据）
-     */
     getBoundingBox(): BoundingBox | null;
-    /**
-     * 计算点云的 bounding box
-     * @param splats splat 数组
-     * @returns BoundingBox
-     */
+    getCPUPositions(): Float32Array | null;
     private computeBoundingBox;
-    /**
-     * 是否支持指定的 SH 模式
-     */
-    supportsSHMode(mode: ISHMode): boolean;
-    /**
-     * 获取渲染器能力
-     */
+    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

@@ -10,8 +10,9 @@
 import { Renderer } from "../core/Renderer";
 import { Camera } from "../core/Camera";
 import { CompactSplatData } from "./PLYLoaderMobile";
-import { BoundingBox, SHMode, RendererCapabilities, IGSSplatRendererWithCapabilities } from "./IGSSplatRenderer";
-export type { BoundingBox } from "./IGSSplatRenderer";
+import type { BoundingBox, Vec3Tuple } from "../types";
+import { SHMode, RendererCapabilities } from "../types";
+import type { IGSSplatRendererWithCapabilities } from "./IGSSplatRenderer";
 /**
  * GSSplatRendererMobile - 移动端优化渲染器
  * 实现 IGSSplatRenderer 接口
@@ -30,6 +31,7 @@ export declare class GSSplatRendererMobile implements IGSSplatRendererWithCapabi
     private sorter;
     private positionsBuffer;
     private boundingBox;
+    private cpuPositions;
     private frameCount;
     private sortEveryNFrames;
     private position;
@@ -45,7 +47,7 @@ export declare class GSSplatRendererMobile implements IGSSplatRendererWithCapabi
     /**
      * 获取位置
      */
-    getPosition(): [number, number, number];
+    getPosition(): Vec3Tuple;
     /**
      * 设置旋转 (欧拉角, 弧度)
      */
@@ -53,7 +55,7 @@ export declare class GSSplatRendererMobile implements IGSSplatRendererWithCapabi
     /**
      * 获取旋转
      */
-    getRotation(): [number, number, number];
+    getRotation(): Vec3Tuple;
     /**
      * 设置缩放
      */
@@ -61,7 +63,7 @@ export declare class GSSplatRendererMobile implements IGSSplatRendererWithCapabi
     /**
      * 获取缩放
      */
-    getScale(): [number, number, number];
+    getScale(): Vec3Tuple;
     /**
      * 设置旋转/缩放中心点 (pivot)
      */
@@ -69,7 +71,7 @@ export declare class GSSplatRendererMobile implements IGSSplatRendererWithCapabi
     /**
      * 获取旋转/缩放中心点 (pivot)
      */
-    getPivot(): [number, number, number];
+    getPivot(): Vec3Tuple;
     /**
      * 更新模型矩阵
      * 变换顺序: T * Tp * R * S * Tp^-1
@@ -115,6 +117,7 @@ export declare class GSSplatRendererMobile implements IGSSplatRendererWithCapabi
      * 获取 bounding box
      */
     getBoundingBox(): BoundingBox | null;
+    getCPUPositions(): Float32Array | null;
     /**
      * 设置排序频率
      * @param n 每 n 帧排序一次