@d5techs/3dgs-lib 1.0.0

package/dist/App.d.ts

@@ -0,0 +1,142 @@
+/**
+ * App - 统一调度入口
+ *
+ * 重构后的职责：
+ * - 初始化和协调各子系统
+ * - 渲染循环管理
+ * - 模型加载（委托给加载器）
+ * - 对外提供简洁的 API
+ *
+ * 场景管理委托给 SceneManager
+ * Gizmo 交互委托给 GizmoManager
+ */
+import { Renderer } from "./core/Renderer";
+import { Camera } from "./core/Camera";
+import { OrbitControls } from "./core/OrbitControls";
+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 };
+/**
+ * 统一进度回调类型
+ * @param progress 进度值 0-100
+ * @param stage 当前阶段: 'download' | 'parse' | 'upload'
+ */
+export type ProgressCallback = (progress: number, stage: 'download' | 'parse' | 'upload') => void;
+/**
+ * App - 统一调度入口
+ */
+export declare class App {
+    private canvas;
+    private renderer;
+    private camera;
+    private controls;
+    private meshRenderer;
+    private glbLoader;
+    private objLoader;
+    private sceneManager;
+    private gizmoManager;
+    private isRunning;
+    private animationId;
+    private useMobileRenderer;
+    private boundOnResize;
+    constructor(canvas: HTMLCanvasElement);
+    /**
+     * 初始化应用
+     */
+    init(): Promise<void>;
+    /**
+     * 加载 GLB 文件
+     */
+    addGLB(url: string): Promise<number>;
+    /**
+     * 加载 OBJ 文件
+     */
+    addOBJ(url: string): Promise<Mesh[]>;
+    /**
+     * 加载 PLY 文件 (3D Gaussian Splatting)
+     */
+    addPLY(urlOrBuffer: string | ArrayBuffer, onProgress?: ProgressCallback, isLocalFile?: boolean): Promise<number>;
+    /**
+     * 加载 Splat 文件
+     */
+    addSplat(urlOrBuffer: string | ArrayBuffer, onProgress?: ProgressCallback, isLocalFile?: boolean): Promise<number>;
+    /**
+     * 添加测试立方体
+     */
+    addTestCube(): void;
+    /**
+     * 添加测试球体
+     */
+    addTestSphere(): void;
+    /**
+     * 开始渲染循环
+     */
+    start(): void;
+    /**
+     * 停止渲染循环
+     */
+    stop(): void;
+    private animate;
+    private render;
+    private onResize;
+    getMeshCount(): number;
+    getMeshByIndex(index: number): Mesh | null;
+    getMeshRange(startIndex: number, count: number): Mesh[];
+    clearMeshes(): void;
+    removeMeshByIndex(index: number): boolean;
+    getSplatCount(): number;
+    clearSplats(): void;
+    setSplatPosition(x: number, y: number, z: number): void;
+    getSplatPosition(): [number, number, number] | null;
+    setSplatRotation(x: number, y: number, z: number): void;
+    getSplatRotation(): [number, number, number] | null;
+    setSplatScale(x: number, y: number, z: number): void;
+    getSplatScale(): [number, number, number] | null;
+    setSHMode(mode: 0 | 1 | 2 | 3): void;
+    getSHMode(): number;
+    getSplatBoundingBox(): BoundingBox | null;
+    getMeshRangeBoundingBox(startIndex: number, count: number): BoundingBox | null;
+    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;
+    frameCurrentModel(animate?: boolean): boolean;
+    getTransformGizmo(): import(".").TransformGizmoV2;
+    getViewportGizmo(): import(".").ViewportGizmo;
+    getBoundingBoxRenderer(): import(".").BoundingBoxRenderer;
+    setGizmoMode(mode: GizmoMode): void;
+    setGizmoTarget(object: TransformableObject | null): void;
+    setSelectionBoundingBox(box: BoundingBox | null): void;
+    setSelectionBoundingBoxProvider(provider: BoundingBoxProvider | null): void;
+    clearSelectionBoundingBox(): void;
+    /**
+     * 创建 Mesh 组的变换代理
+     */
+    createMeshGroupProxy(startIndex: number, count: number): MeshGroupProxy | null;
+    /**
+     * 获取 Splat 的变换代理
+     */
+    getSplatTransformProxy(): SplatTransformProxy | null;
+    /**
+     * 创建 Splat 包围盒提供者
+     */
+    createSplatBoundingBoxProvider(): SplatBoundingBoxProvider | null;
+    getRenderer(): Renderer;
+    getCamera(): Camera;
+    getControls(): OrbitControls;
+    getMeshRenderer(): MeshRenderer;
+    getGSRenderer(): GSSplatRenderer | undefined;
+    getGSRendererMobile(): GSSplatRendererMobile | undefined;
+    isUsingMobileRenderer(): boolean;
+    private fetchWithProgress;
+    private parsePLYBuffer;
+    /**
+     * 销毁应用及所有资源
+     */
+    destroy(): void;
+}

package/dist/core/BoundingBoxRenderer.d.ts

@@ -0,0 +1,70 @@
+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;
+}
+/**
+ * BoundingBoxRenderer - 包围盒线框渲染器
+ * 用于显示选中对象的包围盒，支持动态跟随
+ */
+export declare class BoundingBoxRenderer {
+    private renderer;
+    private camera;
+    private pipeline;
+    private uniformBuffer;
+    private bindGroup;
+    private vertexBuffer;
+    private provider;
+    private staticBoundingBox;
+    private lineColor;
+    private cornerRatio;
+    constructor(renderer: Renderer, camera: Camera);
+    /**
+     * 创建渲染管线
+     */
+    private createPipeline;
+    /**
+     * 创建顶点缓冲区（预分配）
+     */
+    private createVertexBuffer;
+    /**
+     * 设置包围盒数据提供者（动态模式）
+     * 每帧会从 provider 获取最新的包围盒数据
+     */
+    setProvider(provider: BoundingBoxProvider | null): void;
+    /**
+     * 设置静态包围盒（不会自动更新）
+     */
+    setBoundingBox(box: BoundingBox | null): void;
+    /**
+     * 清除包围盒
+     */
+    clear(): void;
+    /**
+     * 设置线条颜色
+     */
+    setLineColor(r: number, g: number, b: number): void;
+    /**
+     * 生成顶点数据
+     */
+    private generateVertices;
+    /**
+     * 渲染包围盒
+     */
+    render(pass: GPURenderPassEncoder): void;
+    /**
+     * 销毁资源
+     */
+    destroy(): void;
+}

package/dist/core/Camera.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Camera - 相机矩阵计算
+ * 只负责视图矩阵和投影矩阵
+ */
+export declare class Camera {
+    position: Float32Array;
+    target: Float32Array;
+    up: Float32Array;
+    fov: number;
+    aspect: number;
+    near: number;
+    far: number;
+    viewMatrix: Float32Array;
+    projectionMatrix: Float32Array;
+    viewProjectionMatrix: Float32Array;
+    constructor();
+    /**
+     * 设置宽高比
+     */
+    setAspect(aspect: number): void;
+    /**
+     * 更新视图和投影矩阵
+     */
+    updateMatrix(): void;
+    /**
+     * 计算视图矩阵 (lookAt)
+     */
+    private updateViewMatrix;
+    /**
+     * 计算投影矩阵 (透视投影)
+     */
+    private updateProjectionMatrix;
+    private subtract;
+    private cross;
+    private dot;
+    private normalize;
+    private multiplyMatrices;
+}

package/dist/core/OrbitControls.d.ts

@@ -0,0 +1,101 @@
+import { Camera } from "./Camera";
+/**
+ * OrbitControls - 轨道控制器
+ * 只负责鼠标/触摸输入控制相机
+ */
+export declare class OrbitControls {
+    private camera;
+    private canvas;
+    distance: number;
+    theta: number;
+    phi: number;
+    minDistance: number;
+    maxDistance: number;
+    minPhi: number;
+    maxPhi: number;
+    rotateSpeed: number;
+    zoomSpeed: number;
+    panSpeed: number;
+    touchZoomSpeed: number;
+    touchPanSpeed: number;
+    private isDragging;
+    private lastX;
+    private lastY;
+    private touchMode;
+    private lastTouchDistance;
+    private lastTouchCenter;
+    enabled: boolean;
+    private boundOnMouseDown;
+    private boundOnMouseMove;
+    private boundOnMouseUp;
+    private boundOnWheel;
+    private boundOnTouchStart;
+    private boundOnTouchMove;
+    private boundOnTouchEnd;
+    private boundOnContextMenu;
+    constructor(camera: Camera, canvas: HTMLCanvasElement);
+    /**
+     * 设置事件监听
+     */
+    private setupEventListeners;
+    /**
+     * 移除事件监听
+     */
+    private removeEventListeners;
+    /**
+     * 销毁控制器
+     */
+    destroy(): void;
+    private onMouseDown;
+    private onMouseMove;
+    private onMouseUp;
+    private onWheel;
+    private onTouchStart;
+    private onTouchMove;
+    private onTouchEnd;
+    /**
+     * 计算双指之间的距离
+     */
+    private getTouchDistance;
+    /**
+     * 计算双指的中心点
+     */
+    private getTouchCenter;
+    /**
+     * 根据球坐标更新相机位置
+     */
+    update(): void;
+    /**
+     * 切换到标准视图
+     * @param axis 轴 'X' | 'Y' | 'Z'
+     * @param positive 是否正向
+     * @param animate 是否动画过渡
+     */
+    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;
+}

package/dist/core/Renderer.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Renderer - WebGPU 初始化 + 帧提交
+ * 只负责 WebGPU 设备管理和渲染通道
+ */
+export declare class Renderer {
+    private canvas;
+    private _device;
+    private _context;
+    private _format;
+    private _depthTexture;
+    private _depthTextureView;
+    private commandEncoder;
+    private renderPassEncoder;
+    private resizeObserver;
+    private _clearColor;
+    constructor(canvas: HTMLCanvasElement);
+    /**
+     * 设置背景颜色
+     */
+    setClearColor(r: number, g: number, b: number, a?: number): void;
+    /**
+     * 通过十六进制设置背景颜色
+     */
+    setClearColorHex(hex: string): void;
+    /**
+     * 获取背景颜色（十六进制）
+     */
+    getClearColorHex(): string;
+    get device(): GPUDevice;
+    get context(): GPUCanvasContext;
+    get format(): GPUTextureFormat;
+    get depthFormat(): GPUTextureFormat;
+    /**
+     * 获取渲染宽度（像素）
+     */
+    get width(): number;
+    /**
+     * 获取渲染高度（像素）
+     */
+    get height(): number;
+    /**
+     * 初始化 WebGPU
+     */
+    init(): Promise<void>;
+    /**
+     * 创建深度纹理
+     */
+    private createDepthTexture;
+    /**
+     * 设置 resize 监听
+     */
+    private setupResizeObserver;
+    /**
+     * 销毁渲染器资源
+     */
+    destroy(): void;
+    /**
+     * 开始帧 - 创建命令编码器和渲染通道
+     */
+    beginFrame(): GPURenderPassEncoder;
+    /**
+     * 结束帧 - 提交命令
+     */
+    endFrame(): void;
+    /**
+     * 获取 canvas 宽高比
+     */
+    getAspectRatio(): number;
+}

package/dist/core/ViewportGizmo.d.ts

@@ -0,0 +1,83 @@
+import { Camera } from "./Camera";
+import { Renderer } from "./Renderer";
+/**
+ * ViewportGizmo - 视口坐标轴指示器
+ * 在画布右上角显示当前相机朝向
+ */
+export declare class ViewportGizmo {
+    private renderer;
+    private camera;
+    private canvas;
+    private pipeline;
+    private uniformBuffer;
+    private bindGroup;
+    private vertexBuffer;
+    private indexBuffer;
+    private vertexCount;
+    private indexCount;
+    private size;
+    private margin;
+    private projMatrix;
+    private viewMatrix;
+    private axes;
+    private onAxisClick?;
+    constructor(renderer: Renderer, camera: Camera, canvas: HTMLCanvasElement);
+    /**
+     * 设置轴点击回调
+     */
+    setOnAxisClick(callback: (axis: string, positive: boolean) => void): void;
+    /**
+     * 创建渲染管线
+     */
+    private createPipeline;
+    /**
+     * 创建 Gizmo 几何体（三个轴 + 箭头）
+     */
+    private createGeometry;
+    /**
+     * 创建圆柱体几何
+     */
+    private createCylinder;
+    /**
+     * 创建圆锥几何
+     */
+    private createCone;
+    /**
+     * 创建球体几何
+     */
+    private createSphere;
+    /**
+     * 创建 uniform buffer
+     */
+    private createUniformBuffer;
+    /**
+     * 设置正交投影矩阵
+     */
+    private setupOrthoProjection;
+    /**
+     * 更新 Gizmo 视图矩阵（从相机提取旋转部分）
+     */
+    private updateViewMatrix;
+    /**
+     * 渲染 Gizmo
+     */
+    render(pass: GPURenderPassEncoder): void;
+    /**
+     * 处理点击事件，检测是否点击了某个轴
+     */
+    handleClick(clientX: number, clientY: number): boolean;
+    /**
+     * 检测点击了哪个轴
+     */
+    private detectClickedAxis;
+    private cross;
+    private normalize;
+    /**
+     * 设置 Gizmo 大小
+     */
+    setSize(size: number): void;
+    /**
+     * 设置边距
+     */
+    setMargin(margin: number): void;
+}

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

@@ -0,0 +1,90 @@
+import { Vec3 } from "../math/Vec3";
+import { Mat4 } from "../math/Mat4";
+import { Shape, ShapeConfig } from "./Shape";
+/**
+ * ArcShapeConfig - 圆弧形状配置
+ */
+export interface ArcShapeConfig extends ShapeConfig {
+    tubeRadius?: number;
+    ringRadius?: number;
+    sectorAngle?: number;
+    tolerance?: number;
+}
+/**
+ * ArcDisplayMode - 圆弧显示模式
+ */
+export type ArcDisplayMode = 'sector' | 'ring' | 'none';
+/**
+ * ArcShape - 圆弧形状（用于旋转 Gizmo）
+ * 参考 PlayCanvas 引擎的 ArcShape 实现
+ *
+ * 圆环默认在 XZ 平面上（绕 Y 轴），通过 rotation 旋转到正确的轴
+ */
+export declare class ArcShape extends Shape {
+    private _tubeRadius;
+    private _ringRadius;
+    private _sectorAngle;
+    private _tolerance;
+    private _displayMode;
+    private _sectorVertexBuffer;
+    private _sectorIndexBuffer;
+    private _sectorIndexCount;
+    private _ringVertexBuffer;
+    private _ringIndexBuffer;
+    private _ringIndexCount;
+    private _dynamicRotation;
+    constructor(config: ArcShapeConfig);
+    get tubeRadius(): number;
+    set tubeRadius(value: number);
+    get ringRadius(): number;
+    set ringRadius(value: number);
+    get sectorAngle(): number;
+    set sectorAngle(value: number);
+    get tolerance(): number;
+    set tolerance(value: number);
+    get displayMode(): ArcDisplayMode;
+    /**
+     * 设置动态旋转（用于面向相机）
+     */
+    setDynamicRotation(rotation: Vec3): void;
+    /**
+     * 获取局部变换矩阵（包含动态旋转）
+     */
+    getLocalTransform(): Mat4;
+    /**
+     * 更新碰撞数据
+     */
+    private _updateTriData;
+    /**
+     * 切换显示模式
+     */
+    show(mode: ArcDisplayMode): void;
+    /**
+     * 创建圆环几何体
+     */
+    private createTorusGeometry;
+    /**
+     * 创建渲染用的 GPU 几何体（同时创建 sector 和 ring 两种）
+     */
+    createGeometry(device: GPUDevice): void;
+    /**
+     * 创建圆环网格数据
+     */
+    private _createTorusMeshData;
+    /**
+     * 获取顶点缓冲区（根据显示模式）
+     */
+    getVertexBuffer(): GPUBuffer | null;
+    /**
+     * 获取索引缓冲区（根据显示模式）
+     */
+    getIndexBuffer(): GPUBuffer | null;
+    /**
+     * 获取索引数量（根据显示模式）
+     */
+    getIndexCount(): number;
+    /**
+     * 销毁 GPU 资源
+     */
+    destroy(): void;
+}

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

@@ -0,0 +1,51 @@
+import { Shape, ShapeConfig } from "./Shape";
+/**
+ * ArrowShapeConfig - 箭头形状配置
+ */
+export interface ArrowShapeConfig extends ShapeConfig {
+    gap?: number;
+    lineThickness?: number;
+    lineLength?: number;
+    arrowThickness?: number;
+    arrowLength?: number;
+    tolerance?: number;
+}
+/**
+ * ArrowShape - 箭头形状（用于平移 Gizmo）
+ * 参考 PlayCanvas 引擎的 ArrowShape 实现
+ */
+export declare class ArrowShape extends Shape {
+    private _gap;
+    private _lineThickness;
+    private _lineLength;
+    private _arrowThickness;
+    private _arrowLength;
+    private _tolerance;
+    constructor(config: ArrowShapeConfig);
+    get gap(): number;
+    set gap(value: number);
+    get lineThickness(): number;
+    set lineThickness(value: number);
+    get lineLength(): number;
+    set lineLength(value: number);
+    get arrowThickness(): number;
+    set arrowThickness(value: number);
+    get arrowLength(): number;
+    set arrowLength(value: number);
+    /**
+     * 更新碰撞数据
+     */
+    private _updateTriData;
+    /**
+     * 创建单位锥体几何体（底面半径1，高度1，底面在y=0，顶点在y=1）
+     */
+    private createConeGeometry;
+    /**
+     * 创建单位圆柱几何体（半径1，高度1，中心在原点）
+     */
+    private createCylinderGeometry;
+    /**
+     * 创建渲染用的 GPU 几何体
+     */
+    createGeometry(device: GPUDevice): void;
+}

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

@@ -0,0 +1,47 @@
+import { Shape, ShapeConfig } from "./Shape";
+/**
+ * BoxLineShapeConfig - 方块线形状配置（用于缩放 Gizmo）
+ */
+export interface BoxLineShapeConfig extends ShapeConfig {
+    gap?: number;
+    lineThickness?: number;
+    lineLength?: number;
+    boxSize?: number;
+    tolerance?: number;
+}
+/**
+ * BoxLineShape - 方块线形状（用于缩放 Gizmo）
+ * 参考 PlayCanvas 引擎的 BoxLineShape 实现
+ */
+export declare class BoxLineShape extends Shape {
+    private _gap;
+    private _lineThickness;
+    private _lineLength;
+    private _boxSize;
+    private _tolerance;
+    constructor(config: BoxLineShapeConfig);
+    get gap(): number;
+    set gap(value: number);
+    get lineThickness(): number;
+    set lineThickness(value: number);
+    get lineLength(): number;
+    set lineLength(value: number);
+    get boxSize(): number;
+    set boxSize(value: number);
+    /**
+     * 更新碰撞数据
+     */
+    private _updateTriData;
+    /**
+     * 创建单位方块几何体（边长1，中心在原点）
+     */
+    private createBoxGeometry;
+    /**
+     * 创建单位圆柱几何体
+     */
+    private createCylinderGeometry;
+    /**
+     * 创建渲染用的 GPU 几何体
+     */
+    createGeometry(device: GPUDevice): void;
+}