Manager API 参考

本文档汇总了所有 Manager 类的公共 API。

ModelManager

维护每个已加载的模型，并提供用于模型存储、跟踪和查询的统一接口。

constructor(maxModels: number = 10000)

关键方法

模型管理:

addModel(model: Omit<ModelEntry, 'id'>): ModelEntry – 添加一个模型并生成唯一 ID。如果达到容量限制则抛出错误。
removeModel(id: string): boolean – 通过 ID 移除模型。
clearAllModels(): void – 移除所有模型。

模型查询:

getModels(): ModelInfo[] – 返回简化的元数据（便于 UI/React 渲染安全使用）。
getFullModels(): ModelEntry[] – 返回包含完整 pointCloud 引用的所有模型条目。
getModelWithPointCloud(modelType: 'ply' | 'onnx' | 'fbx', id?: string): ModelEntry | null – 获取特定的模型条目。
getModelsByType(modelType: 'ply' | 'onnx' | 'fbx'): ModelEntry[] – 按类型获取模型。
getVisibleModels(): ModelEntry[] – 仅获取可见模型。
getDynamicModels(): ModelEntry[] – 仅获取动态模型。
findModelByName(name: string): ModelEntry | null – 通过名称查找模型（首个匹配项）。

统计信息:

getModelCount(): number – 获取模型总数。
getRemainingCapacity(): number – 获取剩余模型容量。
getTotalPoints(): number – 获取所有模型的总点数。
getTotalVisiblePoints(): number – 获取总可见点数。
isAtCapacity(): boolean – 检查是否达到模型上限。

可见性:

setModelVisibility(id: string, visible: boolean): boolean – 设置模型可见性。

变换:

旧版方法（不推荐）: 这些方法通过分别设置位置、旋转、缩放来操作变换，内部会组合成变换矩阵。它们是为了向后兼容而保留的早期 API。

setModelPosition(id: string, x: number, y: number, z: number): boolean – 设置模型位置（旧版，通过 TRS 组合创建变换矩阵）。
getModelPosition(id: string): [number, number, number] | null – 获取模型位置（从变换矩阵中提取）。
setModelRotation(id: string, x: number, y: number, z: number): boolean – 设置模型旋转（旧版，受限，仅支持欧拉角）。
getModelRotation(id: string): [number, number, number] | null – 获取模型旋转（旧版，受限，从矩阵提取欧拉角可能不准确）。
setModelScale(id: string, scale: number | [number, number, number]): boolean – 设置模型缩放（旧版，受限）。
getModelScale(id: string): [number, number, number] | null – 获取模型缩放（旧版，受限，从矩阵提取缩放可能不准确）。

推荐方法: 直接操作变换矩阵，这是更现代、更灵活、更准确的方式。

setModelTransform(id: string, transform: Float32Array | number[]): boolean – 直接设置完整的 4×4 变换矩阵（推荐）。
getModelTransform(id: string): Float32Array | null – 获取完整的 4×4 变换矩阵（推荐）。

名称管理:

hasModelWithName(name: string): boolean – 检查模型名称是否存在。
generateUniqueName(baseName: string): string – 基于基础名称生成唯一名称。

FileLoader

加载并解析多种高斯格式（PLY, SPZ, KSplat, SPLAT, SOG, Compressed PLY）和 FBX 文件。

constructor(modelManager: ModelManager, callbacks: LoadingCallbacks)

关键方法

加载:

loadFile(file: File, device: GPUDevice): Promise<ModelEntry | null> – 从 File 对象加载。自动检测格式（Gaussian 或 FBX）。
loadSample(filename: string, device: GPUDevice, expectedType?: string): Promise<ModelEntry | null> – 从 URL 加载。支持所有高斯格式。

格式检测:

isFileTypeSupported(filename: string): boolean – 检查文件格式是否受支持。
getSupportedExtensions(): string[] – 返回所有受支持的文件扩展名。
getFileType(filename: string): string | null – 从文件名检测文件类型。
getGaussianFormat(filename: string): string | null – 获取特定的高斯格式（ply, spz, ksplat 等）。

支持的格式:

Gaussian: .ply, .spz, .ksplat, .splat, .sog, .compressed.ply
Mesh: .fbx
注意: ONNX 文件应通过 ONNXManager 加载，而不是 FileLoader。

ONNXManager

加载 ONNX 模型并管理动态点云的 GPU 端推理。

constructor(modelManager: ModelManager)

关键方法

加载:

loadONNXModel(device: GPUDevice, modelPath: string, cameraMatrix: Float32Array, projectionMatrix: Float32Array, name?: string, options?: ONNXLoadOptions): Promise<ModelEntry> – 加载 ONNX 模型并创建 DynamicPointCloud。
loadONNXFromFile(device: GPUDevice, file: File, cameraMatrix?: Float32Array | null, projectionMatrix?: Float32Array | null): Promise<ModelEntry> – 从 File 对象加载 ONNX。

管理:

disposeModel(modelId: string): void – 清理 GPU 缓冲区和 ORT 会话。
dispose(): void – 销毁所有 ONNX 模型。

相机更新:

updateCameraMatrices(modelName: string, cameraMatrix: Float32Array, projectionMatrix: Float32Array): Promise<void> – 更新用于 ONNX 推理的相机矩阵。

查询:

hasONNXModels(): boolean – 检查是否加载了任何 ONNX 模型。
getONNXModels(): ModelEntry[] – 返回所有 ONNX 模型条目。
getGenerator(id: string): ONNXGenerator | undefined – 通过模型 ID 获取 ONNXGenerator。
getPointCloud(id: string): DynamicPointCloud | undefined – 通过模型 ID 获取 DynamicPointCloud。

性能:

getONNXPerformanceStats(): { modelCount: number; totalGenerators: number; totalPointClouds: number } – 返回性能统计信息。

CameraManager

初始化并更新活动相机/控制器。

constructor()

关键方法

initCamera(canvas: HTMLCanvasElement): void
switchController(type: 'orbit' | 'fps'): void
update(deltaTime: number): void
resize(canvas: HTMLCanvasElement): void
resetCamera(): void
getCameraMatrix(): mat4
getProjectionMatrix(): mat4
getController(): CameraController
setupCameraForPointCloud(pointCloud: PointCloud): void
setOrbitCenter(center: vec3): void
getDebugInfo(): any
getControllerType(): ControllerType
getCamera(): PerspectiveCamera | null
getPosition(): vec3
getRotation(): quat
setPosition(position: vec3): void
setRotation(rotation: quat): void
getViewMatrix(): mat4
getViewProjectionMatrix(): mat4
getFrustumPlanes(): Float32Array
isControllerType(type: ControllerType): boolean

AnimationManager

每帧更新动态模型。

constructor(modelManager: ModelManager)

关键方法

updateDynamicPointClouds(view: mat4, proj: mat4, time: number): void
controlDynamicAnimation(action: 'start' | 'pause' | 'resume' | 'stop', speed?: number): void
setDynamicAnimationTime(time: number): void
getDynamicPerformanceStats(): Array<{ modelName: string; stats: any }>
getDebugInfo(): any
getAnimationStats(): AnimationStats
setDebugLogging(enabled: boolean): void
getLastUpdateTime(): number
getUpdateCount(): number
getTotalUpdateTime(): number
getAverageUpdateTime(): number
forceUpdate(): void

RenderLoop

拥有渲染/更新循环、帧调度和性能跟踪。

constructor(modelManager: ModelManager, animationManager: AnimationManager, cameraManager: CameraManager)

关键方法

生命周期:

init(gpu: WebGPUContext, renderer: GaussianRenderer, canvas: HTMLCanvasElement): void – 使用 GPU 上下文和渲染器进行初始化。
start(): void – 启动渲染循环。
stop(): void – 停止渲染循环。
isRunning(): boolean – 检查循环是否正在运行。

渲染状态:

setGaussianScale(scale: number): void – 设置全局高斯缩放。
getGaussianScale(): number – 获取当前高斯缩放。
setBackgroundColor(color: [number, number, number, number]): void – 设置背景颜色。
getBackgroundColor(): [number, number, number, number] – 获取当前背景颜色。

回调:

setCallbacks(callbacks: FPSCallbacks): void – 设置 FPS 和点数更新回调。

状态 & 性能:

getState(): AppState – 获取当前渲染状态。
getPerformanceInfo(): object – 返回性能信息。
getFPS(): number – 获取当前 FPS。
getFrameCount(): number – 获取总帧数。
getLastFrameTime(): number – 获取上一帧时间（毫秒）。
getAverageFrameTime(): number – 获取平均帧时间。
setTargetFPS(fps: number): void – 设置目标 FPS（用于节流）。
getTargetFPS(): number – 获取目标 FPS。
getDebugInfo(): any – 返回调试信息。

GaussianLoader

高级便捷服务，结合了 FileLoader 和 ONNXManager 来构建 GaussianModel 实例。简化了与 Three.js 集成时的模型加载。

constructor(fileLoader: FileLoader, onnxManager: ONNXManager)

GaussianLoadOptions

interface GaussianLoadOptions {
  name?: string;
  onnxOptions?: ONNXLoadOptions;
}

关键方法

特定格式创建:

createFromPLY(renderer, modelPath, options?): Promise<GaussianModel> – 从 PLY 文件创建。
createFromSPZ(renderer, modelPath, options?): Promise<GaussianModel> – 从 SPZ 文件创建。
createFromKSplat(renderer, modelPath, options?): Promise<GaussianModel> – 从 KSplat 文件创建。
createFromSplat(renderer, modelPath, options?): Promise<GaussianModel> – 从 SPLAT 文件创建。
createFromSOG(renderer, modelPath, options?): Promise<GaussianModel> – 从 SOG 文件创建。
createFromGaussian(renderer, modelPath, options?, formatHint?): Promise<GaussianModel> – 从任何高斯格式创建（自动检测）。

ONNX 创建:

createFromONNX(renderer, modelPath, cameraMatrix, projectionMatrix, options?): Promise<GaussianModel> – 从 ONNX 模型创建。

自动检测:

createFromFile(renderer, modelPath, cameraMatrices?, options?, fileType?): Promise<GaussianModel> – 自动检测格式并创建模型。

实用工具:

createFromEntry(entry: ModelEntry): GaussianModel – 从现有的 ModelEntry 创建。
isFormatSupported(filename: string): boolean – 检查格式是否受支持。
getSupportedFormats(): string[] – 获取所有支持的格式。
detectFormat(filename: string): string | null – 从文件名检测格式。

FBXLoaderManager

加载 FBX 文件并将其注册到 ModelManager。

constructor(modelManager: ModelManager, callbacks?: FBXLoaderCallbacks)

interface FBXLoaderCallbacks {
  onProgress?: (progress: number, message: string) => void;
  onError?: (error: string) => void;
  onSuccess?: (model: ModelEntry) => void;
}

关键方法

loadFromFile(file, options?): Promise<ModelEntry>
loadFromUrl(url, options?): Promise<ModelEntry>
dispose(): void

注意: FBX + WebGPU 兼容性有限；推荐使用 GLTF/GLB。

支持类型 (Supporting types)

interface ModelInfo {
  id: string;
  name: string;
  visible: boolean;
  pointCount: number;
  isDynamic: boolean;
  modelType: 'ply' | 'onnx' | 'fbx';
  colorMode?: 'sh' | 'rgb';
  colorChannels?: number;
}

interface LoadingCallbacks {
  onProgress: (show: boolean, text?: string, pct?: number) => void;
  onError: (msg: string) => void;
}

interface ONNXLoadOptions {
  staticInference?: boolean;
  debugLogging?: boolean;
}

interface FPSCallbacks {
  onFPSUpdate: (fps: number) => void;
  onPointCountUpdate: (count: number) => void;
}

interface AppState {
  background: [number, number, number, number];
  gaussianScale: number;
  animationId: number;
  lastTime: number;
  frames: number;
  fpsAccumStart: number;
}

interface AnimationStats {
  updateCount: number;
  totalUpdateTime: number;
  averageUpdateTime: number;
  totalDynamicModels: number;
  activeDynamicModels: number;
}

type ControllerType = 'orbit' | 'fps';

interface LoadProgress {
  stage: string;
  progress: number;
  message?: string;
}