跳转至

Utils 模块

Visionary Utils 模块 收集了系统其余部分所依赖的底层构建块：数学原语、IEEE‑754 float16 工具、WebGPU 仪表化和渲染器引导实用程序。它用一个内聚的工具包取代了分散在 Managers, IO, 和 Renderer 代码中的一次性辅助函数，使高斯泼溅 (Gaussian Splatting) 代码保持紧凑和可测试。

模块概览

  • 位置: src/utils/
  • 职责: 数学辅助、float16/球谐函数 (Spherical Harmonics) 打包、GPU 缓冲/调试工具、渲染器/环境设置辅助
  • 主要依赖: gl-matrix, three/webgpu, WebGPU API

目录

src/utils/
├── index.ts                  # 公共表面
├── aabb.ts                   # AABB 原语
├── camera-math.ts            # 相机/FOV 转换
├── transforms.ts             # 共享变换常量
├── gpu.ts                    # 缓冲辅助, SH 数学, GPUStopwatch
├── half.ts                   # IEEE754 float16 + SH 打包
├── vector-math.ts            # Vec3 辅助 + 平面拟合器
├── env-map-helper.ts         # Three.js WebGPU 的 HDR/PMREM 工作流
├── renderer-init-helper.ts   # 渲染器克隆 & 环境引导
└── debug-gpu-buffers.ts      # 计数管线和着色器缓冲检查

以此为基础的能力地图

1. 数学与几何原语 (Math & Geometry Primitives)

  • 不可变的 Aabb 类用于快速边界查询
  • 相机数学 (deg2rad, fov2focal, focal2fov) 由 Controllers 和 IO 共享
  • VIEWPORT_Y_FLIP 变换常量用于渲染器/视图矩阵约定
  • vector-math 辅助函数 (dot, add, normalize, planeFromPoints) 被高斯加载器和布局工具重用

2. Float16 & SH 数据管线 (Float16 & SH Data Pipelines)

  • 高精度 f32_to_f16 / f16_to_f32 转换，具有可配置的舍入、FTZ、饱和及遗留模拟
  • 用于 ONNX 张量和 GPU 上传的批量 packF16Array / unpackF16Array 函数
  • makeCopySH_PackedF16 将 PLY/ONNX f_dc_* / f_rest_* 通道重新打包为 WGSL 着色器消费的固定 24×u32 布局

3. GPU 仪表化与调试 (GPU Instrumentation & Debugging)

  • 按位 align4 / align8 辅助函数保证合法的复制/映射大小
  • readWholeBuffer, dumpU32, dumpHex, 和 keyToNum 涵盖日常调试
  • GPUStopwatch 使用时间戳查询进行每阶段性能分析
  • debug-gpu-buffers.ts 暴露 readGPUBuffer, compareBufferValues, 和 debugCountPipeline 以将 ONNX 推理计数一直跟踪到着色器 uniform
  • buildCov, sigmoid, shNumCoefficients, shDegreeFromNumCoeffs 保持高斯数学集中化

4. 渲染器与环境辅助工具 (Renderer & Environment Helpers)

  • EnvMapHelper 包装 HDR 加载、PMREM 生成、色调映射同步和渲染器环境更新，并对构建后的生命周期进行防御性检查
  • RendererInitHelper 提供单一入口点以克隆渲染器设置，为每个渲染器重建 PMREM 资源，并在使用共享场景之前确保 WebGPU 后端/设备就绪

典型工作流

  1. 渲染器镜像 (Renderer Mirroring) – 复制生产渲染器以用于捕获/预览，而不共享 GPU 资源：
await RendererInitHelper.initializeRenderer(
  previewRenderer,
  previewScene,
  { sourceRenderer: liveRenderer, width, height }
);

  1. ONNX → 着色器计数验证 (ONNX → Shader Count Verification) – 调试动态高斯推理时，debugCountPipeline 确认 ONNX 输出缓冲、ModelParams 缓冲和着色器存储保持同步。

  2. HDR 环境引导 (HDR Environment Bootstrap) – 即使在构建输出加载后 renderer.backend.device 不立即可用，EnvMapHelper.loadHDRTexture + createPMREMEnvironmentMap 也能将 .hdr 文件转换为色调映射后的 scene.environment 纹理。

使用亮点

// 相机实用工具
import { deg2rad, fov2focal } from 'src/utils';
const vFov = deg2rad(60);
const focal = fov2focal(vFov, canvas.height);

// GPU 性能仪表化
const stopwatch = new GPUStopwatch(device, 32);
stopwatch.start(encoder, 'gaussian-pass');
// ... 编码 Pass ...
stopwatch.stop(encoder, 'gaussian-pass');
stopwatch.end(encoder);
const timings = await stopwatch.takeMeasurements(device.queue);

// 带回退 HDR 的渲染器克隆
const { envMap } = await RendererInitHelper.initializeRenderer(
  captureRenderer,
  captureScene,
  { fallbackHdrUrl: '/public/textures/hdr/daytime.hdr' }
);
EnvMapHelper.setupSceneEnvironment(captureScene, envMap, null);

// 用于相机自动调平的平面拟合
const { centroid, normal } = planeFromPoints(sampledPoints);
if (normal) {
  console.log('Scene up vector', normal);
}

集成说明

  • Managers 重用渲染器辅助函数来启动专用预览渲染器，而不触及全局状态。
  • IO / FileLoader 将 float16 打包和球谐函数布局委托给 half.ts，保证跨格式 (PLY, SPZ, KSplat, ONNX) 的 GPU 缓冲位一致性。
  • Renderer / Controllers 每当相机装备或实例化缓冲更改时，都依赖相机数学、Aabb 和高斯协方差辅助函数。
  • Diagnostics 表面消费 debug-gpu-buffers 实用程序进行现场调试，而无需引入重型工具。

可靠性与性能实践

  • 预分配的类型化数组视图避免在 float16 转换期间的流失。
  • 每个 GPU 回读辅助函数都强制执行 4/8 字节对齐并立即销毁暂存缓冲。
  • 渲染器辅助函数使用显式设备/PMREM 检查加上微任务以让后端刷新，以此防御部分构造的 WebGPU 后端。
  • 平面拟合和高斯数学函数尽早拒绝非有限输入，以防止 NaN 传播到 WGSL 存储缓冲中。

因此，Utils 模块是 Visionary 的共享工具箱：每当您需要数学、打包、GPU 计时或渲染器引导胶水代码时，您都会获得经过实战检验的辅助函数，而不是临时的代码。

相关文档