@realsee/five-webgpu 1.0.0-alpha.2 → 1.0.0-alpha.3

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

@@ -1,8 +1,40 @@
 import { Fetcher } from "../../utils/ajax";
-import { PBMGaussianSplattingObject } from '../objects/pbmGaussianSplattingObject';
+import type { PBMGaussianSplattingObject } from '../objects/pbmGaussianSplattingObject';
 import { LoadResultType } from './shared';
 /**
- * 加载spz格式的数据
+ * SPZ 纯解码的输出：仅包含原始属性数组（无 THREE / DOM 依赖），
+ * 因此可在 Worker 中安全运行。`packedData` 预留给后续在 Worker 内
+ * 用 WASM pack 后回填（见 Task 1.2）。
+ */
+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>;
+/**
+ * 解析 spz 格式数据为 `PBMGaussianSplattingObject`。
+ *
+ * - 解码 + WASM pack 全部在 `SPZ_Decode_Worker` 内完成，主线程不阻塞、
+ *   不重复 decode/pack（多路复用调度见文件末尾第 3 节）。
+ * - 仅在主线程动态 import 并构造 `PBMGaussianSplattingObject`（THREE 依赖），
+ *   避免把 THREE 打进 worker 包。
  * @returns Promise<PBMGaussianSplattingObject>
  */
 export declare function parseSpz(fileBytes: Uint8Array | ArrayBuffer): Promise<PBMGaussianSplattingObject>;
@@ -12,3 +44,19 @@ export declare function loadSpz(url: string, options?: {
     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/materials/pbmGaussianSplattingNodeMaterial.d.ts

@@ -8,11 +8,12 @@
  *   - 2D 椭圆：求 Σ' 特征值 / 特征向量 → 主轴 √(8λ)
  *   - 片元透明度：exp(-0.5‖δ‖²) (δ 为贴切空间单位化坐标)
  *
- * 数据通过 DataTexture 上传：
- *   - u_texture       RGBA32UI (2048 宽) — 每 splat 16 字节压缩（color / center f16×3 / quat oct / log-scale×3）
+ * 数据通过 DataTexture / 大数据纹理上传（阶段 E / 8 uint32 布局，2 texel/splat）：
+ *   - splatIndex      实例属性(float) — 第 i 实例要绘制的全局点索引 P（CPU reorder 紧凑写入）
+ *   - dataTexture     RGBA32UI (2048 宽) — 每 splat 2 texel：
+ *       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_transformIndices R32UI (1024 宽) — 每 splat 的对象索引
- *   - u_layerIndices  R32UI (1024 宽) — 每 splat 的 viewlayer 索引
  *   - u_shTexture     RGBA32F — SH 系数（degree 1/2/3 线性展开）
  */
 import * as THREE from 'three/webgpu';
@@ -23,11 +24,12 @@ export interface PBMGaussianSplattingNodeMaterialOptions {
 }
 export declare class PBMGaussianSplattingNodeMaterial extends THREE.NodeMaterial {
     readonly isPBMGaussianSplattingMaterial: true;
-    dataTexture: THREE.DataTexture | null;
+    dataTexture: THREE.Texture | null;
     transformsTexture: THREE.DataTexture | null;
     transformIndicesTexture: THREE.DataTexture | null;
     layerIndicesTexture: THREE.DataTexture | null;
     shTexture: THREE.DataTexture | null;
+    numPoints: number;
     shTextureSize: THREE.Vector2;
     aggregationEnabled: boolean;
     aggregationProgress: number;
@@ -40,6 +42,7 @@ export declare class PBMGaussianSplattingNodeMaterial extends THREE.NodeMaterial
     layerClipperRanges: THREE.Vector2[];
     clipperMatricesInverse: THREE.Matrix4[];
     private _uDataTex;
+    private _uNumPoints;
     private _uTransformsTex;
     private _uTransformIndicesTex;
     private _uLayerIndicesTex;

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

@@ -2,10 +2,17 @@ import * as THREE from "three/webgpu";
 import type { PBMClipperParameter } from "../materials/pbmMaterial";
 export interface SplatData {
     numPoints: number;
-    positions: Float32Array;
-    colors: Uint8Array;
-    scales: Float32Array;
-    rotations: Float32Array;
+    positions?: Float32Array;
+    colors?: Uint8Array;
+    scales?: Float32Array;
+    rotations?: Float32Array;
+    /**
+     * 预 pack 好的 GPU 数据（8 uint32/splat，2 texel RGBA32UI）。
+     * texel0: [0..2]=posX/Y/Z float32 位模式, [3]=R|G<<8|B<<16|A<<24；
+     * texel1: [4..6]=half 精度协方差上三角 6 分量, [7]=transformIndex<<16|layerIndex。
+     * 由 worker 内 WASM `_pack` 生成后回传（见 Task 1.2 / 3.1）。
+     */
+    packedData?: Uint32Array;
     sh1?: Float32Array;
     sh2?: Float32Array;
     sh3?: Float32Array;
@@ -25,6 +32,8 @@ export declare class PBMGaussianSplattingObject extends THREE.Points<THREE.Buffe
     usedSHDegree: number;
     gsViewLayerKey: string;
     gsClippers: readonly PBMClipperParameter[];
+    /** 加载时在 worker 中预 pack 好的 GPU 数据（8 uint32/splat） */
+    packedData: Uint32Array;
     private _selected;
     private _boundingBox;
     lastMatrixWorld: THREE.Matrix4 | null;
@@ -42,6 +51,14 @@ export declare class PBMGaussianSplattingObject extends THREE.Points<THREE.Buffe
     get selected(): boolean;
     set selected(selected: boolean);
     get boundingBox(): THREE.Box3;
+    /**
+     * 从 packedData 即时解码第 index 个 splat 的 3D 协方差矩阵（half-precision → float）。
+     * 用于 BVH 法线拟合——只在命中点按需解码。
+     * packedData texel1 布局：[4]=cov00|cov01(half2), [5]=cov02|cov11(half2), [6]=cov12|cov22(half2)。
+     * pack 端遵循 Cov4_Convention（协方差整体 ×4），此处除以 4 还原真实 Σ。
+     * 返回 6 个上三角分量 [s00, s01, s02, s11, s12, s22]，数据不足时返回 null。
+     */
+    decodeCov3D(index: number): Float32Array | null;
     dispose(): void;
     raycast(raycaster: THREE.Raycaster, intersects: THREE.Intersection[]): void;
 }

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

@@ -1,73 +1,172 @@
 import * as THREE from 'three/webgpu';
-import { RenderData } from '../../gaussian-splatting/util/renderData';
 import { PBMGaussianSplattingNodeMaterial } from '../materials/pbmGaussianSplattingNodeMaterial';
 /**
- * 3DGS 渲染 Mesh（WebGPU / TSL 版）
+ * 3DGS 渲染 Mesh（WebGPU / TSL 版，纯 CPU 数据准备）
  *
- * 与 five (WebGL2) 版本同构：
- *   - 单一四边形几何 + splatIndex 实例属性（排序结果驱动）
- *   - 双 slot（active/pending）+ 池复用纹理
- *   - SortWorker 处理 radix-64K 排序
+ * 主循环用四个协作者准备数据（**无任何 compute shader**）：
+ *   - `SplatAssembler`：per-object region 增量 diff + **CPU 拼装** 大数据纹理
+ *     （把各对象 packedData 紧凑拷进 CPU 缓冲，写 transformIndex/layerIndex 到 texel1.w；
+ *     经 THREE.DataTexture 上传供主材质采样）
+ *   - `TransformStore`：细粒度 transform 更新（9 texel/对象，含 CPU 预算 inverse）+ 排序用 20 float/对象
+ *   - `LayerRegistry`：layerKey → 稳定 layerIndex
+ *   - `SHStore`：按对象顺序连续写入 SH 纹理
  *
- * 唯一差异：将 `THREE.ShaderMaterial` 换成 `PBMGaussianSplattingNodeMaterial`（TSL）。
- * 所有「uniform.value = …」赋值改为「material.<field> = …」。
- * NUM_GS_CLIPPERS / NUM_GS_LAYERS / MAX_SH_DEGREE 的变更通过 `customProgramCacheKey`
- * + `material.needsUpdate = true` 触发管线重建。
+ * 布局三一致（Requirements 13.1 / 13.2）：`SplatAssembler.regionList` 顺序 ≡ `TransformStore`
+ * 索引顺序 ≡ `SHStore` 写入顺序。四个协作者都从**同一有序 `objects` 数组、同一顺序**同步，
+ * 因此不会产生 transformIndex / SH 错位；`onBeforeRender` 中另加防御性一致性断言兜底。
+ *
+ * 排序：把 `SplatAssembler.extractSortInputs()`（世界坐标 + transformIndex）与
+ * `TransformStore.transforms`（20 float/对象）喂给 Sort_Worker，回传的 `depthIndex`
+ * 保存为 `orderData`。每帧（order 或布局变化时）在 **CPU 端** 用「旧布局→当前布局」段表
+ * 把 orderData remap 到当前布局，紧凑写入 `splatIndex` 实例属性，材质用 `splatIndex` 取点驱动
+ * instanced draw（tile 增删布局变化时保持排序与大纹理映射一致、不闪烁）。
+ *
+ * 大数据纹理：
+ *   - `SplatAssembler` 在对象集合变化时在 **CPU** 端把各对象 packedData 紧凑拼进一张
+ *     `rgba32uint` 大纹理缓冲（2 texel/splat，texel1.w = transformIndex<<16|layerIndex），
+ *     经 `THREE.DataTexture` 上传由主材质 `textureLoad` 采样（见 `assembler.dataTexture`）。
+ *     仅在 tile 集合变化时组装一次；相机移动帧不重组装。
+ *   - per-splat 的 transformIndicesTexture / layerIndicesTexture 已折叠进大纹理 texel1.w，不再单独产出；
+ *     `transformsTexture` 与 `shTexture` 由对应 store 直接提供，布局与既有材质一致。
  */
 declare class PBMGaussianSplattingRenderMesh extends THREE.Mesh<THREE.InstancedBufferGeometry, PBMGaussianSplattingNodeMaterial> {
     private gsSceneState;
-    renderData: RenderData | null;
     needsRender: boolean;
+    private assembler;
+    private transformStore;
+    private layerRegistry;
+    private shStore;
     private sortWorker;
-    private depthIndex;
+    /**
+     * 大纹理待组装标记：tile 集合变化（rebuildScene）时置 true；onBeforeRender 中即调用
+     * `assembler.assemble()`（CPU 拼装 + DataTexture 上传）并清除。相机移动帧不置位（不重组装）。
+     */
+    private assemblePending;
+    /** splatIndex 实例属性的当前容量（点数）；不足时按 2 的幂扩容。 */
     private splatIndexCapacity;
-    private activeSlot;
-    private pendingSlot;
-    private rebuildGeneration;
+    /** 单调递增的排序请求代；每代记录其所基于的布局快照，回传时按代取回（防异步错配）。 */
+    private sortGeneration;
+    /** 当前排序输入是否已上传给 worker（场景/transform 变化时置 false 触发重传）。 */
+    private sortDataUploaded;
+    /** 排序输入（布局 / transform）自上次上传后是否已变化——脏则强制重排并重传。 */
+    private sortInputsDirty;
     private forceClipperUniformRefresh;
-    private incrementalUpdateInFlight;
-    private freeSlotPool;
+    /**
+     * Sort_Worker 是否已进入不可恢复的失败态（WASM 加载失败）。一旦置位，Render_Mesh
+     * 持续降级为空绘制（instanceCount=0），不再尝试消费排序结果（Requirement 18.1）。
+     */
+    private sortWorkerFailed;
+    /** 当前 order 长度（= 最近一次排序回传的 depthIndex 长度 = 该次排序时 vertexCount）。 */
+    private orderCount;
+    /**
+     * 最近一次排序回传的 depthIndex 副本（基于 orderBaseSnapshot 布局的全局点索引 P 的排列）。
+     * 作为 CPU reorder 的输入源：`applyReorderCPU` 用「orderBaseSnapshot → 当前布局」段表把它
+     * remap 到当前布局，紧凑写入 splatIndex 实例属性，从而在 tile 增删（布局变化）时保持排序与
+     * 大纹理映射一致、不闪烁。
+     */
+    private orderData;
+    /** order 内容变化（新排序回传）→ 需重跑 CPU reorder。 */
+    private orderDirty;
+    /** 布局变化（LOD 增删 / 场景重建）→ 需以新布局（新段表）重跑 CPU reorder。 */
+    private layoutDirty;
+    /** 当前存活实例数（= 最近一次 applyReorderCPU 写入 splatIndex 的点数）。 */
+    private aliveCount;
+    /** 当前 order 所基于的布局快照（= 该次排序发起时的布局）。 */
+    private orderBaseSnapshot;
+    /** generation → 该次排序发起时的布局快照。 */
+    private snapshotByGen;
+    private prevSortCameraMatrix;
+    /** 平移增量阈值（世界单位）：超过才重排。 */
+    sortCameraDistance: number;
+    /** 姿态相似度阈值（|quat 点积|）：低于才重排（0.99 ≈ 约 16° 内不重排）。 */
+    sortCameraCoorient: number;
+    /** 最小重排间隔（ms）：即使脏也不超过此频率，0=不限。 */
+    sortMinIntervalMs: number;
+    private sortLastTime;
     private _scratchViewProj;
-    private dataTexture;
-    private transformsTexture;
-    private transformIndicesTexture;
-    private layerIndicesTexture;
-    private shTexture;
     private usedSHDegree;
     constructor();
-    private ensureSplatIndexCapacity;
-    private getExpandedCapacity;
     private createGeometry;
+    /**
+     * 确保 splatIndex 实例属性容量 >= requiredCount；不足时按 2 的幂扩容（保留旧内容）。
+     * 返回当前（可能是新建的）属性。
+     */
+    private ensureSplatIndexCapacity;
     private createMaterial;
     private createDefaultLayerClipperRanges;
     private createDefaultClipperMatrices;
-    private createTextures;
-    private createSHTexture;
     /**
-     * 设置球谐阶数
-     * @param degree SH 阶数 (0, 1, 或 2)
+     * 应用排序结果：
+     *   1. 保存 depthIndex 副本到 `orderData`（作为 CPU reorder 的输入源；实际 remap 在
+     *      onBeforeRender 中由 applyReorderCPU 完成，此处不写 splatIndex）。
+     *   2. 置 orderDirty（新排序回传 → 需重跑 CPU reorder）。
+     *   3. 按 generation 取回该次排序真正基于的布局快照，作为 reorder 基准，并清理更旧快照
+     *      （worker 结果按 generation 单调返回，更旧快照不会再用到）。
+     * 保证：每次回传的 depthIndex 恒为「该代排序时 totalPoints」的一个排列，点数守恒。
      */
-    private setMaxShDegree;
-    private bindSlotTextures;
-    private disposeSlot;
-    private recycleSlot;
-    private disposeTextures;
     private applyDepthIndex;
-    private swapPendingToActive;
-    private createSlot;
-    private updateSlotTextures;
-    private postSortData;
-    private sortDataRebuilding;
-    private requestSort;
-    private syncTransformsForSlot;
+    /** 捕获当前布局：assembler.regions 的 {object, start, count}（顺序即全局点区间顺序）。 */
+    private snapshotLayout;
+    /**
+     * 用「排序时旧布局 → 当前布局」构造 reorder 段表：
+     *   - 存活对象：{ oldStart, oldEnd, delta = 当前 start - 旧 start, removed: false }
+     *   - 被删对象：{ oldStart, oldEnd, delta: 0, removed: true }
+     * 段按 oldStart 升序（base 已按 start 升序）、区间不重叠；相邻同类段（同 removed 且
+     * removed 或 delta 相同、且首尾相接）合并以压低段数（供 applyReorderCPU 二分查找）。
+     */
+    private buildSegments;
+    /**
+     * 二分查找覆盖全局点索引 P 的段（段按 oldStart 升序、区间 [oldStart,oldEnd) 连续无重叠）。
+     * 找不到（P 越界，理论上不会发生）返回 null。
+     */
+    private findSegment;
+    /**
+     * CPU reorder：把最近一次排序回传的 depthIndex（orderData，基于 orderBaseSnapshot 旧布局的
+     * 全局点索引 P 的排列）用「旧布局 → 当前布局」段表 remap 到当前布局，紧凑写入 splatIndex 实例属性：
+     *   - 存活对象点 P → 写入 P + delta；
+     *   - 被删对象点（removed）→ 跳过（不写，实例数不计）。
+     * 从而在 tile 增删（布局变化）时保持排序顺序与大纹理映射一致、不闪烁（等价 five 的 ReorderPass）。
+     * 结果实例数写入 `geometry.instanceCount`（= 存活点数 n）。material.numPoints 设为当前布局总点数
+     * 作 shader 端 P>=numPoints 的保护性剔除（正常情况下存活区都 < numPoints）。
+     */
+    private applyReorderCPU;
     private collectObjects;
     private isSceneNeedsRebuild;
     private getClipperHash;
     private updateClipperCounts;
+    /**
+     * clipper uniforms 直接来自 `LayerRegistry`（不再依赖 RenderData）。layerKey 取值与
+     * LayerRegistry 一致（`gsViewLayerKey || uuid`），保证 layerIndex ↔ clipper 区间对齐。
+     */
     private updateClipperUniforms;
-    private startPendingRebuild;
-    private tryStartIncrementalUpdate;
-    onBeforeRender: (_renderer: any, scene: THREE.Scene, camera: THREE.Camera, ..._rest: any[]) => void;
+    /**
+     * 场景变化时按**同一有序 objects**依次同步四个协作者，保证布局三一致：
+     * layerRegistry / transformStore 先行（assembler 的 resolveIndices 依赖二者的 indexOf/layerIndexOf），
+     * 再 assembler.sync（增量 diff + 连续 start 偏移，不触碰 GPU）→ shStore.sync；大纹理 GPU 组装
+     * 延迟到 onBeforeRender 中 device 就绪时的 assembler.assemble(device)。
+     */
+    private rebuildScene;
+    /**
+     * 防御性断言：regionList 顺序 ≡ objects 顺序 ≡ TransformStore 索引顺序（Requirements 13.1/13.2）。
+     * 四者由 rebuildScene 从同一 objects 同序同步，正常情况下恒成立；不成立即视为错误状态并告警。
+     */
+    private assertLayoutConsistency;
+    /**
+     * 把排序输入喂给 Sort_Worker：位置 + transformIndex 来自 assembler.extractSortInputs()，
+     * 变换矩阵来自 transformStore.transforms（20 float/对象，与 sort.cpp `_sort` 步长一致）。
+     * 每次上传 ++generation，回传时据此丢弃过期结果。
+     */
+    private postSortData;
+    /**
+     * 是否需要重排：
+     *   - 排序输入脏（布局 / transform 变化）或尚未上传过 → 强制重排；
+     *   - 否则比较相机相对「上次排序时快照」的平移 / 姿态增量，均小于阈值则跳过（小角度节流）。
+     */
+    private shouldSort;
+    private requestSort;
+    /** 把 store 产出的纹理与 SH 阶数同步到材质。 */
+    private syncMaterialTextures;
+    onBeforeRender: (renderer: any, scene: THREE.Scene, camera: THREE.Camera, ..._rest: any[]) => void;
     dispose(): void;
 }
 export { PBMGaussianSplattingRenderMesh };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realsee/five-webgpu",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "description": "Realsee Renderer SDK",
   "author": "BEIKE REALSEE TECHNOLOGY (HK) LIMITED",
   "license": "SEE LICENSE IN TERMS.txt",

package/plugins/index.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 7/15/2026
- * Version: 1.0.0-alpha.2
+ * Generated: 2026/8/11
+ * Version: 1.0.0-alpha.3
  * Terms:
  * Realsee SDK License Agreement
  * Update: July 28, 2021

package/plugins/index.mjs

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 7/15/2026
- * Version: 1.0.0-alpha.2
+ * Generated: 2026/8/11
+ * Version: 1.0.0-alpha.3
  * Terms:
  * Realsee SDK License Agreement
  * Update: July 28, 2021

package/react/index.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 7/15/2026
- * Version: 1.0.0-alpha.2
+ * Generated: 2026/8/11
+ * Version: 1.0.0-alpha.3
  * Terms:
  * Realsee SDK License Agreement
  * Update: July 28, 2021

package/react/index.mjs

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 7/15/2026
- * Version: 1.0.0-alpha.2
+ * Generated: 2026/8/11
+ * Version: 1.0.0-alpha.3
  * Terms:
  * Realsee SDK License Agreement
  * Update: July 28, 2021

package/umd/five-plugins.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 7/15/2026
- * Version: 1.0.0-alpha.2
+ * Generated: 2026/8/11
+ * Version: 1.0.0-alpha.3
  * Terms:
  * Realsee SDK License Agreement
  * Update: July 28, 2021

package/umd/five-react.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 7/15/2026
- * Version: 1.0.0-alpha.2
+ * Generated: 2026/8/11
+ * Version: 1.0.0-alpha.3
  * Terms:
  * Realsee SDK License Agreement
  * Update: July 28, 2021