@realsee/five-webgpu 1.0.0-alpha.12 → 1.0.0-alpha.14

package/five/model/index.d.ts

@@ -14,12 +14,24 @@ export { PBMMeshPhongNodeMaterial, } from './materials/nodes/pbmMeshPhongNodeMat
 export { PBMMeshPhysicalNodeMaterial, } from './materials/nodes/pbmMeshPhysicalNodeMaterial';
 export { PBMMeshPanoOnlyNodeMaterial, } from './materials/nodes/pbmMeshPanoOnlyNodeMaterial';
 export { type LoadResultType } from "./loaders/shared";
-export { loadPbm } from "./loaders/pbm";
-export { loadAt3d } from "./loaders/at3d";
-export { loadDome } from "./loaders/dome";
-export { loadDomez } from "./loaders/domez";
-export { loadPly } from "./loaders/ply";
-export { loadGltf } from "./loaders/gltf";
+import type { loadPbm as LoadPbmFn } from "./loaders/pbm";
+import type { loadAt3d as LoadAt3dFn } from "./loaders/at3d";
+import type { loadDome as LoadDomeFn } from "./loaders/dome";
+import type { loadDomez as LoadDomezFn } from "./loaders/domez";
+import type { loadPly as LoadPlyFn } from "./loaders/ply";
+import type { loadGltf as LoadGltfFn } from "./loaders/gltf";
+/** 加载 PBM 格式模型（懒加载版本，实际实现见 `./loaders/pbm` 中的 `loadPbm`）。 */
+export declare const loadPbm: typeof LoadPbmFn;
+/** 加载 AT3D 格式模型（懒加载版本，实际实现见 `./loaders/at3d` 中的 `loadAt3d`）。 */
+export declare const loadAt3d: typeof LoadAt3dFn;
+/** 加载 Dome 格式全景模型（懒加载版本，实际实现见 `./loaders/dome` 中的 `loadDome`）。 */
+export declare const loadDome: typeof LoadDomeFn;
+/** 加载 Domez 格式全景模型（懒加载版本，实际实现见 `./loaders/domez` 中的 `loadDomez`）。 */
+export declare const loadDomez: typeof LoadDomezFn;
+/** 加载 PLY 格式模型（懒加载版本，实际实现见 `./loaders/ply` 中的 `loadPly`）。 */
+export declare const loadPly: typeof LoadPlyFn;
+/** 加载 glTF/GLB 格式模型（懒加载版本，实际实现见 `./loaders/gltf` 中的 `loadGltf`）。 */
+export declare const loadGltf: typeof LoadGltfFn;
 export { type TilesetHeader, type TileHeader, type TrajectoryHeader } from './tile3d/header';
 export { Tile, type TileContentData } from './tile3d/tile';
 export { TileNode } from './tile3d/tile-node';

package/five/model/loaders/glTF-helpers/extensions/KHR_gaussian_splatting_compression_spz.d.ts

@@ -1,7 +1,7 @@
 import * as THREE from 'three/webgpu';
 import { BaseExtension } from './base';
 import type { Parser } from '../parser';
-import { PBMGaussianSplattingObject } from '../../../objects/pbmGaussianSplattingObject';
+import type { PBMGaussianSplattingObject } from '../../../objects/pbmGaussianSplattingObject';
 export declare const EXTENSION_NAME = "KHR_gaussian_splatting_compression_spz";
 export declare class KHR_gaussian_splatting_compression_spz extends BaseExtension {
     load(gaussianSplattingExtension: {

package/five/model/loaders/glTF-helpers/extensions/KHR_gaussian_splatting_compression_spz_2.d.ts

@@ -1,7 +1,7 @@
 import * as THREE from 'three/webgpu';
 import { BaseExtension } from './base';
 import type { Parser } from '../parser';
-import { PBMGaussianSplattingObject } from '../../../objects/pbmGaussianSplattingObject';
+import type { PBMGaussianSplattingObject } from '../../../objects/pbmGaussianSplattingObject';
 export interface GaussianSplattingExtensionSpz2 {
     bufferView: number;
 }

package/five/model/loaders/ply.d.ts

@@ -3,12 +3,8 @@ import { Fetcher } from "../../utils/ajax";
 import { LoadResultType } from './shared';
 import { PBMPointCloud } from '../objects/pbmPointCloud';
 import { PBMMesh } from '../objects/pbmMesh';
-export declare function loadPly<Type extends 'geometry' | 'line' | 'pbmMesh' | 'pbmPointCloud', ResultType = {
-    'geometry': THREE.BufferGeometry;
-    'line': THREE.Line<THREE.BufferGeometry>;
-    'pbmMesh': PBMMesh;
-    'pbmPointCloud': PBMPointCloud;
-}[Type]>(url: string, options?: {
+import { PBMGaussianSplattingObject } from '../objects/pbmGaussianSplattingObject';
+interface PlyBuildOptions {
     modelUpAxis?: 'Y' | 'Z';
     upAxis?: 'Y' | 'Z';
     light?: boolean;
@@ -18,7 +14,27 @@ export declare function loadPly<Type extends 'geometry' | 'line' | 'pbmMesh' | '
         itemNames: string[];
         normalized?: boolean;
     }>;
+}
+/**
+ * 加载 PLY。
+ *
+ * type 为 'auto' 时按 header 自动识别：
+ * - 3DGS PLY（含 f_dc / opacity / scale / rot 等属性，可带 f_rest SH）→ PBMGaussianSplattingObject，解码在 Worker 中完成
+ * - 其它 PLY → PBMPointCloud（与 type: 'pbmPointCloud' 完全一致）
+ * - supersplat compressed PLY → 报错
+ *
+ * 坐标约定对所有 type 一致：modelUpAxis === 'Y' 时施加 ROTATE_X_MATRIX，
+ * upAxis === 'Y' 时施加 ROTATE_X_MATRIX_INVERSE，默认均为 'Z'。
+ */
+export declare function loadPly<Type extends 'geometry' | 'line' | 'pbmMesh' | 'pbmPointCloud' | 'auto', ResultType = {
+    'geometry': THREE.BufferGeometry;
+    'line': THREE.Line<THREE.BufferGeometry>;
+    'pbmMesh': PBMMesh;
+    'pbmPointCloud': PBMPointCloud;
+    'auto': PBMPointCloud | PBMGaussianSplattingObject;
+}[Type]>(url: string, options?: PlyBuildOptions & {
     type?: Type;
     fetcher?: Fetcher;
     onDownloadProgress?: (percent: number, loaded?: number, total?: number) => void;
 }): Promise<LoadResultType<ResultType>>;
+export {};

package/five/model/loaders/spz.d.ts

@@ -1,62 +1,22 @@
 import { Fetcher } from "../../utils/ajax";
-import type { PBMGaussianSplattingObject } from '../objects/pbmGaussianSplattingObject';
 import { LoadResultType } from './shared';
+import type { DecodeKind } from '../../gaussian-splatting/worker/decodeWorker';
+export { detectPlyKind } from '../../gaussian-splatting/worker/decodeWorker';
+export type { DecodeKind, DecodedSpz, DecodedGaussianPlyPacked, PlyKind } from '../../gaussian-splatting/worker/decodeWorker';
 /**
- * SPZ 纯解码的输出：仅包含原始属性数组（无 THREE / DOM 依赖），
- * 因此可在 Worker 中安全运行。`packedData` 预留给后续在 Worker 内
- * 用 WASM pack 后回填（见 Task 1.2）。
+ * 按 kind 把字节流发到共享解码 Worker。
+ * transfer=true 且 bytes 恰好覆盖整个 ArrayBuffer 时直接转移所有权（不拷贝，调用方之后不能再用该 buffer）；
+ * 否则拷贝出独立 ArrayBuffer 再转移。
  */
-export interface DecodedSpz {
-    numPoints: number;
-    shDegree: number;
-    positions: Float32Array;
-    colors: Uint8Array;
-    scales: Float32Array;
-    rotations: Float32Array;
-    sh1?: Float32Array;
-    sh2?: Float32Array;
-    sh3?: Float32Array;
-    /** Worker 内 WASM pack 好的 8 uint32/splat GPU 数据（Task 1.2 填入）。 */
-    packedData?: Uint32Array;
-}
-/**
- * 纯解码函数：把 SPZ 字节流（gzip）解码为原始属性数组。
- *
- * - 不触碰主线程 / DOM，仅使用 `DecompressionStream`、`DataView`、TypedArray，
- *   因此可在 Worker 内直接运行。
- * - 保留 magic / version 校验（非法魔数或不支持的版本会 reject）。
- * - 数据不足（读越界）时由 `GunzipReader` 抛出 `Unexpected EOF` 而 reject。
- */
-export declare function decodeSpz(fileBytes: Uint8Array | ArrayBuffer): Promise<DecodedSpz>;
+export declare function decodeInWorker<T>(kind: DecodeKind, bytes: Uint8Array, transfer?: boolean): Promise<T>;
 /**
  * 解析 spz 格式数据为 `PBMGaussianSplattingObject`。
- *
- * - 解码 + WASM pack 全部在 `SPZ_Decode_Worker` 内完成，主线程不阻塞、
- *   不重复 decode/pack（多路复用调度见文件末尾第 3 节）。
- * - 仅在主线程动态 import 并构造 `PBMGaussianSplattingObject`（THREE 依赖），
- *   避免把 THREE 打进 worker 包。
- * @returns Promise<PBMGaussianSplattingObject>
+ * 解码 + WASM pack 全部在共享解码 Worker 内完成，主线程不阻塞。
  */
-export declare function parseSpz(fileBytes: Uint8Array | ArrayBuffer): Promise<PBMGaussianSplattingObject>;
+export declare function parseSpz(fileBytes: Uint8Array | ArrayBuffer): Promise<any>;
 export declare function loadSpz(url: string, options?: {
     modelUpAxis?: 'Y' | 'Z';
     upAxis?: 'Y' | 'Z';
     fetcher?: Fetcher;
     onDownloadProgress?: (percent: number, loaded?: number, total?: number) => void;
 }): Promise<LoadResultType>;
-/** SPZ_Decode_Worker 的解码请求。 */
-export interface SpzDecodeRequest {
-    requestId: number;
-    fileBytes: ArrayBuffer;
-}
-/** SPZ_Decode_Worker 的解码响应（成功回传 decoded，失败回传 error）。 */
-export interface SpzDecodeResponse {
-    requestId: number;
-    decoded?: DecodedSpz;
-    error?: string;
-}
-/**
- * 构造一个 SPZ_Decode_Worker 实例（自引用 inline worker）。
- * 主线程的多路复用调度基于该入口创建共享 Worker。
- */
-export declare function createSpzDecodeWorker(): Worker;

package/five/model/loaders/spz.worker.d.ts

@@ -0,0 +1,37 @@
+/**
+ * SPZ 纯解码的输出：仅包含原始属性数组（无 THREE / DOM 依赖），
+ * 因此可在 Worker 中安全运行。`packedData` 为 Worker 内 WASM pack 后回填。
+ */
+export interface DecodedSpz {
+    numPoints: number;
+    shDegree: number;
+    positions: Float32Array;
+    colors: Uint8Array;
+    scales: Float32Array;
+    rotations: Float32Array;
+    sh1?: Float32Array;
+    sh2?: Float32Array;
+    sh3?: Float32Array;
+    /** Worker 内 WASM pack 好的 8 uint32/splat GPU 数据。 */
+    packedData?: Uint32Array;
+}
+/**
+ * 纯解码函数：把 SPZ 字节流（gzip）解码为原始属性数组。
+ *
+ * - 不触碰主线程 / DOM，仅使用 `DecompressionStream`、`DataView`、TypedArray，
+ *   因此可在 Worker 内直接运行。
+ * - 保留 magic / version 校验（非法魔数或不支持的版本会 reject）。
+ * - 数据不足（读越界）时由 `GunzipReader` 抛出 `Unexpected EOF` 而 reject。
+ */
+export declare function decodeSpz(fileBytes: Uint8Array | ArrayBuffer): Promise<DecodedSpz>;
+/** SPZ_Decode_Worker 的解码请求。 */
+export interface SpzDecodeRequest {
+    requestId: number;
+    fileBytes: ArrayBuffer;
+}
+/** SPZ_Decode_Worker 的解码响应（成功回传 decoded，失败回传 error）。 */
+export interface SpzDecodeResponse {
+    requestId: number;
+    decoded?: DecodedSpz;
+    error?: string;
+}

package/five/model/materials/pbmGaussianSplattingNodeMaterial.d.ts

@@ -15,13 +15,13 @@
  *       texel0: [posX/Y/Z 的 float32 位模式(bitcast), RGBA(uint8×4) 颜色]
  *       texel1: [cov00|cov01, cov02|cov11, cov12|cov22 的 half(unpack2x16float), transformIndex<<16|layerIndex]
  *   - u_transforms    RGBA32F (9 宽) — 每对象 36 float = matrixWorld16 + selected4 + inverse(matrixWorld)16
- *   - u_shTexture     RGBA32F — SH 系数（degree 1/2/3 线性展开）
+ *   - bakedColorTexture RGBA16F (2048 宽，1 texel/splat) — SHBaker 按全局点索引 P 烘焙的 DC+SH 颜色（shBaked 变体才读）
  */
 import * as THREE from 'three/webgpu';
 export interface PBMGaussianSplattingNodeMaterialOptions {
     numGsLayers?: number;
     numGsClippers?: number;
-    maxShDegree?: number;
+    shBaked?: boolean;
 }
 export declare class PBMGaussianSplattingNodeMaterial extends THREE.NodeMaterial {
     readonly isPBMGaussianSplattingMaterial: true;
@@ -29,17 +29,17 @@ export declare class PBMGaussianSplattingNodeMaterial extends THREE.NodeMaterial
     transformsTexture: THREE.DataTexture | null;
     transformIndicesTexture: THREE.DataTexture | null;
     layerIndicesTexture: THREE.DataTexture | null;
-    shTexture: THREE.DataTexture | null;
+    bakedColorTexture: THREE.Texture | null;
     numPoints: number;
     useOrderTexture: boolean;
     orderTexture: THREE.Texture | null;
-    shTextureSize: THREE.Vector2;
+    instanceSize: number;
     aggregationEnabled: boolean;
     aggregationProgress: number;
     aggregationPointDuration: number;
     aggregationBoundsMin: THREE.Vector3;
     aggregationBoundsMax: THREE.Vector3;
-    maxShDegree: number;
+    shBaked: boolean;
     numGsLayers: number;
     numGsClippers: number;
     layerClipperRanges: THREE.Vector2[];
@@ -50,8 +50,7 @@ export declare class PBMGaussianSplattingNodeMaterial extends THREE.NodeMaterial
     private _uTransformsTex;
     private _uTransformIndicesTex;
     private _uLayerIndicesTex;
-    private _uShTex;
-    private _uShTextureSize;
+    private _uBakedColorTex;
     private _uAggregationEnabled;
     private _uAggregationProgress;
     private _uAggregationPointDuration;
@@ -75,11 +74,6 @@ export declare class PBMGaussianSplattingNodeMaterial extends THREE.NodeMaterial
      * 否则会创建占位 EmptyTexture；之后通过 `.value = newTex` 替换即可。
      */
     private _ensureUniforms;
-    /**
-     * 计算 SH 纹理 UV（整数行列）——与 GLSL getSHDataUV 逻辑一致
-     * paddedComponentCount = ceil(shComponentCount/4)*4
-     */
-    private _buildSHUv;
     setup(builder: THREE.NodeBuilder): void;
     copy(source: PBMGaussianSplattingNodeMaterial): this;
 }

package/five/model/objects/pbmGaussianSplattingObject.d.ts

@@ -1,5 +1,19 @@
 import * as THREE from "three/webgpu";
 import type { PBMClipperParameter } from "../materials/pbmMaterial";
+/**
+ * 给 THREE.Object3D 的事件表加一个 'dispose' 事件，供 PBMGaussianSplattingObject.dispose 时广播；
+ * compute 路径的 Arena 据此释放该 tile 占用的 per-tile GPU 缓冲
+ * （gsplat-compute-arena Requirement 13.8）。
+ *
+ * 声明方式与 `pbmPointCloud.ts` / `pbmPointCloudObject.ts` 现有的同款扩展一致。interface 合并
+ * 允许同名成员重复声明，前提是类型完全相同（否则报 TS2717）；这几处都声明为 `dispose: {}`，
+ * 已实测编译通过，因此各模块各自自洽、互不依赖，不需要从别处 import 类型。
+ */
+declare module 'three/webgpu' {
+    interface Object3DEventMap {
+        dispose: {};
+    }
+}
 export interface SplatData {
     numPoints: number;
     positions?: Float32Array;
@@ -13,10 +27,16 @@ export interface SplatData {
      * 由 worker 内 WASM `_pack` 生成后回传（见 Task 1.2 / 3.1）。
      */
     packedData?: Uint32Array;
-    sh1?: Float32Array;
-    sh2?: Float32Array;
-    sh3?: Float32Array;
+    /** 8 位量化打包后的 SH（sh-core 布局，SH_UINT32_PER_SPLAT[shDegree] uint32/splat） */
+    shPacked?: Uint32Array;
     shDegree?: number;
+    /** SH 量化范围，缺省 1（SPZ） */
+    shMax?: number;
+    /**
+     * 数据是否经过抗锯齿（Mip-Splatting）训练，来自 SPZ header flags 的 bit0。
+     * 由 `spz.ts` 的 `DecodedSpz.flagAntiAlias` 透传而来（gsplat-compute-cull R4.2）。
+     */
+    antiAliased?: boolean;
 }
 /**
  * 3DGS 源对象：承载 BufferGeometry 属性 + world matrix，不参与直接绘制
@@ -27,24 +47,75 @@ export declare class PBMGaussianSplattingObject extends THREE.Points<THREE.Buffe
     transformChanged: boolean;
     selectedChanged: boolean;
     transferDetached: boolean;
+    /**
+     * 渲染参数（`preBlurAmount` / `blurAmount`）变化标记。
+     *
+     * **与 `transformChanged` 刻意分开**：这类参数只影响屏幕空间的形状与不透明度，
+     * 不改变点的深度，因此不影响深度排序——只需重传 Object_Params_Mirror，
+     * 不必触发重排序，也不必碰 transform 数据（gsplat-compute-cull R4.9）。
+     */
+    renderParamsChanged: boolean;
     numPoints: number;
     maxSHDegree: number;
     usedSHDegree: number;
+    initAnimationEnabled: boolean;
     gsViewLayerKey: string;
     gsClippers: readonly PBMClipperParameter[];
     /** 加载时在 worker 中预 pack 好的 GPU 数据（8 uint32/splat） */
     packedData: Uint32Array;
+    /** 8 位量化打包后的 SH，布局见 sh-core/codec.ts；无 SH 时为 null */
+    shPacked: Uint32Array | null;
+    /** SH 量化范围：解码为 (b - 128) / 128 * shMax */
+    shMax: number;
+    /** 局部包围盒中心（构造时缓存），用于 SH 重算判据中的 tile 距离 */
+    readonly localBoxCenter: THREE.Vector3;
+    /**
+     * 数据是否经过抗锯齿（Mip-Splatting）训练。来自 SPZ header flags 的 bit0。
+     *
+     * 决定 `preBlurAmount` / `blurAmount` 的默认取值，即渲染端走纯 dilation
+     * 还是「2D mip 低通 + opacity 补偿」路径。
+     *
+     * 数据来源不提供该标志时（非 SPZ 来源、或旧数据）按 `false` 处理，即保守地
+     * 走 dilation 路径——宁可偏胖也不偏亮（gsplat-compute-cull R4.12）。
+     */
+    readonly antiAliased: boolean;
     private _selected;
+    private _disposed;
     private _boundingBox;
     lastMatrixWorld: THREE.Matrix4 | null;
+    /** `preBlurAmount` 的手动覆盖值；`null` 表示未覆盖、按 `antiAliased` 推导默认值。 */
+    private _preBlurAmount;
+    /** `blurAmount` 的手动覆盖值；`null` 表示未覆盖、按 `antiAliased` 推导默认值。 */
+    private _blurAmount;
+    /**
+     * 投影后 2D 协方差对角线上的「纯膨胀」量，单位屏幕空间方差 px²。
+     *
+     * 只放大 splat、**不**调整 opacity，用于让亚像素 splat 不至于消失或闪烁
+     * （即 Inria 原版 3DGS 的 dilation trick）。代价是远景 splat 会偏亮偏胖
+     * ——能量没有随面积增大而摊薄。
+     *
+     * 默认：`antiAliased` 数据为 0（不需要这层兜底），否则为 `PRE_BLUR_DEFAULT_NON_AA`。
+     */
+    get preBlurAmount(): number;
+    set preBlurAmount(value: number);
+    /**
+     * 投影后 2D 协方差对角线上的「低通核」量，单位屏幕空间方差 px²。
+     *
+     * 除膨胀协方差外还按 `ρ = sqrt(det(Σ) / det(Σ + εI))` 补偿 opacity，使 splat 的
+     * 积分能量守恒——面积变大、浓度变淡，于是既不闪烁也不变亮。这就是 Mip-Splatting
+     * 在 2D 端的抗锯齿（EWA 低通滤波的近似），等价于 gsplat 的 `rasterize_mode="antialiased"`。
+     *
+     * 默认：`antiAliased` 数据为 `BLUR_DEFAULT_AA`（**须与训练一致**），否则为 0（不启用）。
+     */
+    get blurAmount(): number;
+    set blurAmount(value: number);
+    /** 清除两个补偿参数的手动覆盖，回到由 `antiAliased` 推导的默认值。 */
+    resetBlurAmounts(): void;
     get positions(): Float32Array;
     get rotations(): Float32Array;
     get scales(): Float32Array;
     get colors(): Uint8Array;
     get selection(): Uint8Array;
-    get sh1(): Float32Array | undefined;
-    get sh2(): Float32Array | undefined;
-    get sh3(): Float32Array | undefined;
     constructor(splatData?: SplatData);
     serialize(): Uint8Array<ArrayBuffer>;
     reattach(positions: ArrayBufferLike, rotations: ArrayBufferLike, scales: ArrayBufferLike, colors: ArrayBufferLike, selection: ArrayBufferLike): void;
@@ -68,6 +139,20 @@ export declare class PBMGaussianSplattingObject extends THREE.Points<THREE.Buffe
      * 返回 6 个上三角分量 [s00, s01, s02, s11, s12, s22]，数据不足时返回 null。
      */
     decodeCov3D(index: number): Float32Array | null;
+    /**
+     * 释放自身资源，并在释放之后派发一次 'dispose' 事件
+     * （gsplat-compute-arena Requirement 13.1）。
+     *
+     * 该事件供 compute 路径的 Arena 释放这个 tile 的 per-tile GPU 缓冲。
+     *
+     * **已核实的事实（勿据此误判主次）**：当前 tile 卸载链路走的是 `TileNode.dispose()`，
+     * 而后者只执行 `disposers` 闭包、不遍历 `pbmObjects` 逐个调 `dispose()`。所以从 tile 卸载到这里
+     * **不存在调用链，这个事件在当前代码里实际不会被触发**。
+     * 它只是防御性的第二条释放路径（将来若有调用方直接 dispose 单个 3DGS 对象，资源不会漏），
+     * 真正生效的主路径是 Arena 侧的「从 tile 集合移除时释放」。
+     *
+     * 守卫使重复调用只派发一次；`geometry.dispose()` 本身幂等，加守卫不改变既有语义。
+     */
     dispose(): void;
     raycast(raycaster: THREE.Raycaster, intersects: THREE.Intersection[]): void;
 }