2. 场景对象与交互 (Object & Interaction)
在 VisionaryCore 中，对象控制主要聚焦于 数据模型控制（针对 Gaussian Splatting 的渲染属性与动画）。
2.1 高斯模型对象 (GaussianModel)
GaussianModel 继承自 THREE.Object3D。它通过内部的 ModelEntry 持有点云数据，并负责将 Object3D 的变换矩阵同步给 GPU。
2.1.1 基础变换与自动同步 (Auto-Sync)
GaussianModel 实现了智能的 Auto-Sync 机制，当你修改 position、rotation 或 scale 时，模型会自动感知这些变化，并在后台实时更新底层的 splat 数据和渲染矩阵。
因此，你可以像操作任何普通的 Three.js 网格一样操作高斯模型，无需手动调用 updateMatrix 或任何同步方法。
import { GaussianModel } from 'src/app/GaussianModel';
const gaussian_model = result.models[0]; // 类型为 GaussianModel
// 1. 直接修改属性，系统会自动检测并同步到 GPU
gaussian_model.position.set(0, 5, 0);
gaussian_model.rotation.y = Math.PI / 4;
gaussian_model.scale.setScalar(2.0);
// 2. 显式隐藏 (同步控制 Three.js 和底层渲染器)
gaussian_model.setModelVisible(false);
注意：
GaussianModel的scale属性控制的是模型整体的空间缩放；而下文的GaussianScale控制的是每个粒子的膨胀程度。
2.1.2 渲染参数控制 (Visual Parameters)
您可以根据当前上下文持有的是 模型引用 还是 模型 ID，选择两种等效的控制方式。
核心参数表
| 参数名称 | 模型方法 | 渲染器方法 (需 ID) | 默认值 | 说明 |
|---|---|---|---|---|
| 可见性 | setModelVisible(bool) |
setModelVisible(id, bool) |
true |
控制渲染显隐 |
| 粒子尺寸 | setGaussianScale(num) |
setModelGaussianScale(id, num) |
1.0 |
调整 Splat 膨胀程度，消除空洞 |
| 透明度 | setOpacityScale(num) |
setModelOpacityScale(id, num) |
1.0 |
全局透明度乘数 |
| SH 等级 | setMaxShDeg(0-3) |
setModelMaxShDeg(id, num) |
3 |
球谐函数阶数 |
| 裁剪阈值 | setCutoffScale(num) |
setModelCutoffScale(id, num) |
1.0 |
粒子剔除阈值 |
方式 A：基于对象 (Object-Based)
当您从加载器 (loadUnifiedModel) 直接获取到模型对象，或者通过射线检测 (Raycaster) 命中对象时，直接调用最方便。
import { GaussianModel } from 'src/app/GaussianModel';
// 假设 model 是 GaussianModel 实例
model.setGaussianScale(1.5); // 粒子变大
model.setMaxShDeg(3); // 开启最高画质
model.setOpacityScale(0.8); // 变透明
方式 B：基于渲染器 (Renderer-Based)
当您在 UI 层只维护了模型列表的 ID（例如 model_0, model_1），或者需要批量管理时，使用渲染器接口。
import { GaussianThreeJSRenderer } from 'src/app/GaussianThreeJSRenderer';
// GaussianThreeJSRenderer 会解析 ID 并代理调用模型方法
const modelId = "model_0";
renderer.setModelGaussianScale(modelId, 1.5);
renderer.setModelMaxShDeg(modelId, 3);
2.2 4D 动画控制 (Animation)
对于动态 4D Gaussian Splatting (ONNX 格式)，GaussianModel 封装了完整的时间轴控制逻辑。
播放控制
import { GaussianModel } from 'src/app/GaussianModel';
import { GaussianThreeJSRenderer } from 'src/app/GaussianThreeJSRenderer';
// 单个模型控制
model.startAnimation(1.0); // 播放，速度 1.0x
model.pauseAnimation(); // 暂停
model.stopAnimation(); // 停止并归零
// 全局控制 (通过渲染器)
renderer.startAllAnimations(1.0);
renderer.stopAllAnimations();
时间轴精细调节
在渲染循环 (animate) 中，必须调用 updateDynamicModels 来驱动推理。
import { GaussianModel } from 'src/app/GaussianModel';
import { GaussianThreeJSRenderer } from 'src/app/GaussianThreeJSRenderer';
// 每一帧调用
renderer.updateDynamicModels(camera, currentTime);
// 手动控制参数
model.setAnimationTime(2.5); // 跳转到 2.5s
model.setTimeScale(0.5); // 慢放 (时间流逝速度)
model.setTimeOffset(1.0); // 时间偏移 (用于多模型错帧)
model.setAnimationIsLoop(true); // 开启循环播放