cookbookcanonicalOWNER-2026-07-10

Cookbook — 3DGUT gs_config profile · cb-3dgut-config

Owner directive (2026-07-10), canonical. "Enhance the POD for Gaussian Splatting by implementing NVIDIA configuration" — citing nv-tlabs/3dgrut and the 3DGUT paper. [src: HOS-Instance/library/blueprints/bp-003-codeland-engine.md:34]

What 3DGUT / 3DGRUT are

3DGRUT is NVIDIA's research trainer-and-renderer for gaussian splatting: instead of the classic EWA affine projection it approximates each gaussian's screen footprint with an unscented transform (a small set of sigma points pushed through the true camera model), which lets it stay accurate under distorted lenses, fisheye, and rolling-shutter capture, and it pairs that projection with a ray-traced gaussian pass rather than a pure rasterizer. It is a CUDA/PyTorch application — it cannot run in a browser, and as third-party OSS it stays outside our runtime under the zero-OSS ruling. What we adopt is its configuration vocabulary and its interchange format: a gs_config block whose field names mirror 3DGRUT's config files, plus its standard 3DGS PLY export as an ingest path into our own gaussian-splatting pipeline. Reference: github.com/nv-tlabs/3dgrut and research.nvidia.com/labs/toronto-ai/3DGUT (consulted for field names only; no documentation text is copied). The block is authored per-biome and overridable per-holonprint, and is tunable in kernel-spatial-site's Lab surface (see bp-003-codeland-engine).

The three parameter domains

A gs_config block is not one knob-set — its keys act at three different stages, and a key that belongs to one stage is meaningless at another. Keeping them separate is what makes the block honest.

  1. Trainer-side (render.ut.*, render.particle_kernel_*, strategy.densify.*) — settings a real 3DGRUT run would consume: the unscented-transform weights (alpha, beta, kappa, in_image_margin_factor, require_all_sigma_points_valid), the particle kernel degree and response floor, the densify clone/split gradient thresholds. Our WebGL runtime has no unscented projection and no per-ray distorted camera, so it cannot execute these — but it records and validates them so a genome round-trips to a 3DGRUT run unchanged.
  2. Ingest-side (render.particle_kernel_min_response, strategy.prune.*, strategy.prune_scale.*, strategy.max_splats) — the prune / decimate rules our hand-rolled PLY-to-splat converter actually applies while baking a trained scene down into the 32-byte .splat record: drop splats below the alpha floor, drop below the density threshold, drop oversized splats, then importance-decimate to the splat budget for the tier.
  3. Runtime-side (spark.*) — the handful of parameters the WebGL rasterizer can honor live: max_std_dev (kernel cutoff, mapped to SparkRenderer maxStdDev), focal_adjustment, sort_radial, lod_splat_scale. These are the only keys the Lab's sliders move in real time. [src: HOS-Instance/packages/engine/src/engine/renderer.ts:44]

The PLY interop contract

3DGRUT — and any other 3DGS trainer — exports a standard gaussian-splatting PLY: per-vertex position, optional normals, f_dc_0..2 (SH DC term), optional f_rest_*, opacity, scale_0..2, rot_0..3. Our gen-3d --mode ply reads that layout with a hand-rolled reader (ascii + binary-little-endian headers, tolerant of missing normals / SH rest), converts each vertex to our packed form — colour from the SH DC term, alpha through a sigmoid, scale through exp, quaternion normalized — applies the ingest-side prune/decimate rules from gs_config, and writes the existing 32-byte .splat via the shared writer that spark-renderer already consumes. This is the photoreal path the biome directive asks for: a scene trained anywhere lands in our pipeline without a bespoke exporter.

The round-trip guarantee

The design rule that ties the three domains together: a parameter the runtime cannot honor is carried and validated, never silently dropped. The validator range-checks every key and rejects unknown keys inside gs_config, but it keeps the trainer-side settings intact even though Spark ignores them at render time. That way the same genome is both a live WebGL configuration and a faithful description of the 3DGRUT run that produced (or could reproduce) the scene — the round trip from trainer to browser and back loses nothing.

Composition

See also

Linked from — 2 cards