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

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

@@ -4,8 +4,9 @@ export { PBMGaussianSplattingObject, type SplatData, } from "./objects/pbmGaussi
 export { PBMGaussianSplattingObject as PBMGSObject, } from "./objects/pbmGaussianSplattingObject";
 export { PBMPointCloud, type PointCloudData, } from "./objects/pbmPointCloud";
 export { PBMGaussianSplattingRenderMesh, } from "./objects/pbmGaussianSplattingRenderMesh";
-export { PBMGaussianSplattingNodeMaterial, } from "./materials/pbmGaussianSplattingNodeMaterial";
-export { PBMUpdateable, PBMPanoFilter, type IPBMMaterial, type PBMPanoFilterValue, type PBMAlphaMode, type PBMClipperParameter, type PBMColorStyle, type PBMFloorStyle, type PBMPanoPicture, type PBMHDRConfig, type PBMPanoDepth, type PBMPointBack, type PBMPointCloudShaderType, type PBMPointShape, type PBMPointSize, type PBMRefinedScreen, type PBMTransition, } from "./materials/pbmMaterial";
+export { PBMGaussianSplattingNodeMaterial, type PBMGaussianSplattingNodeMaterialOptions, } from "./materials/pbmGaussianSplattingNodeMaterial";
+export { PBMPointCloudMaterial, } from "./materials/pbmPointCloudMaterial";
+export { PBMUpdateable, PBMPanoFilter, PBMCustomNode, PBMVertexMarkFlag, 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/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/nodes/pbmMeshBasicNodeMaterial.d.ts

@@ -9,6 +9,8 @@ export declare class PBMMeshBasicNodeMaterial extends THREE.MeshBasicNodeMateria
     static get type(): string;
     readonly isPBMMeshBasicNodeMaterial = true;
     constructor(parameters?: THREE.MeshBasicNodeMaterialParameters);
+    customProgramCacheKey(): string;
+    setupVertex(builder: THREE.NodeBuilder): THREE.Node;
     setup(builder: THREE.NodeBuilder): void;
     setupObserver(builder: THREE.NodeBuilder): THREE.NodeMaterialObserver;
 }

package/five/model/materials/nodes/pbmMeshPanoOnlyNodeMaterial.d.ts

@@ -9,6 +9,8 @@ export declare class PBMMeshPanoOnlyNodeMaterial extends THREE.MeshBasicNodeMate
     static get type(): string;
     readonly isPBMPanoOnlyNodeMaterial = true;
     constructor(parameters?: THREE.MeshBasicNodeMaterialParameters);
+    customProgramCacheKey(): string;
+    setupVertex(builder: THREE.NodeBuilder): THREE.Node;
     setup(builder: THREE.NodeBuilder): void;
     setupObserver(builder: THREE.NodeBuilder): THREE.NodeMaterialObserver;
 }

package/five/model/materials/nodes/pbmMeshPhongNodeMaterial.d.ts

@@ -9,6 +9,8 @@ export declare class PBMMeshPhongNodeMaterial extends THREE.MeshPhongNodeMateria
     static get type(): string;
     readonly isPBMMeshPhongNodeMaterial = true;
     constructor(parameters?: THREE.MeshPhongNodeMaterialParameters);
+    customProgramCacheKey(): string;
+    setupVertex(builder: THREE.NodeBuilder): THREE.Node;
     setup(builder: THREE.NodeBuilder): void;
     setupObserver(builder: THREE.NodeBuilder): THREE.NodeMaterialObserver;
 }

package/five/model/materials/nodes/pbmMeshPhysicalNodeMaterial.d.ts

@@ -9,6 +9,8 @@ export declare class PBMMeshPhysicalNodeMaterial extends THREE.MeshPhysicalNodeM
     static get type(): string;
     readonly isPBMMeshPhysicalNodeMaterial = true;
     constructor(parameters?: THREE.MeshPhysicalNodeMaterialParameters);
+    customProgramCacheKey(): string;
+    setupVertex(builder: THREE.NodeBuilder): THREE.Node;
     setup(builder: THREE.NodeBuilder): void;
     setupObserver(builder: THREE.NodeBuilder): THREE.NodeMaterialObserver;
 }

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

@@ -8,11 +8,13 @@
  *   - 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 紧凑写入）
+ *                     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]
  *   - 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 +25,14 @@ 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;
+    useOrderTexture: boolean;
+    orderTexture: THREE.Texture | null;
     shTextureSize: THREE.Vector2;
     aggregationEnabled: boolean;
     aggregationProgress: number;
@@ -40,6 +45,8 @@ export declare class PBMGaussianSplattingNodeMaterial extends THREE.NodeMaterial
     layerClipperRanges: THREE.Vector2[];
     clipperMatricesInverse: THREE.Matrix4[];
     private _uDataTex;
+    private _uOrderTex;
+    private _uNumPoints;
     private _uTransformsTex;
     private _uTransformIndicesTex;
     private _uLayerIndicesTex;

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

@@ -1,20 +1,282 @@
 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';
 export type PBMTransition = 'BLACK' | 'SPREAD' | 'FADE';
 export type PBMFloorStyle = 'VISIBILITY' | 'OPACITY';
+/**
+ * 屋顶样式（仅在 vertexMarks 为 true、即模型带屋顶标记时生效）
+ * - AUTO: 根据相机俯仰角渐进裁切屋顶（默认，原有行为）
+ * - HIDE: 始终隐藏屋顶，与视角无关
+ */
+export type PBMRoofStyle = 'AUTO' | 'HIDE';
 export type PBMColorStyle = 'RGB' | 'ALTITUDE' | 'CONSTANT';
 export type PBMPointShape = 'SQUARE' | 'CIRCLE';
 export type PBMPointSize = 'FIXED' | 'ATTENUATION';
 export type PBMPointBack = 'VISIBLE' | 'HIDDEN' | 'DARK';
+/**
+ * 顶点标注档位（按位掩码）。
+ * 每一类标注对应一位，可按位独立启用；新增档位时在此追加一位即可。
+ */
+export declare const PBMVertexMarkFlag: {
+    readonly none: 0;
+    readonly roof: 2;
+    readonly hidden: 4;
+    /** 全开，默认包含未来新增的所有标注档位 */
+    readonly all: 255;
+};
 export declare class PBMUpdateable extends Subscribe<{
     "update": () => void;
 }> {
 }
+/** PBMCustomNode 生效的材质类型 */
+export type PBMCustomNodeTargetType = 'basic' | 'phong' | 'standard' | 'panoOnly' | 'pointcloud';
+/**
+ * 全景分支中可供自定义节点使用的节点上下文。
+ * 这些字段是稳定的 PBM API，业务方不需要直接依赖内部 defines.ts 路径。
+ */
+export interface PBMCustomNodePanoContext {
+    /** 全景点位在世界空间中的原点（pano 矩阵的平移列） */
+    origin: THREE.Node<'vec3'>;
+    /** 当前片元对应的全景采样方向（已含 zoom 校正），可直接用于采样该 slot 的 cube 贴图 */
+    sampleDirection: THREE.Node<'vec3'>;
+    /**
+     * 该 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 处理后的全景颜色
+     * @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，
+ *   因此分支判断要用 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'>;
+    /**
+     * 相机朝向（世界空间单位向量，由 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'>;
+}
+/**
+ * 节点插槽定义
+ *
+ * 每个插槽是一个函数，接收当前管线中的节点，返回修改后的节点。
+ * 用户在函数中可自由使用 TSL API（uniform、attribute、Fn、数学运算等）。
+ */
+export interface PBMCustomNodeSlots {
+    /**
+     * 模型基础颜色修改（在全景混合之前）
+     * - Mesh 材质：在 colorMode 处理之后、pano 混合之前调用
+     * - PointCloud 材质：在实例颜色读取 + HSV 调整之后调用
+     *
+     * @param color - 当前模型颜色 (vec3, linear working space)
+     * @returns 修改后的颜色 (vec3)
+     */
+    modelColor?: (color: THREE.Node<'vec3'>, context: PBMCustomNodeContext) => THREE.Node<'vec3'>;
+    /**
+     * 全景颜色修改（在全景采样 + HDR + filter 之后，与模型混合之前）
+     * 仅在启用全景贴图时生效。
+     *
+     * @param panoColor - 当前全景采样颜色 (vec3)
+     * @returns 修改后的全景颜色 (vec3)
+     */
+    panoColor?: (panoColor: THREE.Node<'vec3'>, context: PBMCustomNodeContext) => THREE.Node<'vec3'>;
+    /**
+     * 最终输出颜色修改（在全部管线处理完成后、return 之前）
+     *
+     * @param color - 当前最终颜色 (vec4, 含 alpha)
+     * @returns 修改后的最终颜色 (vec4)
+     */
+    outputColor?: (color: THREE.Node<'vec4'>, context: PBMCustomNodeContext) => THREE.Node<'vec4'>;
+    /**
+     * 自定义 discard 逻辑（在管线 discard 判断之后额外追加）
+     * 返回的 bool 节点为 true 时丢弃该片元。
+     *
+     * @returns 是否丢弃 (bool node)
+     */
+    discard?: (context: PBMCustomNodeContext) => THREE.Node<'bool'>;
+    /**
+     * 顶点位置偏移（世界空间）
+     * 在标准顶点变换之后、投影之前应用。
+     * 注意：PointCloud 材质中此插槽作用于 instancePosition 展开后的 view 空间。
+     *
+     * @param position - 当前世界空间位置 (vec3)
+     * @returns 修改后的世界空间位置 (vec3)
+     */
+    vertexPosition?: (position: THREE.Node<'vec3'>, context: PBMCustomNodeContext) => THREE.Node<'vec3'>;
+}
+export interface PBMCustomNodeOptions {
+    /** 生效的材质类型 */
+    type: readonly PBMCustomNodeTargetType[];
+    /** 节点插槽 */
+    slots: PBMCustomNodeSlots;
+    /**
+     * 自定义标量 uniforms（可选）。
+     * 登记在这里的 uniform，写其 `.value` 时会自动触发所属材质刷新（见 watchUniforms）。
+     * 注意：uniformArray 的数据在 `.array`/元素上，`.value` setter 捕获不到，
+     * 不要放进这里；这类改动请在原地修改后显式调用 {@link PBMCustomNode.markNeedsUpdate}。
+     */
+    uniforms?: Record<string, THREE.UniformNode<any, any>>;
+}
+export declare class PBMCustomNode extends PBMUpdateable {
+    readonly id: string;
+    /** 生效的材质类型 */
+    readonly type: readonly PBMCustomNodeTargetType[];
+    /** TSL Node 插槽 */
+    readonly slots: PBMCustomNodeSlots;
+    /**
+     * 登记的标量 uniforms（仅 UniformNode）。写其 `.value` 会自动触发材质刷新。
+     * uniformArray 请勿放这里（.value setter 捕获不到），改用 markNeedsUpdate()。
+     */
+    readonly uniforms: Record<string, THREE.UniformNode<any, any>>;
+    constructor(options: PBMCustomNodeOptions);
+    /**
+     * 包装登记的 uniforms：写 `.value` 时自动 emit('update')，触发所属材质刷新
+     * （配合 Parameter 对 customNodes 的监听 + customNodesVersion 被监视属性）。
+     */
+    private watchUniforms;
+    /**
+     * 手动标记 uniform 已变化、需要把最新值刷新到所有相关材质。
+     * 用于原地修改 uniformArray / Vector 等 `.value` setter 捕获不到的场景。
+     */
+    markNeedsUpdate(): void;
+    /**
+     * 判断此 CustomNode 是否对指定材质类型生效
+     */
+    appliesTo(materialType: PBMCustomNodeTargetType): boolean;
+    /**
+     * 生成用于 customProgramCacheKey 的标识字符串
+     * 包含 id + 目标材质类型 + 启用的 slot 名称。
+     */
+    get cacheKey(): string;
+}
+/**
+ * 生成 customNodes 数组的 customProgramCacheKey 片段。
+ * 在 NodeMaterial 的 customProgramCacheKey() 中调用。
+ */
+export declare function customNodesCacheKey(customNodes: readonly PBMCustomNode[] | undefined): string;
 export interface PBMPanoFilterValue {
     saturationSaturationBias: number;
     contrastContrastBias: number;
@@ -74,10 +336,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 */
@@ -104,12 +371,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;
@@ -117,12 +386,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;
@@ -141,7 +412,8 @@ export interface IPBMMaterial {
     pointScale: number;
     pointMinPixel: number;
     pointMaxPixel: number;
-    vertexMarks: boolean;
+    useVertexMarkRoof: boolean;
+    useVertexMarkHidden: boolean;
     colorAlpha: number;
     alphaMode: string;
     modelAlpha: number;
@@ -152,6 +424,7 @@ export interface IPBMMaterial {
     floorIndex: number;
     shownFloorIndex: number;
     floorStyle: string;
+    roofStyle: PBMRoofStyle;
     brightness: number;
     colorSaturation: number;
     colorBrightness: number;
@@ -160,6 +433,15 @@ export interface IPBMMaterial {
     maxDisplayBoost: number;
     modelBoundingMin: THREE.Vector3;
     modelBoundingMax: THREE.Vector3;
+    /** 自定义节点列表（TSL Node 级别的材质扩展） */
+    customNodes: readonly PBMCustomNode[];
+    /**
+     * 自定义节点 uniform 的“脏计数器”。
+     * 被 NodeMaterialObserver 监视（见 pbmProperties）：任一 customNode 的 uniform 变化时，
+     * Parameter 会 ++ 此值，从而让 observer 判定材质需要刷新、把最新 uniform 上传到所有材质。
+     * 该值不进入 shader，仅作刷新触发用。
+     */
+    customNodesVersion: number;
 }
 export type PBMPropertyKey = keyof Omit<IPBMMaterial, 'isPBMMaterial'>;
 export declare const pbmProperties: PBMPropertyKey[];

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

@@ -46,12 +46,3 @@ export type PBMMeshMaterial = PBMMeshBasicMaterial | PBMMeshPhongMaterial | PBMM
 export declare function createPBMMeshMaterial(shaderType?: PBMMeshShaderType | {
     shaderType?: PBMMeshShaderType;
 }): PBMMeshMaterial;
-export interface PBMPointCloudMaterial extends THREE.Material, IPBMMaterial {
-}
-export declare class PBMPointCloudMaterial extends THREE.Material implements IPBMMaterial {
-    readonly isPBMMaterial: true;
-    readonly shaderType = "standard";
-    constructor();
-    copy(source: PBMPointCloudMaterial): this;
-}
-export declare function createPBMPointCloudMaterial(): PBMPointCloudMaterial;

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

@@ -16,7 +16,7 @@ export declare class PBMPointCloudNodeMaterial extends THREE.NodeMaterial {
     pointBack: PBMPointBack;
     colorStyle: PBMColorStyle;
     floorStyle: PBMFloorStyle;
-    vertexMarks: boolean;
+    vertexMarks: boolean | number;
     pointScale: number;
     pointMinPixel: number;
     pointMaxPixel: 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">;
@@ -47,7 +50,10 @@ export declare const colorSaturation: THREE.Node<"float">;
 export declare const colorBrightness: THREE.Node<"float">;
 export declare const isCurrentFloor: THREE.VarNode<"bool">;
 export declare const isRoof: THREE.VarNode<"bool">;
-export declare const isRoofCut: 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,20 +7,13 @@
  * 通用工具函数（rgb2hsv, hsv2rgb, resolutionUniform, pixelRatioUniform）在 utils.ts 中。
  */
 import * as THREE from 'three/webgpu';
-import type { PBMTransition, PBMColorStyle } from '../pbmMaterial';
-import { IPBMMaterial } from '../pbmMaterial';
-export interface SetupPanoOutputOptions {
-    useVertexMark: boolean;
-    useFloorStyleVisibility: boolean;
-    useGradientTexture: boolean;
-    useRefinedScreen: boolean;
-    usePanoFilter: boolean;
-    usePanoDepth: boolean;
-    useHDR: boolean;
-    colorMode: PBMColorStyle;
-    transition: PBMTransition;
-}
-export declare function setupMeshOutput(material: THREE.NodeMaterial & IPBMMaterial, builder: THREE.NodeBuilder): void;
-export declare function setupMeshPanoOnlyOutput(material: THREE.NodeMaterial & IPBMMaterial, builder: THREE.NodeBuilder): void;
+import type { PBMCustomNodeTargetType, IPBMMaterial } from '../pbmMaterial';
+export declare function setupMeshOutput(material: THREE.NodeMaterial & IPBMMaterial, builder: THREE.NodeBuilder, materialType: PBMCustomNodeTargetType): void;
+/**
+ * 在 NodeMaterial 已完成 morph/skinning/instance 等标准顶点处理后，
+ * 对世界空间位置应用 custom vertexPosition，再转换回裁剪空间。
+ */
+export declare function setupMeshVertex(material: THREE.NodeMaterial & IPBMMaterial, materialType: PBMCustomNodeTargetType, baseVertex: THREE.Node): THREE.Node;
+export declare function setupMeshPanoOnlyOutput(material: THREE.NodeMaterial & IPBMMaterial, builder: THREE.NodeBuilder, materialType: PBMCustomNodeTargetType): void;
 export declare function setupPointCloudVertex(material: THREE.NodeMaterial & THREE.Material & IPBMMaterial, builder: THREE.NodeBuilder): THREE.Node;
 export declare function setupPointCloudOutput(material: THREE.NodeMaterial & IPBMMaterial, builder: THREE.NodeBuilder): void;

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">>;