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

package/five/gaussian-splatting/pipelines/gpuSortPipeline.d.ts

@@ -1,35 +1,12 @@
 import * as THREE from 'three/webgpu';
 import { GSplatPipeline, type PipelineFrameParams, type PipelineIndexSource } from './gsplatPipeline';
-/**
- * GPU 排序管线（Pipeline_Mode = `RASTER_GPU_SORT`）
- *
- * 组合 `SortAdapter` + `RadixSortModule`：一次 `requestSort` 在**同一帧内**完成
- * Distance_Range 计算 → keygen → radix sort → Order_Texture 写入（Requirement 12.1 / 12.2），
- * 结果经 Order_Texture 供材质顶点阶段 `textureLoad` 取点。
- *
- * 与 CPU 管线的关键差异：
- * - 排序是**同步生效**的（本帧 submit、本帧绘制读取），因此没有 generation 配对、没有
- *   Reorder_CPU、没有 `splatIndex` 上传（Requirement 12.4）；
- * - 因为同帧生效，也就**不需要主动请求额外的 Render_Frame**（Requirement 12.3）——
- *   `CpuSortPipeline` 那个 `onNeedsRender` 回调在这里没有对应物；
- * - Data_Texture 必须在排序前就位，这由 Render_Mesh 把 `assembler.assemble()` 提前到排序之前
- *   保证（Requirement 12.5）。
- *
- * 不可用性（`unusable`）汇聚三个来源，经 `checkLimits` 统一走「解析为 `RASTER_CPU_SORT` →
- * 下一帧 `syncPipelineMode` 切换」这条降级路径（Requirement 15.4 / 16.1 / 16.3），
- * 本类内部不写单独的降级分支。
- */
 export declare class GpuSortPipeline extends GSplatPipeline {
     /** 原生设备。取不到（非 WebGPU 后端）时管线直接进入失败态。 */
     private readonly device;
-    /** 3DGS ↔ 通用排序模块的对接层。构造失败或 device lost 后为 null。 */
+    /** 3DGS ↔ 通用排序模块的对接层。构造失败或已 dispose 后为 null。 */
     private sortAdapter;
-    /** compute pipeline（keygen / radix sort / prefix sum）创建失败（Requirement 16.1）。 */
+    /** compute pipeline（keygen / radix sort / prefix sum）创建失败。 */
     private _pipelineCreateFailed;
-    /** `GPUDevice` 触发 lost 事件（Requirement 16.3）。 */
-    private _deviceLost;
-    /** `dispose()` 之后忽略迟到的 `device.lost` 回调，避免在已释放对象上写状态。 */
-    private _disposed;
     /** 是否已产出过至少一次有效排序结果（Order_Texture 已写入）。 */
     private _hasSorted;
     /** 最近一次成功排序时的 Total_Points（= Order_Texture 当前承载的点数）。 */
@@ -45,9 +22,8 @@ export declare class GpuSortPipeline extends GSplatPipeline {
      * 管线是否已不可用。为真时 `checkLimits` 返回「GPU 管线已失效」，
      * 下一帧的 `syncPipelineMode` 把模式解析为 `RASTER_CPU_SORT` 并完成切换。
      *
-     * 三个来源：
-     * - `_pipelineCreateFailed`：compute pipeline 创建失败（Requirement 16.1）
-     * - `_deviceLost`：`GPUDevice` 丢失（Requirement 16.3）
+     * 两个来源：
+     * - `_pipelineCreateFailed`：compute pipeline 创建失败
      * - `sortAdapter.unusable`：keygen dispatch 规模超设备单维上限。keygen shader 只用 `gid.x`
      *   编址，无法像排序模块那样退化为 2D dispatch，其承载上限（约 1677 万点）低于
      *   `checkLimits` 按 2D dispatch 允许的规模，所以这一项必须由本 getter 补上——
@@ -61,7 +37,7 @@ export declare class GpuSortPipeline extends GSplatPipeline {
      * `min(本帧点数, 最近一次排序的点数)` 是一层保护：若布局在排序后变大而本帧尚未重排，
      * 多出来的实例在 Order_Texture 里没有对应条目，不绘制它们比绘制越界读到的 0 更正确。
      *
-     * 返回 0 的情形：管线不可用（Requirement 16.1 / 16.3）、尚无有效排序结果
+     * 返回 0 的情形：管线不可用、尚无有效排序结果
      * （Requirement 8.10，含刚切换到本管线的那几帧）、Total_Points 为 0（Requirement 16.5）。
      */
     get instanceCount(): number;
@@ -92,7 +68,5 @@ export declare class GpuSortPipeline extends GSplatPipeline {
     frameUpdate(ctx: PipelineFrameParams): void;
     /** 释放全部 GPU 资源：`SortAdapter`（含 Key_Buffer、uniform、Order_Texture、排序模块）与占位纹理。 */
     dispose(): void;
-    /** 释放 `SortAdapter` 并清零排序状态，使 `instanceCount` 立即回到 0。 */
-    private releaseAdapter;
     private ensurePlaceholderTexture;
 }

package/five/gaussian-splatting/pipelines/pipelineMode.d.ts

@@ -20,8 +20,7 @@ export interface GSplatPipelineUsability {
  *
  * @param device 已就绪的 `GPUDevice`
  * @param totalPoints 当前场景的 Total_Points
- * @param activePipeline 当前生效的管线（可选）。其 `unusable` 为真时（compute pipeline
- *   创建失败或 device lost）一并视为不可用，使运行期失败复用同一条降级路径。
+ * @param activePipeline 当前生效的管线（可选）。其 `unusable` 为真时一并视为不可用。
  * @returns 不可用时返回可读的原因字符串，可用时返回 `null`
  */
 export declare function checkLimits(device: GPUDevice, totalPoints: number, activePipeline?: GSplatPipelineUsability | null): string | null;

package/five/gaussian-splatting/sh-core/codec.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SPZ：把文件 SH 段直接打包为 outDegree 布局，不经 float；超出 outDegree 的高阶字节被跳过。
+ */
+export declare function packSpzSH(src: Uint8Array, numSplats: number, fileDegree: number, outDegree: number): Uint32Array;
+/**
+ * PLY：float 系数（N × SH_BYTES_PER_SPLAT[degree]）量化并打包。
+ *
+ * shMax 取 `max|x| * 128 / 127`，使最大正值也落在可表示范围 `[-shMax, shMax * 127 / 128]` 内。
+ */
+export declare function quantizeAndPackSH(coeffs: Float32Array, numSplats: number, degree: number): {
+    packed: Uint32Array;
+    shMax: number;
+};

package/five/gaussian-splatting/sh-core/constants.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SH 布局常量与基函数常数。
+ *
+ * sh-core 只依赖 TypeScript 标准库，不 import three / WebGL / WebGPU，以便 five-webgpu 复用。
+ */
+/** 渲染端支持的最高 SH 阶数，改为 3 即启用 3 阶 */
+export declare const MAX_RENDER_SH_DEGREE: 2 | 3;
+/** 每通道累计 SH 系数个数，下标为阶数（0..3） */
+export declare const SH_COEFFS: readonly [0, 3, 8, 15];
+/** 每 splat 有效字节数（= SH_COEFFS * 3，每系数每通道 1 字节） */
+export declare const SH_BYTES_PER_SPLAT: readonly [0, 9, 24, 45];
+/** 每 splat 占用的 RGBA32UI texel 数（= ceil(bytes / 16)） */
+export declare const SH_TEXELS_PER_SPLAT: readonly [0, 1, 2, 3];
+/** 每 splat 占用的 uint32 个数（= texel * 4） */
+export declare const SH_UINT32_PER_SPLAT: readonly [0, 4, 8, 12];
+/** SPZ 文件内每 splat SH 字节数（按文件阶数，3 阶也计入，用于步长） */
+export declare const SPZ_SH_BYTES: readonly [0, 9, 24, 45];
+export declare const SH_C1 = 0.4886025;
+/** 2 阶基函数常数，对应 xy, yz, (2zz-xx-yy), xz, (xx-yy) */
+export declare const SH_C2: readonly [1.0925484, -1.0925484, 0.3153916, -1.0925484, 0.5462742];
+/**
+ * 3 阶基函数常数，对应
+ * y(3xx-yy), xyz, y(4zz-xx-yy), z(2zz-3xx-3yy), x(4zz-xx-yy), z(xx-yy), x(xx-3yy)
+ */
+export declare const SH_C3: readonly [-0.5900435899266435, 2.890611442640554, -0.4570457994644658, 0.3731763325901154, -0.4570457994644658, 1.445305721320277, -0.5900435899266435];
+export type SHDegree = 1 | 2 | 3;
+export declare function isSHDegree(d: number): d is SHDegree;
+/** 生成 SH 常数的 GLSL 声明，供 shader 注入 */
+export declare function shConstantsGLSL(): string;

package/five/gaussian-splatting/sh-core/index.d.ts

@@ -0,0 +1,4 @@
+export * from './constants';
+export * from './codec';
+export * from './rebakePolicy';
+export * from './texelRange';

package/five/gaussian-splatting/sh-core/rebakePolicy.d.ts

@@ -0,0 +1,20 @@
+/**
+ * SH 烘焙颜色的重算判定（纯函数）。
+ *
+ * 判据：相机在 tile 局部坐标系下相对上次烘焙位置（anchor）的位移
+ * 超过 `tan(angle) * max(1, tileDistance)` 时需要重算。
+ * 即"视角变化超过 angle 度"，远处的 tile 需要更大的位移才会重算。
+ */
+export interface Vec3Like {
+    x: number;
+    y: number;
+    z: number;
+}
+/** 默认重算阈值角度（度） */
+export declare const DEFAULT_REBAKE_ANGLE = 10;
+/**
+ * 是否需要重新烘焙。任一输入非法时返回 true（颜色正确性优先于省掉一次烘焙）。
+ */
+export declare function needsRebake(camLocal: Vec3Like, anchor: Vec3Like, tileDistance: number, angleDeg: number): boolean;
+/** 合法（有限且位于 [0, 90)）则原样返回，否则返回 null */
+export declare function sanitizeRebakeAngle(angleDeg: number): number | null;

package/five/gaussian-splatting/sh-core/texelRange.d.ts

@@ -0,0 +1,18 @@
+/** 区域 [startTexel, endTexel) 在宽 width 的纹理中覆盖的行 [y0, y1) */
+export declare function texelRows(startTexel: number, endTexel: number, width: number): {
+    y0: number;
+    y1: number;
+};
+export interface ScissorRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * 传给 three `setScissor` 的参数（逻辑像素）。
+ * three 会把 scissor 乘以 dpr 再逐项 floor，而目标纹理是 texel 空间、与 dpr 无关，
+ * 因此先按 dpr 反算，再外扩 ceil(2 / dpr) + 1 行列，保证实际裁剪框覆盖所需范围。
+ * scissor 只是性能优化，正确性由片元 discard 保证。
+ */
+export declare function dprSafeScissor(y0: number, y1: number, width: number, dpr: number): ScissorRect;

package/five/gaussian-splatting/shAssembler.d.ts

@@ -0,0 +1,14 @@
+import type { PBMGaussianSplattingObject } from '../model/objects/pbmGaussianSplattingObject';
+import { SHTileResource } from './shTileResource';
+/**
+ * per-tile SH 资源的增量管理：新加入的对象创建并上传一次，持续存在的对象原样复用，
+ * 移出的对象释放。不组装跨对象的 SH 大纹理，由 SHBaker 按 tile 直接读取。
+ */
+export declare class SHAssembler {
+    private map;
+    private disposed;
+    sync(objects: readonly PBMGaussianSplattingObject[], appliedDegree: number): void;
+    get(object: PBMGaussianSplattingObject): SHTileResource | undefined;
+    clear(): void;
+    dispose(): void;
+}

package/five/gaussian-splatting/shBakeScheduler.d.ts

@@ -0,0 +1,26 @@
+import * as THREE from 'three/webgpu';
+import type { PBMGaussianSplattingObject } from '../model/objects/pbmGaussianSplattingObject';
+import type { SHAssembler } from './shAssembler';
+import type { BakeJob } from './shBaker';
+/** 一个 tile 在当前渲染路径下的全局点区间 */
+export interface BakeEntry {
+    object: PBMGaussianSplattingObject;
+    /** 全局点起点（Fallback：regions.start；Compute：layout.startPoint） */
+    start: number;
+    count: number;
+}
+/**
+ * 决定每帧哪些 tile 需要重新烘焙 SH 颜色。
+ * 强制条件：新 tile、起点变化、阶数变化、matrixWorld 变化、forceAll（目标重分配 / 路径切换）；
+ * 其余由 needsRebake（相机局部位移超过 tan(angle) * max(1, distance)）判定。
+ * 每 tile 每帧一次矩阵求逆，开销只与 tile 数线性相关。
+ */
+export declare class SHBakeScheduler {
+    rebakeAngle: number;
+    private states;
+    private warnedMissing;
+    plan(entries: readonly BakeEntry[], sh: SHAssembler, cameraWorld: THREE.Vector3, appliedDegree: number, forceAll: boolean, out: BakeJob[]): void;
+    /** 丢弃已移出场景的对象状态 */
+    prune(alive: ReadonlySet<PBMGaussianSplattingObject>): void;
+    clear(): void;
+}

package/five/gaussian-splatting/shBaker.d.ts

@@ -0,0 +1,44 @@
+import * as THREE from 'three/webgpu';
+import type { PBMGaussianSplattingObject } from '../model/objects/pbmGaussianSplattingObject';
+import type { SHTileResource } from './shTileResource';
+/** 烘焙纹理宽度（1 texel / splat） */
+export declare const BAKE_WIDTH = 2048;
+export interface BakeJob {
+    object: PBMGaussianSplattingObject;
+    /** 当前渲染路径下的全局点起点 */
+    start: number;
+    count: number;
+    res: SHTileResource;
+    /** 相机在 tile 局部坐标系下的位置 */
+    camLocal: THREE.Vector3;
+}
+/**
+ * SH 预烘焙：把每个 job 对应 tile 的每个 splat 的 `max(DC + SH(dir), 0)` 以 half 精度写入
+ * 烘焙纹理（RGBA16F，宽 2048，1 texel / splat，按当前渲染路径的全局点索引寻址）。
+ * 每个 job 一次 `renderer.render`（共享材质换参数，原因见 SHBakeMaterial 注释）。
+ */
+export declare class SHBaker {
+    private target;
+    private targetHeight;
+    private readonly scene;
+    private readonly camera;
+    private readonly geometry;
+    private readonly placeholder;
+    private readonly passes;
+    private disposed;
+    constructor();
+    get texture(): THREE.Texture | null;
+    /**
+     * 保证容量（高度只增不减）。
+     * @returns reallocated 为 true 表示目标被重新分配（旧内容丢失，需全部重烘焙）；ok 为 false 表示超出最大纹理尺寸
+     */
+    ensureCapacity(totalPoints: number, maxTextureSize: number): {
+        reallocated: boolean;
+        ok: boolean;
+    };
+    /** 释放烘焙目标（appliedDegree 变为 0 时调用） */
+    releaseTarget(): void;
+    bake(renderer: THREE.WebGPURenderer, jobs: readonly BakeJob[], degree: number): void;
+    dispose(): void;
+    private getPass;
+}

package/five/gaussian-splatting/shTileResource.d.ts

@@ -0,0 +1,22 @@
+import * as THREE from 'three/webgpu';
+import type { PBMGaussianSplattingObject } from '../model/objects/pbmGaussianSplattingObject';
+import { type SHDegree } from './sh-core';
+/**
+ * 单个 tile 的常驻 GPU 资源：
+ * - `base`：packedData（中心 + DC 颜色 + 协方差），2 texel / splat；
+ * - `sh`：shPacked（sh-core 布局的 8 位量化 SH），SH_TEXELS_PER_SPLAT[degree] texel / splat。
+ * 加入时上传一次，之后常驻直到对象移出，与渲染路径无关。
+ */
+export declare class SHTileResource {
+    readonly base: THREE.DataTexture;
+    readonly sh: THREE.DataTexture;
+    readonly degree: SHDegree;
+    readonly texelsPerSplat: number;
+    readonly shMax: number;
+    readonly count: number;
+    readonly baseWidth: number;
+    readonly shWidth: number;
+    private disposed;
+    constructor(object: PBMGaussianSplattingObject);
+    dispose(): void;
+}

package/five/gaussian-splatting/splatAssembler.d.ts

@@ -38,7 +38,7 @@ export declare class SplatAssembler {
      * - 新增对象：新建 region；
      * - 移除对象：删除 region。
      *
-     * regionList 顺序严格按传入 objects 顺序（须与 TransformStore/SHStore 布局一致），
+     * regionList 顺序严格按传入 objects 顺序（须与 TransformStore 布局一致），
      * 并按累积 count 计算各区域连续 `start` 偏移。
      */
     sync(objects: readonly PBMGaussianSplattingObject[], resolveIndices: (obj: PBMGaussianSplattingObject) => {

package/five/gaussian-splatting/transformStore.d.ts

@@ -28,9 +28,9 @@ export declare class TransformStore {
     get transforms(): Float32Array;
     /** 按对象顺序分配 transformIndex，写入每对象矩阵 + selected + 预算 inverse，并重建纹理。 */
     sync(objects: readonly PBMGaussianSplattingObject[]): void;
-    /** 单对象 transform / selected 变化：就地更新两套表示 + 标记纹理整张重传。 */
+    /** 单对象 transform / selected / 低通参数变化：就地更新两套表示 + 标记纹理整张重传。 */
     updateOne(object: PBMGaussianSplattingObject): void;
-    /** 把第 i 个对象的 matrixWorld / selected / inverse 写入 GPU 数据与排序数据两处。 */
+    /** 把第 i 个对象的 matrixWorld / selected / 低通参数 / inverse 写入 GPU 数据与排序数据两处。 */
     private writeObject;
     private rebuildTexture;
     dispose(): void;

package/five/gaussian-splatting/worker/decodeWorker.d.ts

@@ -0,0 +1,72 @@
+/** DC 颜色 → SPZ 8bit 编码（不先截断到 [0,1]，SH 叠加在未截断的颜色上），非有限值返回 0 */
+export declare function encodeSpzColor(c: number): number;
+/** SPZ 8bit 编码 → DC 颜色 */
+export declare function decodeSpzColor(byte: number): number;
+/** Convert a float16 stored as a uint16 number back to a float32 */
+export declare function fromHalf(h: number): number;
+export interface DecodedSpz {
+    numPoints: number;
+    shDegree: number;
+    /**
+     * SPZ header flags 的 bit0（FLAG_ANTIALIASED）。
+     * true 表示这份数据在训练期启用了 Mip-Splatting / gsplat 的抗锯齿模式
+     * （rasterize_mode="antialiased"）：其 opacity 是在「渲染端会做 2D 低通 +
+     * opacity 补偿」的前提下拟合出来的，因此渲染端必须做同样的补偿才能得到
+     * 正确亮度；若不做补偿，远景 splat 会偏亮。
+     * false 表示原始 3DGS 训练，渲染端应改用纯 dilation（不补偿 opacity）。
+     */
+    flagAntiAlias: boolean;
+    positions: Float32Array;
+    colors: Uint8Array;
+    scales: Float32Array;
+    rotations: Float32Array;
+    /** 量化打包后的 SH（sh-core 布局，SH_UINT32_PER_SPLAT[shDegree] uint32/splat），shDegree 为 0 时缺省 */
+    shPacked?: Uint32Array;
+    /** SH 量化范围，SPZ 恒为 1 */
+    shMax: number;
+    /** worker 中 pack 好的 GPU 数据（8 uint32/splat），主线程构造 PBMGSObject 后可直接用于上传 */
+    packedData?: Uint32Array;
+}
+/** 解码 SPZ 字节流为原始属性数组（gunzip + 逐字段解析） */
+export declare function decodeSpz(fileBytes: Uint8Array | ArrayBuffer): Promise<DecodedSpz>;
+export interface DecodedGaussianPly {
+    numPoints: number;
+    /** 文件实际 SH 阶数 */
+    shBands: 0 | 1 | 2 | 3;
+    /** min(shBands, MAX_RENDER_SH_DEGREE) */
+    shDegree: number;
+    positions: Float32Array;
+    /** rgb 为 SPZ 编码，a = round(sigmoid(opacity) * 255) */
+    colors: Uint8Array;
+    scales: Float32Array;
+    /** w, x, y, z，已归一化 */
+    rotations: Float32Array;
+    /**
+     * SH_BYTES_PER_SPLAT[shDegree] float/splat，coeff-major（sh[k*3 + c]），shDegree 为 0 时缺省；
+     * 非有限值已置 0；由 worker 交给 sh-core 的 quantizeAndPackSH 量化打包
+     */
+    shCoeffs?: Float32Array;
+}
+export type PlyKind = 'gaussian' | 'gaussian-compressed' | 'generic';
+/**
+ * 只看 header 判断 PLY 应按哪种方式渲染：
+ * - 含 `chunk` element（supersplat compressed PLY）→ 'gaussian-compressed'
+ * - vertex 含全部 3DGS 必需属性（x/y/z、f_dc_0..2、opacity、scale_0..2、rot_0..3）→ 'gaussian'
+ * - 其它（普通点云 / 网格，或 header 无法解析）→ 'generic'
+ * 不做格式（ascii / 大端）校验：3DGS 的格式问题由解码器给出明确错误。
+ */
+export declare function detectPlyKind(bytes: Uint8Array): PlyKind;
+/** 解码 3DGS PLY 为 Five 内部属性数组 */
+export declare function decodeGaussianPly(bytes: Uint8Array): DecodedGaussianPly;
+export type DecodeKind = 'spz' | 'gaussian-ply';
+/** Worker 回传的 3DGS PLY 解码结果（只含构造 PBMGSObject 所需数据） */
+export interface DecodedGaussianPlyPacked {
+    numPoints: number;
+    shBands: number;
+    shDegree: number;
+    packedData: Uint32Array;
+    /** 量化打包后的 SH（sh-core 布局），shDegree 为 0 时缺省 */
+    shPacked?: Uint32Array;
+    /** SH 量化范围（quantizeAndPackSH 输出），无 SH 时为 1 */
+    shMax: number;
+}

package/five/index.d.ts

@@ -1,6 +1,5 @@
 /// <reference types="./declare" />
 
-import "./certificates/hardware";
 export * from './model';
 export * from "./work";
 export * from "./renderer";