@realsee/five-webgpu 1.0.0-alpha.1 → 1.0.0-alpha.10

package/five/model/materials/tsl/utils.d.ts

@@ -5,7 +5,20 @@ import * as THREE from 'three/webgpu';
 export declare const rgb2hsv: THREE.TSL.FnNode<[number | THREE.Node], THREE.Node<"vec3">>;
 export declare const hsv2rgb: THREE.TSL.FnNode<[number | THREE.Node], THREE.Node<"vec3">>;
 export declare const unpackRGBAToDepth: THREE.TSL.FnNode<[number | THREE.Node], THREE.Node<"float">>;
+/**
+ * 由 gainmap 值计算 HDR 增益系数
+ * @description 与 UltraHDR 规范一致：
+ * 1. gain 为数据（非颜色），取值 [0,1]
+ * 2. 解码 gamma：pow(gain, 1/gamma)（规范为 `log_recovery = pow(recovery, 1.0/map_gamma)`）
+ * 3. 在 log2 空间用 min/maxContentBoost 插值，再乘显示器容量权重
+ * 4. capacity 上下限相等（分母为 0）时权重取 0，避免 NaN
+ */
 export declare const hdrBoost: THREE.TSL.FnNode<[number | THREE.Node, number | THREE.Node, number | THREE.Node, number | THREE.Node, number | THREE.Node, number | THREE.Node, number | THREE.Node], THREE.Node<"vec3">>;
+/**
+ * 应用 gainmap 偏移，得到最终 HDR 颜色
+ * @description 与 UltraHDR 规范一致：`(sdr + offsetSdr) * boost - offsetHdr`
+ */
+export declare const hdrOffset: THREE.TSL.FnNode<[number | THREE.Node, number | THREE.Node, number | THREE.Node, number | THREE.Node], THREE.Node<"vec3">>;
 export declare const zoomVector: THREE.TSL.FnNode<[number | THREE.Node, number | THREE.Node, number | THREE.Node], THREE.Node<"vec3">>;
 /** 计算全景采样方向：用 mat4 矩阵右乘方向向量 (w=0) 得到旋转后的方向 */
 export declare const sampleDirection: THREE.TSL.FnNode<[number | THREE.Node, number | THREE.Node, number | THREE.Node, number | THREE.Node], THREE.Node<"vec3">>;

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;
@@ -41,7 +50,24 @@ export declare class PBMGaussianSplattingObject extends THREE.Points<THREE.Buffe
     reattach(positions: ArrayBufferLike, rotations: ArrayBufferLike, scales: ArrayBufferLike, colors: ArrayBufferLike, selection: ArrayBufferLike): void;
     get selected(): boolean;
     set selected(selected: boolean);
+    /**
+     * 对象空间（未经任何变换）的 AABB，由 packedData / positions 的原始坐标构建。
+     *
+     * 直接返回内部实例以避免每次访问都分配，**调用方不得修改**。
+     * 与 `boundingBox` 的区别：后者已把 `position` 与 `scale` 烘进结果（但忽略旋转与父级变换），
+     * 因此不能再与 `matrixWorld` 组合使用；本 getter 才是可配合 `matrixWorld` 求世界空间角点的那一个，
+     * GPU 排序的 Distance_Range 计算依赖它。
+     */
+    get objectSpaceBoundingBox(): THREE.Box3;
     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,138 @@
 import * as THREE from 'three/webgpu';
-import { RenderData } from '../../gaussian-splatting/util/renderData';
 import { PBMGaussianSplattingNodeMaterial } from '../materials/pbmGaussianSplattingNodeMaterial';
 /**
  * 3DGS 渲染 Mesh（WebGPU / TSL 版）
  *
- * 与 five (WebGL2) 版本同构：
- *   - 单一四边形几何 + splatIndex 实例属性（排序结果驱动）
- *   - 双 slot（active/pending）+ 池复用纹理
- *   - SortWorker 处理 radix-64K 排序
+ * 主循环用四个协作者准备数据：
+ *   - `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` 中另加防御性一致性断言兜底。
+ *
+ * 排序：本类**不再自己排序**。排序、绘制索引来源与绘制实例数一律经 `GSplatPipeline` 抽象基类
+ * 消费（Requirement 10.2）：
+ *   - `RASTER_CPU_SORT`（`CpuSortPipeline`）：wasm worker 排序 + Reorder_CPU，索引来自
+ *     `splatIndex` 实例属性；
+ *   - `RASTER_GPU_SORT`（`GpuSortPipeline`）：GPU radix sort，索引来自 R32UI Order_Texture。
+ * 「本帧是否需要排序」由 `SortThrottle` 判定（相机小平移 / 小角度 / min-interval 门），
+ * 与管线实现无关，两条路径的节流行为完全一致。管线按 `pipelineMode` 解析结果整体切换，
+ * 本类不引用 Sort_Worker、排序模块或任何 WebGPU 资源。
+ *
+ * 大数据纹理：
+ *   - `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 sortWorker;
-    private depthIndex;
-    private splatIndexCapacity;
-    private activeSlot;
-    private pendingSlot;
-    private rebuildGeneration;
+    private assembler;
+    private transformStore;
+    private layerRegistry;
+    private shStore;
+    /**
+     * 当前生效的排序管线。由 `syncPipelineMode` 按 Current_Pipeline_Mode 创建 / 重建，
+     * 尚未创建（首帧之前）时为 null。
+     */
+    private pipeline;
+    /** 排序节流器：判定本 Render_Frame 是否需要调用 `pipeline.requestSort`。 */
+    private throttle;
+    /** Requested_Pipeline_Mode（外部经 `pipelineMode` 写入，下一帧生效）。 */
+    private _requestedPipelineMode;
+    /**
+     * Current_Pipeline_Mode（`resolvePipelineMode` 的解析结果，永不为 `AUTO`）。
+     * 初值取 CPU 排序：管线未创建前对外报告最保守的取值。
+     */
+    private _activePipelineMode;
+    /**
+     * 创建当前 `pipeline` 时所用的渲染器。渲染器只能从 `onBeforeRender` 拿到，因此管线在首帧
+     * 才创建；若本 Mesh 被挂到另一个渲染器上（renderer 身份变化），管线持有的 device 资源不再
+     * 有效，需连同模式一起重建。
+     */
+    private _pipelineRenderer;
+    /**
+     * 传给管线的每帧参数。**跨帧复用同一个对象**（Requirement 10.7），每帧填字段后传入，
+     * 不在渲染循环里新建。`camera` 由每帧填充，构造时无值。
+     */
+    private _frameParams;
+    /**
+     * 大纹理待组装标记：tile 集合变化（rebuildScene）时置 true；onBeforeRender 中即调用
+     * `assembler.assemble()`（CPU 拼装 + DataTexture 上传）并清除。相机移动帧不置位（不重组装）。
+     */
+    private assemblePending;
     private forceClipperUniformRefresh;
-    private incrementalUpdateInFlight;
-    private freeSlotPool;
-    private _scratchViewProj;
-    private dataTexture;
-    private transformsTexture;
-    private transformIndicesTexture;
-    private layerIndicesTexture;
-    private shTexture;
     private usedSHDegree;
     constructor();
-    private ensureSplatIndexCapacity;
-    private getExpandedCapacity;
+    /**
+     * Requested_Pipeline_Mode（`GSPLAT_PIPELINE_*`）。写入后在**下一帧**由
+     * `syncPipelineMode` 解析并按需重建管线，便于开发期在同场景下对比两条管线
+     * （Requirement 13.2）。
+     */
+    get pipelineMode(): number;
+    set pipelineMode(value: number);
+    /** 实际生效的 Current_Pipeline_Mode（解析后的结果，永不为 `AUTO`）。 */
+    get currentPipelineMode(): number;
+    /** 平移增量阈值（世界单位）：超过才重排。 */
+    get sortCameraDistance(): number;
+    set sortCameraDistance(value: number);
+    /** 姿态相似度阈值（|quat 点积|）：低于才重排（0.99 ≈ 约 16° 内不重排）。 */
+    get sortCameraCoorient(): number;
+    set sortCameraCoorient(value: number);
+    /** 最小重排间隔（ms）：即使脏也不超过此频率，0=不限。 */
+    get sortMinIntervalMs(): number;
+    set sortMinIntervalMs(value: number);
     private createGeometry;
     private createMaterial;
     private createDefaultLayerClipperRanges;
     private createDefaultClipperMatrices;
-    private createTextures;
-    private createSHTexture;
-    /**
-     * 设置球谐阶数
-     * @param degree SH 阶数 (0, 1, 或 2)
-     */
-    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;
     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；大纹理组装
+     * 延迟到 onBeforeRender 中的 assembler.assemble()。
+     */
+    private rebuildScene;
+    /**
+     * 防御性断言：regionList 顺序 ≡ objects 顺序 ≡ TransformStore 索引顺序（Requirements 13.1/13.2）。
+     * 四者由 rebuildScene 从同一 objects 同序同步，正常情况下恒成立；不成立即视为错误状态并告警。
+     */
+    private assertLayoutConsistency;
+    /** 把 store 产出的纹理与 SH 阶数同步到材质。 */
+    private syncMaterialTextures;
+    /**
+     * 每帧一次的 Pipeline_Mode 检查与管线切换（Requirement 8.2）。
+     *
+     * 之所以每帧检查而非首帧一次性初始化：`pipelineMode` 的运行时修改要在下一帧生效
+     * （Requirement 8.6 / 13.2），且 `totalPoints` 增长导致 limits 越界、或 GPU 管线运行期失效
+     * （compute pipeline 创建失败 / device lost，经 `unusable` 汇聚）时都要能自动降级。
+     * 所有降级情形统一归结为「`resolvePipelineMode` 返回 `RASTER_CPU_SORT`」后由本方法完成切换
+     * （Requirement 15.4），因此不存在第二条降级代码路径。
+     *
+     * 模式未变且管线已就绪时只做一次整数比较即返回，开销可忽略（Requirement 8.10）。
+     *
+     * @param renderer 本帧渲染器（由 `onBeforeRender` 传入，是取 `GPUDevice` 的唯一入口）
+     * @param totalPoints 当前布局的 Total_Points，用于按实际规模检查 limits
+     */
+    private syncPipelineMode;
+    onBeforeRender: (renderer: any, scene: THREE.Scene, camera: THREE.Camera, ..._rest: any[]) => void;
     dispose(): void;
 }
 export { PBMGaussianSplattingRenderMesh };

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

@@ -60,7 +60,6 @@ export declare class PBMPointCloud extends THREE.Mesh<THREE.InstancedBufferGeome
     outlineGain: number;
     distanceGain: number;
     useAddBlend: boolean;
-    vertexMarks: boolean;
     clippers: readonly PBMClipperParameter[];
     readonly modelBoundingMin: THREE.Vector3;
     readonly modelBoundingMax: THREE.Vector3;

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

@@ -42,7 +42,7 @@ export declare class PBMPointCloudObject extends THREE.Object3D {
     outlineGain: number;
     distanceGain: number;
     useAddBlend: boolean;
-    vertexMarks: boolean;
+    vertexMarks: boolean | number;
     clippers: readonly PBMClipperParameter[];
     readonly modelBoundingMin: THREE.Vector3;
     readonly modelBoundingMax: THREE.Vector3;

package/five/model/parameter.d.ts

@@ -1,14 +1,15 @@
 import * as THREE from 'three/webgpu';
-import { type PBMPanoPicture, type PBMPanoDepth, type PBMRefinedScreen, type PBMTransition, type PBMFloorStyle, type PBMColorStyle, type PBMClipperParameter, type PBMPanoFilter, type PBMPointShape, type PBMPointSize, type PBMPointBack } from './materials/pbmMaterial';
+import { type PBMPanoPicture, type PBMPanoDepth, type PBMRefinedScreen, type PBMTransition, type PBMFloorStyle, type PBMRoofStyle, type PBMColorStyle, type PBMClipperParameter, type PBMPanoFilter, type PBMPointShape, type PBMPointSize, type PBMPointBack, type PBMCustomNode } from './materials/pbmMaterial';
 import type { TileRequestOrder } from './tile3d/types';
 import type { Camera } from '../core/camera';
 export interface ParameterMaterialValue {
     /**
-     * 是否生效标注
-     * 开启后，模型顶点上会预置 `_feature_id_rsmask` 标记。
-     * _feature_id_rsmask=1，在俯视等特定视角下，引擎会自动隐藏被标记的顶点对应的 Mesh，从而实现“开盖”效果，让室内布局观测更加清晰、观感更好。
+     * 是否生效标注（按位掩码 PBMVertexMarkFlag）
+     * 开启后，模型顶点上会预置 `_feature_id_rsmask` 标记，可按位独立控制开盖(roof)与隐藏(hidden)。
+     * _feature_id_rsmask=1 对应 roof，在俯视等特定视角下引擎会自动隐藏被标记的顶点对应的 Mesh，从而实现“开盖”效果，让室内布局观测更加清晰、观感更好。
+     * 兼容旧的 boolean：true=全开(all)，false=全关(none)。
      */
-    vertexMarks: boolean;
+    vertexMarks: boolean | number;
     /** 起始点 */
     pano0: PBMPanoPicture | null;
     /** 结束点 */
@@ -31,6 +32,8 @@ export interface ParameterMaterialValue {
     opacity: number;
     /** 楼层样式 */
     floorStyle: PBMFloorStyle;
+    /** 屋顶样式（仅在 vertexMarks 为 true 时生效；AUTO 按视角渐切，HIDE 始终隐藏） */
+    roofStyle: PBMRoofStyle;
     /** 颜色样式 */
     colorStyle: PBMColorStyle;
     /** 模型颜色*/
@@ -78,6 +81,13 @@ export interface ParameterMaterialValue {
     /** 3dgs球谐阶数*/
     gaussianSplattingSHDegree: number;
     maxDisplayBoost: number;
+    /** 自定义节点列表（TSL Node 级别的材质扩展） */
+    customNodes: readonly PBMCustomNode[];
+    /**
+     * 自定义节点 uniform 的脏计数器（内部维护，无需手动设置）。
+     * 任一 customNode emit('update') 时自动递增，用于触发材质刷新。
+     */
+    customNodesVersion: number;
 }
 export interface ParameterTilesetValue {
     /** 模型显示最小细化层级 */
@@ -130,6 +140,11 @@ export declare class Parameter {
     resolveValue<K extends keyof ParameterValue>(name: K, ...values: Partial<ParameterValue>[]): ParameterValue[K];
     resolveValue(...baseValues: Partial<ParameterValue>[]): ResolvedParameterValue;
     private assignValue;
+    /**
+     * 递增 customNodesVersion 并 bump 参数版本，促使模型重新下发参数、
+     * 令 NodeMaterialObserver 检测到 customNodesVersion 变化而刷新（上传 customNode 的 uniform）。
+     */
+    private bumpCustomNodesVersion;
     set<T extends keyof ParameterValue>(name: T, value: ParameterValue[T]): this;
     set(values: Partial<ParameterValue>): this;
     reset(...names: (keyof ParameterValue)[]): this;

package/five/model/tile3d/index.d.ts

@@ -73,6 +73,8 @@ export declare class Tile3D extends THREE.Object3D {
     loadContent(tile: Tile): Promise<void>;
     unloadContent(tile: Tile): Promise<void>;
     loadAllTilesets(): Promise<void>;
+    loadTrajectory(trajectory: Trajectory): Promise<void>;
+    unloadTrajectory(trajectory: Trajectory): Promise<void>;
     intersectRaycaster(raycaster: THREE.Raycaster, target?: Intersection[]): Intersection[];
     update(renderer: THREE.WebGPURenderer, camera: Camera, modelScene: ModelScene, model: Model): boolean;
     dispose(): void;

package/five/model/tile3d/tileset.d.ts

@@ -12,6 +12,11 @@ export interface TilesetOptions {
     onTileLoad: (tile: Tile) => any;
     onTileUnload: (tile: Tile) => any;
     onTileError: (tile: Tile, error: Error) => any;
+    trajectoryLoader: (trajectory: Trajectory) => Promise<void>;
+    trajectoryUnloader: (trajectory: Trajectory) => Promise<void>;
+    onTrajectoryLoad: (trajectory: Trajectory) => any;
+    onTrajectoryUnload: (trajectory: Trajectory) => any;
+    onTrajectoryError: (trajectory: Trajectory, error: Error) => any;
 }
 export declare class Tileset {
     asset: {

package/five/model/tile3d/trajectory-content.d.ts

@@ -0,0 +1,53 @@
+import * as THREE from 'three/webgpu';
+import type { Trajectory } from './trajectory';
+import { Fetcher } from '../../utils/ajax';
+/**
+ * 轨迹的两套自定义着色器原为 GLSL `ShaderMaterial`，WebGPURenderer 只支持 NodeMaterial
+ * （其它材质类型会被退化成空白 NodeMaterial），这里按 GLSL 逐层翻译为 TSL：
+ *
+ * 管道 TRAJECTOR_PIPE：
+ *   vertex:   `vUv = uv;` + `transformed += normalize(objectNormal) * displacementScalar`
+ *   fragment: `if (mod(abs(vUv.x * totalLength + dashOffset), dashSize.x + dashSize.y) > dashSize.x) discard;`
+ *             `vec4 diffuseColor = vec4(mix(diffuse, diffuse2, vUv.x), opacity);`
+ * 圆球 TRAJECTOR_SPHERE：
+ *   vertex:   `transformed += normalize(objectNormal) * displacementScalar`
+ *   fragment: `vec4 diffuseColor = vec4(diffuse, opacity);`
+ *
+ * 说明：
+ * - 原 shader 里的 `<tonemapping_fragment>` / `<colorspace_fragment>` 由渲染器的 Output 通道统一处理
+ *   （WebGPURenderer 把 tone mapping 与输出色彩空间放到独立的输出 pass），<fog_fragment> /
+ *   `<premultiplied_alpha_fragment>` 对应 NodeMaterial 的 `fog` / `premultipliedAlpha` 属性（默认 fog 生效）。
+ * - 颜色不再调用 `convertSRGBToLinear()`：r152+ 的 `new THREE.Color(hex)` 已经按 sRGB 解释并转到线性工作空间，
+ *   再转换一次会变暗。
+ * - `uniform()` 生成的 uniform 节点保留 `.value` 读写，所以材质上挂的 `uniforms` 与 GLSL 版本用法一致
+ *   （见 trajectory-node.ts 的 dashOffset 动画）。
+ */
+declare function createPipeUniforms(): {
+    diffuse: THREE.UniformNode<"color", THREE.Color>;
+    diffuse2: THREE.UniformNode<"color", THREE.Color>;
+    opacity: THREE.UniformNode<"float", number>;
+    displacementScalar: THREE.UniformNode<"float", number>;
+    totalLength: THREE.UniformNode<"float", number>;
+    dashSize: THREE.UniformNode<"vec2", THREE.Vector2>;
+    dashOffset: THREE.UniformNode<"float", number>;
+};
+declare function createSphereUniforms(): {
+    diffuse: THREE.UniformNode<"color", THREE.Color>;
+    opacity: THREE.UniformNode<"float", number>;
+    displacementScalar: THREE.UniformNode<"float", number>;
+};
+export type TrajectoryPipeUniforms = ReturnType<typeof createPipeUniforms>;
+export type TrajectorySphereUniforms = ReturnType<typeof createSphereUniforms>;
+export type TrajectoryPipeMaterial = THREE.NodeMaterial & {
+    uniforms: TrajectoryPipeUniforms;
+};
+export type TrajectorySphereMaterial = THREE.NodeMaterial & {
+    uniforms: TrajectorySphereUniforms;
+};
+export declare function loadTrajectory<T extends Trajectory>(trajectory: T, options: {
+    fetcher: Fetcher;
+    search?: string;
+    renderer?: THREE.WebGPURenderer;
+}): Promise<T>;
+export declare function unloadTrajectory(trajectory: Trajectory): void;
+export {};

package/five/renderer/compute-renderers/binned/binned-core.d.ts

@@ -0,0 +1,46 @@
+/** 光栅参数（像素直径）：≤ SMALL 单线程绘制，≤ LARGE 按点协作，更大按 8×8 子块协作 */
+export declare const RASTER_CONFIG: {
+    readonly smallThreshold: 8;
+    readonly largeThreshold: 16;
+    /** 桶容量 = clamp(总点数 × ratio, min, max) */
+    readonly bucketRatio: 0.125;
+    readonly bucketMin: 16384;
+    readonly bucketMax: number;
+    /** 子块容量 = clamp(桶容量 × 169 × ratio, min, max) */
+    readonly subBlockRatio: 0.02;
+    readonly subBlockMin: number;
+    readonly subBlockMax: number;
+};
+/**
+ * 分桶协作光栅的 GPU 资源与命令编码。
+ * classify 按点尺寸分类：Small 直接绘制，Medium / Large 入桶；
+ * 随后 coop_medium 每个 workgroup 绘制一个点，coop_large 每个 workgroup 绘制一个 8×8 子块。
+ */
+export declare class BinnedCore {
+    private readonly device;
+    private readonly frameUniformBuffer;
+    private readonly pipes;
+    private readonly counters;
+    private readonly args;
+    private buckets;
+    private subBlocks;
+    private bucketCap;
+    private subBlockCap;
+    private classifyBG;
+    private argsBG;
+    private coopBG;
+    private boundFramebuffer;
+    constructor(device: GPUDevice, tileBindGroupLayout: GPUBindGroupLayout, frameUniformBuffer: GPUBuffer);
+    get bucketCapacity(): number;
+    get subBlockCapacity(): number;
+    /** 每帧编码前调用：按点数调整容量（只增不减），并保证 bind group 引用当前 framebuffer */
+    prepare(totalPoints: number, framebuffer: GPUBuffer): void;
+    encodeClearCounters(encoder: GPUCommandEncoder): void;
+    /** 一个 tile 的分类 dispatch */
+    encodeClassify(pass: GPUComputePassEncoder, tileBindGroup: GPUBindGroup, pointCount: number): void;
+    /** 所有 tile 分类完成后：写 indirect 参数，再协作绘制 Medium / Large 点 */
+    encodeCoop(pass: GPUComputePassEncoder): void;
+    dispose(): void;
+    private allocate;
+    private createBindGroups;
+}

package/five/renderer/compute-renderers/binned/binned-pipelines.d.ts

@@ -0,0 +1,10 @@
+export interface BinnedPipelines {
+    readonly classifyBGL: GPUBindGroupLayout;
+    readonly argsBGL: GPUBindGroupLayout;
+    readonly coopBGL: GPUBindGroupLayout;
+    readonly classifier: GPUComputePipeline;
+    readonly argsBuilder: GPUComputePipeline;
+    readonly coopMedium: GPUComputePipeline;
+    readonly coopLarge: GPUComputePipeline;
+}
+export declare function createBinnedPipelines(device: GPUDevice, tileBindGroupLayout: GPUBindGroupLayout): BinnedPipelines;

package/five/renderer/compute-renderers/binned/shaders/args-builder.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/renderer/compute-renderers/binned/shaders/classify.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/renderer/compute-renderers/binned/shaders/coop.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/renderer/compute-renderers/pointcloud-compute-renderer.d.ts

@@ -3,12 +3,14 @@ import type { PBMPointCloud } from '../../model/objects/pbmPointCloud';
 /**
  * 基于 Compute Shader 的点云渲染器
  *
- * 渲染管线：清除 framebuffer → 计算着色器计算点云 → 全屏四边形显示。
+ * 渲染管线：清除 framebuffer → 分桶协作光栅点云 → 全屏四边形显示。
  * 从调用方接收 GPUDevice（不自行请求 adapter/device）。
  */
 export declare class PointCloudComputeRenderer {
     private device;
     private format;
+    /** 显示 pipeline 的 color target 格式，需与目标 RT 的 GPU 纹理格式一致 */
+    get colorFormat(): GPUTextureFormat;
     private width;
     private height;
     private pointBuffer;
@@ -18,44 +20,12 @@ export declare class PointCloudComputeRenderer {
     private frameUniformBuffer;
     private displayParamsBuffer;
     private clearPipeline;
-    private rasterizePipeline;
     private fullscreenQuadPipeline;
+    private tileBindGroupLayout;
     private clearBindGroup;
     private rasterizeBindGroup;
     private displayBindGroup;
     private pointCount;
-    private static readonly FRAME_UNIFORM_SIZE;
-    private static readonly TILE_UNIFORM_SIZE;
-    private static readonly OFFSET_VIEW_PROJ;
-    private static readonly OFFSET_SCREEN_WIDTH;
-    private static readonly OFFSET_SCREEN_HEIGHT;
-    private static readonly OFFSET_POINT_SIZE_MODE;
-    /** pointAttenPack: mix(-proj[2][3]), scale(2/proj[1][1]), pad, pad */
-    private static readonly OFFSET_POINT_ATTEN_PACK;
-    /** viewZRow: viewMatrix 第三行，用于 mvPosition.z */
-    private static readonly OFFSET_VIEW_Z_ROW;
-    private static readonly OFFSET_POINT_SCALE;
-    private static readonly OFFSET_POINT_MIN_PIXEL;
-    private static readonly OFFSET_POINT_MAX_PIXEL;
-    private static readonly OFFSET_PIXEL_RATIO;
-    private static readonly OFFSET_RESOLUTION_Y;
-    private static readonly OFFSET_POINT_PIXEL_HARD_MAX;
-    private static readonly OFFSET_POINT_SHAPE;
-    /** 与 rasterize.wgsl FrameUniforms 连续布局一致（无 per-tile model/bbox） */
-    private static readonly OFFSET_CAMERA_WORLD;
-    private static readonly OFFSET_CAMERA_FORWARD;
-    private static readonly OFFSET_CONSTANT_COLOR;
-    private static readonly OFFSET_COLOR_GAIN;
-    private static readonly OFFSET_STYLE_PACK;
-    private static readonly OFFSET_FLOOR_PACK;
-    private static readonly OFFSET_CLIP0_INV;
-    private static readonly OFFSET_CLIP0_META;
-    private static readonly OFFSET_CLIP1_INV;
-    private static readonly OFFSET_CLIP1_META;
-    private static readonly OFFSET_TILE_MODEL;
-    private static readonly OFFSET_TILE_BBOX_MIN;
-    private static readonly OFFSET_TILE_BBOX_MAX;
-    private static readonly OFFSET_TILE_PACK;
     private readonly frameUniformScratch;
     private readonly tileUniformScratch;
     private readonly pointSizeUniformState;
@@ -64,8 +34,10 @@ export declare class PointCloudComputeRenderer {
     private gradientSampler;
     private fullscreenQuadPipelineAdditive;
     private ready;
-    /** 同一 compute pass 内避免对 rasterize 管线重复 setPipeline（多 tile 连续 dispatch 时略减开销） */
-    private lastBoundComputePipeline;
+    private binnedCore;
+    /** 本帧 viewProj，用于计算 tile mvp */
+    private readonly frameViewProj;
+    private readonly tileMvpScratch;
     /**
      * tile 级 GPU 资源缓存：用强引用 Map 而非 WeakMap，配合 PBMPointCloud.dispose
      * 派发的 'dispose' 事件主动销毁 buffer，确保 tile 卸载后内存立即归还。
@@ -93,6 +65,8 @@ export declare class PointCloudComputeRenderer {
     }, rasterResources?: {
         gradientView: GPUTextureView;
     }): void;
+    /** 每帧编码 tile 之前调用：按本帧总点数准备分桶资源 */
+    prepareFrame(totalPointCount: number): void;
     /**
      * 每帧调用一次：写入共享 frame uniform（viewProj、屏幕、点大小、相机、材质、裁切）。
      */
@@ -116,6 +90,8 @@ export declare class PointCloudComputeRenderer {
     /** 与 five vertex.glsl 中 ATTENUATION 分支一致，避免透视/正交 matrixLerp 时 clip.w 失真。 */
     private writePointAttenuationUniforms;
     private writeFrameUniformsDataView;
+    /** 写入尺寸分类阈值与桶容量 */
+    private writeRasterUniforms;
     private writeTileUniformsDataView;
     /**
      * 调整 framebuffer 大小并更新屏幕尺寸 uniform。
@@ -124,12 +100,12 @@ export declare class PointCloudComputeRenderer {
     resize(width: number, height: number): void;
     /** 写入 clear：可并入同一 compute pass，与其它 rasterize dispatch 一起提交。 */
     encodeFramebufferClear(computePass: GPUComputePassEncoder): void;
-    /** 按当前 bindGroup / pointCount 追加一次 rasterize dispatch（需先 setPointCloud + writeTileUniform）。 */
+    /** 为当前 tile 追加一次分类 dispatch（需先 setPointCloud + writeTileUniform）。 */
     encodeRasterize(computePass: GPUComputePassEncoder): void;
     encodeFramebufferDisplay(renderPass: GPURenderPassEncoder, options?: {
         additive?: boolean;
     }): void;
-    /** 单帧：clear + 多次 rasterize + display，一次 queue.submit（Potree 等多块场景同款思路）。 */
+    /** 单帧：clear + 各 tile 分类 + 协作光栅 + display，一次 queue.submit。 */
     submitMergedPointCloudFrame(colorTextureView: GPUTextureView, depthTextureView: GPUTextureView, rasterizeSteps: (computePass: GPUComputePassEncoder) => void, options?: {
         clear?: boolean;
         display?: boolean;

package/five/renderer/compute-renderers/shaders/lib/color.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/renderer/compute-renderers/shaders/lib/cull.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/renderer/compute-renderers/shaders/lib/encode.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/renderer/compute-renderers/shaders/lib/point-setup.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/renderer/compute-renderers/shaders/lib/point-size.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/renderer/compute-renderers/shaders/lib/raster.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/renderer/compute-renderers/shaders/lib/size-class.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/five/renderer/compute-renderers/shaders/lib/tile-bindings.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;