Skip to content

Commit 896969e

Browse files
JasonLSCJasonLSC
committed
misc: update README.md
1 parent 91d813a commit 896969e

File tree

3 files changed

+118
-78
lines changed

3 files changed

+118
-78
lines changed

‎README.md‎

Lines changed: 16 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,40 @@
1-
# gsplat
1+
# GSCodec Studio
22

3-
[![Core Tests.](https://github.com/nerfstudio-project/gsplat/actions/workflows/core_tests.yml/badge.svg?branch=main)](https://github.com/nerfstudio-project/gsplat/actions/workflows/core_tests.yml)
4-
[![Docs](https://github.com/nerfstudio-project/gsplat/actions/workflows/doc.yml/badge.svg?branch=main)](https://github.com/nerfstudio-project/gsplat/actions/workflows/doc.yml)
5-
6-
[http://www.gsplat.studio/](http://www.gsplat.studio/)
7-
8-
gsplat is an open-source library for CUDA accelerated rasterization of gaussians with python bindings. It is inspired by the SIGGRAPH paper [3D Gaussian Splatting for Real-Time Rendering of Radiance Fields](https://repo-sam.inria.fr/fungraph/3d-gaussian-splatting/), but we’ve made gsplat even faster, more memory efficient, and with a growing list of new features!
9-
10-
<div align="center">
11-
<video src="https://github.com/nerfstudio-project/gsplat/assets/10151885/64c2e9ca-a9a6-4c7e-8d6f-47eeacd15159" width="100%" />
12-
</div>
3+
GSCodec Studio is an open-source framework for Gaussian Splats Compression, including static and dynamic splats representation, reconstruction and compression. It is bulit upon an open-source 3D Gaussian Splatting library [gsplat](https://github.com/nerfstudio-project/gsplat), and extended to support 1) dynamic splats representation, 2) training-time compression simulation, 3) more test-time compression strategies.
134

145
## Installation
156

167
**Dependence**: Please install [Pytorch](https://pytorch.org/get-started/locally/) first.
178

18-
The easiest way is to install from PyPI. In this way it will build the CUDA code **on the first run** (JIT).
9+
Then, you can install the gsplat library extended with more compression features from source code. In this way it will build the CUDA code during installation.
1910

2011
```bash
21-
pip install gsplat
12+
pip install .
13+
# pip install -e . (develop mode)
2214
```
2315

24-
Alternatively you can install gsplat from source. In this way it will build the CUDA code during installation.
25-
26-
```bash
27-
pip install git+https://github.com/nerfstudio-project/gsplat.git
28-
```
29-
30-
We also provide [pre-compiled wheels](https://docs.gsplat.studio/whl) for both linux and windows on certain python-torch-CUDA combinations (please check first which versions are supported). Note this way you would have to manually install [gsplat's dependencies](https://github.com/nerfstudio-project/gsplat/blob/6022cf45a19ee307803aaf1f19d407befad2a033/setup.py#L115). For example, to install gsplat for pytorch 2.0 and cuda 11.8 you can run
31-
```
32-
pip install ninja numpy jaxtyping rich
33-
pip install gsplat --index-url https://docs.gsplat.studio/whl/pt20cu118
34-
```
35-
36-
To build gsplat from source on Windows, please check [this instruction](docs/INSTALL_WIN.md).
37-
3816
## Evaluation
3917

40-
This repo comes with a standalone script that reproduces the official Gaussian Splatting with exactly the same performance on PSNR, SSIM, LPIPS, and converged number of Gaussians. Powered by gsplat’s efficient CUDA implementation, the training takes up to **4x less GPU memory** with up to **15% less time** to finish than the official implementation. Full report can be found [here](https://docs.gsplat.studio/main/tests/eval.html).
18+
**Preparations**
19+
Same as gsplat, we need to install some extra dependencies and download the relevant datasets before the evaluation.
4120

4221
```bash
4322
cd examples
4423
pip install -r requirements.txt
4524
# download mipnerf_360 benchmark data
4625
python datasets/download_dataset.py
47-
# run batch evaluation
48-
bash benchmarks/basic.sh
26+
# place other dataset under 'data' folder
4927
```
5028

51-
## Examples
29+
**Static Gaussian Splats Compression**
5230

53-
We provide a set of examples to get you started! Below you can find the details about
54-
the examples (requires to install some exta dependencies via `pip install -r examples/requirements.txt`)
31+
We provide a script that enables more memory-efficient Gaussian splats while maintaining high visual quality, such as representing the Truck scene with only about 8MB of storage.
5532

56-
- [Train a 3D Gaussian splatting model on a COLMAP capture.](https://docs.gsplat.studio/main/examples/colmap.html)
57-
- [Fit a 2D image with 3D Gaussians.](https://docs.gsplat.studio/main/examples/image.html)
58-
- [Render a large scene in real-time.](https://docs.gsplat.studio/main/examples/large_scale.html)
59-
60-
61-
## Development and Contribution
62-
63-
This repository was born from the curiosity of people on the Nerfstudio team trying to understand a new rendering technique. We welcome contributions of any kind and are open to feedback, bug-reports, and improvements to help expand the capabilities of this software.
64-
65-
This project is developed by the following wonderful contributors (unordered):
66-
67-
- [Angjoo Kanazawa](https://people.eecs.berkeley.edu/~kanazawa/) (UC Berkeley): Mentor of the project.
68-
- [Matthew Tancik](https://www.matthewtancik.com/about-me) (Luma AI): Mentor of the project.
69-
- [Vickie Ye](https://people.eecs.berkeley.edu/~vye/) (UC Berkeley): Project lead. v0.1 lead.
70-
- [Matias Turkulainen](https://maturk.github.io/) (Aalto University): Core developer.
71-
- [Ruilong Li](https://www.liruilong.cn/) (UC Berkeley): Core developer. v1.0 lead.
72-
- [Justin Kerr](https://kerrj.github.io/) (UC Berkeley): Core developer.
73-
- [Brent Yi](https://github.com/brentyi) (UC Berkeley): Core developer.
74-
- [Zhuoyang Pan](https://panzhy.com/) (ShanghaiTech University): Core developer.
75-
- [Jianbo Ye](http://www.jianboye.org/) (Amazon): Core developer.
76-
77-
We also have a white paper with about the project with benchmarking and mathematical supplement with conventions and derivations, available [here](https://arxiv.org/abs/2409.06765). If you find this library useful in your projects or papers, please consider citing:
78-
79-
```
80-
@article{ye2024gsplatopensourcelibrarygaussian,
81-
title={gsplat: An Open-Source Library for {Gaussian} Splatting},
82-
author={Vickie Ye and Ruilong Li and Justin Kerr and Matias Turkulainen and Brent Yi and Zhuoyang Pan and Otto Seiskari and Jianbo Ye and Jeffrey Hu and Matthew Tancik and Angjoo Kanazawa},
83-
year={2024},
84-
eprint={2409.06765},
85-
journal={arXiv preprint arXiv:2409.06765},
86-
archivePrefix={arXiv},
87-
primaryClass={cs.CV},
88-
url={https://arxiv.org/abs/2409.06765},
89-
}
33+
```bash
34+
bash benchmarks/compression/final_exp/mcmc_tt_sim.sh
9035
```
9136

92-
We welcome contributions of any kind and are open to feedback, bug-reports, and improvements to help expand the capabilities of this software. Please check [docs/DEV.md](docs/DEV.md) for more info about development.
37+
## More examples
38+
**Dynamic Gaussian Splats Compression**
39+
40+
**Extract Per-Frame Static Gaussian from Dynamic Splats**

‎README_gsplat.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# gsplat
2+
3+
[![Core Tests.](https://github.com/nerfstudio-project/gsplat/actions/workflows/core_tests.yml/badge.svg?branch=main)](https://github.com/nerfstudio-project/gsplat/actions/workflows/core_tests.yml)
4+
[![Docs](https://github.com/nerfstudio-project/gsplat/actions/workflows/doc.yml/badge.svg?branch=main)](https://github.com/nerfstudio-project/gsplat/actions/workflows/doc.yml)
5+
6+
[http://www.gsplat.studio/](http://www.gsplat.studio/)
7+
8+
gsplat is an open-source library for CUDA accelerated rasterization of gaussians with python bindings. It is inspired by the SIGGRAPH paper [3D Gaussian Splatting for Real-Time Rendering of Radiance Fields](https://repo-sam.inria.fr/fungraph/3d-gaussian-splatting/), but we’ve made gsplat even faster, more memory efficient, and with a growing list of new features!
9+
10+
<div align="center">
11+
<video src="https://github.com/nerfstudio-project/gsplat/assets/10151885/64c2e9ca-a9a6-4c7e-8d6f-47eeacd15159" width="100%" />
12+
</div>
13+
14+
## Installation
15+
16+
**Dependence**: Please install [Pytorch](https://pytorch.org/get-started/locally/) first.
17+
18+
The easiest way is to install from PyPI. In this way it will build the CUDA code **on the first run** (JIT).
19+
20+
```bash
21+
pip install gsplat
22+
```
23+
24+
Alternatively you can install gsplat from source. In this way it will build the CUDA code during installation.
25+
26+
```bash
27+
pip install git+https://github.com/nerfstudio-project/gsplat.git
28+
```
29+
30+
We also provide [pre-compiled wheels](https://docs.gsplat.studio/whl) for both linux and windows on certain python-torch-CUDA combinations (please check first which versions are supported). Note this way you would have to manually install [gsplat's dependencies](https://github.com/nerfstudio-project/gsplat/blob/6022cf45a19ee307803aaf1f19d407befad2a033/setup.py#L115). For example, to install gsplat for pytorch 2.0 and cuda 11.8 you can run
31+
```
32+
pip install ninja numpy jaxtyping rich
33+
pip install gsplat --index-url https://docs.gsplat.studio/whl/pt20cu118
34+
```
35+
36+
To build gsplat from source on Windows, please check [this instruction](docs/INSTALL_WIN.md).
37+
38+
## Evaluation
39+
40+
This repo comes with a standalone script that reproduces the official Gaussian Splatting with exactly the same performance on PSNR, SSIM, LPIPS, and converged number of Gaussians. Powered by gsplat’s efficient CUDA implementation, the training takes up to **4x less GPU memory** with up to **15% less time** to finish than the official implementation. Full report can be found [here](https://docs.gsplat.studio/main/tests/eval.html).
41+
42+
```bash
43+
cd examples
44+
pip install -r requirements.txt
45+
# download mipnerf_360 benchmark data
46+
python datasets/download_dataset.py
47+
# run batch evaluation
48+
bash benchmarks/basic.sh
49+
```
50+
51+
## Examples
52+
53+
We provide a set of examples to get you started! Below you can find the details about
54+
the examples (requires to install some exta dependencies via `pip install -r examples/requirements.txt`)
55+
56+
- [Train a 3D Gaussian splatting model on a COLMAP capture.](https://docs.gsplat.studio/main/examples/colmap.html)
57+
- [Fit a 2D image with 3D Gaussians.](https://docs.gsplat.studio/main/examples/image.html)
58+
- [Render a large scene in real-time.](https://docs.gsplat.studio/main/examples/large_scale.html)
59+
60+
61+
## Development and Contribution
62+
63+
This repository was born from the curiosity of people on the Nerfstudio team trying to understand a new rendering technique. We welcome contributions of any kind and are open to feedback, bug-reports, and improvements to help expand the capabilities of this software.
64+
65+
This project is developed by the following wonderful contributors (unordered):
66+
67+
- [Angjoo Kanazawa](https://people.eecs.berkeley.edu/~kanazawa/) (UC Berkeley): Mentor of the project.
68+
- [Matthew Tancik](https://www.matthewtancik.com/about-me) (Luma AI): Mentor of the project.
69+
- [Vickie Ye](https://people.eecs.berkeley.edu/~vye/) (UC Berkeley): Project lead. v0.1 lead.
70+
- [Matias Turkulainen](https://maturk.github.io/) (Aalto University): Core developer.
71+
- [Ruilong Li](https://www.liruilong.cn/) (UC Berkeley): Core developer. v1.0 lead.
72+
- [Justin Kerr](https://kerrj.github.io/) (UC Berkeley): Core developer.
73+
- [Brent Yi](https://github.com/brentyi) (UC Berkeley): Core developer.
74+
- [Zhuoyang Pan](https://panzhy.com/) (ShanghaiTech University): Core developer.
75+
- [Jianbo Ye](http://www.jianboye.org/) (Amazon): Core developer.
76+
77+
We also have a white paper with about the project with benchmarking and mathematical supplement with conventions and derivations, available [here](https://arxiv.org/abs/2409.06765). If you find this library useful in your projects or papers, please consider citing:
78+
79+
```
80+
@article{ye2024gsplatopensourcelibrarygaussian,
81+
title={gsplat: An Open-Source Library for {Gaussian} Splatting},
82+
author={Vickie Ye and Ruilong Li and Justin Kerr and Matias Turkulainen and Brent Yi and Zhuoyang Pan and Otto Seiskari and Jianbo Ye and Jeffrey Hu and Matthew Tancik and Angjoo Kanazawa},
83+
year={2024},
84+
eprint={2409.06765},
85+
journal={arXiv preprint arXiv:2409.06765},
86+
archivePrefix={arXiv},
87+
primaryClass={cs.CV},
88+
url={https://arxiv.org/abs/2409.06765},
89+
}
90+
```
91+
92+
We welcome contributions of any kind and are open to feedback, bug-reports, and improvements to help expand the capabilities of this software. Please check [docs/DEV.md](docs/DEV.md) for more info about development.

‎examples/benchmarks/compression/final_exp/mcmc_tt_sim.sh‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -41,15 +41,15 @@ run_single_scene() {
4141
echo "Running $SCENE on GPU: $GPU_ID"
4242

4343
# train without eval
44-
# CUDA_VISIBLE_DEVICES=$GPU_ID python simple_trainer.py mcmc --eval_steps -1 --disable_viewer --data_factor 1 \
45-
# --strategy.cap-max $CAP_MAX \
46-
# --data_dir $SCENE_DIR/$SCENE/ \
47-
# --result_dir $RESULT_DIR/$SCENE/ \
48-
# --compression_sim \
49-
# --entropy_model_opt \
50-
# --rd_lambda $RD_LAMBDA \
51-
# --shN_ada_mask_opt \
52-
# --compression entropy_coding
44+
CUDA_VISIBLE_DEVICES=$GPU_ID python simple_trainer.py mcmc --eval_steps -1 --disable_viewer --data_factor 1 \
45+
--strategy.cap-max $CAP_MAX \
46+
--data_dir $SCENE_DIR/$SCENE/ \
47+
--result_dir $RESULT_DIR/$SCENE/ \
48+
--compression_sim \
49+
--entropy_model_opt \
50+
--rd_lambda $RD_LAMBDA \
51+
--shN_ada_mask_opt \
52+
--compression png
5353

5454

5555
# eval: use vgg for lpips to align with other benchmarks
@@ -59,7 +59,7 @@ run_single_scene() {
5959
--result_dir $RESULT_DIR/$SCENE/ \
6060
--lpips_net vgg \
6161
--ckpt $RESULT_DIR/$SCENE/ckpts/ckpt_29999_rank0.pt \
62-
--compression entropy_coding
62+
--compression png
6363

6464
}
6565
# ----------------- Main Job --------------------- #

0 commit comments

Comments
 (0)