CityGaussian: large-scale 3DGS reconstruction on the Gaussian Lightning codebase

The problem CityGaussian targets: city-scale scenes that do not fit one GPU

Standard 3D Gaussian Splatting assumes a scene small enough that every Gaussian can be held and optimised on one device. Aerial or street-level captures of a campus, a district or a whole city break that assumption twice: the point budget grows past what a single card can hold, and the optimisation loop becomes slow enough that iteration is impractical. CityGaussian is the official implementation of two papers aimed at exactly that scale, CityGaussian (ECCV 2024) and CityGaussianV2 (ICLR 2025). The README lists the intended audience implicitly through its features: multi-GPU reconstruction with controllable memory cost, model partition and data assignment analysis, and geometric evaluation of large scenes. This is a research codebase for people who already have a COLMAP-style capture of a large area and want to train and render it, not a library you drop into an application. The README's own scene table covers LFLS, SMBU, Upper Campus and MatrixCity Aerial and Street, which tells you the expected input is a multi-view capture of a real place rather than a single object.

How the reconstruction pipeline is put together

The main branch has been rebased onto Gaussian Lightning v0.10.1, so the architecture is not CityGaussian's own training loop. It is a Lightning-based framework that CityGaussian extends. The pyproject.toml declares the distribution name gaussian-splatting-lightning and exposes console entry points rather than a single script: gs-fit, gs-val, gs-test and gs-predict for the standard Gaussian path, segany-fit, segany-val, segany-test and segany-predict for the segmentation-related path, and gs-viewer for the web viewer. That split is the clearest architectural signal in the repository: fitting, validation, testing and prediction are separate commands, and the viewer is a separate process. The CityGaussian-specific contribution sits on top of that, in the multi-GPU partition and assignment logic and in the mesh extraction and trajectory-aligned rendering described in the feature list. Because the repository is a Jupyter Notebook project by primary language, a meaningful part of the visible surface is notebooks and scripts rather than importable modules. The README also points at doc/vggt_x.md for VGGT-X support, which adds joint pose and 3DGS optimisation for imperfect COLMAP results such as those produced by 3D foundation models. The README's TODO list still shows two open items, an official appearance embedding implementation and V1-style LoD support, so the level-of-details behaviour of the original V1 is not present on main; the README directs you to the V1-Original branch if you need the original code.

Installing CityGaussian and running a first fit

There is no install command in the README itself. It links to doc/installation.md, doc/data_preparation.md and doc/run&eval.md, and those are the authoritative sources for the exact steps. The repository ships a requirements.txt that simply includes requirements/lightning23.txt, which is the dependency set for the Gaussian Lightning base. The console scripts come from the pyproject.toml entry points, so once the package is installed the commands are on your PATH.

pip install -r requirements.txt

After installation, the entry points declared in pyproject.toml are what you invoke. The names are exactly as declared there, and doc/run&eval.md is where the argument sets for your dataset live.

gs-fit
gs-val
gs-viewer

For data, doc/data_preparation.md covers the expected layout, and the README notes that COLMAP results for the main datasets have been released. Checkpoints for CityGaussianV2 are published on Hugging Face under TeslaYang123/CityGaussianV2 and on Baidu Netdisk, with the link given in the README's results section. If you want to inspect a trained scene rather than train one, gs-viewer is the entry point the project provides, and the feature list describes it as a web viewer inherited from Gaussian Lightning. Expect the first real run to be a data preparation exercise: the reconstruction quality depends on the COLMAP poses you feed in, and the VGGT-X path exists precisely because those poses are often imperfect.

Where CityGaussian stops being the right tool

The licence is the first hard boundary. The README places the work under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International, and the repository's LICENSE.md is flagged as NOASSERTION by the hosting metadata, so the badge and the README are the clearest statement of terms. NonCommercial and ShareAlike are not compatible with shipping this inside a closed commercial product, and ShareAlike propagates to derivative work. If your use case is a commercial product, this is the wrong repository regardless of how well it reconstructs a city. The second boundary is hardware. The headline feature is multi-GPU reconstruction with controllable memory cost and, in the README's words, no limit on GPU amount. That is a feature for people with a multi-GPU node. On a single consumer card, the partition machinery is overhead you are not using, and a plain 3DGS implementation will be simpler to reason about. The third boundary is scope. The README's TODO list still has an unchecked item for official appearance embedding, and V1-style LoD is not on main. If your work depends on either, main is not the branch you want. Finally, the geometric metrics in the README's table are not uniformly strong: F1-Score on MatrixCity Street is 0.461 and precision 0.325, and the README explains that this is a deliberate trade, made by adjusting depth_ratio, in favour of a more complete road surface. If you need precise surfaces rather than complete ones, the default configuration is working against you.

CityGaussian against VastGaussian and BlockGaussian

The related searches around this project cluster on a few neighbouring names, and the comparison that matters is about how each handles scale. VastGaussian and BlockGaussian are the other well-known answers to the same question: how do you train Gaussians over an area too large for one device? The typical approach in that family is to divide the scene into blocks or chunks, train each independently, and merge or stitch the results, which means the partition boundary becomes a quality problem you have to manage. CityGaussian's stated approach is different in emphasis: the README describes CityGaussian-style multi-GPU reconstruction with controllable memory cost and no limit on GPU amount, and separately lists analysis of model partition and data assignment as a feature. That framing suggests partition and assignment are treated as first-class objects in the codebase rather than as a preprocessing step you perform before training. The second axis of difference is geometry. CityGaussianV2 adds 2DGS-style mesh extraction and large-scale scene geometric performance evaluation, so it produces a surface as well as a radiance field, and the README's table reports precision, recall and F1 alongside SSIM, PSNR and LPIPS. If you only need novel view synthesis, that geometric machinery is extra surface area. If you need a mesh, it is the reason to pick this over a pure rendering implementation. CityGS-X appears in the search list but the README does not describe it, so nothing can be said about it here.

Maintenance, upgrade cost and what the licence means in practice

The repository is not archived, and the last push was on 2026-08-16, which is recent enough that the main branch is being touched. The release history is short and spaced: CityGaussian_V1.2 in October 2024, V1.5 in November 2024, and CityGaussian_V2.0 in January 2025. The news entries run through October 2025, with the VGGT-X support announcement. There is no evidence in the repository of a stable tagged API, and the rebase onto Gaussian Lightning v0.10.1 is itself an upgrade cost: the main branch is no longer the original V1 code, and the README tells you to switch to the V1-Original branch if you need that. Anyone with scripts written against V1 will be porting them. Because the project is a research codebase with notebooks and scripts at the top level, expect to read the code rather than rely on documentation. The licence question deserves a direct answer rather than hedging, and the answer is that CC BY-NC-SA 4.0 is a content licence applied to software here, which is unusual and worth raising with whoever handles licensing at your organisation before you build on it. Attribution and ShareAlike both apply, and the NonCommercial term is the one that decides most adoption questions. None of this is legal advice; it is a statement of what the README says.

Editorial conclusion

Adopt it if you are doing academic or internal research on city-scale Gaussian Splatting and you have multi-GPU hardware, because the multi-GPU path and the 2DGS-style mesh extraction are the parts you cannot get from a plain 3DGS fork. Do not adopt it if you need a permissively licensed component in a commercial product, since the repository is under CC BY-NC-SA 4.0, or if you only have a single consumer GPU. Before committing, verify two things against doc/installation.md and doc/run&eval.md: that the submodules under submodules/ build in your environment, and that the depth_ratio setting gives you the surface completeness you want, because the README states that lowering it to 0.0 trades surface quality for an unbroken road.

Frequently asked questions

Official sources

1. Issues
2. Linketic/CityGaussian on GitHub
3. Project website
4. README
5. Releases