3D Gaussian Splatting (Packaged Python Version)
This repo is the refactored python training and inference code for 3D Gaussian Splatting. Forked from commit a2a91d9093fd791fb01f556fa717f8d9f2cfbdd7. We refactored the original code following the standard Python package structure, while keeping the algorithms used in the code identical to the original version.
Features
- organize the code as a standard Python package
- exposure compensation
- camera and 3DGS parameters joint training
- depth regularization
- local relative depth regularization
- image mask
- integrated gsplat backend
- integrated 2DGS from gsplat
Downstream Projects
- InstantSplat(Refactored): Z. Fan et al., "InstantSplat: Sparse-view Gaussian Splatting in Seconds," CVPR NRI 2024
- reduced-3dgs(Refactored): P. Papantonakis et al., "Reducing the Memory Footprint of 3D Gaussian Splatting," Proceedings of the ACM on Computer Graphics and Interactive Techniques, vol. 7, no. 1, May 2024
- 3dgs-mcmc(Refactored): S. Kheradmand et al., "3D Gaussian Splatting as Markov Chain Monte Carlo," NeurIPS Spotlight Presentation 2024
- lapis-gs(Refactored): Y. Shi et al., "LapisGS: Layered Progressive 3D Gaussian Splatting for Adaptive Streaming," 3DV 2025
- gscompressor(Original): Compress 3DGS scenes by Draco.
- gsvvcompressor(Original): A modular video compression framework for Gaussian Splatting models.
- TrackerSplat(Original): D. Yin et al., "TrackerSplat: Exploiting Point Tracking for Fast and Robust Dynamic 3D Gaussians Reconstruction," SIGGRAPH Asia 2025
Install
Prerequisites
- Pytorch (>= v2.4 recommended)
- CUDA Toolkit (12.4 recommended, match with PyTorch version)
- gsplat
PyPI Install
pip install --upgrade gaussian-splatting
or build latest from source:
pip install wheel setuptools
pip install --upgrade git+https://github.com/yindaheng98/gaussian-splatting.git@master --no-build-isolation
Development Install
git clone --recursive https://github.com/yindaheng98/gaussian-splatting
cd gaussian-splatting
pip install tqdm plyfile tifffile numpy opencv-python pillow open3d
pip install git+https://github.com/nerfstudio-project/gsplat.git
pip install --target . --upgrade . --no-deps
Quick Start
- Download dataset (T&T+DB COLMAP dataset, size 650MB):
wget https://repo-sam.inria.fr/fungraph/3d-gaussian-splatting/datasets/input/tandt_db.zip -P ./data
unzip data/tandt_db.zip -d data/
- Train 3DGS with densification (same with original 3DGS)
python -m gaussian_splatting.train -s data/truck -d output/truck -i 30000 --mode densify
- Render or view 3DGS
python -m gaussian_splatting.render -s data/truck -d output/truck -i 30000 --mode densify
python -m gaussian_splatting.viewer -d output/truck -i 30000
- Joint training 3DGS and camera (load the trained 3DGS)
python -m gaussian_splatting.train -s data/truck -d output/truck-camera -i 30000 --mode camera -l output/truck/point_cloud/iteration_30000/point_cloud.ply
- Render 3DGS with optimized cameras
python -m gaussian_splatting.render -s data/truck -d output/truck-camera -i 30000 --mode camera --load_camera output/truck-camera/cameras.json
💡 This repo does not contain code for creating dataset. If you want to create your own dataset, please refer to InstantSplat or use convert.py. The folder that
-s/sourcepoints at must follow the dataset format below.
💡 See .vscode/launch.json for more example. See gaussian_splatting.train and gaussian_splatting.render for full options.
Dataset format
ColmapCameraDataset reads one COLMAP scene folder:
<data>/
images/
<name>.jpg # RGB image; the relative path must match the name stored in COLMAP
<name>_mask.tiff # optional image mask; if missing, <name>_mask.png is used
depths/ # optional; loaded unless --no_depth_data
<name>.tiff # depth map; if missing, <name>.png is used
<name>_mask.tiff # optional depth mask; if missing, <name>_mask.png is used
sparse/0/
cameras.bin # intrinsics; if unreadable, cameras.txt is used
images.bin # extrinsics; if unreadable, images.txt is used
points3D.ply # sparse points for Gaussian init; if missing, points3D.bin then points3D.txt
<name> is the COLMAP image name without its extension, including any subdirectory. images/foo/bar.jpg pairs with images/foo/bar_mask.tiff and depths/foo/bar.tiff.
- The camera model must be undistorted
PINHOLEorSIMPLE_PINHOLE. - A missing mask or depth file logs a warning and that map is skipped.
--no_image_maskskips image masks.--no_depth_dataskips depth maps and depth masks. - When the image file size differs from the size stored in COLMAP, the file size is used.
| File | Contents |
|---|---|
| RGB image | Any image Pillow can open. RGB is scaled to [0, 1]. |
| Image mask, depth mask | Single channel. .tiff is read as float and used as stored. .png is uint8 and divided by 255. 1 keeps the pixel and 0 drops it. When both extensions exist, .tiff is used. |
| Depth | Single channel. Store metric or relative depth as float .tiff. .png is cast to float as stored. When both extensions exist, .tiff is used. |
See (Optional) Generate depth maps for writing depths/ with Depth-Anything-V2. Gaussian initialization reads sparse/0/points3D.* separately via colmap_init.
2D Gaussian Splatting (2DGS)
- Train 2DGS with densification
python -m gaussian_splatting.train -s data/truck -d output/truck-2dgs -i 30000 --mode normal-densify --backend gsplat-2dgs
- Render or view 2DGS
python -m gaussian_splatting.render -s data/truck -d output/truck-2dgs -i 30000 --backend gsplat-2dgs
python -m gaussian_splatting.viewer -d output/truck-2dgs -i 30000 --backend gsplat-2dgs
- Joint training 2DGS and camera (load the trained 2DGS)
python -m gaussian_splatting.train -s data/truck -d output/truck-2dgs-camera -i 30000 --mode normal-camera -l output/truck-2dgs/point_cloud/iteration_30000/point_cloud.ply --backend gsplat-2dgs
- Render 2DGS with optimized cameras
python -m gaussian_splatting.render -s data/truck -d output/truck-2dgs-camera -i 30000 --mode camera --load_camera output/truck-2dgs-camera/cameras.json --backend gsplat-2dgs
(Optional) Generate depth maps before training
- Prepare Depth-Anything-V2
git clone https://github.com/DepthAnything/Depth-Anything-V2.git
mkdir checkpoints
wget -O checkpoints/depth_anything_v2_vitl.pth https://huggingface.co/depth-anything/Depth-Anything-V2-Large/resolve/main/depth_anything_v2_vitl.pth?download=true
- Generate depth maps
# (Recommanded) save depth map as floating-point tiff file
python tools/run_depth_anything_v2.py --encoder vitl --img-path data/truck/images --outdir data/truck/depths
# (not Recommanded) save depth map as uint8 png file
python Depth-Anything-V2/run.py --encoder vitl --pred-only --grayscale --img-path data/truck/images --outdir data/truck/depths
API Usage
Gaussian models
GaussianModel is the basic 3DGS model.
from gaussian_splatting import GaussianModel
gaussians = GaussianModel(sh_degree).to(device)
If you want cameras-3DGS joint training, use CameraTrainableGaussianModel, the rendering process is different.
from gaussian_splatting import CameraTrainableGaussianModel
gaussians = CameraTrainableGaussianModel(sh_degree).to(device)
save and load params:
gaussians.save_ply("output/truck/point_cloud/iteration_30000/point_cloud.ply")
gaussians.load_ply("output/truck/point_cloud/iteration_30000/point_cloud.ply")
init 3DGS with sparse point cloud extracted by colmap:
from gaussian_splatting.dataset.colmap import colmap_init
colmap_init(gaussians, "data/truck")
Dataset
Folder layout, mask names, and depth names are described in Dataset format.
Basic colmap dataset:
from gaussian_splatting.dataset.colmap import ColmapCameraDataset, colmap_init
dataset = ColmapCameraDataset("data/truck")
save to JSON and load JSON dataset:
dataset.save_cameras("output/truck/cameras.json")
from gaussian_splatting import JSONCameraDataset
dataset = JSONCameraDataset("output/truck/cameras.json")
Dataset with trainable cameras:
from gaussian_splatting import TrainableCameraDataset
dataset = TrainableCameraDataset("data/truck") # init cameras from colmap
dataset = TrainableCameraDataset.from_json("output/truck/cameras.json") # init cameras from saved json
Inference
for camera in dataset:
out = gaussians(camera)
image = out["render"]
... # compute loss, save image or others
Trainers
gaussian_splatting.trainer contains a series of trainers for optimizing 3DGS models.
Core Trainers
Basic training methods that handle fundamental optimization tasks:
BaseTrainer only optimize the 3DGS parameters, without densification or camera optimization.
from gaussian_splatting.trainer import BaseTrainer
trainer = BaseTrainer(
gaussians,
scene_extent=dataset.scene_extent(),
... # see gaussian_splatting/trainer/base.py for full options
)
BaseDensificationTrainer optimize the 3DGS parameters with densification.
from gaussian_splatting.trainer import BaseDensificationTrainer
trainer = BaseDensificationTrainer(
gaussians,
scene_extent=dataset.scene_extent(),
... # see gaussian_splatting/trainer/densifier/densifier.py for full options
)
BaseCameraTrainer jointly optimize the 3DGS parameters and cameras, without densification.
from gaussian_splatting.trainer import BaseCameraTrainer
trainer = BaseCameraTrainer(
gaussians,
scene_extent=dataset.scene_extent(),
dataset=dataset,
... # see gaussian_splatting/trainer/camera_trainable.py for full options
)
BaseDepthTrainer optimize the 3DGS parameters with depth regularization.
from gaussian_splatting.trainer import BaseDepthTrainer
trainer = BaseDepthTrainer(
gaussians,
scene_extent=dataset.scene_extent(),
... # see gaussian_splatting/trainer/base.py for full options
)
DepthCameraTrainer integrated BaseCameraTrainer with depth regularization.
from gaussian_splatting.trainer import SHLiftTrainer
trainer = SHLiftTrainer(
gaussians,
scene_extent=dataset.scene_extent(),
dataset=dataset,
... # see gaussian_splatting/trainer/sh_lift.py for full options
)
Enhanced Trainers
Gaussian Splatting paper also introduce two tricks "opacity reset" and "lifting SH", they are also included. The basic methods can be integrated with opacity reset and lifting SH. For example:
BaseOpacityResetDensificationTrainer integrated BaseDensificationTrainer with opacity reset.
from gaussian_splatting.trainer import BaseOpacityResetDensificationTrainer
trainer = OpacityResetDensificationTrainer(
gaussians,
scene_extent=dataset.scene_extent(),
... # see gaussian_splatting/trainer/combinations.py for full options
)
DepthOpacityResetDensificationTrainer integrated BaseOpacityResetDensificationTrainer with depth regularization.
from gaussian_splatting.trainer import DepthOpacityResetDensificationTrainer
trainer = DepthOpacityResetDensificationTrainer(
gaussians,
scene_extent=dataset.scene_extent(),
... # see gaussian_splatting/trainer/combinations.py for full options
)
BaseSHLiftOpacityResetDensificationTrainer integrated BaseOpacityResetDensificationTrainer with lifting SH.
from gaussian_splatting.trainer import BaseSHLiftOpacityResetDensificationTrainer
trainer = BaseSHLiftOpacityResetDensificationTrainer(
gaussians,
scene_extent=dataset.scene_extent(),
... # see gaussian_splatting/trainer/combinations.py for full options
)
DepthSHLiftOpacityResetDensificationTrainer integrated DepthOpacityResetDensificationTrainer with lifting SH.
from gaussian_splatting.trainer import DepthSHLiftOpacityResetDensificationTrainer
trainer = DepthSHLiftOpacityResetDensificationTrainer(
gaussians,
scene_extent=dataset.scene_extent(),
... # see gaussian_splatting/trainer/combinations.py for full options
)
Similarly, there are BaseOpacityResetDensificationCameraTrainer, DepthOpacityResetDensificationCameraTrainer, BaseSHLiftOpacityResetDensificationCameraTrainer, DepthSHLiftOpacityResetDensificationCameraTrainer that integrated the above with camera training.
For more, please refer to train.py and trainer/combinations.py.
Training
To use any trainer:
for camera in dataset:
loss, out = trainer.step(camera)
Discussion on Additional Features
Local Relative Depth Regularization
Problem: Global Depth Rescaling Limitation
The default implementation uses DepthAnythingV2 for depth estimation (tools/run_depth_anything_v2.py). These estimated depth maps are then scaled using one global factor per scene (trainer/depth.py or in the github.com/graphdeco-inria/gaussian-splatting/utils/make_depth_scale.py).
However, this approach suffers from local inaccuracies due to limitations inherent in monocular depth predictions.
As demonstrated below, monocular depth estimation frequently introduces local distortions with global rescaling (for instance, people are pouring wine, but the spout is not positioned directly above the wine glass.):
Using globally scaled depth alone results in artifacts and incorrectly placed surfaces during rendering:
Overlaying rendered depth map with DepthAnythingV2-estimated depth map manifests these shortcomings clearly. While background walls and foreground table approximately match ground truth, depth estimates for people remain significantly inaccurate:
Root Cause: Spatial Error Patterns in DepthAnythingV2
Although the output depth estimation from DepthAnythingV2 appears visually plausible when inspected independently (as illustrated in the figure below), local depth scale variations remain substantial.
Therefore, a single global scaling cannot account adequately for these local discrepancies.
Solution: Local relative depth regularization
Considering that DepthAnythingV2 produces relatively accurate local depth relationships, this repo introduces local relative depth regularization strategy. Specifically, the strategy involves:
- Divide the depth map into small overlapping windows.
- Compute scaling and offset corrections individually per window.
- Apply these local corrections to guide model predictions.
Implementation details are provided in the function compute_local_relative_depth_loss in trainer/depth.py.
The resulting improvements are clearly visible, significantly reducing artifacts:
Overlaying it with DepthAnythingV2-estimated depth map:
Local regularization notably improves background alignment (e.g., walls), but some inaccuracies remain for complex foreground shapes such as people. This clearly highlights inherent limitations and persistent spatial error patterns in the monocular DepthAnythingV2 estimations.
3D Gaussian Splatting for Real-Time Radiance Field Rendering
Bernhard Kerbl*, Georgios Kopanas*, Thomas Leimkühler, George Drettakis (* indicates equal contribution)
| Webpage | Full Paper | Video | Other GRAPHDECO Publications | FUNGRAPH project page |
| T&T+DB COLMAP (650MB) | Pre-trained Models (14 GB) | Viewers for Windows (60MB) | Evaluation Images (7 GB) |
This repository contains the official authors implementation associated with the paper "3D Gaussian Splatting for Real-Time Radiance Field Rendering", which can be found here. We further provide the reference images used to create the error metrics reported in the paper, as well as recently created, pre-trained models.
Abstract: Radiance Field methods have recently revolutionized novel-view synthesis of scenes captured with multiple photos or videos. However, achieving high visual quality still requires neural networks that are costly to train and render, while recent faster methods inevitably trade off speed for quality. For unbounded and complete scenes (rather than isolated objects) and 1080p resolution rendering, no current method can achieve real-time display rates. We introduce three key elements that allow us to achieve state-of-the-art visual quality while maintaining competitive training times and importantly allow high-quality real-time (≥ 30 fps) novel-view synthesis at 1080p resolution. First, starting from sparse points produced during camera calibration, we represent the scene with 3D Gaussians that preserve desirable properties of continuous volumetric radiance fields for scene optimization while avoiding unnecessary computation in empty space; Second, we perform interleaved optimization/density control of the 3D Gaussians, notably optimizing anisotropic covariance to achieve an accurate representation of the scene; Third, we develop a fast visibility-aware rendering algorithm that supports anisotropic splatting and both accelerates training and allows realtime rendering. We demonstrate state-of-the-art visual quality and real-time rendering on several established datasets.
BibTeX
@Article{kerbl3Dgaussians,
author = {Kerbl, Bernhard and Kopanas, Georgios and Leimk{\"u}hler, Thomas and Drettakis, George},
title = {3D Gaussian Splatting for Real-Time Radiance Field Rendering},
journal = {ACM Transactions on Graphics},
number = {4},
volume = {42},
month = {July},
year = {2023},
url = {https://repo-sam.inria.fr/fungraph/3d-gaussian-splatting/}
}1 maintainer
Metadata
1 maintainer
Release files for gaussian-splatting 2.10.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| gaussian_splatting-2.10.4.tar.gz | 4.5 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| gaussian_splatting-2.10.4-cp312-cp312-win_amd64.whl | CPython 3.12 | CPython 3.12 | Windows x86-64 | Details |
| gaussian_splatting-2.10.4-cp311-cp311-win_amd64.whl | CPython 3.11 | CPython 3.11 | Windows x86-64 | Details |
| gaussian_splatting-2.10.4-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.11 | CPython 3.11 | Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 | Details |
| gaussian_splatting-2.10.4-cp310-cp310-win_amd64.whl | CPython 3.10 | CPython 3.10 | Windows x86-64 | Details |
| gaussian_splatting-2.10.4-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.10 | CPython 3.10 | Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 | Details |
Total release size: 22.5 MB
Release files / gaussian_splatting-2.10.4.tar.gz
| Download URL | gaussian_splatting-2.10.4.tar.gz |
|---|---|
| Size | 4.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
38767f1211a76ca2f56734f6470eed69df545a24d9ff30dc21e4d7338da871a2
|
|
BLAKE2b-256 checksum How to use checksums |
f8cd404f7159474ac4865b7d2968fdf0dfc6d67baba23c05ba21037c075b0279
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / gaussian_splatting-2.10.4-cp312-cp312-win_amd64.whl
| Download URL | gaussian_splatting-2.10.4-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 980.7 kB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
77a9613db9ca3370de71d427d8e7569feb1c04507aa989e8f32297e7c7874c43
|
|
BLAKE2b-256 checksum How to use checksums |
8617acb57a6263119fea83d8438cfc5746ce15ad92bda6ea99336200ed1b5254
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / gaussian_splatting-2.10.4-cp311-cp311-win_amd64.whl
| Download URL | gaussian_splatting-2.10.4-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 979.4 kB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
81ba09980de81f543b9d5598184c64d3d171529adeacd611b7230ad851fb2a0e
|
|
BLAKE2b-256 checksum How to use checksums |
5149795f29f8f4fda17a9156df354e25c823361b99b88b11c516308380b88685
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / gaussian_splatting-2.10.4-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | gaussian_splatting-2.10.4-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 7.5 MB |
| Tags | CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
eaebd70946dc845d943e819d106659a067b71db326afec1cee1aed352c37ed11
|
|
BLAKE2b-256 checksum How to use checksums |
9551853f2192cd9a0ecde2ad736a658d202f38affdadfb257db6c7ca8986bf90
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / gaussian_splatting-2.10.4-cp310-cp310-win_amd64.whl
| Download URL | gaussian_splatting-2.10.4-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 977.1 kB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
ed3dbd86b53e29747a4b33398bb0a1f4146d174f9d5e935d87a27530c8885fa6
|
|
BLAKE2b-256 checksum How to use checksums |
bae203a36090710859b0efe4c1944ffdfda5cfb4a61806836adbaa8fea5ea53d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / gaussian_splatting-2.10.4-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | gaussian_splatting-2.10.4-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 7.5 MB |
| Tags | CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
5640c0a3368e74aae87f35c8cb7d0e0eac2c7723d2d8df1bfab6152985b31fcb
|
|
BLAKE2b-256 checksum How to use checksums |
c9090d81325c5c15449a46ead481ce4042d2cf18d5aabb48759ac1c1ef364347
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency log
