@realsee/five-webgpu 1.0.0-alpha.5 → 1.0.0-alpha.6

package/five/meshes/panoCircleMeshCustom.d.ts

@@ -26,6 +26,7 @@ declare class PanoCircleMeshCustom extends THREE.Object3D implements PanoCircleM
     loading: boolean;
     disabled: boolean;
     private panoMesh;
+    private panoU;
     constructor(options?: PanoCircleMeshCustomOptions);
     setProgress(progress: number): void;
     setOpacity(opacity: number): void;

package/five/model/index.d.ts

@@ -5,7 +5,7 @@ export { PBMGaussianSplattingObject as PBMGSObject, } from "./objects/pbmGaussia
 export { PBMPointCloud, type PointCloudData, } from "./objects/pbmPointCloud";
 export { PBMGaussianSplattingRenderMesh, } from "./objects/pbmGaussianSplattingRenderMesh";
 export { PBMGaussianSplattingNodeMaterial, } from "./materials/pbmGaussianSplattingNodeMaterial";
-export { PBMUpdateable, PBMPanoFilter, PBMCustomNode, customNodesCacheKey, type IPBMMaterial, type PBMPanoFilterValue, type PBMAlphaMode, type PBMClipperParameter, type PBMColorStyle, type PBMFloorStyle, type PBMRoofStyle, type PBMPanoPicture, type PBMHDRConfig, type PBMPanoDepth, type PBMPointBack, type PBMPointCloudShaderType, type PBMPointShape, type PBMPointSize, type PBMRefinedScreen, type PBMTransition, type PBMCustomNodeSlots, type PBMCustomNodeTargetType, type PBMCustomNodeOptions, type PBMCustomNodeContext, type PBMCustomNodePanoContext, } from "./materials/pbmMaterial";
+export { PBMUpdateable, PBMPanoFilter, PBMCustomNode, customNodesCacheKey, type IPBMMaterial, type PBMPanoFilterValue, type PBMAlphaMode, type PBMClipperParameter, type PBMColorStyle, type PBMFloorStyle, type PBMRoofStyle, type PBMPanoPicture, type PBMPanoGainmap, type PBMPanoDepth, type PBMPointBack, type PBMPointCloudShaderType, type PBMPointShape, type PBMPointSize, type PBMRefinedScreen, type PBMTransition, type PBMCustomNodeSlots, type PBMCustomNodeTargetType, type PBMCustomNodeOptions, type PBMCustomNodeContext, type PBMCustomNodePanoContext, } from "./materials/pbmMaterial";
 export { type PBMMeshMaterial, PBMMeshBasicMaterial, PBMMeshPhongMaterial, PBMMeshPhysicalMaterial, PBMMeshPanoOnlyMaterial } from './materials/pbmMeshMaterial';
 export { registerPBMMaterials, } from './materials/pbmMaterialRegister';
 export { PBMMeshBasicNodeMaterial, } from './materials/nodes/pbmMeshBasicNodeMaterial';

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

@@ -10,6 +10,7 @@
  *
  * 数据通过 DataTexture / 大数据纹理上传（阶段 E / 8 uint32 布局，2 texel/splat）：
  *   - splatIndex      实例属性(float) — 第 i 实例要绘制的全局点索引 P（CPU reorder 紧凑写入）
+ *                     useOrderTexture 开启时改由 orderTexture（R32UI，宽 2048）按 instanceIndex 取 P
  *   - 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]
@@ -30,6 +31,8 @@ export declare class PBMGaussianSplattingNodeMaterial extends THREE.NodeMaterial
     layerIndicesTexture: THREE.DataTexture | null;
     shTexture: THREE.DataTexture | null;
     numPoints: number;
+    useOrderTexture: boolean;
+    orderTexture: THREE.Texture | null;
     shTextureSize: THREE.Vector2;
     aggregationEnabled: boolean;
     aggregationProgress: number;
@@ -42,6 +45,7 @@ export declare class PBMGaussianSplattingNodeMaterial extends THREE.NodeMaterial
     layerClipperRanges: THREE.Vector2[];
     clipperMatricesInverse: THREE.Matrix4[];
     private _uDataTex;
+    private _uOrderTex;
     private _uNumPoints;
     private _uTransformsTex;
     private _uTransformIndicesTex;

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

@@ -1,7 +1,7 @@
 import * as THREE from "three/webgpu";
 import { Subscribe } from '../../utils/subscribe';
 import type { PanoId } from '../../utils/pano';
-import type { HDRCfgData } from '../../utils/hdr-data';
+import { type GainmapCfgData } from '../../utils/gainmap-data';
 import type { ParameterValue } from '../parameter';
 export type PBMPointCloudShaderType = 'pointcloud';
 export type PBMAlphaMode = 'OPAQUE' | 'MASK' | 'BLEND';
@@ -28,58 +28,144 @@ export type PBMCustomNodeTargetType = 'basic' | 'phong' | 'standard' | 'panoOnly
  * 这些字段是稳定的 PBM API，业务方不需要直接依赖内部 defines.ts 路径。
  */
 export interface PBMCustomNodePanoContext {
-    /** 全景点位在世界空间中的原点 */
+    /** 全景点位在世界空间中的原点（pano 矩阵的平移列） */
     origin: THREE.Node<'vec3'>;
-    /** 当前片元对应的全景采样方向 */
+    /** 当前片元对应的全景采样方向（已含 zoom 校正），可直接用于采样该 slot 的 cube 贴图 */
     sampleDirection: THREE.Node<'vec3'>;
-    /** SDR 全景颜色 */
+    /**
+     * 该 slot 的 SDR 全景颜色（cube 贴图采样结果）
+     * @description 仅在该 slot 有贴图时可用：未加载 pano 数据（`pano0Map` / `pano1Map` 为 null）时引用会抛
+     * `THREE.TSL: texture( value ) expects a valid instance of THREE.Texture()`，
+     * 需要业务侧先在 slot 里判空（例如 `if (material.pano0Map == null) return color;`）再引用
+     */
     sdrColor: THREE.Node<'vec3'>;
-    /** HDR 处理后的全景颜色 */
+    /**
+     * HDR 处理后的全景颜色
+     * @description 该 slot 未启用 HDR 时（无 gainmap 数据，或 `parameter.useHDR` 关闭）回退为
+     * {@link sdrColor}，业务无需判断「HDR 数据是否存在」即可安全引用；
+     * 注意回退目标本身依赖贴图存在，该 slot 无贴图时同样会抛错（见 {@link sdrColor}）
+     */
     hdrColor: THREE.Node<'vec3'>;
-    /** 全景深度可信度 */
+    /**
+     * 全景深度可信度
+     * @description 该 slot 无深度贴图（或深度剔除未启用）时为常量 0，即不做深度剔除
+     */
     depthTrust: THREE.Node<'float'>;
 }
 /**
  * PBMCustomNode callback 可访问的内置 TSL 节点。
  *
- * 注意：这里暴露的是节点表达式，不是 CPU 侧的实时数值；它们会被编译进当前材质的 shader。
+ * 注意：
+ * - 这里暴露的是节点表达式，不是 CPU 侧的实时数值；它们会被编译进当前材质的 shader，
+ *   因此分支判断要用 TSL 逻辑节点（`.and()` / `.or()` / `mix()` / `If()` …），不能用 JS 的 `if` / 三元。
+ * - 引用即参与编译：slot 里用到的字段（及其依赖的 attribute / varying / uniform / 贴图）才会进入 program，
+ *   未引用的字段不产生开销；反过来，比如引用 {@link isHiddenCut} 会顺带把 `_feature_id_rsmask` 属性与
+ *   `v_hiddenMark` varying 编进当前材质，即使该材质的 `vertexMarks` 为 false。
+ * - 各字段的实际可用性取决于当前材质配置（是否点云、是否启用 HDR 等），见各字段说明；
+ *   各 slot 的调用时机见 {@link PBMCustomNodeSlots}。
  */
 export interface PBMCustomNodeContext {
-    /** 当前片元的世界空间位置 */
+    /**
+     * 当前片元的世界空间位置
+     * @description 已包含 instance / skinning / morph 变换与自定义 `vertexPosition` 的偏移；
+     * 点云材质中为点中心（billboard quad 展开前）的位置
+     */
     positionWorld: THREE.Node<'vec3'>;
-    /** 当前片元的视图空间位置 */
+    /**
+     * 当前片元的视图空间（相机空间）位置
+     * @description 口径同 {@link positionWorld}；点云材质中为点中心位置
+     */
     positionView: THREE.Node<'vec3'>;
-    /** 相机朝向（世界/模型渲染使用的 varying） */
+    /**
+     * 相机朝向（世界空间单位向量，由 viewMatrix 推导并作为 varying 传入）
+     * @description 与相机位置无关的纯朝向；内置屋顶 AUTO 裁切用 `-cameraDirection.y` 表示「向下看」的程度
+     */
     cameraDirection: THREE.Node<'vec3'>;
-    /** 当前渲染分辨率 */
+    /**
+     * 当前渲染分辨率（CSS 像素）
+     * @description 取自 `camera.resolution` 或 renderer viewport；换算成物理像素需乘 {@link pixelRatio}
+     * （如 SPREAD 过渡用它计算屏幕中心）
+     */
     resolution: THREE.Node<'vec2'>;
-    /** 当前像素比 */
+    /** 当前像素比（`camera.pixelRatio` / `renderer.getPixelRatio()`） */
     pixelRatio: THREE.Node<'float'>;
     /** 模型/全景渲染参数 */
+    /** 起始点位 → 结束点位的过渡进度 [0, 1] */
     progress: THREE.Node<'float'>;
+    /**
+     * 显示端增益上限（`parameter.maxDisplayBoost`）
+     * @description 与 gainmap 的 capacity 上下限一起决定 HDR 提亮权重；未启用 HDR 时无意义
+     */
     maxDisplayBoost: THREE.Node<'float'>;
+    /**
+     * 模型显隐进度 [0, 1]：0 = 仅显示全景（模型不可见），1 = 完全显示模型
+     * @description 同时驱动 roof / hidden 裁切进度（`pow(modelAlpha, 5)`）与 panoOnly 材质的不透明度
+     */
     modelAlpha: THREE.Node<'float'>;
+    /** 模型颜色透明度系数（与 {@link floorOpacity} 一起乘入输出 alpha） */
     colorAlpha: THREE.Node<'float'>;
+    /**
+     * 场景亮度倍数（`parameter.brightness`）
+     * @description 注意：当前 TSL 输出管线未把它乘入 alpha（GLSL 版 mesh 为
+     * `alpha * floorOpacity * brightness`），内置渲染下暂不生效，仅自定义节点引用时才会进入 shader
+     */
     brightness: THREE.Node<'float'>;
+    /**
+     * HSV 饱和度偏移（`parameter.colorSaturation`，正值提饱和）
+     * @description 点云材质的内置颜色管线已应用；mesh 材质未应用，供自定义节点自行使用
+     */
     colorSaturation: THREE.Node<'float'>;
+    /** HSV 亮度偏移（`parameter.colorBrightness`，正值提亮），口径同 {@link colorSaturation} */
     colorBrightness: THREE.Node<'float'>;
+    /** 常量颜色（`colorStyle === 'CONSTANT'` 时作为模型基础色） */
     constantColor: THREE.Node<'vec3'>;
-    /** 楼层和屋顶状态 */
+    /** 楼层、屋顶与隐藏标记状态 */
+    /** 当前渲染对象所属楼层索引（由模型/瓦片数据写入；bounding mesh 等不归属楼层的对象为 `-1`） */
     floorIndex: THREE.Node<'float'>;
+    /** 用户指定高亮显示的楼层索引；`-1` 表示所有楼层都算「当前楼层」 */
     shownFloorIndex: THREE.Node<'float'>;
+    /** 是否属于当前显示楼层（`shownFloorIndex < 0` 时恒为 true） */
     isCurrentFloor: THREE.Node<'bool'>;
+    /** 非当前楼层的淡出系数（随相机俯仰推导），当前楼层为 1 */
     floorOpacity: THREE.Node<'float'>;
+    /**
+     * 是否命中屋顶标记档位（`_feature_id_rsmask = 1`）
+     * @description 与 {@link isHidden} 一样直接由顶点属性推导，不受 `material.vertexMarks` 开关影响
+     */
     isRoof: THREE.Node<'bool'>;
+    /** 屋顶裁切判定（`roofStyle = 'AUTO'`）：命中屋顶标记、且高度超过按相机俯仰角计算的阈值 */
     isRoofCameraCut: THREE.Node<'bool'>;
+    /** 屋顶裁切判定（`roofStyle = 'HIDE'`）：命中屋顶标记、且高度超过按 `modelAlpha` 计算的阈值 */
     isRoofModelAlphaCut: THREE.Node<'bool'>;
+    /**
+     * 是否命中隐藏标记档位（`_feature_id_rsmask = 2`）
+     * @description 直接由顶点属性推导（几何体无该属性时回退 0，恒为 false），
+     * 与 {@link isRoof} 一致，**不受** `material.vertexMarks` 开关影响；
+     * 管线内置的自动隐藏裁切才受该开关门禁
+     */
+    isHidden: THREE.Node<'bool'>;
+    /**
+     * 隐藏裁切判定：命中隐藏标记档位、且世界高度超过由 `modelAlpha` 驱动的高度阈值
+     * @description Mesh 材质在 `vertexMarks` 开启时已按此判定 discard，自定义节点可直接复用它做额外处理
+     */
+    isHiddenCut: THREE.Node<'bool'>;
+    /** 模型包围盒最小角（与 {@link positionWorld} 同空间，用于高度裁切与高度色） */
     modelBoundingMin: THREE.Node<'vec3'>;
+    /** 模型包围盒最大角，口径同 {@link modelBoundingMin} */
     modelBoundingMax: THREE.Node<'vec3'>;
-    /** 起始/结束全景点位的采样结果 */
+    /**
+     * 起始点位的全景采样结果
+     * @description 字段含义、以及「无数据时的回退行为」见 {@link PBMCustomNodePanoContext}
+     */
     pano0: PBMCustomNodePanoContext;
+    /** 结束点位的全景采样结果，口径同 {@link pano0} */
     pano1: PBMCustomNodePanoContext;
     /** 点云相关参数 */
+    /** 点大小基数（ATTENUATION 模式下与分辨率、视图距离一起换算为像素大小） */
     pointScale: THREE.Node<'float'>;
+    /** 点大小下限（CSS 像素，实际约束时会乘 {@link pixelRatio}） */
     pointMinPixel: THREE.Node<'float'>;
+    /** 点大小上限（CSS 像素，实际约束时会乘 {@link pixelRatio}） */
     pointMaxPixel: THREE.Node<'float'>;
 }
 /**
@@ -239,10 +325,15 @@ export interface PBMPanoPicture {
     matrix: THREE.Matrix4;
     /** 缩放 */
     zoom: number;
-    hdrConfig?: PBMHDRConfig;
+    /** HDR gainmap（无 HDR 时不存在） */
+    gainmap?: PBMPanoGainmap;
 }
-export interface PBMHDRConfig extends HDRCfgData {
+/** pano 的 HDR gainmap：增益图六视图 cube 贴图 + 增益图配置 */
+export interface PBMPanoGainmap {
+    /** 增益图六视图贴图 */
     map: THREE.CubeTexture;
+    /** 增益图配置 */
+    cfg: GainmapCfgData;
 }
 export interface PBMPanoDepth {
     /** 点位 Id */
@@ -269,12 +360,14 @@ export interface IPBMMaterial {
     pano0Histogram: THREE.Vector4;
     pano0Matrix: THREE.Matrix4;
     pano0Zoom: number;
-    pano0GainMap: THREE.CubeTexture | null;
+    pano0Gainmap: THREE.CubeTexture | null;
     pano0HdrMaxContentBoost: number;
     pano0HdrMinContentBoost: number;
     pano0HdrCapacityMin: number;
     pano0HdrCapacityMax: number;
     pano0HdrGamma: number;
+    pano0HdrOffsetSdr: number;
+    pano0HdrOffsetHdr: number;
     pano0DepthMap: THREE.CubeTexture | null;
     pano0DepthMaxDepth: number;
     pano1Map: THREE.CubeTexture | null;
@@ -282,12 +375,14 @@ export interface IPBMMaterial {
     pano1Histogram: THREE.Vector4;
     pano1Matrix: THREE.Matrix4;
     pano1Zoom: number;
-    pano1GainMap: THREE.CubeTexture | null;
+    pano1Gainmap: THREE.CubeTexture | null;
     pano1HdrMaxContentBoost: number;
     pano1HdrMinContentBoost: number;
     pano1HdrCapacityMin: number;
     pano1HdrCapacityMax: number;
     pano1HdrGamma: number;
+    pano1HdrOffsetSdr: number;
+    pano1HdrOffsetHdr: number;
     pano1DepthMap: THREE.CubeTexture | null;
     pano1DepthMaxDepth: number;
     panoFilterSaturationBias: number;

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

@@ -3,7 +3,6 @@ export declare const TRANSPARENT: THREE.ConstNode<"vec4", THREE.Vector4>;
 export declare const resolution: THREE.UniformNode<"vec2", THREE.Vector2>;
 export declare const pixelRatio: THREE.UniformNode<"float", number>;
 export declare const vCameraDirection: THREE.VaryingNode<"vec3">;
-export declare const vRoofMark: THREE.VaryingNode<"float">;
 export declare const progress: THREE.Node<"float">;
 export declare const maxDisplayBoost: THREE.Node<"float">;
 export declare const modelAlpha: THREE.Node<"float">;
@@ -15,6 +14,8 @@ export declare const pano0HdrMinContentBoost: THREE.Node<"float">;
 export declare const pano0HdrCapacityMin: THREE.Node<"float">;
 export declare const pano0HdrCapacityMax: THREE.Node<"float">;
 export declare const pano0HdrGamma: THREE.Node<"float">;
+export declare const pano0HdrOffsetSdr: THREE.Node<"float">;
+export declare const pano0HdrOffsetHdr: THREE.Node<"float">;
 export declare const pano0DepthMaxDepth: THREE.Node<"float">;
 export declare const pano1Matrix: THREE.Node<"mat4">;
 export declare const pano1Zoom: THREE.Node<"float">;
@@ -24,6 +25,8 @@ export declare const pano1HdrMinContentBoost: THREE.Node<"float">;
 export declare const pano1HdrCapacityMin: THREE.Node<"float">;
 export declare const pano1HdrCapacityMax: THREE.Node<"float">;
 export declare const pano1HdrGamma: THREE.Node<"float">;
+export declare const pano1HdrOffsetSdr: THREE.Node<"float">;
+export declare const pano1HdrOffsetHdr: THREE.Node<"float">;
 export declare const pano1DepthMaxDepth: THREE.Node<"float">;
 export declare const panoFilterSaturationBias: THREE.Node<"float">;
 export declare const panoFilterContrastBias: THREE.Node<"float">;
@@ -49,6 +52,8 @@ export declare const isCurrentFloor: THREE.VarNode<"bool">;
 export declare const isRoof: THREE.VarNode<"bool">;
 export declare const isRoofCameraCut: THREE.VarNode<"bool">;
 export declare const isRoofModelAlphaCut: THREE.VarNode<"bool">;
+export declare const isHidden: THREE.VarNode<"bool">;
+export declare const isHiddenCut: THREE.VarNode<"bool">;
 export declare const pano0Origin: THREE.VarNode<"vec3">;
 export declare const pano0SampleDirection: THREE.VarNode<"vec3">;
 export declare const pano1Origin: THREE.VarNode<"vec3">;

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

@@ -7,18 +7,7 @@
  * 通用工具函数（rgb2hsv, hsv2rgb, resolutionUniform, pixelRatioUniform）在 utils.ts 中。
  */
 import * as THREE from 'three/webgpu';
-import type { PBMTransition, PBMColorStyle, PBMCustomNodeTargetType, IPBMMaterial } from '../pbmMaterial';
-export interface SetupPanoOutputOptions {
-    useVertexMark: boolean;
-    useFloorStyleVisibility: boolean;
-    useGradientTexture: boolean;
-    useRefinedScreen: boolean;
-    usePanoFilter: boolean;
-    usePanoDepth: boolean;
-    useHDR: boolean;
-    colorMode: PBMColorStyle;
-    transition: PBMTransition;
-}
+import type { PBMCustomNodeTargetType, IPBMMaterial } from '../pbmMaterial';
 export declare function setupMeshOutput(material: THREE.NodeMaterial & IPBMMaterial, builder: THREE.NodeBuilder, materialType: PBMCustomNodeTargetType): void;
 /**
  * 在 NodeMaterial 已完成 morph/skinning/instance 等标准顶点处理后，

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

@@ -12,6 +12,12 @@ export declare function panoColor(options: {
     transition: PBMTransition;
     usePanoFilter: boolean;
     useRefinedScreen: boolean;
-    useHDR: boolean;
-    usePanoDepth: boolean;
+    /** pano0 的 HDR 分支开关 */
+    usePano0HDR: boolean;
+    /** pano1 的 HDR 分支开关 */
+    usePano1HDR: boolean;
+    /** pano0 的深度剔除开关 */
+    usePano0Depth: boolean;
+    /** pano1 的深度剔除开关 */
+    usePano1Depth: boolean;
 }): THREE.TSL.FnNode<[number | THREE.Node], THREE.VarNode<"vec3">>;

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

@@ -50,6 +50,15 @@ 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）。

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

@@ -1,9 +1,9 @@
 import * as THREE from 'three/webgpu';
 import { PBMGaussianSplattingNodeMaterial } from '../materials/pbmGaussianSplattingNodeMaterial';
 /**
- * 3DGS 渲染 Mesh（WebGPU / TSL 版，纯 CPU 数据准备）
+ * 3DGS 渲染 Mesh（WebGPU / TSL 版）
  *
- * 主循环用四个协作者准备数据（**无任何 compute shader**）：
+ * 主循环用四个协作者准备数据：
  *   - `SplatAssembler`：per-object region 增量 diff + **CPU 拼装** 大数据纹理
  *     （把各对象 packedData 紧凑拷进 CPU 缓冲，写 transformIndex/layerIndex 到 texel1.w；
  *     经 THREE.DataTexture 上传供主材质采样）
@@ -15,11 +15,14 @@ import { PBMGaussianSplattingNodeMaterial } from '../materials/pbmGaussianSplatt
  * 索引顺序 ≡ `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 增删布局变化时保持排序与大纹理映射一致、不闪烁）。
+ * 排序：本类**不再自己排序**。排序、绘制索引来源与绘制实例数一律经 `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 紧凑拼进一张
@@ -36,100 +39,61 @@ declare class PBMGaussianSplattingRenderMesh extends THREE.Mesh<THREE.InstancedB
     private transformStore;
     private layerRegistry;
     private shStore;
-    private sortWorker;
+    /**
+     * 当前生效的排序管线。由 `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;
-    /** splatIndex 实例属性的当前容量（点数）；不足时按 2 的幂扩容。 */
-    private splatIndexCapacity;
-    /** 单调递增的排序请求代；每代记录其所基于的布局快照，回传时按代取回（防异步错配）。 */
-    private sortGeneration;
-    /** 当前排序输入是否已上传给 worker（场景/transform 变化时置 false 触发重传）。 */
-    private sortDataUploaded;
-    /** 排序输入（布局 / transform）自上次上传后是否已变化——脏则强制重排并重传。 */
-    private sortInputsDirty;
     private forceClipperUniformRefresh;
+    private usedSHDegree;
+    constructor();
     /**
-     * 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 增删（布局变化）时保持排序与
-     * 大纹理映射一致、不闪烁。
+     * Requested_Pipeline_Mode（`GSPLAT_PIPELINE_*`）。写入后在**下一帧**由
+     * `syncPipelineMode` 解析并按需重建管线，便于开发期在同场景下对比两条管线
+     * （Requirement 13.2）。
      */
-    private orderData;
-    /** order 内容变化（新排序回传）→ 需重跑 CPU reorder。 */
-    private orderDirty;
-    /** 布局变化（LOD 增删 / 场景重建）→ 需以新布局（新段表）重跑 CPU reorder。 */
-    private layoutDirty;
-    /** 当前存活实例数（= 最近一次 applyReorderCPU 写入 splatIndex 的点数）。 */
-    private aliveCount;
-    /** 当前 order 所基于的布局快照（= 该次排序发起时的布局）。 */
-    private orderBaseSnapshot;
-    /** generation → 该次排序发起时的布局快照。 */
-    private snapshotByGen;
-    private prevSortCameraMatrix;
+    get pipelineMode(): number;
+    set pipelineMode(value: number);
+    /** 实际生效的 Current_Pipeline_Mode（解析后的结果，永不为 `AUTO`）。 */
+    get currentPipelineMode(): number;
     /** 平移增量阈值（世界单位）：超过才重排。 */
-    sortCameraDistance: number;
+    get sortCameraDistance(): number;
+    set sortCameraDistance(value: number);
     /** 姿态相似度阈值（|quat 点积|）：低于才重排（0.99 ≈ 约 16° 内不重排）。 */
-    sortCameraCoorient: number;
+    get sortCameraCoorient(): number;
+    set sortCameraCoorient(value: number);
     /** 最小重排间隔（ms）：即使脏也不超过此频率，0=不限。 */
-    sortMinIntervalMs: number;
-    private sortLastTime;
-    private _scratchViewProj;
-    private usedSHDegree;
-    constructor();
+    get sortMinIntervalMs(): number;
+    set sortMinIntervalMs(value: number);
     private createGeometry;
-    /**
-     * 确保 splatIndex 实例属性容量 >= requiredCount；不足时按 2 的幂扩容（保留旧内容）。
-     * 返回当前（可能是新建的）属性。
-     */
-    private ensureSplatIndexCapacity;
     private createMaterial;
     private createDefaultLayerClipperRanges;
     private createDefaultClipperMatrices;
-    /**
-     * 应用排序结果：
-     *   1. 保存 depthIndex 副本到 `orderData`（作为 CPU reorder 的输入源；实际 remap 在
-     *      onBeforeRender 中由 applyReorderCPU 完成，此处不写 splatIndex）。
-     *   2. 置 orderDirty（新排序回传 → 需重跑 CPU reorder）。
-     *   3. 按 generation 取回该次排序真正基于的布局快照，作为 reorder 基准，并清理更旧快照
-     *      （worker 结果按 generation 单调返回，更旧快照不会再用到）。
-     * 保证：每次回传的 depthIndex 恒为「该代排序时 totalPoints」的一个排列，点数守恒。
-     */
-    private applyDepthIndex;
-    /** 捕获当前布局：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;
@@ -142,8 +106,8 @@ declare class PBMGaussianSplattingRenderMesh extends THREE.Mesh<THREE.InstancedB
     /**
      * 场景变化时按**同一有序 objects**依次同步四个协作者，保证布局三一致：
      * layerRegistry / transformStore 先行（assembler 的 resolveIndices 依赖二者的 indexOf/layerIndexOf），
-     * 再 assembler.sync（增量 diff + 连续 start 偏移，不触碰 GPU）→ shStore.sync；大纹理 GPU 组装
-     * 延迟到 onBeforeRender 中 device 就绪时的 assembler.assemble(device)。
+     * 再 assembler.sync（增量 diff + 连续 start 偏移，不触碰 GPU）→ shStore.sync；大纹理组装
+     * 延迟到 onBeforeRender 中的 assembler.assemble()。
      */
     private rebuildScene;
     /**
@@ -151,21 +115,23 @@ declare class PBMGaussianSplattingRenderMesh extends THREE.Mesh<THREE.InstancedB
      * 四者由 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;
+    /**
+     * 每帧一次的 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;
 }

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: {