App 模块

App 模块作为 3D 高斯泼溅 (Gaussian Splatting) WebGPU 查看器的核心协调器。它实现了 基于管理器的架构 (Manager-based Architecture)，以解耦加载、渲染、动画和用户交互逻辑。该模块管理完整的应用程序生命周期，从初始化到渲染，并协调所有其他模块，包括 WebGPU 上下文管理、UI 交互和渲染管线编排。

模块概览

路径: src/app/
目的: 应用程序生命周期管理和 UI 协调
依赖: renderer, point_cloud, camera, controls, io 模块

核心组件

组件	文件	目的
`App`	`app.ts`	主应用程序类和生命周期协调器
`ModelManager`	`managers/model-manager.ts`	数据所有权和模型跟踪
`FileLoader`	`managers/file-loader.ts`	统一资源加载器 (PLY, SPZ, KSplat, SPLAT, SOG, Compressed PLY, ONNX, FBX)
`ONNXManager`	`managers/onnx-manager.ts`	动态 ONNX 模型管理
`CameraManager`	`managers/camera-manager.ts`	相机和控制器管理
`AnimationManager`	`managers/animation-manager.ts`	动态内容更新
`RenderLoop`	`managers/render-loop.ts`	帧周期和渲染协调
`WebGPUContext`	`webgpu-context.ts`	WebGPU 初始化和上下文管理
`UIController`	`ui-controller.ts`	用户交互和事件处理
`DOMElements`	`dom-elements.ts`	DOM 元素引用和工具

快速开始

基本用法

import { App } from './src/app';

// 创建并初始化应用程序
const app = new App();
await app.init();

// 加载高斯模型 (支持多种格式)
await app.loadGaussian('model.ply');
// 或者
await app.loadGaussian('model.spz');
await app.loadGaussian('model.ksplat');
await app.loadGaussian('model.splat');
await app.loadGaussian('model.sog');

// 加载用于动态推理的 ONNX 模型
await app.loadONNXModel('./models/dynamic.onnx', 'Dynamic Model', false);

应用程序初始化流程

DOM 设置 - 通过 DOMElements 查询并缓存所有必需的 DOM 元素
管理器初始化 - 创建所有管理器实例 (Model, File, ONNX, Camera, Animation, RenderLoop)
ORT 环境 - 初始化 ONNX Runtime 环境
WebGPU 上下文 - 使用 ORT 集成初始化 WebGPU 设备 (带回退机制)
渲染器创建 - 使用 GPU 资源设置高斯渲染器
相机设置 - 使用默认设置初始化透视相机
UI 绑定 - 为用户交互附加事件监听器
渲染循环 - 启动主动画帧循环

关键特性

文件加载

多种格式: 支持 PLY, SPZ, KSplat, SPLAT, SOG, compressed PLY, ONNX, 和 FBX
拖放: 直接从文件系统加载文件
示例文件: 通过 loadSample() 预加载演示文件
进度跟踪: 带有 UI 反馈的实时加载进度
错误处理: 全面的错误消息和恢复机制
格式检测: 通过 detectGaussianFormat() 自动检测格式

相机控制

多种控制器: 通过 switchController() 切换轨道 (Orbit) 和第一人称 (FPS) 相机模式
鼠标导航: 左键旋转，右键平移
滚动缩放: 鼠标滚轮控制相机距离
键盘输入: 集成控制器的 WASD 移动
重置功能: 一键重置相机位置
自动取景: 针对点云自动设置相机

渲染控制

高斯缩放: 通过 setGaussianScale() 实时调整高斯点大小
背景颜色: 通过 setBackgroundColor() 自定义场景背景
性能统计: FPS 监控和点数显示
响应式视口: 自动调整画布大小
多模型渲染: 支持多个并发模型

WebGPU 管理

ORT 集成: 与 ONNX Runtime 共享 WebGPU 设备
特性检测: 自动检查 WebGPU 能力
上下文配置: 最佳 GPU 上下文设置与回退机制
错误恢复: 针对不支持浏览器的优雅回退
资源管理: 高效的 GPU 内存处理

动态模型

ONNX 支持: 加载并运行 ONNX 模型以生成动态点云
实时推理: 针对动态内容的每帧 GPU 推理
动画控制: 启动、暂停、恢复和停止动态动画
性能跟踪: 监控推理性能指标

架构

App 模块使用 基于管理器的架构，其中 App 类作为协调专门管理器的外观 (Facade)：

┌─────────────────────────────────────────┐
│              App (Facade)               │  ← 主协调器
├─────────────────────────────────────────┤
│  UIController  │  DOMElements          │  ← UI 层
│  WebGPUContext │  GaussianRenderer      │  ← 渲染层
└────────────────┬────────────────────────┘
                 │ 委托给 (delegates to)
┌────────────────┴────────────────────────┐
│           管理器层 (Manager Layer)       │
├─────────────────────────────────────────┤
│  ModelManager      │  FileLoader        │  ← 数据管理
│  ONNXManager       │  CameraManager     │  ← 动态与视图控制
│  AnimationManager  │  RenderLoop        │  ← 更新与渲染周期
└─────────────────────────────────────────┘
                 │ 使用 (uses)
┌────────────────┴────────────────────────┐
│         核心子系统 (Core Subsystems)     │
├─────────────────────────────────────────┤
│  PointCloud / DynamicPointCloud         │
│  GaussianRenderer                       │
│  IO Module (defaultLoader)              │
└─────────────────────────────────────────┘

有关详细的设计决策，请参阅架构指南。

使用示例

自定义初始化

import { App } from './src/app';

const app = new App();

// 带有错误处理的自定义初始化
try {
  await app.init();
  console.log('Application started successfully');

  // 编程式加载模型
  await app.loadGaussian('path/to/model.ply');
} catch (error) {
  console.error('Failed to initialize:', error);
}

加载不同格式

// 加载 PLY 格式
await app.loadGaussian('model.ply');

// 加载 SPZ 格式
await app.loadSPZ('model.spz');

// 加载 KSplat 格式
await app.loadKSplat('model.ksplat');

// 加载 SPLAT 格式
await app.loadSplat('model.splat');

// 加载 SOG 格式
await app.loadSOG('model.sog');

// 加载 ONNX 模型 (静态推理)
await app.loadONNXModel('./models/model.onnx', 'Model Name', true);

// 加载 ONNX 模型 (动态每帧推理)
await app.loadONNXModel('./models/dynamic.onnx', 'Dynamic Model', false);

访问管理器

// 获取管理器实例以用于高级用法
const modelManager = app.getModelManager();
const cameraManager = app.getCameraManager();
const onnxManager = app.getONNXManager();
const animationManager = app.getAnimationManager();
const renderLoop = app.getRenderLoop();

// 获取调试信息
const debugInfo = app.getDebugInfo();
console.log(debugInfo);

浏览器兼容性

Chrome/Edge: 113+ (完整 WebGPU 支持)
Firefox: 需要启用 WebGPU 的 Nightly 版本
Safari: 需要 WebGPU 实验性功能

性能考量

内存使用: 随点云大小扩展 (最高支持 1600万点)
GPU 要求: 大型数据集建议使用独立 GPU
画布分辨率: 自动适应设备像素比
帧率: 目标 60fps，带动态质量调整

错误处理

App 模块包含全面的错误处理：

WebGPU 不可用: 显示包含浏览器建议的回退消息
文件加载错误: 在模态对话框中显示具体错误消息
GPU 内存限制: 带有用户反馈的优雅降级
渲染器故障: 带有错误报告的恢复机制

开发说明

管理器架构: 职责被分离到专门的管理器中，以实现更好的模块化
状态管理: 集中在 AppState 接口 (RenderLoop) 中的应用程序状态
事件系统: 通过 UICallbacks 的基于回调的 UI 交互系统
资源清理: 适当的 GPU 资源生命周期管理
性能监控: 内置 FPS 和内存使用跟踪
格式支持: 使用 IO 模块中的 defaultLoader 进行统一格式处理
ORT 集成: 与 ONNX Runtime 共享 WebGPU 设备，以实现高效的 GPU 使用