Skip to content

README.md

Latest commit

 

History

History
112 lines (76 loc) · 5.97 KB

README.md

File metadata and controls

112 lines (76 loc) · 5.97 KB
Raw

DecoupleGS

Interactive 3D Gaussian Splatting for End-to-End Autonomous Driving Testing

Unofficial, independent reimplementation of the ECCV 2026 paper

Paper Base License

Siying Li · Ying Ni · Jie Sun · Jian Sun · Haotian Shi
Original paper authors — this repository is not affiliated with or endorsed by them.

DecoupleGS cumulative module visualization

Static background, canonical insertion, real-SH rotation, opacity grounding, relighting, and contact shadow on a public HUGSIM/3DRealCar checkpoint.

Important

This is an independent reimplementation from the public paper and supplementary material, not the authors' code. It intentionally uses HUGSIM as a pinned submodule rather than copying or forking its repository. All DecoupleGS Python source is published directly in overlay/.

Overview

DecoupleGS separates a driving scene into a persistent static 3DGS background and independently controllable canonical vehicle assets. At runtime each vehicle is compressed, relit, registered to the map and road surface, transformed into the world frame, and composed with the background for one unified rasterization pass.

static background ─────────────────────────────────────────────┐
canonical assets → VQ decode → relight → SE(3) / SH rotation ─┼→ unified primitive stream
HD map + trajectory → DTW → SE(2) → opacity grounding ────────┘             │
                                                                            ▼
                                                             one CUDA rasterization
                                                                            │
                                                             UniAD / VAD closed loop

The implementation follows the disclosed settings: 30k background iterations, 20k vehicle iterations, 0.005 pruning threshold, 1024/512 codebooks, 0.99 EMA, five-pixel mask dilation, 27-D local SH probes, and a 2 Hz closed-loop policy update.

Visual results

Vehicle crop module comparison

The checked-in visual is generated from a public HUGSIM scene and 3DRealCar asset. It shows the cumulative effect of canonical insertion, SH rotation, opacity grounding, relighting, and contact shadows. The original HDRI supervision and target renderer are not public, so the relighting stage uses the documented public replacement calibration.

Implemented components

Paper component Implementation status
Object-centric canonical decomposition Implemented
Degree 0–3 real-SH Wigner-D rotation Implemented and equivariance-tested
Importance pruning + K-Means / EMA VQ Implemented
DTW + SE(2) Orthogonal Procrustes + grounding Implemented
Local SH probe + affine OLS relighting Implemented with a public replacement protocol
Parametric contact shadow Implemented
Unified static/dynamic rasterization Implemented on HUGSIM_splat
IDM/MOBIL background traffic Implemented
UniAD / VAD closed-loop evaluation Implemented

The paper's fused CUDA kernels and exact evaluation assets are unpublished. This reimplementation uses a one-call HUGSIM_splat path plus an independently developed static-stream cache and stable dynamic insertion path.

Quick start

git clone --recurse-submodules git@github.com:Functionhx/DecoupleGS.git
cd DecoupleGS

# Verify the pinned HUGSIM base and copy the complete DecoupleGS source overlay.
bash scripts/bootstrap_hugsim.sh

cd 3rdparty/HUGSIM
bash tools/setup_decouplegs_conda.sh YOUR_EXISTING_ENV decouplegs
conda activate decouplegs

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q tests
python tools/smoke_test_decouplegs_cuda.py

For a fresh environment, create environment-decouplegs.yml inside 3rdparty/HUGSIM first. The setup supports cloning an existing compatible Conda environment so cached packages and compiled dependencies are reused.

Reproduction coverage

The public replacement protocol was exercised on 20 3DRealCar assets, eight reconstructed nuScenes scenes, 1,296 temporally held-out re-insertion views, 400 strict closed-loop episodes, and dense runtime tests up to 50 dynamic agents. CPU numerical tests plus CUDA forward/backward and raster-equivalence smoke tests pass.

These results show that the released pipeline is executable end to end; they do not claim equivalence to the authors' private clips, HDRIs, vehicle identities, planner seeds, or unpublished fused kernels.

Repository layout

3rdparty/HUGSIM/             HUGSIM base, pinned as a Git submodule
overlay/                     complete DecoupleGS Python, configs, tools, and tests
scripts/bootstrap_hugsim.sh  validates the base commit and copies the overlay
artifacts/                   checked-in visual results for this implementation
METRICS.md                   paper-vs-reproduction metric notes

The implementation is ordinary source code, not a compressed patch. Browse overlay/decouplegs/, overlay/tools/, overlay/configs/, and overlay/tests/ directly on GitHub.

To apply it manually:

cp -a overlay/. 3rdparty/HUGSIM/

Data and dependencies

This repository does not redistribute nuScenes, PandaSet, SAM weights, planner weights, or 3DRealCar checkpoints. HUGSIM, 3DRealCar, nuScenes/PandaSet, SAM, MapTRv2, UniAD, and VAD remain their respective authors' projects and licenses.

Metric protocol and deliberate non-equivalent comparisons: METRICS.md.