splatreg

Register Gaussian splats: align and merge 3DGS scans into one SE(3)/Sim(3) frame.

---

gsplat renders your Gaussians; splatreg registers them. Two 3DGS scans of the same scene go in, one SE(3) or Sim(3) transform comes out, and (optionally) one fused, deduped splat. Pure PyTorch, no meshing, no CUDA extension, no point-cloud detour; works with anything that speaks the standard 3DGS PLY (gsplat, Nerfstudio, INRIA, SuperSplat) or hands over tensors.

What you get that no other splat registrar ships (each claim traced in Results and RESULTS.md):

• Provably correct SH rotation. When a recovered transform is baked in, the higher-order spherical-harmonic bands (f_rest) are mixed by the real-basis Wigner-D matrix, so glossy highlights turn with the splat instead of staying stuck in the old capture frame. Test-locked against an independent basis evaluator to ~2.4e-15 in float64 (tests/test_sh_rotation.py).
• Align WITHOUT merging. apply_transform() (and splatreg align) bakes the recovered pose into the source and writes it as its own PLY: both scans stay separate files, now in one frame, ready for any viewer or editor.
• Photometric refinement with per-pair exposure compensation and a coarse-to-fine render ladder, for the poses geometry cannot see (symmetry, texture-only DoF): 5°/7 mm down to 0.36°/0.5 mm on the real rasterizer.
• Pose covariance on every builtin-LM solve (info["information"] / info["covariance"]), so the result plugs straight into a pose graph with an honest weight, None when singular, never faked.
• MAC maximal-clique seed (init="mac", Zhang et al. CVPR 2023) for contaminated correspondence sets, with the honest measured verdict: a wash on official 3DMatch/3DLoMatch, a decisive win in the structured-decoy regime (78° failure vs <0.2°).
• Sim(3) scale recovery, which none of the competing splat tools attempt at all.

Install

pip install splatreg

# editable / dev
git clone https://github.com/Archerkattri/splatreg.git
cd splatreg
pip install -e ".[test]"

30-second quickstart

The 3-line merge (Python):

from splatreg.api import merge
from splatreg.io import load_ply, save_ply

fused = merge([load_ply("a.ply"), load_ply("b.ply")])   # register + fuse + dedupe
save_ply(fused, "fused.ply")                            # opens in SuperSplat / any viewer

Align without merging (both scans stay separate files, registered into one frame):

from splatreg.api import register, apply_transform
from splatreg.io import load_ply, save_ply

target, source = load_ply("a.ply"), load_ply("b.ply")
result = register(target, source, transform="sim3")     # init="fast" by default (~17 ms)
save_ply(apply_transform(source, result.T, result.scale), "b_aligned.ply")
# a.ply untouched; a.ply + b_aligned.ply now line up in any viewer.

result.T          # recovered 4x4 similarity [[s*R, t], [0, 1]], maps source -> target
result.scale      # recovered scale s (1.0 for transform="se3")
result.converged  # solver convergence flag
result.info       # diagnostics incl. pose information/covariance, ambiguity flag

Or entirely from the shell (standard 3DGS PLY in/out, composes with SuperSplat / gsplat / Nerfstudio exports; see the CLI guide):

splatreg align target.ply source.ply -o aligned.ply    # register + write the aligned source
splatreg merge a.ply b.ply -o fused.ply                # register + fuse + dedupe N splats
splatreg info x.ply                                    # count / bounds / SH degree / stats

Object pose and camera localization ride on the same core:

from splatreg import estimate_object_pose, localize_camera, coarse_localize_camera

result = estimate_object_pose(model_splat, observation_splat)    # ADD / ADD-S / AUC built in
result = localize_camera(scene_splat, frame, init_T_WC=T_init)   # needs splatreg[render]
T_coarse = coarse_localize_camera(scene_splat, frame)            # prior-free CPU seed

Capability matrix

Honest comparison against the tools people actually use for this job. The accuracy row is measured head-to-head on a real splat with known ground truth (RESULTS.md §5c); editor columns reflect their design (manual transforms, not registration).

	splatreg	splatalign	GaussianSplattingRegistration	SuperSplat / SplatTransform
Automatic splat-to-splat registration	yes (5 init modes)	ICP from identity	Open3D RANSAC+ICP	no (manual gizmo / user-given transform)
Measured rotation error, real splat + GT	5.2°	15.3°	36.3°	n/a
Sim(3) scale recovery	yes, native	no (SE(3) only)	no (SE(3) only)	manual
SH (f_rest) rotated with the splat	yes, test-locked	no	no	not in any splat registrar we know of
Merge + overlap dedupe	yes	no	no dedupe	concat only
Photometric refine (exposure comp + ladder)	yes	no	no	no
Pose covariance for pose graphs	yes	no	no	n/a
Honest ambiguity flag (never silent-wrong)	yes	no	no	n/a
Pure PyTorch library + CLI	yes	script	GUI	editor / CLI

Results

Every number is measured and reproducible; the provenance column points at the full record.

Benchmark	splatreg	reference	provenance
Real-splat merge (103k Gaussians)	Chamfer 10.3 → 2.0 mm (5.1×), overlap 0.03 → 0.67 (22×)	naive concat	RESULTS.md §5d, examples/merge_demo.py
Photometric refine (real rasterizer)	5°/7 mm → 0.36°/0.5 mm (~1.1 s)	geometric stage alone worsens the symmetric case 6.0°→11.2°	benchmarks/photometric_refine_results.md
Official 3DMatch recall (1279 pairs, Choi/Zeng protocol)	91.5% mean, 93.5% pooled	GeoTransformer ~92%, Open3D ~77%	RESULTS.md §5b
Official 3DLoMatch (hard, 10-30% overlap)	72.5% mean, 74.4% pooled	GeoTransformer ~74%, Open3D ~20%	RESULTS.md §5b
vs splat competitors (real splat, known GT Sim3)	5.2° (SE3), recovers scale (Sim3)	splatalign 15.3°, GS-Registration 36.3°	RESULTS.md §5c
Object pose (canonical YCB CAD, 14 models × 4 poses)	ADD-S AUC 0.995, 100% < 2 cm	n/a	RESULTS.md §5f-ycb
Camera localization (real splat, known perturbation)	median 5°/10 mm → 0.11°/1.35 mm	n/a	RESULTS.md §5g
Known-transform recovery	36/36 = 100% (GPU full grid); 6/6 CPU smoke in 41 s	n/a	RESULTS.md §1, §5j
Registration speed	~17 ms (fast init), 104 ms (learned)	GeoTransformer ~50 ms, Open3D 142 ms	RESULTS.md §5e
SH rotation correctness	rotated-coeff evaluation error ~2.4e-15 (float64)	n/a	tests/test_sh_rotation.py, RESULTS.md §5j
Exposure compensation	tinted-pair scale error 3.99% → 0.47% (clean: 0.01%, harmless)	no-compensation baseline	RESULTS.md §5j
Pose covariance	SPD when well-constrained, scales with noise, None when singular	n/a	tests/test_pose_covariance.py

Init modes: trade speed for robustness

init=	what	when
"fast" (default)	FPFH + GPU-batched RANSAC seed → closed-form LM	objects / full-overlap, ~17 ms
"robust"	Open3D FPFH+RANSAC seed → splatreg refine + scale	real metre-scale scans
"learned"	pretrained GeoTransformer seed → splatreg refine + scale	best accuracy on real scans
"mac"	MAC maximal-clique consensus (Zhang et al. CVPR 2023) → weighted SVD → refine	outlier-heavy / multi-consensus correspondence sets
"global"	blind super-Fibonacci SO(3) sweep	robust fallback, any rotation

The MAC verdict, stated honestly. init="mac" reimplements the MAC hypothesis generator (SC²-weighted rigidity graph → maximal cliques → weighted SVD per clique, with explicit caps) in pure torch + networkx (pip install "splatreg[mac]"). On synthetic contaminated sets (tests/test_mac.py) it matches the RANSAC engine at 30/60/90% random outliers and decisively wins the structured-decoy regime (RANSAC fails at ~78°, MAC stays <0.2°). Measured on the full official splits (same forward/voxel/refine, only the hypothesis stage differs) it is a wash, not a lift: 3DLoMatch 72.1/74.6 vs LGR's 72.5/74.4, 3DMatch 91.7/93.8 vs 91.5/93.5, every delta within ±4 pairs, at ~+50% runtime. GeoTransformer's native-voxel correspondences are already consensus-dominated, so the default stays seed_selector="lgr"; "mac" is the tool for genuinely contaminated correspondence sets (RESULTS.md §5k).

How it works

splatreg takes two splats and finds the rigid (SE(3)) or similarity (Sim(3), +scale) transform that aligns them, then optionally merges and dedupes them into one. It is the missing registration half of the Gaussian-splatting toolchain (the splat-to-splat alignment SuperSplat / INRIA / geospatial users keep asking for, where today's tooling punts to a manual gizmo).

flowchart LR
    A["splat A<br/>(target)"]:::s --> G
    B["splat B<br/>(source)"]:::s --> G
    G["<b>Global aligner</b><br/>super-Fibonacci SO(3) seeds<br/>+ batched trimmed ICP<br/><i>(or FPFH / learned / MAC)</i>"]:::g --> L
    L["<b>Levenberg-Marquardt</b><br/>multi-residual:<br/>ICP + Gaussian-SDF<br/>SE(3) / Sim(3)"]:::l --> T["T*  (4×4)<br/>+ merge / dedupe"]:::o
    classDef s fill:#e8f6f8,stroke:#17becf,color:#0b3d44;
    classDef g fill:#fff1ee,stroke:#ff6b5b,color:#5a1a12;
    classDef l fill:#eef7ee,stroke:#2e8b57,color:#143d22;
    classDef o fill:#f3eefc,stroke:#7d52c7,color:#2c1654;

Loading

1. Global init: a coarse pose from a dense super-Fibonacci rotation sweep + batched trimmed ICP (no local-minimum trap), with FPFH+RANSAC, learned (GeoTransformer), and MAC maximal-clique seeds for harder real scans.
2. Refinement: a from-scratch Levenberg-Marquardt core over ICP (point-to-point / point-to-plane) and splatreg's flagship Gaussian-SDF residual, solving the full SE(3) or Sim(3) tangent, with the pose information/covariance exposed at the optimum.

The Gaussian-SDF residual

No competitor packages this. splatreg derives a smooth signed-distance field directly from the target Gaussians (no mesh, no marching cubes) and drives registration by it:

w_i(p) = exp(−‖p − q_i‖² / 2σ²)              # Gaussian kernel weight per anchor
q̃(p)   = Σ w_i q_i / Σ w_i                    # kernel-weighted centroid
ñ(p)   = Σ w_i n_i / ‖Σ w_i n_i‖              # kernel-weighted surface normal
d(p)   = (p − q̃(p)) · ñ(p)                    # signed distance, the residual

d(p) vanishes exactly when source points land on the target surface. It has a closed-form, audited Jacobian and is a reusable primitive:

from splatreg.geometry.gaussian_sdf import gaussian_sdf, gaussian_sdf_grad
sdf, normal = gaussian_sdf(target, query_points, sigma=0.02)       # signed distance + normal
sdf, grad   = gaussian_sdf_grad(target, query_points, sigma=0.02)  # + exact ∇_p d

Validation

Every number is reproducible; full record in RESULTS.md.

python -m pytest tests/ -q                        # 143 passing
python tests/test_jacobians.py                    # analytic vs numerical Jacobian audit
python examples/validate_recovery.py --fast       # CPU smoke: 6/6 recovery in ~41 s
SPLATREG_DEVICE=cuda python examples/validate_recovery.py --device cuda   # 36/36 recovery
SPLATREG_DEVICE=cuda python benchmarks/robustness_bench.py --device cuda
python examples/merge_demo.py                     # real-splat merge demo

Limitations

splatreg is honest about its edges (full detail in RESULTS.md):

• Heavy overlap loss (keep ≤ 40%) is genuinely ambiguous. The rotation-disambiguating geometry is physically absent; even the true pose does not seat cleanly. The aligner flags these honestly (result.info['ambiguous'] / ['confidence']) and never silently wrong-poses. merge and track are designed for high-overlap captures.
• Scale is unobservable under thin overlap. Under ~20% shared geometry the Sim(3) scale residual valley is flat; the line-search tightens scale on its own objective but cannot recover what the geometry does not carry.
• Cost on rigid SE(3). Plain ICP reaches the same SE(3) success and is far faster; the SDF residual buys scale + implicit-field robustness at a real compute cost. Use track() (~17 ms/frame) for the warm-start real-time path.

Documentation

Full docs at https://archerkattri.github.io/splatreg/: quickstart, CLI guide, init modes (incl. the MAC verdict), photometric refinement (when and why, with the measured three-case table), PLY interop (splatfacto/INRIA/SuperSplat round-trip + the SH-under-rotation detail), benchmarks, and the API reference. Or run the Colab quickstart (CPU-only, no assets needed).

Citation

If splatreg is useful in your research, please cite it (see CITATION.cff; GitHub's "Cite this repository" button gives BibTeX/APA). The DOI is the Zenodo concept DOI and always resolves to the latest archived release:

@software{attri_splatreg,
  author  = {Attri, Krishi},
  title   = {splatreg: composable SE(3)/Sim(3) registration for 3D Gaussian Splatting},
  url     = {https://github.com/Archerkattri/splatreg},
  doi     = {10.5281/zenodo.20633466},
  version = {1.3.0},
  year    = {2026}
}

License & layout

BSD 3-Clause: permissive, composes with the gsplat / Theseus / GTSAM ecosystem. splatreg/ is the library (api, align, align_features, mac, sh, bundle, spatial_index, core/lie, geometry/gaussian_sdf, residuals/, solvers/lm, cli), plus tests/, benchmarks/, examples/, docs_site/. Full validation record: RESULTS.md.