git:20261015.2bf11c8 to git:20261018.1c54257

---

name: luxar-gsplat-pipeline

description: >-

Fit, calibrate, and build LOD for Gaussian splats with the Luxar CLI. Use when

a user wants to turn a 3D/nD volume (.zarr, .zarr.zip, .tiff, .npy, .npz) into a

.gsplats.zarr, choose the splat count K, build level-of-detail topologies for the

web viewer, run tiled fits on one GPU, or add a fitted gsplat node to a Luxar

scene from Python. Covers the canonical cal -> fit -> lod pipeline, the full

gsplat CLI option surface, and the Python fitting API. (For fitting a whole

multi-timepoint timelapse across many GPUs or a Slurm cluster, use the

luxar-hpc-batch-fit skill instead.)

---

# Luxar GSplat pipeline

Luxar fits **Gaussian splats** to scientific volumes and serves them to a WebGL

viewer. The standalone artifact is a `.gsplats.zarr` (format v3.4 — a node tree;

older v3.x files are still read transparently).

All commands below are subcommands of `luxar gsplat`.

## The canonical pipeline: cal -> fit -> lod

1. **`cal`** — pick the splat count `K*` in a principled way (blind-spot

cross-validation; reports K*, curve type, noise floor, PSNR ceiling).

2. **`fit`** — fit splats to the volume at the chosen `K*`.

3. **`lod`** — build a representation topology (LOD / partition) for the viewer.

```bash

# 1. Calibrate K (Noise2Self blind-spot sweep). Writes cal.json.

luxar gsplat cal volume.zarr cal.json --n-grid 5 --k-max 128000 # faster

# 2. Fit at the recommended K* (read K* from cal.json, or use a --preset).

luxar gsplat fit volume.tiff splats.gsplats.zarr --seeds <K*>

luxar gsplat fit volume.tiff splats.gsplats.zarr --preset standard --seeds 8000

luxar gsplat fit data.zarr.zip splats.gsplats.zarr --timepoint 0 --channel 0

# 3. Build a topology (--recipe is REQUIRED). See "Choosing a LOD recipe".

luxar gsplat lod splats.gsplats.zarr out.gsplats.zarr --recipe stream --n-lods 6

```

Presets: `draft` / `standard` / `hifi` / `ultra` / `n2s` (`n2s` = the manuscript's

blind-spot protocol, and `cal`'s default). Override any preset knob, e.g.

`--iters 8000`. Generate a config template with

`luxar gsplat fit --dump-config --preset hifi > config.yaml`, then `--config config.yaml`.

### Background floor suppression (`--floor`, default `auto`)

A constant pedestal (camera offset, autofluorescence) is the worst case for a

localized-Gaussian basis, so `fit`, `cal`, and `batch-fit` all subtract a

background floor (clip at 0) BEFORE normalization — output amplitudes are

therefore background-relative. `--floor` is ON by default (`auto`):

- `auto` — histogram-mode estimate, capped at the median (a no-op on clean data

with no pedestal).

- `pNN` — subtract that percentile of non-zero voxels, e.g. `--floor p10`.

- a plain number — subtract a fixed value, e.g. `--floor 110`.

- `none` or `0` — disable (legacy hard-min behaviour; use to reproduce old numbers

or when `auto` lands inside the specimen on a near-all-zero stack; see below).

`cal` applies the same `--floor` up front so K* is measured on floor-suppressed

data, matching how you fit.

**Stay on `auto` unless you have measured otherwise.** A `pNN` floor subtracts a

percentile of non-zero voxels, so on sparse data it lands wherever the sparsity

```bash

luxar gsplat fit volume.tiff out.gsplats.zarr # --floor auto (default, recommended)

luxar gsplat fit volume.tiff out.gsplats.zarr --floor p10 # subtract 10th percentile

luxar gsplat cal volume.tiff cal.json --floor none # legacy (no floor)

```

## Tuning a fit

### Scoring a fit

**`fit` already stamps the quality of the fit it just did** into `result.stats`

the input in raw units but on the fit's **background-relative basis**: the level

the fit actually subtracted (`image_min`: the resolved floor when suppression is

on, otherwise the data minimum or percentile endpoint) is removed and clipped,

while fit-time normalization is undone.

Reach for `compare` when scoring against a *different* reference than the volume

that was fitted — a denoised variant's untouched source, another arm's target:

```bash

luxar gsplat compare fitted.gsplats.zarr original.tiff --output-json metrics.json

```

### Scoring a STACKED or TRANSFORMED archive (read before `gsplat compare`)

Five separate wrong numbers were produced in one day by the same mistake:

### Denoising before a fit (`luxar gsplat denoise`, or your own filter)

### Symptom → knob

An index into the measured sections, not a substitute for them.

| Symptom | Reach for |

| --- | --- |

| Thin/faint structure missing | start with `--floor auto`, never a higher floor; on a near-all-zero stack also test `--floor none` — "Background floor suppression" above — then raise K |

| `compare` says a known-good archive is mediocre | you compared a stacked 4D store whole, or across a transform — "Scoring a STACKED or TRANSFORMED archive" |

| Noise survives a denoising pass that measured well | you measured displacement, not removal — "Denoising before a fit"; on isolated-voxel noise use a component-size filter |

| Thin filaments render as chains of beads | the six-knob schedule under "The Python API defaults to 1000 iters" below. NOT more seeds (measured *worse*), and NOT a preset: a preset moves `n_iters`, `early_stop_patience` and `max_eccentricity` — but nothing on this schedule, so `enable_dynamic_ops`, `patience` (the plateau LR-decay one, default 15, NOT `early_stop_patience`) and `l1_diag` all stay where they are and you must set them yourself |

| Blobby, over-smoothed detail | more K first, then a preset for iterations (early stopping makes a preset's `n_iters` a ceiling, so raise them when the loss is still falling at the cap) — but on thin structure read the beading row first |

| Result far bigger than needed | `decimate --target N` / `-f 0.1`, or `cull --target vol.npy -p 95` — not a lower `--cull-retention` and a refit |

| Boxy steps at tile boundaries | suspect the SOURCE (mosaic seams, coverage count), not the fit — measure the artefact's period first |

| First paint costs hundreds of requests | you picked a partition recipe on byte size — "First paint cost" under "Choosing a LOD recipe"; prefer `overview`, or raise `--max-elements` |

| Fit is slow, exploring | `--preset draft` (2,000 iters) for the search, one `hifi` run at the end |

## Traps that cost real time

Each of these has burned a whole fit cycle. Check them before you launch a long run.

- **`--seeds` is a whole-volume budget, but only for the CLI.** `luxar gsplat fit

--seeds K` divides K across the tiles it makes. The *Python* `fit_tiled_gsplats`

does NOT — an integer `seeds` there is handed to every tile unchanged, so N tiles

fit ~N × seeds splats. And `--tiling auto` is the DEFAULT, so a gigavoxel volume

- **`--cal` / `--k-star-ref` / `--feature-*` apply ONLY to `--tiling content`.**

Under `--tiling none|uniform` they are ignored — the CLI prints a `⚠ … apply only

to --tiling content` line, but in a long arbol log that scrolls past. The symptom

is a fit that lands at a few hundred splats when you asked for K* = 128,000,

because `seeds` silently fell back to `auto`. A `cal --auto-region` K* is

- **A/B two fits only at equal splat count.** Splat count dominates every quality

metric, so comparing a 1.4 M-splat variant against a 2.7 M-splat one measures the

count, not the variable you changed. Fix the seed budget on both arms.

- **Size VRAM for the per-splat intermediates, not the volume tensor.** A 3.2 Gvoxel

whole-volume fit asked for 95 GiB after the volume itself came to 12.9 GB. Tile it.

## Choosing a LOD recipe (`lod --recipe`)

Recipes are scale-ordered — pick by element count `N`, then check "First paint

cost" below, which overrides this ordering when first paint is request-constrained:

| Recipe | What it builds | Use when |

| --- | --- | --- |

| `flat` | single bare leaf, no LOD | tiny N / debug |

| `stream` | one leaf + additive prefix-sum ladder (fast first paint) | small/medium N |

| `levels` | coarse→fine substitutive replacement levels (zoom across scales) | medium/large N |

| `tiles` | spatial BSP parts, each culled + its own stream ladder | large N |

| `overview` | instant coarse substitutive cap + fine tiles branch | huge N |

| `adaptive` | BSP parts, each its own substitutive `levels` group | largest N |

`stream` is *additive* (progressively refines ONE leaf); `levels` is *substitutive*

(swaps a coarse level for a finer one as the object grows on screen). `overview` and

`adaptive` compose the two over spatial tiles.

### Scale-ordered is the wrong first question. Ask about the VIEW.

**Default to `stream`, and make anything costlier justify itself.** Element count

alone is a poor guide: a 128M-splat timelapse wants `stream`, while a 0.7M-splat

```bash

luxar gsplat lod in.gsplats.zarr out.gsplats.zarr --recipe stream --n-lods 6

luxar gsplat lod in.gsplats.zarr out.gsplats.zarr --recipe tiles --max-elements 250000

luxar gsplat lod in.gsplats.zarr out.gsplats.zarr --recipe overview -K 8 --max-elements 250000

luxar gsplat lod in.gsplats.zarr out.gsplats.zarr --recipe adaptive --parts 8 -K 4 -L 2

```

`stream` default method is `auto`: `greedy` (optimal at every prefix) at

N ≤ 5000, else the cheap O(N log N) `self_energy` for large N. Override with

`--coarsen-dims` lists center-column indices coarsening may merge over (the rest

become hard barriers — e.g. a time or channel axis must stay a barrier).

### First paint cost: choose on eager rungs, not on N

On a request-constrained host, recipe choice is driven by the rungs fetched before

first paint, not by element count or total tree nodes:

```

first-pass rungs = eager parts × 1 level × min(3, rungs per level)

converged rungs = eager parts × 1 level × rungs per level

requests ≥ eager rungs × arrays per rung (+ one per extra chunk)

```

A `kind=lod` group fetches only its default level; a `kind=partition` group fetches

every part. A cold stream pass commits two rungs and prefetches a third, but background

refinement drains the rest, so size hard limits against the converged count. The

loader derivation, selector thresholds, measured example, and exact `requestCount`

procedure are in

[references/first-paint-requests.md](references/first-paint-requests.md).

**On a node with a hidden dimension, count elements per SLICE, not per node.** A

ladder's rungs are sized against the whole node while the viewer draws one hidden

- **`overview` — ~3 eager rungs, independent of part count.** Its root is a

`kind=lod` whose fine partition defers behind a fills-screen selector. Crossing

it loads every fine part at once, so this saves opening-view requests, not total

session requests.

- **`tiles`, `adaptive` — every part is eager**, so ~3 × P rungs on the first pass.

The part factor buys frustum culling and, for `adaptive`, per-tile detail; pay it

when requests are not the binding limit.

- **`stream`, `levels` — one eager leaf/level at load**, but `levels` promotes on

frame 1 for typical whole-object framing, so do not assume its tree depth makes it

the cheapest opening view.

So when first paint is request-constrained: prefer `overview` over `adaptive`/`tiles`

at huge N, or raise `--max-elements` to cut the part count. At one part,

`adaptive`/`tiles` reduce to the cheap `levels`/`stream` shapes behind a partition

wrapper; use those recipes directly. Large byte size alone is not a reason to choose

`adaptive`.

## Tiled fits (large volumes)

```bash

luxar gsplat fit large.zarr out.gsplats.zarr --tiling uniform --tile-size 256 --overlap 32

# Parallel tiles on ONE GPU (no Slurm); -j auto accounts for GPU memory plus

# shared host RAM/CPU limits.

luxar gsplat fit large.zarr out.gsplats.zarr --tiling uniform --tile-size 256 -j 4

# Content-adaptive boxes (more splats where the volume is busy); needs a density.

luxar gsplat fit vol.zarr out.gsplats.zarr --tiling content --cal cal.json -j 8

# Per-part LOD AT FIT TIME (tiled partition only): stream -> tiles,

# levels -> adaptive. Avoids a separate `lod` pass (which rejects a partition).

luxar gsplat fit large.zarr out.gsplats.zarr --tiling uniform -j 4 --recipe stream --n-lods 6

```

## Whole-timelapse fitting at scale

## Inspect, compare, convert, edit

```bash

luxar gsplat info splats.gsplats.zarr # statistics

luxar gsplat render splats.gsplats.zarr out.npy --shape 128,128,128

luxar gsplat compare fitted.gsplats.zarr original.tiff # PSNR / SSIM / MSE

luxar gsplat napari splats.gsplats.zarr # inspect in napari

luxar gsplat view splats.gsplats.zarr # quick web viewer

luxar gsplat convert splats.gsplats.zarr scene.luxar.zarr --center # -> web scene

luxar gsplat cull in.gsplats.zarr out.gsplats.zarr --target vol.npy # error-budget cull

luxar gsplat filter in.gsplats.zarr out.gsplats.zarr --amplitude-min 0.1

luxar gsplat slice in.gsplats.zarr out.gsplats.zarr "0:50, :, 10:90"

luxar gsplat merge a.gsplats.zarr b.gsplats.zarr -o merged.gsplats.zarr

luxar gsplat partition in.gsplats.zarr part.gsplats.zarr --parts 4 --rule sah

luxar gsplat migrate-format legacy.gsplats.zarr v3.gsplats.zarr # legacy -> v3.4

```

## Python fitting API

For programmatic fitting (e.g. in a demo or notebook), import from `luxar.gsplats`:

```python

import numpy as np

from luxar.gsplats import fit_gaussian_splats, generate_seeds

volume = np.load("volume.npy").astype(np.float32) # any nD array

# Optional: generate seeds explicitly (else fit_gaussian_splats seeds internally).

seeds = generate_seeds(volume, method="auto", device="auto")

result = fit_gaussian_splats(

volume,

seeds=seeds, # int count | float ratio | ndarray centers | GSplatData | None

n_iters=5000, # presets are a CLI concept; set knobs directly here

lr=0.01,

loss_type="l1", # "l1" | "mse" | "poisson"

max_eccentricity=10.0,

device="cuda", # "auto" | "cpu" | "cuda" | "mps"

cull_retention=0.999, # post-fit cull; the function default

)

# result is a GSplatData: .centers (N,d), .amplitudes (N,), .cholesky_factors (N, d(d+1)/2), .stats

result.save("fitted.gsplats.zarr", ordering="hilbert")

```

### The Python API defaults to 1000 iters — BELOW `draft`. Always set a schedule.

`fit_gaussian_splats`'s `n_iters` defaults to **1000**: below the CLI's lowest preset

(`draft` = 2000) and a fifth of `standard` (5000). The CLI does NOT share it: with no

`--preset`, `load_fit_config` resolves the `standard` preset, so:

```bash

luxar gsplat fit vol.tiff out.gsplats.zarr # standard: 5000 iters

luxar gsplat fit vol.tiff out.gsplats.zarr --preset draft # 2000

```

**From Python, pass `n_iters` (and `early_stop_patience`) on every real fit.**

```python

result = fit_gaussian_splats(

volume,

n_iters=10_000, # 1000 leaves splats at their seed shape

patience=200, # 15 decays the shape LR away early

early_stop_patience=2000, # 300 stops before shapes settle

enable_dynamic_ops=False, # relocation RESETS splats to isotropic mid-fit

max_eccentricity=None, # 10.0 caps the axis ratio at sqrt(10)

l1_diag=0.0, # the default penalty pulls toward isotropy

)

```

## Add a fitted gsplat node to a Luxar scene

A `.gsplats.zarr` is a detached scene subtree; graft it into a scene three ways

(scene authoring API — see the `luxar-visualization` skill for the full scene flow):

```python

from luxar import LuxarZarrCompiler, Dimensions

with LuxarZarrCompiler("scene.luxar.zarr") as compiler:

scene = compiler.create_scene(dimensions=Dimensions.default_3d())

# (a) From a fitted file (auto-lowers multi-level LOD pyramids to a kind=lod group):

scene.add_gsplats_from_file("embryo", "fitted.gsplats.zarr")

# (b) From an in-memory fit result (GSplatData from fit_gaussian_splats):

scene.add_gsplats_from_data("embryo", result)

# (c) Fit in one step from a volume:

scene.add_gsplats_from_volume("embryo", volume, seeds=8000, n_iters=5000, device="cuda")

# (d) From raw arrays — cholesky_factors is the packed lower-triangular factor L

# of the COVARIANCE (Σ = L·Lᵀ); 3D = (N,6):

# [L00, L10, L11, L20, L21, L22]. Diagonal is scale-like:

# isotropic std σ -> [σ,0,σ,0,0,σ] (NOT 1/σ)

# This is the Group.add_gsplats / AdditiveSubLOD docstring contract.

scene.add_gsplats("trio", centers=c, amplitudes=a, cholesky_factors=L, colors=rgb)

```

The CLI shortcut `luxar gsplat convert fitted.gsplats.zarr scene.luxar.zarr --center`

## Notes

- **Full CLI option tables** (every flag for `fit` / `cal` / `lod`, defaults, and the

not shown above.

- The `lod` command **rejects an existing partition** — to add LOD to tiled output,

use `fit --recipe` / `batch-fit merge --recipe` (per-part LOD as it streams), or

`gsplat additive` to ladder every leaf of an existing tree structure-preservingly.

- LOD switch thresholds are auto-derived by SCREEN-AREA occupancy halving and

- See `docs/specs/GSPLATS_ZARR_FORMAT.md` for the v3.4 node-tree format.