@d5techs/3dgs-lib 1.0.0

package/dist/gs/GSSplatRenderer.d.ts

@@ -0,0 +1,217 @@
+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"
+}
+/**
+ * 移动端优化配置
+ */
+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 排序
+ * - 移动端自动优化（降低排序频率、使用紧凑格式）
+ */
+export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities {
+    private renderer;
+    private camera;
+    private pipelineL0;
+    private pipelineL1;
+    private pipelineL2;
+    private pipelineL3;
+    private pipelineL0Compact;
+    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 position;
+    private rotation;
+    private scale;
+    private pivot;
+    private modelMatrix;
+    private performanceTier;
+    private optimizationConfig;
+    private frameCount;
+    private useCompactFormat;
+    constructor(renderer: Renderer, camera: Camera);
+    /**
+     * 设置位置
+     */
+    setPosition(x: number, y: number, z: number): void;
+    /**
+     * 获取位置
+     */
+    getPosition(): [number, number, number];
+    /**
+     * 设置旋转 (欧拉角, 弧度)
+     */
+    setRotation(x: number, y: number, z: number): void;
+    /**
+     * 获取旋转
+     */
+    getRotation(): [number, number, number];
+    /**
+     * 设置缩放
+     */
+    setScale(x: number, y: number, z: number): void;
+    /**
+     * 获取缩放
+     */
+    getScale(): [number, number, number];
+    /**
+     * 设置旋转/缩放中心点 (pivot)
+     */
+    setPivot(x: number, y: number, z: number): void;
+    /**
+     * 获取旋转/缩放中心点 (pivot)
+     */
+    getPivot(): [number, number, number];
+    /**
+     * 更新模型矩阵
+     * 变换顺序: T * Tp * R * S * Tp^-1
+     * 即: 先移到原点，缩放，旋转，再移回pivot，最后应用用户平移
+     */
+    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 四个版本)
+     */
+    private createPipelines;
+    /**
+     * 创建 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 数组
+     */
+    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
+     */
+    private computeBoundingBox;
+    /**
+     * 是否支持指定的 SH 模式
+     */
+    supportsSHMode(mode: ISHMode): boolean;
+    /**
+     * 获取渲染器能力
+     */
+    getCapabilities(): RendererCapabilities;
+    /**
+     * 销毁资源
+     */
+    destroy(): void;
+}

package/dist/gs/GSSplatRendererMobile.d.ts

@@ -0,0 +1,147 @@
+/**
+ * GSSplatRendererMobile - 移动端优化的 3D Gaussian Splatting 渲染器
+ *
+ * 优化特点：
+ * 1. 使用纹理存储 splat 数据，减少 GPU 内存占用 (~52 bytes/splat vs 256 bytes)
+ * 2. 仅支持 L0 模式（无 SH 计算）
+ * 3. 从纹理采样获取 splat 属性（使用 RGBA32Float 保证精度）
+ * 4. 使用简化的排序器
+ */
+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";
+/**
+ * GSSplatRendererMobile - 移动端优化渲染器
+ * 实现 IGSSplatRenderer 接口
+ */
+export declare class GSSplatRendererMobile implements IGSSplatRendererWithCapabilities {
+    private renderer;
+    private camera;
+    private pipeline;
+    private uniformBindGroupLayout;
+    private textureBindGroupLayout;
+    private uniformBuffer;
+    private uniformBindGroup;
+    private textureBindGroup;
+    private compressedTextures;
+    private splatCount;
+    private sorter;
+    private positionsBuffer;
+    private boundingBox;
+    private frameCount;
+    private sortEveryNFrames;
+    private position;
+    private rotation;
+    private scaleValue;
+    private pivot;
+    private modelMatrix;
+    constructor(renderer: Renderer, camera: Camera);
+    /**
+     * 设置位置
+     */
+    setPosition(x: number, y: number, z: number): void;
+    /**
+     * 获取位置
+     */
+    getPosition(): [number, number, number];
+    /**
+     * 设置旋转 (欧拉角, 弧度)
+     */
+    setRotation(x: number, y: number, z: number): void;
+    /**
+     * 获取旋转
+     */
+    getRotation(): [number, number, number];
+    /**
+     * 设置缩放
+     */
+    setScale(x: number, y: number, z: number): void;
+    /**
+     * 获取缩放
+     */
+    getScale(): [number, number, number];
+    /**
+     * 设置旋转/缩放中心点 (pivot)
+     */
+    setPivot(x: number, y: number, z: number): void;
+    /**
+     * 获取旋转/缩放中心点 (pivot)
+     */
+    getPivot(): [number, number, number];
+    /**
+     * 更新模型矩阵
+     * 变换顺序: T * Tp * R * S * Tp^-1
+     * 即: 先移到原点，缩放，旋转，再移回pivot，最后应用用户平移
+     */
+    private updateModelMatrix;
+    /**
+     * 获取当前模型矩阵
+     */
+    getModelMatrix(): Float32Array;
+    /**
+     * 创建渲染管线
+     */
+    private createPipeline;
+    /**
+     * 创建 uniform buffer
+     * 布局: view (64) + proj (64) + model (64) + cameraPos (12) + pad (4) + screenSize (8) + pad (8) + textureSize (8) + pad (8) = 240 bytes
+     */
+    private createUniformBuffer;
+    /**
+     * 设置紧凑格式的 splat 数据
+     * @param data 紧凑格式的 splat 数据
+     */
+    setCompactData(data: CompactSplatData): void;
+    /**
+     * 创建 bind groups
+     */
+    private createBindGroups;
+    /**
+     * 计算 bounding box
+     */
+    private computeBoundingBox;
+    /**
+     * 渲染
+     * @param pass 渲染通道编码器
+     */
+    render(pass: GPURenderPassEncoder): void;
+    /**
+     * 获取 splat 数量
+     */
+    getSplatCount(): number;
+    /**
+     * 获取 bounding box
+     */
+    getBoundingBox(): BoundingBox | null;
+    /**
+     * 设置排序频率
+     * @param n 每 n 帧排序一次
+     */
+    setSortFrequency(n: number): void;
+    /**
+     * 设置 SH 模式（移动端仅支持 L0）
+     */
+    setSHMode(mode: SHMode): void;
+    /**
+     * 获取当前 SH 模式
+     */
+    getSHMode(): SHMode;
+    /**
+     * 是否支持指定的 SH 模式
+     */
+    supportsSHMode(mode: SHMode): boolean;
+    /**
+     * 获取渲染器能力
+     */
+    getCapabilities(): RendererCapabilities;
+    /**
+     * 内部销毁资源（不销毁管线）
+     */
+    private destroyInternal;
+    /**
+     * 销毁资源
+     */
+    destroy(): void;
+}

package/dist/gs/GSSplatSorter.d.ts

@@ -0,0 +1,105 @@
+/**
+ * GSSplatSorter - GPU Counting Sort 深度排序器
+ *
+ * 基于 PlayCanvas 的排序算法实现，使用 Counting Sort
+ * 时间复杂度 O(n)，远比 Bitonic Sort O(n log²n) 更快
+ *
+ * 流程：
+ * 1. 剔除 + 计算深度 + 统计计数
+ * 2. 前缀和计算偏移
+ * 3. 散射到最终位置
+ *
+ * iOS 兼容性：
+ * - iOS WebGPU 对大型原子数组支持有限
+ * - 默认使用 65536 个桶（桌面/Android）
+ * - iOS 使用 4096 个桶（减少原子操作压力）
+ */
+/**
+ * 屏幕尺寸信息
+ */
+export interface ScreenInfo {
+    width: number;
+    height: number;
+}
+/**
+ * 剔除参数
+ */
+export interface CullingOptions {
+    nearPlane: number;
+    farPlane: number;
+    pixelThreshold: number;
+}
+/**
+ * 排序器配置选项
+ */
+export interface SorterOptions {
+    /** 深度桶数量（必须是 2 的幂次），默认根据平台自动选择 */
+    numBuckets?: number;
+}
+/**
+ * GSSplatSorter - GPU Counting Sort 排序器
+ */
+export declare class GSSplatSorter {
+    private device;
+    private splatCount;
+    private cullingParamsBuffer;
+    private countersBuffer;
+    private visibleIndicesBuffer;
+    private depthKeysBuffer;
+    private bucketCountsBuffer;
+    private bucketOffsetsBuffer;
+    private bucketPositionsBuffer;
+    private sortedIndicesBuffer;
+    private drawIndirectBuffer;
+    private resetCountersPipeline;
+    private resetBucketCountsPipeline;
+    private cullAndCountPipeline;
+    private updateDrawIndirectPipeline;
+    private prefixSumPipeline;
+    private resetBucketPositionsPipeline;
+    private scatterPipeline;
+    private cullingBindGroupLayout;
+    private cullingBindGroup;
+    private prefixSumBindGroupLayout;
+    private prefixSumBindGroup;
+    private scatterBindGroupLayout;
+    private scatterBindGroup;
+    private readonly WORKGROUP_SIZE;
+    private readonly numBuckets;
+    private screenWidth;
+    private screenHeight;
+    private cullingOptions;
+    constructor(device: GPUDevice, splatCount: number, splatBuffer: GPUBuffer, cameraBuffer: GPUBuffer, options?: SorterOptions);
+    /**
+     * 设置屏幕尺寸
+     */
+    setScreenSize(width: number, height: number): void;
+    /**
+     * 设置剔除参数
+     */
+    setCullingOptions(options: Partial<CullingOptions>): void;
+    /**
+     * 执行剔除和排序
+     * 每帧调用
+     *
+     * 优化：合并所有 compute pass 到单次 GPU 提交
+     * WebGPU 保证同一 command buffer 中的命令按顺序执行
+     */
+    sort(): void;
+    /**
+     * 获取排序后的索引 buffer（用于渲染）
+     */
+    getIndicesBuffer(): GPUBuffer;
+    /**
+     * 获取 DrawIndirect buffer
+     */
+    getDrawIndirectBuffer(): GPUBuffer;
+    /**
+     * 获取 splat 总数量
+     */
+    getSplatCount(): number;
+    /**
+     * 销毁资源
+     */
+    destroy(): void;
+}

package/dist/gs/GSSplatSorterMobile.d.ts

@@ -0,0 +1,86 @@
+/**
+ * GSSplatSorterMobile - 移动端优化的 GPU 排序器
+ *
+ * 与主排序器的区别：
+ * 1. 使用紧凑的位置数据（仅 xyz，无 scale/rotation）
+ * 2. 简化的剔除逻辑（移除屏幕尺寸剔除）
+ * 3. 针对 iOS 优化的桶数量
+ */
+/**
+ * 排序器配置
+ */
+export interface SorterOptions {
+    numBuckets?: number;
+}
+/**
+ * 剔除选项
+ */
+export interface CullingOptions {
+    nearPlane: number;
+    farPlane: number;
+    pixelThreshold: number;
+}
+/**
+ * GSSplatSorterMobile - 移动端排序器
+ */
+export declare class GSSplatSorterMobile {
+    private device;
+    private splatCount;
+    private cullingParamsBuffer;
+    private countersBuffer;
+    private visibleIndicesBuffer;
+    private depthKeysBuffer;
+    private bucketCountsBuffer;
+    private bucketOffsetsBuffer;
+    private bucketPositionsBuffer;
+    private sortedIndicesBuffer;
+    private drawIndirectBuffer;
+    private resetCountersPipeline;
+    private resetBucketCountsPipeline;
+    private cullAndCountPipeline;
+    private updateDrawIndirectPipeline;
+    private prefixSumPipeline;
+    private resetBucketPositionsPipeline;
+    private scatterPipeline;
+    private cullingBindGroupLayout;
+    private cullingBindGroup;
+    private prefixSumBindGroupLayout;
+    private prefixSumBindGroup;
+    private scatterBindGroupLayout;
+    private scatterBindGroup;
+    private readonly WORKGROUP_SIZE;
+    private readonly numBuckets;
+    private screenWidth;
+    private screenHeight;
+    private cullingOptions;
+    constructor(device: GPUDevice, splatCount: number, positionsBuffer: GPUBuffer, // 紧凑位置数据
+    cameraBuffer: GPUBuffer, options?: SorterOptions);
+    /**
+     * 设置屏幕尺寸
+     */
+    setScreenSize(width: number, height: number): void;
+    /**
+     * 设置剔除选项
+     */
+    setCullingOptions(options: Partial<CullingOptions>): void;
+    /**
+     * 执行排序
+     */
+    sort(): void;
+    /**
+     * 获取排序后的索引 buffer
+     */
+    getIndicesBuffer(): GPUBuffer;
+    /**
+     * 获取 DrawIndirect buffer
+     */
+    getDrawIndirectBuffer(): GPUBuffer;
+    /**
+     * 获取 splat 数量
+     */
+    getSplatCount(): number;
+    /**
+     * 销毁资源
+     */
+    destroy(): void;
+}

package/dist/gs/IGSSplatRenderer.d.ts

@@ -0,0 +1,123 @@
+/**
+ * IGSSplatRenderer - 3D Gaussian Splatting 渲染器统一接口
+ *
+ * 桌面端和移动端渲染器都实现此接口，消除平台判断代码
+ */
+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
+}
+/**
+ * 3D Gaussian Splatting 渲染器接口
+ */
+export interface IGSSplatRenderer {
+    /**
+     * 设置紧凑格式的 splat 数据（推荐）
+     */
+    setCompactData(data: CompactSplatData): void;
+    /**
+     * 设置原始 splat 数据（仅桌面端支持）
+     * 移动端实现可以抛出错误或转换为紧凑格式
+     */
+    setData?(splats: SplatCPU[]): void;
+    /**
+     * 渲染 splats
+     */
+    render(pass: GPURenderPassEncoder): void;
+    /**
+     * 设置位置
+     */
+    setPosition(x: number, y: number, z: number): void;
+    /**
+     * 获取位置
+     */
+    getPosition(): [number, number, number];
+    /**
+     * 设置旋转（欧拉角，弧度）
+     */
+    setRotation(x: number, y: number, z: number): void;
+    /**
+     * 获取旋转
+     */
+    getRotation(): [number, number, number];
+    /**
+     * 设置缩放
+     */
+    setScale(x: number, y: number, z: number): void;
+    /**
+     * 获取缩放
+     */
+    getScale(): [number, number, number];
+    /**
+     * 设置旋转/缩放中心点（pivot）
+     */
+    setPivot(x: number, y: number, z: number): void;
+    /**
+     * 获取旋转/缩放中心点（pivot）
+     */
+    getPivot(): [number, number, number];
+    /**
+     * 获取模型矩阵
+     */
+    getModelMatrix(): Float32Array;
+    /**
+     * 获取 splat 数量
+     */
+    getSplatCount(): number;
+    /**
+     * 获取 bounding box
+     */
+    getBoundingBox(): BoundingBox | null;
+    /**
+     * 设置 SH 模式
+     * 移动端可能只支持 L0
+     */
+    setSHMode?(mode: SHMode): void;
+    /**
+     * 获取当前 SH 模式
+     */
+    getSHMode?(): SHMode;
+    /**
+     * 是否支持指定的 SH 模式
+     */
+    supportsSHMode?(mode: SHMode): boolean;
+    /**
+     * 销毁资源
+     */
+    destroy(): void;
+}
+/**
+ * 渲染器能力描述
+ */
+export interface RendererCapabilities {
+    /** 支持的最高 SH 模式 */
+    maxSHMode: SHMode;
+    /** 是否支持原始 SplatCPU 数据 */
+    supportsRawData: boolean;
+    /** 是否为移动端优化版本 */
+    isMobileOptimized: boolean;
+    /** 最大支持的 splat 数量（0 表示无限制） */
+    maxSplatCount: number;
+}
+/**
+ * 获取渲染器能力（可选方法）
+ */
+export interface IGSSplatRendererWithCapabilities extends IGSSplatRenderer {
+    getCapabilities(): RendererCapabilities;
+}

package/dist/gs/PLYLoader.d.ts

@@ -0,0 +1,22 @@
+/**
+ * PLYLoader - 加载 3D Gaussian Splatting 的 PLY 文件
+ * 支持 binary_little_endian 和 binary_big_endian 格式
+ * 支持多种数据类型: float, double, int, uint, char, uchar, short, ushort
+ */
+/**
+ * CPU 端 Splat 数据结构
+ */
+export type SplatCPU = {
+    mean: [number, number, number];
+    scale: [number, number, number];
+    rotation: [number, number, number, number];
+    colorDC: [number, number, number];
+    opacity: number;
+    shRest?: Float32Array;
+};
+/**
+ * 加载并解析 PLY 文件
+ * @param url PLY 文件的 URL
+ * @returns SplatCPU 数组
+ */
+export declare function loadPLY(url: string): Promise<SplatCPU[]>;