@d5techs/3dgs-lib 1.0.1 → 1.1.0

package/dist/mesh/Mesh.d.ts

@@ -1,12 +1,8 @@
+import type { BoundingBox, Vec3Tuple } from "../types";
 /**
- * Bounding Box 结构（与 GSSplatRenderer 共享接口）
+ * Mesh 包围盒类型别名（保持向后兼容）
  */
-export interface MeshBoundingBox {
-    min: [number, number, number];
-    max: [number, number, number];
-    center: [number, number, number];
-    radius: number;
-}
+export type MeshBoundingBox = BoundingBox;
 /**
  * Mesh - 网格数据结构
  * 存储 GPUBuffer + 变换属性
@@ -41,11 +37,11 @@ export declare class Mesh {
      */
     getWorldBoundingBox(): MeshBoundingBox | 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;

package/dist/scene/SceneManager.d.ts

@@ -6,10 +6,10 @@
  * - Splat 点云
  * - 场景查询（bounding box 等）
  */
-import { Mesh } from "../mesh/Mesh";
+import { Mesh, MeshBoundingBox } from "../mesh/Mesh";
 import { MeshRenderer } from "../mesh/MeshRenderer";
-import { IGSSplatRenderer, BoundingBox } from "../gs/IGSSplatRenderer";
-import { MeshBoundingBox } from "../mesh/Mesh";
+import type { IGSSplatRenderer } from "../gs/IGSSplatRenderer";
+import type { BoundingBox, Vec3Tuple } from "../types";
 /**
  * 场景对象类型
  */
@@ -76,7 +76,7 @@ export declare class SceneManager {
     /**
      * 获取 Splat 位置
      */
-    getSplatPosition(): [number, number, number] | null;
+    getSplatPosition(): Vec3Tuple | null;
     /**
      * 设置 Splat 旋转
      */
@@ -84,7 +84,7 @@ export declare class SceneManager {
     /**
      * 获取 Splat 旋转
      */
-    getSplatRotation(): [number, number, number] | null;
+    getSplatRotation(): Vec3Tuple | null;
     /**
      * 设置 Splat 缩放
      */
@@ -92,7 +92,7 @@ export declare class SceneManager {
     /**
      * 获取 Splat 缩放
      */
-    getSplatScale(): [number, number, number] | null;
+    getSplatScale(): Vec3Tuple | null;
     /**
      * 设置 SH 模式
      */

package/dist/scene/proxies/MeshGroupProxy.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MeshGroupProxy - 多 Mesh 组变换代理对象
+ * 让 TransformGizmo 可以同时操作多个 Mesh
+ */
+import type { TransformableObject, SimpleBoundingBox, Vec3Tuple } from '../../types';
+import type { Mesh } from '../../mesh/Mesh';
+export declare class MeshGroupProxy implements TransformableObject {
+    position: Vec3Tuple;
+    rotation: Vec3Tuple;
+    scale: Vec3Tuple;
+    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(): SimpleBoundingBox | null;
+}

package/dist/scene/proxies/SplatBoundingBoxProvider.d.ts

@@ -0,0 +1,11 @@
+/**
+ * SplatBoundingBoxProvider - PLY/Splat 包围盒提供者
+ * 动态获取 PLY 的包围盒（考虑变换）
+ */
+import type { BoundingBoxProvider, SimpleBoundingBox } from '../../types';
+import type { IGSSplatRenderer } from '../../gs/IGSSplatRenderer';
+export declare class SplatBoundingBoxProvider implements BoundingBoxProvider {
+    private renderer;
+    constructor(renderer: IGSSplatRenderer);
+    getBoundingBox(): SimpleBoundingBox | null;
+}

package/dist/scene/proxies/SplatTransformProxy.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SplatTransformProxy - PLY/Splat 变换代理对象
+ * 实现 TransformableObject 接口，让 TransformGizmo 可以操作 PLY 模型
+ */
+import type { TransformableObject, Vec3Tuple } from '../../types';
+import type { IGSSplatRenderer } from '../../gs/IGSSplatRenderer';
+export declare class SplatTransformProxy implements TransformableObject {
+    position: Vec3Tuple;
+    rotation: Vec3Tuple;
+    scale: Vec3Tuple;
+    private renderer;
+    private center;
+    constructor(renderer: IGSSplatRenderer, center: Vec3Tuple);
+    setPosition(x: number, y: number, z: number): void;
+    setRotation(x: number, y: number, z: number): void;
+    setScale(x: number, y: number, z: number): void;
+}

package/dist/scene/proxies/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 场景代理类统一导出
+ */
+export { SplatTransformProxy } from './SplatTransformProxy';
+export { MeshGroupProxy } from './MeshGroupProxy';
+export { SplatBoundingBoxProvider } from './SplatBoundingBoxProvider';

package/dist/types/geometry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 统一的几何类型定义
+ */
+/**
+ * 3D 向量类型（元组形式）
+ */
+export type Vec3Tuple = [number, number, number];
+/**
+ * 4D 向量类型（元组形式）
+ */
+export type Vec4Tuple = [number, number, number, number];
+/**
+ * 包围盒接口 - 统一定义
+ * 用于 Mesh、Splat、场景等所有 3D 对象
+ */
+export interface BoundingBox {
+    /** 最小点坐标 */
+    min: Vec3Tuple;
+    /** 最大点坐标 */
+    max: Vec3Tuple;
+    /** 中心点坐标 */
+    center: Vec3Tuple;
+    /** 包围球半径 */
+    radius: number;
+}
+/**
+ * 简化的包围盒（仅 min/max）
+ * 用于 BoundingBoxRenderer 等只需要边界的场景
+ */
+export interface SimpleBoundingBox {
+    min: Vec3Tuple;
+    max: Vec3Tuple;
+}
+/**
+ * 变换属性接口
+ */
+export interface Transform {
+    position: Vec3Tuple;
+    rotation: Vec3Tuple;
+    scale: Vec3Tuple;
+}
+/**
+ * 可变换对象接口
+ * 用于 Gizmo 操作的目标对象
+ */
+export interface TransformableObject {
+    position: Vec3Tuple;
+    rotation: Vec3Tuple;
+    scale: Vec3Tuple;
+    setPosition(x: number, y: number, z: number): void;
+    setRotation(x: number, y: number, z: number): void;
+    setScale(x: number, y: number, z: number): void;
+}
+/**
+ * 包围盒提供者接口
+ * 用于动态获取包围盒（考虑变换）
+ */
+export interface BoundingBoxProvider {
+    getBoundingBox(): SimpleBoundingBox | null;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 类型定义统一导出
+ */
+export type { Vec3Tuple, Vec4Tuple, BoundingBox, SimpleBoundingBox, Transform, TransformableObject, BoundingBoxProvider, } from './geometry';
+export type { MaterialData } from './material';
+export { DEFAULT_MATERIAL, DEFAULT_OBJ_MATERIAL } from './material';
+export { SHMode } from './splat';
+export type { RendererCapabilities } from './splat';

package/dist/types/material.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 统一的材质类型定义
+ */
+/**
+ * 材质数据接口
+ * 用于 GLB/OBJ 等模型的材质
+ */
+export interface MaterialData {
+    /** 基础颜色因子 [r, g, b, a] */
+    baseColorFactor: [number, number, number, number];
+    /** 基础颜色纹理 */
+    baseColorTexture: GPUTexture | null;
+    /** 金属度因子 */
+    metallicFactor: number;
+    /** 粗糙度因子 */
+    roughnessFactor: number;
+    /** 是否双面渲染 */
+    doubleSided: boolean;
+}
+/**
+ * 默认材质
+ */
+export declare const DEFAULT_MATERIAL: Readonly<MaterialData>;
+/**
+ * OBJ 默认材质（双面渲染）
+ */
+export declare const DEFAULT_OBJ_MATERIAL: Readonly<MaterialData>;

package/dist/types/splat.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 3D Gaussian Splatting 相关类型定义
+ */
+/**
+ * SH 模式枚举 - 球谐函数级别
+ */
+export declare enum SHMode {
+    L0 = 0,// 仅 DC 颜色（最快）
+    L1 = 1,// DC + L1 SH
+    L2 = 2,// DC + L1 + L2 SH
+    L3 = 3
+}
+/**
+ * 渲染器能力描述
+ */
+export interface RendererCapabilities {
+    /** 支持的最高 SH 模式 */
+    maxSHMode: SHMode;
+    /** 是否支持原始 SplatCPU 数据 */
+    supportsRawData: boolean;
+    /** 是否为移动端优化版本 */
+    isMobileOptimized: boolean;
+    /** 最大支持的 splat 数量（0 表示无限制） */
+    maxSplatCount: number;
+}

package/dist/utils/device.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 设备检测工具函数
+ */
+/**
+ * 检测是否为移动设备
+ * 综合考虑 UA、触摸支持、屏幕尺寸
+ */
+export declare function isMobileDevice(): boolean;
+/**
+ * 获取推荐的设备像素比
+ * 移动端限制 DPI 以避免性能问题
+ */
+export declare function getRecommendedDPR(): number;
+/**
+ * 检测 WebGPU 支持
+ */
+export declare function isWebGPUSupported(): boolean;

package/dist/utils/geometry.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 几何计算工具函数
+ */
+import type { BoundingBox, Vec3Tuple } from '../types';
+/**
+ * 从顶点位置数组计算包围盒
+ * @param positions 顶点位置数组 [x0, y0, z0, x1, y1, z1, ...]
+ * @returns 包围盒信息
+ */
+export declare function computeBoundingBox(positions: ArrayLike<number>): BoundingBox;
+/**
+ * 合并多个包围盒
+ * @param boxes 包围盒数组
+ * @returns 合并后的包围盒，如果输入为空则返回 null
+ */
+export declare function mergeBoundingBoxes(boxes: BoundingBox[]): BoundingBox | null;
+/**
+ * 从 min/max 计算完整的包围盒信息
+ */
+export declare function createBoundingBoxFromMinMax(min: Vec3Tuple, max: Vec3Tuple): BoundingBox;
+/**
+ * 变换包围盒的 8 个角点并计算新的 AABB
+ * @param bbox 原始包围盒
+ * @param modelMatrix 4x4 变换矩阵（列主序）
+ */
+export declare function transformBoundingBox(bbox: BoundingBox, modelMatrix: Float32Array): BoundingBox;

package/dist/utils/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 工具函数统一导出
+ */
+export { isMobileDevice, getRecommendedDPR, isWebGPUSupported, } from './device';
+export { computeBoundingBox, mergeBoundingBoxes, createBoundingBoxFromMinMax, transformBoundingBox, } from './geometry';
+export { loadTextureFromURL, loadTextureFromBlob, loadTextureFromBuffer, createTextureFromImageBitmap, TextureCache, } from './texture';

package/dist/utils/texture.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 纹理加载工具函数
+ */
+/**
+ * 从 URL 加载纹理
+ * @param device GPU 设备
+ * @param url 纹理 URL
+ * @returns GPU 纹理或 null（加载失败时）
+ */
+export declare function loadTextureFromURL(device: GPUDevice, url: string): Promise<GPUTexture | null>;
+/**
+ * 从 Blob 加载纹理
+ * @param device GPU 设备
+ * @param blob 图片 Blob
+ * @returns GPU 纹理或 null（加载失败时）
+ */
+export declare function loadTextureFromBlob(device: GPUDevice, blob: Blob): Promise<GPUTexture | null>;
+/**
+ * 从 ArrayBuffer 加载纹理
+ * @param device GPU 设备
+ * @param buffer 图片数据
+ * @param mimeType MIME 类型
+ * @returns GPU 纹理或 null（加载失败时）
+ */
+export declare function loadTextureFromBuffer(device: GPUDevice, buffer: ArrayBuffer | Uint8Array, mimeType?: string): Promise<GPUTexture | null>;
+/**
+ * 从 ImageBitmap 创建 GPU 纹理
+ * @param device GPU 设备
+ * @param imageBitmap ImageBitmap 对象
+ * @returns GPU 纹理
+ */
+export declare function createTextureFromImageBitmap(device: GPUDevice, imageBitmap: ImageBitmap): GPUTexture;
+/**
+ * 纹理缓存管理器
+ */
+export declare class TextureCache {
+    private cache;
+    private device;
+    constructor(device: GPUDevice);
+    /**
+     * 获取或加载纹理
+     */
+    getOrLoad(url: string): Promise<GPUTexture | null>;
+    /**
+     * 检查缓存中是否存在
+     */
+    has(url: string): boolean;
+    /**
+     * 从缓存获取
+     */
+    get(url: string): GPUTexture | undefined;
+    /**
+     * 添加到缓存
+     */
+    set(url: string, texture: GPUTexture): void;
+    /**
+     * 清空缓存
+     */
+    clear(): void;
+    /**
+     * 销毁所有纹理并清空缓存
+     */
+    destroy(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d5techs/3dgs-lib",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "可扩展的 WebGPU 3D 渲染引擎",
   "type": "module",
   "main": "./dist/3dgs-lib.cjs",