Three.js Integration API 参考

本文档涵盖了构成 Visionary 的 Three.js Integration 层的核心类。

目录

• Three.js Integration API 参考
• 目录
• GaussianThreeJSRenderer
  • constructor(renderer: THREE.WebGPURenderer, scene: THREE.Scene, gaussianModels: GaussianModel[])
  • 渲染生命周期
  • 深度与诊断
  • 模型管理助手
  • 逐模型参数控制
  • 全局动画控制
• GaussianSplattingThreeWebGPU
  • 生命周期
• CameraAdapter \& DirectCameraAdapter
• GaussianModel
• GridHelper
• DebugHelpers
  • constructor(device: GPUDevice)
  • 方法
  • 用法
• ThreeJsCameraAdapter (旧版)
• 使用示例 (Visionary 渲染循环)
• 注意事项

---

GaussianThreeJSRenderer

这是一个驻留在 Three.js 场景内部并驱动混合 WebGPU 管道的高级协调器（Orchestrator）。

constructor(renderer: THREE.WebGPURenderer, scene: THREE.Scene, gaussianModels: GaussianModel[])

const gaussianRenderer = new GaussianThreeJSRenderer(webgpuRenderer, scene, gaussianModels);
scene.add(gaussianRenderer);        // 启用 onBeforeRender 钩子
await gaussianRenderer.init();      // 准备 GaussianRenderer 排序器

渲染生命周期

方法	描述
init(): Promise<void>	确保 GPU 排序管道已编译。构造后调用一次。
renderThreeScene(camera: THREE.Camera): void	将整个场景渲染到内部的 HalfFloat RenderTarget，捕获其 DepthTexture（深度纹理），并将颜色缓冲区 Blit（传输）到画布（线性→sRGB）。启用自动深度模式（默认）时必须调用。
drawSplats(renderer: THREE.WebGPURenderer, scene: THREE.Scene, camera: THREE.Camera): boolean	在当前的交换链（swap chain）中运行高斯渲染通道。如果没有可见的高斯模型，则返回 false。存在 Gizmo 覆盖层时会自动进行合成。
renderOverlayScene(scene: THREE.Scene, camera: THREE.Camera): void	将辅助场景（Gizmo、HUD）渲染到 gizmoOverlayRT 中。请在 drawSplats 之前调用。
updateDynamicModels(camera: THREE.Camera, time?: number): Promise<void>	对每个注册的模型调用 GaussianModel.update(...)，以便 ONNX 点云接收最新的视图/投影变换。

深度与诊断

• setAutoDepthMode(enabled: boolean): void – 切换自动深度捕获。当禁用时，你必须通过 setOccluderMeshes(meshes: THREE.Mesh[]) 提供遮挡物。
• diagnoseDepth(): void – 记录当前深度配置、RT（渲染目标）尺寸和 GaussianRenderer 深度状态。
• disposeDepthResources(): void – 释放缓存的渲染/覆盖目标，以便下一帧重新创建它们（在设备丢失或画布调整大小问题后很有用）。

模型管理助手

• appendGaussianModel(model: GaussianModel): void
• removeModelById(modelId: string): boolean – ID 遵循 model_{index} 模式。
• getGaussianModels(): GaussianModel[] – 返回内部列表的浅拷贝。
• getModelParams(): { ... } – 收集用于 UI 面板的可见性和样条参数（返回对象包含 models 字典，含 id, name, visible, gaussianScale 等属性）。
• setModelVisible(modelId: string, visible: boolean): void
• getModelVisible(modelId: string): boolean

逐模型参数控制

每个 setter 都有一个匹配的 getter（如 getModelGaussianScale，getModelOpacityScale 等）。

• setModelGaussianScale(modelId: string, scale: number)
• setModelMaxShDeg(modelId: string, deg: number)
• setModelKernelSize(modelId: string, size: number)
• setModelOpacityScale(modelId: string, scale: number)
• setModelCutoffScale(modelId: string, scale: number)
• setModelRenderMode(modelId: string, mode: number)
• setModelAnimationIsLoop(modelId: string, loop: boolean)
• setModelTimeScale(modelId: string, scale: number)
• setModelTimeOffset(modelId: string, offset: number)
• setModelTimeUpdateMode(modelId: string, mode: string | number) – 转发到底层 GaussianModel。
• setModelAnimationTime(modelId: string, time: number)
• setModelAnimationSpeed(modelId: string, speed: number)
• startModelAnimation(modelId: string, speed?: number)
• pauseModelAnimation(modelId: string)
• resumeModelAnimation(modelId: string)
• stopModelAnimation(modelId: string)

全局动画控制

• setGlobalTimeScale(scale: number)
• setGlobalTimeOffset(offset: number)
• setGlobalTimeUpdateMode(mode: string | number)
• startAllAnimations(speed?: number)
• pauseAllAnimations()
• resumeAllAnimations()
• stopAllAnimations()
• setAllAnimationTime(time: number)
• setAllAnimationSpeed(speed: number)
• resetParameters() – 恢复全局默认值（scale = 1, SH degree = 3, kernel = 0.1 等）。

---

GaussianSplattingThreeWebGPU

用于将高斯 Splat 直接集成到 WebGPU 渲染图中的低级助手。

生命周期

const gs = new GaussianSplattingThreeWebGPU();
await gs.initialize(webgpuRenderer.backend.device);
await gs.loadPLY('/models/atrium.ply', p => console.log(p));

• initialize(device: GPUDevice): Promise<void> – 必须在任何加载或渲染之前调用。
• loadPLY(url: string, onProgress?: (info: { progress: number }))
• loadFile(file: File, onProgress?: (info: { progress: number }))
• setDepthEnabled(enabled: boolean) – 切换内部管道变体。
• setVisible(visible: boolean)
• render(commandEncoder: GPUCommandEncoder, textureView: GPUTextureView, camera: THREE.PerspectiveCamera, viewport: [number, number], depthView?: GPUTextureView): void – 更新相机适配器，运行 prepareMulti，并编码一个写入 textureView 的渲染通道。当需要网格遮挡时提供 depthView。
• numPoints: number (getter) – 返回当前加载的点云的总 Splat 计数。
• dispose() – 释放 GPU 引用。

---

CameraAdapter & DirectCameraAdapter

同一逻辑的两种变体：

适配器	位置	用例
DirectCameraAdapter	src/three-integration/GaussianSplattingThreeWebGPU.ts	与低级助手打包在一起。
CameraAdapter	src/camera/CameraAdapter.ts	在整个 Visionary 应用中复用（动态模型，编辑器）。

共享 API：

• update(camera: THREE.PerspectiveCamera, viewport: [number, number]): void
• viewMatrix(): mat4
• projMatrix(): mat4
• position(): Float32Array
• frustumPlanes(): Float32Array
• projection.focal(viewport?: [number, number]): [number, number]
• 标志位：transposeRotation, flipProjY, flipProjX, compensatePreprocessYFlip（很少更改；默认值适用于 WebGPU）。

这些适配器通过应用所需的 Y 轴 π 旋转、焦距推导和视口感知宽高比修复，使 Three.js 和 Visionary 保持同步。

---

GaussianModel

位于 src/app/GaussianModel.ts。扩展了 THREE.Object3D，因此编辑器可以将高斯资产放置在场景层次结构中。

主要特性：

• 自动 TRS → GPU 同步（通过拦截 setter 和节流 updateMatrix 覆盖）。
• syncTransformToGPU() / forceSyncToGPU() 用于手动控制。
• setGaussianScale, setOpacityScale, setCutoffScale, setKernelSize, setMaxShDeg 等，镜像了渲染器的逐模型 setter。
• 动态模型支持：update(viewMatrix: mat4, time?: number, projectionMatrix?: mat4) 驱动 ONNX 变形。
• 可见性助手（setModelVisible, getModelVisible, isVisible），动画控制（startAnimation, pauseAnimation, resumeAnimation, stopAnimation, setAnimationTime, setAnimationSpeed, setAnimationIsLoop）。
• AABB 工具：getLocalAABB, setOverrideAABB, getWorldAABB。

---

GridHelper

实用程序包装器（见 src/three-integration/GridHelper.ts），用于在 WebGPU 场景中生成一致的地面网格。

const helper = new GridHelper(10, 10, colorCenterLine, colorGrid);
scene.add(helper.object);
helper.dispose();

暴露 object: THREE.GridHelper 以及一个转发到底层 helper 的 dispose() 方法。

---

DebugHelpers

基于 WebGPU 的调试渲染类，用于在高斯 Splatting 场景中可视化轴、网格和基本几何体。

路径: src/three-integration/DebugHelpers.ts

constructor(device: GPUDevice)

使用提供的 WebGPU 设备创建一个新的 DebugHelpers 实例。

方法

• initialize(format: GPUTextureFormat): Promise<void> – 使用指定的纹理格式初始化调试助手。必须在渲染前调用。
• updateMatrices(viewMatrix: mat4, projMatrix: mat4): void – 更新用于渲染的视图和投影矩阵。
• render(passEncoder: GPURenderPassEncoder, options?: { showAxes?: boolean; showCube?: boolean; showCubeSolid?: boolean; showGrid?: boolean }): void – 将调试助手渲染到提供的渲染通道中。选项控制显示哪些助手。
• setVisible(visible: boolean): void – 控制所有调试助手的可见性。
• dispose(): void – 释放所有 GPU 资源。

用法

import { DebugHelpers } from './three-integration/DebugHelpers';

const debugHelpers = new DebugHelpers(device);
await debugHelpers.initialize(canvasFormat);

// 在渲染循环中
debugHelpers.updateMatrices(viewMatrix, projMatrix);
debugHelpers.render(renderPass, {
  showAxes: true,
  showGrid: true,
  showCube: false
});

---

ThreeJsCameraAdapter (旧版)

src/three-integration/ThreeJsCameraAdapter.ts 包含早于 CameraAdapter 的原始相机适配器。新代码应使用 CameraAdapter 或 DirectCameraAdapter，但保留该类是为了向后兼容。

---

使用示例 (Visionary 渲染循环)

const gaussianRenderer = new GaussianThreeJSRenderer(threeRenderer, scene, gaussianModels);
await gaussianRenderer.init();
scene.add(gaussianRenderer);

function animate(timeMs: number) {
  requestAnimationFrame(animate);

  gaussianRenderer.updateDynamicModels(camera, timeMs * 0.001);
  gaussianRenderer.renderOverlayScene(gizmoScene, camera);
  gaussianRenderer.renderThreeScene(camera);
  gaussianRenderer.drawSplats(threeRenderer, scene, camera);
}

animate(0);

对于需要直接控制命令编码器（没有 Visionary 外壳）的工具链，实例化 GaussianSplattingThreeWebGPU 并手动调用 render(...)，传入你自己的颜色/深度视图。

---

注意事项

1. 设备共享 – 该模块中的每个类都重用 THREE.WebGPURenderer 拥有的 GPU 设备。不会创建额外的画布。
2. 深度 – 自动深度模式默认开启。仅当你确实需要自定义遮挡物网格时才禁用它。
3. 坐标转换 – 始终通过 CameraAdapter/DirectCameraAdapter；在其他地方重复数学计算很容易导致渲染镜像。
4. 变换同步 – GaussianModel 自动处理 TRS 更新，但你可以针对批量编辑禁用自动同步（setAutoSync(false) → 变更 → forceSyncToGPU()）。
5. 动态内容 – 使用 ONNX/4D 资产时，updateDynamicModels 必须在 drawSplats 之前运行，以便点数据与当前相机保持同步。