Improve GSplat LOD system with geometric progression, FOV compensation, and budget balancing fixes

[mvaligursky]

Overhauls the GSplat LOD distance system and budget balancing for better visual quality and stability.

Changes:

• Replace linear lodDistances array API with geometric progression via lodBaseDistance and lodMultiplier — each LOD level transitions at lodBaseDistance * lodMultiplier^i
• O(1) logarithmic LOD index computation replacing O(n) linear distance search
• Add FOV compensation — wider FOV automatically shifts LOD boundaries to account for reduced screen-space detail
• Trigger LOD re-evaluation on camera FOV changes (≥2% threshold)
• Trigger LOD re-evaluation when lodBaseDistance or lodMultiplier change on the component
• Fix budget balancer monotonicity violations — upgrade path now stops immediately when a node can't be upgraded, preventing farther nodes from getting better quality than closer ones
• Add dynamic _budgetScale that uniformly shifts all LOD boundaries to bring initial estimates closer to the budget target, reducing balancer passes

API Changes:

• GSplatComponent.lodBaseDistance (new) — base distance for first LOD transition. Defaults to 5.
• GSplatComponent.lodMultiplier (new) — geometric ratio between successive LOD thresholds. Defaults to 3.
• GSplatComponent.lodDistances (removed) — calls Debug.removed() with migration instructions

Examples:

• All gsplat examples updated to use new lodBaseDistance/lodMultiplier API
• Splat budget controls changed from dropdown to continuous slider (0–10M, 0 = no limit)
• Added budget slider to lod-streaming-sh and lod-instances examples
• lod-streaming: reorganized UI with Camera panel (FOV, High Res)
• world: added Camera panel with Orbit toggle
• lod-instances: renamed "Colorize" to "Hue Animation"

Performance:

• LOD index computation reduced from O(n) linear search to O(1) logarithmic calculation
• Budget scale reduces number of balancer passes needed by bringing initial LOD estimates closer to target

Made with Cursor

[slimbuck]

exciting!

[Copilot]

Pull request overview

This PR modernizes the unified GSplat octree LOD system by moving from manually specified linear threshold arrays to a geometric progression model, adding FOV-aware LOD compensation, and improving budget enforcement behavior and convergence.

Changes:

• Replace lodDistances with lodBaseDistance + lodMultiplier, and compute LOD index in O(1) via logarithms (with FOV compensation).
• Improve global budget enforcement with monotonicity safeguards and a dynamic _budgetScale to reduce balancer passes.
• Update scripts/examples UI to use the new LOD API and add continuous budget/FOV controls.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/scene/gsplat-unified/gsplat-placement.js	Replaces stored LOD distance array with geometric parameters and adds a dirty flag for LOD re-evaluation.
src/scene/gsplat-unified/gsplat-octree-instance.js	Implements FOV-compensated, logarithmic LOD selection and wires component-driven LOD invalidation.
src/scene/gsplat-unified/gsplat-manager.js	Tracks camera FOV for LOD invalidation and adds dynamic _budgetScale to improve budget convergence.
src/scene/gsplat-unified/gsplat-budget-balancer.js	Adjusts budget balancing loops to stop upgrades earlier to avoid near/far quality inversions.
src/framework/components/gsplat/system.js	Updates component property wiring to the new lodBaseDistance / lodMultiplier API.
src/framework/components/gsplat/component.js	Adds new LOD properties, deprecates lodDistances, and forwards LOD changes to placements.
scripts/esm/gsplat/streamed-gsplat.mjs	Updates script attributes and component initialization to use lodBaseDistance.
examples/src/examples/gaussian-splatting/world.example.mjs	Updates example to new LOD API and switches budget control to a continuous slider model.
examples/src/examples/gaussian-splatting/world.controls.mjs	Adds camera orbit toggle and LOD/budget sliders.
examples/src/examples/gaussian-splatting/viewer.example.mjs	Tweaks default lodBehindPenalty for the viewer example.
examples/src/examples/gaussian-splatting/lod-streaming.example.mjs	Updates presets and UI wiring for geometric LOD parameters and budget slider.
examples/src/examples/gaussian-splatting/lod-streaming.controls.mjs	Adds camera FOV + LOD sliders and switches budget to continuous slider control.
examples/src/examples/gaussian-splatting/lod-streaming-sh.example.mjs	Updates presets and adds budget + geometric LOD controls.
examples/src/examples/gaussian-splatting/lod-streaming-sh.controls.mjs	Adds geometric LOD + budget sliders.
examples/src/examples/gaussian-splatting/lod-instances.example.mjs	Switches to budget slider and updates instances to new LOD API.
examples/src/examples/gaussian-splatting/lod-instances.controls.mjs	Renames “Colorize” to “Hue Animation” and adds budget slider.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.