@d5techs/3dgs-lib 1.0.1 → 1.1.1

package/dist/gs/GSSplatSorter.d.ts

@@ -1,18 +1,12 @@
 /**
- * GSSplatSorter - GPU Counting Sort 深度排序器
+ * GSSplatSorter - GPU Radix Sort 深度排序器
  *
- * 基于 PlayCanvas 的排序算法实现，使用 Counting Sort
- * 时间复杂度 O(n)，远比 Bitonic Sort O(n log²n) 更快
+ * 基于 rfs-gsplat-render 的 3-Pass Radix Sort 架构实现:
+ * - 4 个 pass (8-bit 增量，总共 32 位)
+ * - 每个 pass 包含: Upsweep -> Spine -> Downsweep
+ * - 稳定排序，解决远距离闪烁问题
  *
- * 流程：
- * 1. 剔除 + 计算深度 + 统计计数
- * 2. 前缀和计算偏移
- * 3. 散射到最终位置
- *
- * iOS 兼容性：
- * - iOS WebGPU 对大型原子数组支持有限
- * - 默认使用 65536 个桶（桌面/Android）
- * - iOS 使用 4096 个桶（减少原子操作压力）
+ * 参考: rfs-gsplat-render/assets/shaders/radix_sort.wgsl
  */
 /**
  * 屏幕尺寸信息
@@ -28,48 +22,64 @@ export interface CullingOptions {
     nearPlane: number;
     farPlane: number;
     pixelThreshold: number;
+    frustumDilation?: number;
+    /** 最大可见 splat 数量（排序后截断），0 = 不限制 */
+    maxVisibleCount?: number;
 }
 /**
  * 排序器配置选项
  */
 export interface SorterOptions {
-    /** 深度桶数量（必须是 2 的幂次），默认根据平台自动选择 */
+    /** 暂时保留，Radix Sort 不使用桶配置 */
     numBuckets?: number;
 }
 /**
- * GSSplatSorter - GPU Counting Sort 排序器
+ * GSSplatSorter - GPU Radix Sort 排序器
+ * 基于 rfs-gsplat-render 的 3-Pass Radix Sort 实现
  */
 export declare class GSSplatSorter {
     private device;
     private splatCount;
     private cullingParamsBuffer;
-    private countersBuffer;
-    private visibleIndicesBuffer;
     private depthKeysBuffer;
-    private bucketCountsBuffer;
-    private bucketOffsetsBuffer;
-    private bucketPositionsBuffer;
+    private visibleIndicesBuffer;
+    private indirectBuffer;
+    private globalHistogramBuffer;
+    private partitionHistogramBuffer;
+    private keysTempBuffer;
+    private valuesTempBuffer;
+    private sortParamsBuffers;
     private sortedIndicesBuffer;
-    private drawIndirectBuffer;
-    private resetCountersPipeline;
-    private resetBucketCountsPipeline;
-    private cullAndCountPipeline;
-    private updateDrawIndirectPipeline;
-    private prefixSumPipeline;
-    private resetBucketPositionsPipeline;
-    private scatterPipeline;
+    private initIndirectPipeline;
+    private projectCullPipeline;
+    private clampDrawCountPipeline;
     private cullingBindGroupLayout;
     private cullingBindGroup;
-    private prefixSumBindGroupLayout;
-    private prefixSumBindGroup;
-    private scatterBindGroupLayout;
-    private scatterBindGroup;
-    private readonly WORKGROUP_SIZE;
-    private readonly numBuckets;
+    private upsweepPipeline;
+    private spinePipeline;
+    private downsweepPipeline;
+    private upsweepBindGroupLayout;
+    private spineBindGroupLayout;
+    private downsweepBindGroupLayout;
+    private upsweepBindGroups;
+    private spineBindGroups;
+    private downsweepBindGroups;
+    private numPartitions;
     private screenWidth;
     private screenHeight;
     private cullingOptions;
-    constructor(device: GPUDevice, splatCount: number, splatBuffer: GPUBuffer, cameraBuffer: GPUBuffer, options?: SorterOptions);
+    constructor(device: GPUDevice, splatCount: number, splatBuffer: GPUBuffer, cameraBuffer: GPUBuffer, _options?: SorterOptions);
+    /**
+     * 创建 Radix Sort 的 bind groups
+     * 4 个 pass，使用 ping-pong buffers
+     *
+     * Ping-pong 模式:
+     * - Pass 0: depthKeys/visibleIndices -> keysTempBuffer/valuesTempBuffer
+     * - Pass 1: keysTempBuffer/valuesTempBuffer -> depthKeys/visibleIndices
+     * - Pass 2: depthKeys/visibleIndices -> keysTempBuffer/valuesTempBuffer
+     * - Pass 3: keysTempBuffer/valuesTempBuffer -> (depthKeys)/sortedIndicesBuffer
+     */
+    private createRadixSortBindGroups;
     /**
      * 设置屏幕尺寸
      */
@@ -81,9 +91,6 @@ export declare class GSSplatSorter {
     /**
      * 执行剔除和排序
      * 每帧调用
-     *
-     * 优化：合并所有 compute pass 到单次 GPU 提交
-     * WebGPU 保证同一 command buffer 中的命令按顺序执行
      */
     sort(): void;
     /**

package/dist/gs/IGSSplatRenderer.d.ts

@@ -3,26 +3,10 @@
  *
  * 桌面端和移动端渲染器都实现此接口，消除平台判断代码
  */
-import { CompactSplatData } from "./PLYLoaderMobile";
-import { SplatCPU } from "./PLYLoader";
-/**
- * Bounding Box 结构
- */
-export interface BoundingBox {
-    min: [number, number, number];
-    max: [number, number, number];
-    center: [number, number, number];
-    radius: number;
-}
-/**
- * SH 模式枚举
- */
-export declare enum SHMode {
-    L0 = 0,// 仅 DC 颜色（最快）
-    L1 = 1,// DC + L1 SH
-    L2 = 2,// DC + L1 + L2 SH
-    L3 = 3
-}
+import type { CompactSplatData } from "./PLYLoaderMobile";
+import type { SplatCPU } from "./PLYLoader";
+import type { BoundingBox, Vec3Tuple } from "../types";
+import { SHMode, RendererCapabilities } from "../types";
 /**
  * 3D Gaussian Splatting 渲染器接口
  */
@@ -47,7 +31,7 @@ export interface IGSSplatRenderer {
     /**
      * 获取位置
      */
-    getPosition(): [number, number, number];
+    getPosition(): Vec3Tuple;
     /**
      * 设置旋转（欧拉角，弧度）
      */
@@ -55,7 +39,7 @@ export interface IGSSplatRenderer {
     /**
      * 获取旋转
      */
-    getRotation(): [number, number, number];
+    getRotation(): Vec3Tuple;
     /**
      * 设置缩放
      */
@@ -63,7 +47,7 @@ export interface IGSSplatRenderer {
     /**
      * 获取缩放
      */
-    getScale(): [number, number, number];
+    getScale(): Vec3Tuple;
     /**
      * 设置旋转/缩放中心点（pivot）
      */
@@ -71,7 +55,7 @@ export interface IGSSplatRenderer {
     /**
      * 获取旋转/缩放中心点（pivot）
      */
-    getPivot(): [number, number, number];
+    getPivot(): Vec3Tuple;
     /**
      * 获取模型矩阵
      */
@@ -84,6 +68,11 @@ export interface IGSSplatRenderer {
      * 获取 bounding box
      */
     getBoundingBox(): BoundingBox | null;
+    /**
+     * 获取 CPU 端 splat 位置数据（用于射线拾取等交互）
+     * 返回 Float32Array，每 3 个值为一个点的 x, y, z
+     */
+    getCPUPositions(): Float32Array | null;
     /**
      * 设置 SH 模式
      * 移动端可能只支持 L0
@@ -97,24 +86,37 @@ 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;
     /**
      * 销毁资源
      */
     destroy(): void;
 }
-/**
- * 渲染器能力描述
- */
-export interface RendererCapabilities {
-    /** 支持的最高 SH 模式 */
-    maxSHMode: SHMode;
-    /** 是否支持原始 SplatCPU 数据 */
-    supportsRawData: boolean;
-    /** 是否为移动端优化版本 */
-    isMobileOptimized: boolean;
-    /** 最大支持的 splat 数量（0 表示无限制） */
-    maxSplatCount: number;
-}
 /**
  * 获取渲染器能力（可选方法）
  */

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

@@ -2,31 +2,32 @@
  * WebGPU 3D 渲染引擎
  * 库入口文件 - 导出所有公共 API
  */
+export type { Vec3Tuple, Vec4Tuple, BoundingBox, SimpleBoundingBox, Transform, TransformableObject as ITransformableObject, BoundingBoxProvider as IBoundingBoxProvider, MaterialData, RendererCapabilities, } from './types';
+export { SHMode, DEFAULT_MATERIAL, DEFAULT_OBJ_MATERIAL } from './types';
+export { isMobileDevice, getRecommendedDPR, isWebGPUSupported, computeBoundingBox, mergeBoundingBoxes, createBoundingBoxFromMinMax, transformBoundingBox, loadTextureFromURL, loadTextureFromBlob, loadTextureFromBuffer, createTextureFromImageBitmap, TextureCache, } from './utils';
 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 { MaterialData, LoadedMesh } from './loaders/GLBLoader';
+export type { LoadedMesh } from './loaders/GLBLoader';
 export { OBJLoader } from './loaders/OBJLoader';
 export { OBJParser } from './loaders/OBJParser';
 export type { ParsedOBJData, ParsedObject } from './loaders/OBJParser';
 export { MTLParser } from './loaders/MTLParser';
 export type { ParsedMaterial } from './loaders/MTLParser';
-export type { IGSSplatRenderer, IGSSplatRendererWithCapabilities, RendererCapabilities, BoundingBox, SHMode } from './gs/IGSSplatRenderer';
+export type { IGSSplatRenderer, IGSSplatRendererWithCapabilities, } from './gs/IGSSplatRenderer';
 export { loadPLY } from './gs/PLYLoader';
 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, PerformanceTier } from './gs/GSSplatRenderer';
-export { SHMode as GSSHMode } from './gs/GSSplatRenderer';
-export type { MobileOptimizationConfig } 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';
@@ -36,9 +37,12 @@ export { compressSplatsToTextures, destroyCompressedTextures, calculateTextureDi
 export type { CompressedSplatTextures } from './gs/TextureCompressor';
 export { SceneManager } from './scene/SceneManager';
 export type { SceneObjectType, SceneObjectInfo } from './scene/SceneManager';
-export { GizmoManager, SplatTransformProxy as GizmoSplatTransformProxy, MeshGroupProxy as GizmoMeshGroupProxy, SplatBoundingBoxProvider as GizmoSplatBoundingBoxProvider } from './interaction/GizmoManager';
-export { App, SplatTransformProxy, MeshGroupProxy, SplatBoundingBoxProvider } from './App';
+export { SplatTransformProxy, MeshGroupProxy, SplatBoundingBoxProvider, } from './scene/proxies';
+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,50 +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 { IGSSplatRenderer } from "../gs/IGSSplatRenderer";
-import { Mesh } from "../mesh/Mesh";
-/**
- * SplatTransformProxy - PLY/Splat 变换代理对象
- * 实现类似 Mesh 的接口，让 TransformGizmo 可以操作 PLY 模型
- */
-export declare class SplatTransformProxy implements TransformableObject {
-    position: [number, number, number];
-    rotation: [number, number, number];
-    scale: [number, number, number];
-    private renderer;
-    private center;
-    constructor(renderer: IGSSplatRenderer, center: [number, number, number]);
-    setPosition(x: number, y: number, z: number): void;
-    setRotation(x: number, y: number, z: number): void;
-    setScale(x: number, y: number, z: number): void;
-}
-/**
- * MeshGroupProxy - 多 Mesh 组变换代理对象
- * 让 TransformGizmo 可以同时操作多个 Mesh
- */
-export declare class MeshGroupProxy implements TransformableObject {
-    position: [number, number, number];
-    rotation: [number, number, number];
-    scale: [number, number, number];
-    private meshes;
-    constructor(meshes: Mesh[]);
-    setPosition(x: number, y: number, z: number): void;
-    setRotation(x: number, y: number, z: number): void;
-    setScale(x: number, y: number, z: number): void;
-    getBoundingBox(): RendererBoundingBox | null;
-}
-/**
- * SplatBoundingBoxProvider - PLY/Splat 包围盒提供者
- * 动态获取 PLY 的包围盒（考虑变换）
- */
-export declare class SplatBoundingBoxProvider implements BoundingBoxProvider {
-    private renderer;
-    constructor(renderer: IGSSplatRenderer);
-    getBoundingBox(): RendererBoundingBox | null;
-}
+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";
 /**
  * GizmoManager - Gizmo 交互管理器
  */
@@ -84,7 +47,7 @@ export declare class GizmoManager {
     /**
      * 获取变换 Gizmo
      */
-    getTransformGizmo(): TransformGizmoV2;
+    getTransformGizmo(): TransformGizmo;
     /**
      * 设置 Gizmo 模式
      */
@@ -104,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;
+}

package/dist/loaders/GLBLoader.d.ts

@@ -1,14 +1,6 @@
 import { Mesh } from '../mesh/Mesh';
-/**
- * 材质数据
- */
-export interface MaterialData {
-    baseColorFactor: [number, number, number, number];
-    baseColorTexture: GPUTexture | null;
-    metallicFactor: number;
-    roughnessFactor: number;
-    doubleSided: boolean;
-}
+import type { MaterialData } from '../types';
+export type { MaterialData };
 /**
  * 加载后的 Mesh 数据（包含材质）
  */
@@ -51,7 +43,7 @@ export declare class GLBLoader {
     /**
      * 计算顶点数据的 bounding box
      */
-    private computeBoundingBox;
+    private computeBoundingBoxFromPositions;
     /**
      * 获取访问器数据 - 修复字节对齐问题
      */

package/dist/loaders/OBJLoader.d.ts

@@ -54,7 +54,7 @@ export declare class OBJLoader {
      * 计算顶点数据的 bounding box
      * Requirement 3.5: 计算并存储 bounding box 信息
      */
-    private computeBoundingBox;
+    private computeBoundingBoxFromPositions;
     /**
      * 创建材质数据
      * Requirement 4.3: 将材质关联到网格

package/dist/mesh/Mesh.d.ts

@@ -1,12 +1,4 @@
-/**
- * Bounding Box 结构（与 GSSplatRenderer 共享接口）
- */
-export interface MeshBoundingBox {
-    min: [number, number, number];
-    max: [number, number, number];
-    center: [number, number, number];
-    radius: number;
-}
+import type { BoundingBox, Vec3Tuple } from "../types";
 /**
  * Mesh - 网格数据结构
  * 存储 GPUBuffer + 变换属性
@@ -23,7 +15,7 @@ export declare class Mesh {
     rotation: Float32Array;
     scale: Float32Array;
     private localBoundingBox;
-    constructor(vertexBuffer: GPUBuffer, vertexCount: number, indexBuffer?: GPUBuffer | null, indexCount?: number, boundingBox?: MeshBoundingBox);
+    constructor(vertexBuffer: GPUBuffer, vertexCount: number, indexBuffer?: GPUBuffer | null, indexCount?: number, boundingBox?: BoundingBox);
     /**
      * 获取顶点 stride（字节数）
      */
@@ -31,21 +23,21 @@ export declare class Mesh {
     /**
      * 设置本地 bounding box
      */
-    setBoundingBox(bbox: MeshBoundingBox): void;
+    setBoundingBox(bbox: BoundingBox): void;
     /**
      * 获取本地 bounding box
      */
-    getLocalBoundingBox(): MeshBoundingBox | null;
+    getLocalBoundingBox(): BoundingBox | null;
     /**
      * 获取世界空间的 bounding box（考虑完整变换：缩放、旋转、平移）
      */
-    getWorldBoundingBox(): MeshBoundingBox | null;
+    getWorldBoundingBox(): BoundingBox | null;
     setPosition(x: number, y: number, z: number): void;
-    getPosition(): [number, number, number];
+    getPosition(): Vec3Tuple;
     setRotation(rx: number, ry: number, rz: number): void;
-    getRotation(): [number, number, number];
+    getRotation(): Vec3Tuple;
     setScale(sx: number, sy: number, sz: number): void;
-    getScale(): [number, number, number];
+    getScale(): Vec3Tuple;
     updateModelMatrix(): void;
     resetTransform(): void;
     destroy(): void;