Point Cloud 模块 API 参考手册
本文档列举了 src/point_cloud 目录下暴露的每一个公共接口。它对应 src/point_cloud 中的 TypeScript 签名，并解释了每个部分如何与更广泛的 WebGPU 管线进行交互。
目录
模块导出
src/point_cloud/index.ts 重新导出了以下内容：
export { PointCloud } from './point_cloud';
export { DynamicPointCloud } from './dynamic_point_cloud';
export type { SplatBuffer } from './splat_buffer';
export * from './layouts'; // getBindGroupLayout, getRenderBindGroupLayout, BUFFER_CONFIG
PointCloud
封装了单个高斯数据集所需的 GPU 缓冲区、绘制 Uniform、模型参数 Uniform 以及绑定组（Bind Groups）。
构造函数
new PointCloud(
device: GPUDevice,
pc: GenericGaussianPointCloudTS,
externalBuffers?: { gaussianBuffer: GPUBuffer; shBuffer: GPUBuffer }
);
pc必须符合GenericGaussianPointCloudTS接口（即 IO 模块中的GaussianDataSource别名）。- 当传入
externalBuffers时，构造函数会跳过 CPU 上传过程并复用这些 GPU 缓冲区（适用于 ONNX 管道或运行时精度转换）。
公共属性
| 属性 | 类型 | 描述 |
|---|---|---|
numPoints |
number |
从 pc.numPoints() 派生的总 Splat 数量。 |
shDeg |
number |
球谐函数（SH）阶数。 |
bbox |
Aabb |
从 pc.bbox() 创建的世界空间包围盒。 |
colorMode |
'sh' | 'rgb' |
指示着色器应如何解释颜色数据（默认为 'sh'）。 |
center |
vec3 |
数据源提供的可选中心点（便于相机定位）。 |
up |
vec3 | null |
可选的向上向量。 |
uniforms |
UniformBuffer |
绘制级别的元数据缓冲区。 |
modelParamsUniforms |
UniformBuffer |
128 字节的块，包含变换矩阵 + 精度数据。 |
mipSplatting, kernelSize, backgroundColor |
可选 | 存储以供渲染器 UI 使用。 |
缓冲区与绑定组访问
| 签名 | 描述 |
|---|---|
bindGroup(): GPUBindGroup |
返回计算管线绑定组（包含高斯数据、SH、Splat 缓冲区、Uniforms）。 |
renderBindGroup(): GPUBindGroup |
返回渲染管线绑定组（包含投影后的 Splat）。 |
getSplatBuffer(): SplatBuffer |
发布高斯/SH GPU 缓冲区以及用于预处理调度大小计算的元数据。 |
replaceStorageBuffers(device, { gaussianBuffer, shBuffer }) |
交换高斯/SH 缓冲区并重建计算绑定组（Splat 缓冲区和 Uniforms 会被复用）。 |
Uniform 与变换辅助函数
| 签名 | 用途 |
|---|---|
updateModelParamsBuffer(transformMatrix: Float32Array, baseOffset = 0) |
使用提供的矩阵/偏移量以及缓存的着色 + 精度字段，重建 128 字节的模型参数块。 |
updateModelParamsWithOffset(transformMatrix, baseOffset) |
为保持向后兼容性而保留的别名。 |
setTransform(matrix: Float32Array | number[]) |
更新缓存的变换（已弃用），并通过 updateModelParamsBuffer 立即刷新 GPU Uniform。 |
渲染控制参数
所有设置器都会将输入限制在安全范围内，并记录应用的值。
| 设置器 | 获取器 | 备注 |
|---|---|---|
setGaussianScaling(scale) |
getGaussianScaling() |
乘以协方差缩放；存储在字节偏移量 72 处。 |
setMaxShDeg(deg) |
getMaxShDeg() |
限制在 [0, 3] 范围内；存储在字节偏移量 76 处。 |
setKernelSize(size) |
getKernelSize() |
非负的 2D 内核半径。 |
setOpacityScale(scale) |
getOpacityScale() |
不透明度的非负乘数。 |
setCutoffScale(scale) |
getCutoffScale() |
最小值为 0.1 以避免塌缩。 |
setRenderMode(mode) |
getRenderMode() |
0=Color (颜色), 1=Normal (法线), 2=Depth (深度)。 |
调整任何参数后，需调用
updateModelParamsBuffer（或setTransform），以便 GPU 副本接收新值。
静态辅助函数（已弃用）
PointCloud.bindGroupLayout(device) 和 PointCloud.renderBindGroupLayout(device) 代理到 layouts.ts，仅为兼容旧版导入而保留。建议直接使用 getBindGroupLayout 和 getRenderBindGroupLayout。
DynamicPointCloud
PointCloud 的子类，支持实时 ONNX 生成器、运行时精度元数据、可选的间接绘制计数以及时间轴驱动的动画控制。
构造函数
new DynamicPointCloud(
device: GPUDevice,
gaussianBuffer: GPUBuffer,
shBuffer: GPUBuffer,
maxPoints: number,
countBuffer?: GPUBuffer,
colorChannels = 48,
precisionInfo?: {
gaussian?: { dataType: PrecisionType; scale?: number; zeroPoint?: number };
color?: { dataType: PrecisionType; scale?: number; zeroPoint?: number };
}
);
colorChannels决定了隐含的 SH 阶数（3 → 0阶, 12 → 1阶, 27 → 2阶, 48 → 3阶）。如果提供 4 个通道，颜色模式将切换为'rgb'。countBuffer（如果提供）将被渲染器用于间接绘制。PrecisionType是描述存储类型的字符串（'float32' | 'float16' | 'int8' | 'uint8'）；scale/zeroPoint是可选的浮点数。
额外属性
| 属性 | 描述 |
|---|---|
colorMode |
从 colorChannels 派生的 'sh' 或 'rgb'。 |
colorChannels |
每个点的颜色系数数量。 |
countBuffer() |
返回可选绘制计数缓冲区的获取器。 |
ONNX 与精度辅助函数
| 签名 | 描述 |
|---|---|
setOnnxGenerator(generator: OnnxGenerator) |
链接负责修改 GPU 缓冲区的 ONNX 运行时包装器。 |
async update(cameraMatrix: mat4, modelTransform: Float32Array, time?: number, projectionMatrix?: mat4, rafNow?: number) |
组合矩阵，计算时间轴驱动的帧时间，调用 generator.generate(...)，并将新数据保留在 GPU 缓冲区中。 |
getGaussianPrecision() / getColorPrecision() |
返回存储的精度元数据对象（如果有）。 |
setPrecisionForShader() |
根据 precisionInfo 重写模型参数缓冲区的第 96–119 字节（数据类型枚举 + 缩放/零点）。修改精度元数据后调用此方法。 |
applyFP16(device, newGauss, newColor) |
便捷方法，用 FP16 版本替换两个存储缓冲区，记录新的精度元数据，并刷新着色器描述符。 |
动画与时间控制
所有动画方法都代理给内部的 TimelineController，因此每帧调用都是安全的。
| 签名 | 描述 |
|---|---|
startAnimation(speed = 1) / pauseAnimation() / resumeAnimation() / stopAnimation() |
标准播放控制。 |
setAnimationTime(time) |
跳转到归一化时间 (0–1)。 |
setAnimationSpeed(speed) / getAnimationSpeed() |
配置时间轴倍率。 |
setAnimationIsLoop(isLoop: boolean) |
切换循环播放与钳位播放。 |
setTimeScale(scale) / getTimeScale() |
应用于计算出的帧时间的额外缩放因子。 |
setTimeOffset(offset) / getTimeOffset() |
包装/钳位之前的附加偏移量。 |
resetFrameTime() |
重置累积时间为零。 |
getFrameTime() |
返回偏移/循环调整之前的原始时间轴时间。 |
setTimeUpdateMode(mode: TimeUpdateMode) / getTimeUpdateMode() |
切换 FIXED_DELTA（固定增量）和 VARIABLE_DELTA（可变增量）更新策略。 |
isAnimationRunning, isAnimationPaused, isAnimationStopped |
反映时间轴状态的只读获取器。 |
诊断与生命周期
| 签名 | 描述 |
|---|---|
getPerformanceStats() |
返回时间轴统计信息加上 ONNX 链接/点数元数据，用于 UI 覆盖层。 |
dispose() |
清除时间轴事件监听器。GPU 缓冲区不会被销毁（它们属于调用者）。 |
绑定组辅助函数与配置
位于 src/point_cloud/layouts.ts。
getBindGroupLayout(device: GPUDevice): GPUBindGroupLayout
返回（并缓存）计算布局：
| 绑定点 | 可见性 | 缓冲区类型 | 内容 |
|---|---|---|---|
0 |
GPUShaderStage.COMPUTE |
read-only-storage |
高斯缓冲区。 |
1 |
GPUShaderStage.COMPUTE |
read-only-storage |
SH 缓冲区。 |
2 |
GPUShaderStage.COMPUTE |
storage |
2D Splat 缓冲区（输出）。 |
3 |
GPUShaderStage.COMPUTE |
uniform |
绘制 Uniforms。 |
getRenderBindGroupLayout(device: GPUDevice): GPUBindGroupLayout
返回（并缓存）渲染布局：
| 绑定点 | 可见性 | 缓冲区类型 | 内容 |
|---|---|---|---|
2 |
GPUShaderStage.VERTEX |
read-only-storage |
与计算步骤共享的投影 Splat 缓冲区。 |
BUFFER_CONFIG
当分配必须匹配预处理和渲染着色器所使用的 WGSL 结构的自定义缓冲区时，请使用 SPLAT_STRIDE。
数据契约与辅助类型
SplatBuffer
type SplatBuffer = {
gaussianBuffer: GPUBuffer;
shBuffer: GPUBuffer;
numPoints: number;
shDegree: number;
bbox: Aabb;
};
由 PointCloud.getSplatBuffer() 返回，以便预处理代码可以调度工作，而无需直接依赖 PointCloud。
GenericGaussianPointCloud
绕过 IO 别名时传递给 PointCloud 的 CPU 侧数据形状：
interface GenericGaussianPointCloud {
gaussianBuffer(): ArrayBuffer;
shCoefsBuffer(): ArrayBuffer;
numPoints(): number;
shDegree(): number;
bbox(): Aabb;
center?: [number, number, number];
up?: [number, number, number] | null;
kernelSize?: number;
mipSplatting?: boolean;
backgroundColor?: [number, number, number];
}
GaussianCompressed & Gaussian
如果你需要在 CPU 上操作 Splat 数据，这些是镜像 WGSL/Rust 布局的实用包装器：
class GaussianCompressed {
bytes: Uint8Array;
constructor(bytes: ArrayBuffer);
}
class Gaussian {
xyz: [number, number, number];
opacity: number;
cov: [number, number, number, number, number, number];
constructor(xyz: [number, number, number], opacity: number, cov: [number, number, number, number, number, number]);
}
这些是轻量级辅助类；生产代码通常使用源自 IO 模块的打包 ArrayBuffer。