Point Cloud 模块
Point Cloud（点云）模块将归一化的高斯 Splat 数据转换为 GPU 资源，从而为 Visionary 的预处理、排序和渲染管线提供动力。它封装了缓冲区创建、绑定组连接、运行时参数调整以及动态 ONNX 驱动的动画，因此系统的其余部分可以专注于算法而不是底层连接。
概览
该模块提供：
- GPU 缓冲区编排 – 上传 CPU 数据或接受预创建的 GPU 缓冲区，并分配用于预处理、排序和间接绘制的投影 2D Splat 缓冲区。
- Uniform 与元数据流 – 维护绘制级 Uniform 以及一个 128 字节的模型参数块，其中携带 WGSL 着色器可理解的变换、Splat 控制参数和精度元数据。
- 绑定组管理 – 提供缓存的计算和渲染绑定组布局，以及自动实例化的绑定组，以匹配预处理 (
@group(0)) 和渲染阶段的预期。 - 运行时控制 – 暴露高斯缩放、球谐函数阶数、内核大小、不透明度、截止阈值和渲染模式的设置器，使工具无需触碰着色器即可调整外观。
- 动态数据路径 –
DynamicPointCloud将基础设施与 ONNX 生成器、可选的绘制计数缓冲区以及时间轴控制器配对，以驱动实时内容。
职责
GPU 数据生命周期
- 接受来自 IO 模块的
GenericGaussianPointCloudTS（GaussianDataSource的别名）对象。 - 将高斯属性和 SH 系数上传到专用的
GPUBuffer对象中，或复用外部生成的缓冲区以实现零拷贝工作流。 - 使用
BUFFER_CONFIG.SPLAT_STRIDE（32 字节）中定义的步幅分配投影 Splat 缓冲区，以便计算着色器可以发出屏幕空间记录加上间接绘制负载。
Uniform 与绑定组连接
- 通过
UniformBuffer初始化绘制 Uniform ([numPoints, shDegree, 0, 0])。 - 用变换、偏移、着色旋钮和精度描述符填充模型参数 Uniform，然后发布辅助方法（
updateModelParamsBuffer,setTransform, 参数设置器）以使其与场景状态保持同步。 - 提供与
layouts.ts中缓存布局相匹配的bindGroup()和renderBindGroup()句柄，保证跨管线的一致性。
动态与感知精度的渲染
- 允许通过
replaceStorageBuffers进行运行时缓冲区交换，实现 FP32→FP16 或量化转换而无需重建对象。 DynamicPointCloud通过 ONNX 生成器挂钩、精度元数据注入（setPrecisionForShader,applyFP16）、用于间接绘制的可选计数缓冲区以及管理播放、循环和时间缩放的TimelineController来增强基类。
核心组件
PointCloud(point_cloud.ts) – 拥有静态数据集的 GPU 缓冲区、Uniform 和绑定组的核心类。DynamicPointCloud(dynamic_point_cloud.ts) – 扩展PointCloud，具有直接 GPU 缓冲区摄入、ONNX 生成器集成和高级时间轴控制。layouts.ts– 暴露getBindGroupLayout、getRenderBindGroupLayout和BUFFER_CONFIG；所有布局均按GPUDevice缓存。splat_buffer.ts– 定义SplatBuffer、GenericGaussianPointCloud和镜像 GPU 内存布局的辅助类。index.ts– Visionary 其余部分使用的统一导出文件。
缓冲区与布局快照
| 缓冲区 | 来源 | 用途标志 | 内容 |
|---|---|---|---|
| 高斯存储 | CPU 上传或外部 GPU 缓冲区 | STORAGE | COPY_DST |
打包的位置、不透明度和协方差（每个 Splat 10× f16）。 |
| SH 存储 | CPU 上传或外部 GPU 缓冲区 | STORAGE | COPY_DST |
打包的球谐函数系数（依赖于阶数）。 |
| 2D Splat 缓冲区 | 每个点云分配 | STORAGE | COPY_SRC | COPY_DST | INDIRECT |
屏幕空间 Splat 负载加上排序键（步幅 = 32 字节）。 |
| 绘制 Uniform | 每个点云分配 | UNIFORM | COPY_DST |
预处理内核使用的 [numPoints, shDegree, …]。 |
| 模型参数 | 每个点云分配 | UNIFORM | COPY_DST |
128 字节块，包含变换、偏移、着色旋钮和精度元数据。 |
模型参数布局 (128 字节)
| 字节范围 | 字段 |
|---|---|
0 – 63 |
4×4 变换矩阵（列主序）。 |
64 – 67 |
预处理器打包多个点云时使用的 baseOffset。 |
68 – 71 |
着色器用的 numPoints 镜像。 |
72 – 75 |
gaussianScaling (高斯缩放)。 |
76 – 79 |
maxShDeg (最大 SH 阶数)。 |
80 – 83 |
kernelSize (内核大小)。 |
84 – 87 |
opacityScale (不透明度缩放)。 |
88 – 91 |
cutoffScale (截止缩放)。 |
92 – 95 |
rendermode (渲染模式)。 |
96 – 99 |
gaussDataType (0=f32, 1=f16, 2=i8, 3=u8)。 |
100 – 103 |
colorDataType。 |
104 – 107 |
gaussScale (用于量化解码)。 |
108 – 111 |
gaussZeroPoint。 |
112 – 115 |
colorScale。 |
116 – 119 |
colorZeroPoint。 |
120 – 127 |
保留/填充以供未来元数据使用。 |
使用模式
import { PointCloud } from 'src/point_cloud';
const gaussianData = await defaultLoader.loadFile(file); // IO 模块
const pc = new PointCloud(device, gaussianData);
pc.updateModelParamsBuffer(modelMatrix);
pc.setGaussianScaling(1.2);
computePass.setBindGroup(0, pc.bindGroup());
renderPass.setBindGroup(0, pc.renderBindGroup());
对于动态源：
import { DynamicPointCloud } from 'src/point_cloud';
const dpc = new DynamicPointCloud(device, gaussianGPU, shGPU, maxPoints, countBuffer, 48, precisionInfo);
dpc.setOnnxGenerator(onnxGenerator);
dpc.setTimeUpdateMode(TimeUpdateMode.VARIABLE_DELTA);
await dpc.update(cameraMatrix, modelMatrix, performance.now());
集成点
- IO 模块 – 提供构造函数使用的
GenericGaussianPointCloudTS实例。 - Preprocess (预处理) 模块 – 使用
bindGroup()读取高斯/SH 数据并写入投影 Splat。 - Sort (排序) 模块 – 消费共享的 2D Splat 缓冲区和间接绘制元数据。
- Renderer (渲染器) 模块 – 使用
renderBindGroup()对投影 Splat 进行采样。 - App/Managers – 调整运行时参数（缩放、内核大小、渲染模式）并在变换更改时触发
updateModelParamsBuffer()。 - ONNX/Tensor 路径 – 将 GPU 缓冲区及精度元数据馈送给
DynamicPointCloud。
文件结构
src/point_cloud/
├── index.ts # 统一导出
├── point_cloud.ts # PointCloud 类
├── dynamic_point_cloud.ts # DynamicPointCloud 子类
├── layouts.ts # 绑定组布局 + 缓冲区配置
└── splat_buffer.ts # 镜像 GPU 内存布局的接口