Skip to content

Utils Module

The Visionary Utils module collects the low-level building blocks the rest of the system depends on: mathematical primitives, IEEE‑754 float16 tooling, WebGPU instrumentation, and renderer bootstrap utilities. It replaces one-off helpers sprinkled across managers, IO, and renderer code with a cohesive toolkit that keeps Gaussian Splatting code compact and testable.

Module Overview

  • Location: src/utils/
  • Responsibilities: math helpers, float16/Spherical Harmonics packing, GPU buffer/debug tooling, renderer/environment setup helpers
  • Key Dependencies: gl-matrix, three/webgpu, WebGPU API

Directory Structure

src/utils/
├── index.ts                  # Public surface
├── aabb.ts                   # AABB primitive
├── camera-math.ts            # Camera/FOV conversions
├── transforms.ts             # Shared transform constants
├── gpu.ts                    # Buffer helpers, SH math, GPUStopwatch
├── half.ts                   # IEEE754 float16 + SH packing
├── vector-math.ts            # Vec3 helpers + plane fitter
├── env-map-helper.ts         # HDR/PMREM workflow for Three.js WebGPU
├── renderer-init-helper.ts   # Renderer cloning & environment bootstrapping
└── debug-gpu-buffers.ts      # Count-pipeline and shader buffer inspection

Capability Map

1. Math & Geometry Primitives

  • Immutable Aabb class for quick bounds queries
  • Camera math (deg2rad, fov2focal, focal2fov) shared by controllers and IO
  • VIEWPORT_Y_FLIP transform constant for renderer/view-matrix conventions
  • vector-math helpers (dot, add, normalize, planeFromPoints) reused by Gaussian loaders and layout tools

2. Float16 & SH Data Pipelines

  • High-accuracy f32_to_f16 / f16_to_f32 conversions with configurable rounding, FTZ, saturation, and legacy emulation
  • Batch packF16Array / unpackF16Array functions for ONNX tensors and GPU uploads
  • makeCopySH_PackedF16 that repacks PLY/ONNX f_dc_* / f_rest_* channels into the fixed 24×u32 layout consumed by WGSL shaders

3. GPU Instrumentation & Debugging

  • Bitwise align4 / align8 helpers guarantee legal copy/map sizes
  • readWholeBuffer, dumpU32, dumpHex, and keyToNum cover day-to-day debugging
  • GPUStopwatch uses timestamp queries for per-stage profiling
  • debug-gpu-buffers.ts exposes readGPUBuffer, compareBufferValues, and debugCountPipeline to trace ONNX inference counts all the way to shader uniforms
  • buildCov, sigmoid, shNumCoefficients, shDegreeFromNumCoeffs keep Gaussian math centralized

4. Renderer & Environment Helpers

  • EnvMapHelper wraps HDR loading, PMREM generation, tone-mapping sync, and renderer environment updates with defensive checks for post-build lifecycles
  • RendererInitHelper provides a single entry point to clone renderer settings, rebuild PMREM resources per renderer, and ensure the WebGPU backend/device is ready before using shared scenes

Typical Workflows

  1. Renderer Mirroring – Duplicate a production renderer for capture/preview without sharing GPU resources: 

    await RendererInitHelper.initializeRenderer(
  previewRenderer,
  previewScene,
  { sourceRenderer: liveRenderer, width, height }
);

  2. ONNX → Shader Count Verification – When debugging dynamic Gaussian inference, debugCountPipeline confirms the ONNX output buffer, ModelParams buffer, and shader storage stay in sync.

  3. HDR Environment Bootstrap – EnvMapHelper.loadHDRTexture + createPMREMEnvironmentMap convert .hdr files into tone-mapped scene.environment textures even when renderer.backend.device is not immediately available after build output loads.

Usage Highlights

// Camera utilities
import { deg2rad, fov2focal } from 'src/utils';
const vFov = deg2rad(60);
const focal = fov2focal(vFov, canvas.height);

// GPU performance instrumentation
const stopwatch = new GPUStopwatch(device, 32);
stopwatch.start(encoder, 'gaussian-pass');
// ... encode passes ...
stopwatch.stop(encoder, 'gaussian-pass');
stopwatch.end(encoder);
const timings = await stopwatch.takeMeasurements(device.queue);

// Renderer clone with fallback HDR
const { envMap } = await RendererInitHelper.initializeRenderer(
  captureRenderer,
  captureScene,
  { fallbackHdrUrl: '/public/textures/hdr/daytime.hdr' }
);
EnvMapHelper.setupSceneEnvironment(captureScene, envMap, null);

// Plane fit for camera auto-leveling
const { centroid, normal } = planeFromPoints(sampledPoints);
if (normal) {
  console.log('Scene up vector', normal);
}

Integration Notes

  • Managers reuse renderer helpers to spin up dedicated preview renderers without touching global state.
  • IO / FileLoader delegates float16 packing and spherical harmonics layout to half.ts, guaranteeing bit-identical GPU buffers across formats (PLY, SPZ, KSplat, ONNX).
  • Renderer / Controllers depend on camera math, Aabb, and Gaussian covariance helpers whenever camera rigs or instancing buffers change.
  • Diagnostics surfaces consume debug-gpu-buffers utilities for field debugging without bringing in heavy tooling.

Reliability & Performance Practices

  • Pre-allocated typed array views avoid churn during float16 conversion.
  • Every GPU readback helper enforces 4/8 byte alignment and destroys staging buffers immediately.
  • Renderer helpers guard against partially constructed WebGPU backends using explicit device/PMREM checks plus microtasks to let the backend flush.
  • Plane fitting and Gaussian math functions reject non-finite inputs early to prevent NaNs propagating into WGSL storage buffers.

The Utils module is therefore the shared toolbox for Visionary: whenever you need math, packing, GPU timing, or renderer bootstrap glue, you get a battle-tested helper instead of ad-hoc code.

  • Architecture – Breakdown of helper categories, float16 pipelines, and GPU tooling design.
  • API Reference – Function-by-function documentation covering math, buffers, and debug helpers.
  • IO Module – Shows where float16/SH packing helpers are consumed during loading.
  • Renderer Module – Demonstrates how renderer bootstrap utilities are applied.
  • Managers Module – Highlights how App managers reuse the shared tooling surface.