2. Scene Objects & Interaction

In Visionary, object control focuses primarily on Data Model Control (rendering attributes and animation for Gaussian Splatting).

2.1 Gaussian Model Object (GaussianModel)

GaussianModel inherits from THREE.Object3D. It holds point cloud data through an internal ModelEntry and is responsible for synchronizing the Object3D transformation matrices to the GPU.

📎 Related Modules: The structure, AABB utilities, and sync mechanisms of GaussianModel are detailed in the 16-models module and its API reference.

2.1.1 Basic Transforms & Auto-Sync

GaussianModel implements an intelligent Auto-Sync mechanism. When you modify position, rotation, or scale, the model automatically detects these changes and updates the underlying splat data and rendering matrices in real-time in the background.

Therefore, you can manipulate the Gaussian model just like any ordinary Three.js mesh, without manually calling updateMatrix or any synchronization methods.

import { GaussianModel } from 'src/app/GaussianModel';

const gaussian_model = result.models[0]; // Type is GaussianModel

// 1. Modify attributes directly; system automatically detects and syncs to GPU
gaussian_model.position.set(0, 5, 0);
gaussian_model.rotation.y = Math.PI / 4;
gaussian_model.scale.setScalar(2.0);

// 2. Explicitly hide (Synchronizes control of Three.js and underlying renderer)
gaussian_model.setModelVisible(false);

Note: The scale property of GaussianModel controls the spatial scaling of the entire model; whereas GaussianScale (mentioned below) controls the inflation degree of individual particles.

2.1.2 Rendering Parameters (Visual Parameters)

You can choose between two equivalent control methods depending on whether you currently hold the Model Reference or the Model ID.

Core Parameter Table

Parameter Name	Model Method	Renderer Method (Requires ID)	Default	Description
Visibility	`setModelVisible(bool)`	`setModelVisible(id, bool)`	`true`	Controls rendering visibility
Particle Size	`setGaussianScale(num)`	`setModelGaussianScale(id, num)`	`1.0`	Adjusts Splat inflation to eliminate holes
Opacity	`setOpacityScale(num)`	`setModelOpacityScale(id, num)`	`1.0`	Global opacity multiplier
SH Degree	`setMaxShDeg(0-3)`	`setModelMaxShDeg(id, num)`	`3`	Spherical Harmonics degree
Cutoff Threshold	`setCutoffScale(num)`	`setModelCutoffScale(id, num)`	`1.0`	Particle culling threshold

📎 Related Modules: All renderer-side setModel*/updateDynamicModels APIs are defined inside GaussianThreeJSRenderer in the 12-three-integration module.

Method A: Object-Based

Most convenient when you get the model object directly from the loader (loadUnifiedModel) or hit an object via Raycaster.

import { GaussianModel } from 'src/app/GaussianModel';

// Assuming model is a GaussianModel instance
model.setGaussianScale(1.5); // Particles get larger
model.setMaxShDeg(3);        // Enable highest quality
model.setOpacityScale(0.8);  // Make transparent

Method B: Renderer-Based

Use the renderer interface when you only maintain a list of model IDs in the UI layer (e.g., model_0, model_1) or need batch management.

import { GaussianThreeJSRenderer } from 'src/app/GaussianThreeJSRenderer';

// GaussianThreeJSRenderer parses ID and proxies call to the model method
const modelId = "model_0";
renderer.setModelGaussianScale(modelId, 1.5);
renderer.setModelMaxShDeg(modelId, 3);

2.2 4D Animation Control

For dynamic 4D Gaussian Splatting (ONNX format), GaussianModel encapsulates complete timeline control logic.

📎 Related Modules: ONNX dynamic inference is handled by the 13-onnx module, and timeline plus batch animation management can be found in the 15-timeline module.

Playback Control

import { GaussianModel } from 'src/app/GaussianModel';
import { GaussianThreeJSRenderer } from 'src/app/GaussianThreeJSRenderer';

// Individual model control
model.startAnimation(1.0); // Play, speed 1.0x
model.pauseAnimation();    // Pause
model.stopAnimation();     // Stop and reset to zero

// Global control (via renderer)
renderer.startAllAnimations(1.0);
renderer.stopAllAnimations();

Timeline Fine-Tuning

In the render loop (animate), updateDynamicModels must be called to drive inference.

import { GaussianModel } from 'src/app/GaussianModel';
import { GaussianThreeJSRenderer } from 'src/app/GaussianThreeJSRenderer';

// Call every frame
renderer.updateDynamicModels(camera, currentTime);

// Manual parameter control
model.setAnimationTime(2.5);      // Jump to 2.5s
model.setTimeScale(0.5);          // Slow motion (Time flow speed)
model.setTimeOffset(1.0);         // Time offset (For staggering multiple models)
model.setAnimationIsLoop(true);   // Enable loop playback