@d5techs/3dgs-lib 1.0.1 → 1.1.1

package/dist/mesh/MeshRenderer.d.ts

@@ -1,6 +1,7 @@
 import { Renderer } from "../core/Renderer";
 import { Camera } from "../core/Camera";
-import { Mesh, MeshBoundingBox } from "./Mesh";
+import { Mesh } from "./Mesh";
+import type { BoundingBox } from "../types";
 import { MaterialData } from "../loaders/GLBLoader";
 /**
  * MeshRenderer - 网格渲染器
@@ -10,12 +11,17 @@ export declare class MeshRenderer {
     private renderer;
     private camera;
     private items;
+    private overlayItems;
     private pipelineTextured;
     private pipelineTexturedDoubleSided;
     private bindGroupLayoutTextured;
     private pipelineUntextured;
     private pipelineUntexturedDoubleSided;
     private bindGroupLayoutUntextured;
+    private overlayPipelineTextured;
+    private overlayPipelineTexturedDoubleSided;
+    private overlayPipelineUntextured;
+    private overlayPipelineUntexturedDoubleSided;
     private sampler;
     private defaultTexture;
     private lightDir;
@@ -28,15 +34,27 @@ export declare class MeshRenderer {
      */
     addMesh(mesh: Mesh, material?: MaterialData): void;
     /**
-     * 移除网格
+     * 移除网格（销毁 GPU 资源）
      */
     removeMesh(mesh: Mesh): void;
+    /**
+     * 从渲染列表中分离网格（不销毁 GPU 资源，可重新添加）
+     */
+    detachMesh(mesh: Mesh): void;
+    /**
+     * 添加覆盖层网格（使用带 depthBias 的管线，贴面不被 3DGS 深度遮挡）
+     */
+    addOverlayMesh(mesh: Mesh, material?: MaterialData): void;
+    /**
+     * 从覆盖层列表中分离网格（不销毁 vertex/index buffer）
+     */
+    detachOverlayMesh(mesh: Mesh): void;
     /**
      * 按索引移除网格
      */
     removeMeshByIndex(index: number): boolean;
     /**
-     * 清空所有网格
+     * 清空所有网格（含覆盖层）
      */
     clear(): void;
     /**
@@ -52,23 +70,21 @@ export declare class MeshRenderer {
      */
     getAmbientIntensity(): number;
     /**
-     * 渲染所有网格
+     * 渲染所有网格（普通 + 覆盖层）
      */
     render(pass: GPURenderPassEncoder): void;
+    private renderItems;
     getMeshCount(): number;
     getMeshByIndex(index: number): Mesh | 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;
-    getCombinedBoundingBox(): MeshBoundingBox | null;
+    getOverlayMeshCount(): number;
+    getOverlayMeshByIndex(index: number): Mesh | null;
+    removeOverlayMeshByIndex(index: number): boolean;
+    getOverlayMeshColor(index: number): [number, number, number, number] | null;
+    setOverlayMeshColor(index: number, r: number, g: number, b: number, a?: number): boolean;
+    setOverlayMeshRangeColor(startIndex: number, count: number, r: number, g: number, b: number, a?: number): number;
+    getCombinedBoundingBox(): BoundingBox | null;
     destroy(): void;
 }

package/dist/scene/SceneManager.d.ts

@@ -8,8 +8,8 @@
  */
 import { Mesh } 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";
 /**
  * 场景对象类型
  */
@@ -61,6 +61,12 @@ export declare class SceneManager {
      * 按索引移除 Mesh
      */
     removeMeshByIndex(index: number): boolean;
+    getOverlayMeshCount(): number;
+    getOverlayMeshByIndex(index: number): Mesh | null;
+    getOverlayMeshRange(startIndex: number, count: number): Mesh[];
+    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;
     /**
      * 获取 Splat 数量
      */
@@ -76,7 +82,7 @@ export declare class SceneManager {
     /**
      * 获取 Splat 位置
      */
-    getSplatPosition(): [number, number, number] | null;
+    getSplatPosition(): Vec3Tuple | null;
     /**
      * 设置 Splat 旋转
      */
@@ -84,7 +90,7 @@ export declare class SceneManager {
     /**
      * 获取 Splat 旋转
      */
-    getSplatRotation(): [number, number, number] | null;
+    getSplatRotation(): Vec3Tuple | null;
     /**
      * 设置 Splat 缩放
      */
@@ -92,7 +98,7 @@ export declare class SceneManager {
     /**
      * 获取 Splat 缩放
      */
-    getSplatScale(): [number, number, number] | null;
+    getSplatScale(): Vec3Tuple | null;
     /**
      * 设置 SH 模式
      */
@@ -104,7 +110,7 @@ export declare class SceneManager {
     /**
      * 获取 Mesh 的组合 bounding box
      */
-    getMeshBoundingBox(): MeshBoundingBox | null;
+    getBoundingBox(): BoundingBox | null;
     /**
      * 获取 Splat 的 bounding box
      */

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.1",
   "description": "可扩展的 WebGPU 3D 渲染引擎",
   "type": "module",
   "main": "./dist/3dgs-lib.cjs",
@@ -58,5 +58,8 @@
     "@webgpu/types": {
       "optional": true
     }
+  },
+  "dependencies": {
+    "fflate": "^0.8.2"
   }
 }