DN-Splatter: Depth and Normal Priors for Gaussian Splatting and Meshing

🌐Project Page | 🖨️ArXiv

This repo implements depth and normal supervision for 3DGS and several mesh extraction scripts.

Demo:

https://github.com/maturk/dn-splatter/assets/30566358/9b3ffe9d-5fe9-4b8c-8426-d578bf877a35

Updates

• 04.09.2024: Support Open3d TSDF to extract mesh, support Patch-based Depth Correlation Loss from SparseGS for monodepth supervision, support visualizing normal estimates from the Gaussian geometry and estimated surface normal from depths, support colmap SFM point cloud initialization for MuSHRoom dataset.
• 14.06.2024: Support gsplat v1.0.0 🚀. Faster training and better memory consumption. Training with --pipeline.model.predict_normals is about 20% slower than without.
• 16.04.2024: Support for DSINE monocular normal supervision.

• 20.04.2024: dn-splatter-big: a variant featuring less aggressive Gaussian culling threshold, which leads to an increased number of Gaussians in the optimized scene. On certain datasets, this can lead to better novel-view synthesis results.

  Installation

  Method 1. Using Conda and Pip

  Follow installation instructions for [Nerfstudio](https://docs.nerf.studio/quickstart/installation.html). This repo is compatible with a `nerfstudio` conda environment. Clone and install DN-Splatter ```bash conda activate nerfstudio git clone https://github.com/maturk/dn-splatter cd dn_splatter/ pip install setuptools==69.5.1 pip install -e . ```

Usage

This repo registers a new model called dn-splatter with various additional options:

Please check the dn_model.py for a full list of supported configs (some are only experimental).

Recommended settings:

For larger indoor captures with sensor depth data (e.g. MuSHRoom / ScanNet++ datasets):

ns-train dn-splatter --data PATH_TO_DATA \
                 --pipeline.model.use-depth-loss True \
                 --pipeline.model.depth-lambda 0.2 \
                 --pipeline.model.use-normal-loss True \
                 --pipeline.model.use-normal-tv-loss True \
                 --pipeline.model.normal-supervision (mono/depth) \

dn-splatter-big:

We also provide a dn-splatter-big variant that increases the number of Gaussians in the scene which may enhance the quality of novel-view synthesis. This increases training time and hardware requirements. Simply replace the dn-splatter keyword with dn-splatter-big in the above commands.

Supported Depth Losses

To train with a specific depth loss, use the flag: --pipeline.model.depth-loss-type DepthLossType where DepthLossType is one of ["MSE", "LogL1", "HuberL1", "L1", "EdgeAwareLogL1", "PearsonDepth"]

For sensor depth supervision we reccommend EdgeAwareLogL1 loss. For monocular depth supervision, we recommend the relative Pearson correlation loss PearsonDepth.

Mesh

To extract a mesh, run the following command:

gs-mesh {dn, tsdf, o3dtsdf, sugar-coarse, gaussians, marching} --load-config [PATH] --output-dir [PATH]

We reccommend gs-mesh dn for large room scale scenes and gs-mesh o3dtsdf for smaller object scale captures.

Mesh algorithm details

Export a mesh with the `gs-mesh --help` command. The following mesh exporters are supported. | gs-mesh | Description | Requires normals?| |--------------------|--------------------------------------------------------------------|-| | gs-mesh dn | Backproject depth and normal maps to Poisson | Yes| | gs-mesh tsdf | TSDF Fusion algorithm | No| | gs-mesh o3dtsdf | TSDF Fusion algorithm used in 2DGS paper | No| | gs-mesh sugar-coarse | Level set extractor from SuGaR (Sec 4.2 from the paper) | Both | | gs-mesh gaussians | Use Gaussian xyzs and normals to Poisson | Yes| Use the `--help` command with each method to see more useful options and settings. For very small object captures, TSDF works well with 0.004 voxel size and 0.02 SDF trunc distance. But TSDF can fail in larger indoor room reconstructions. We reccommend Poisson for more robust results with little hyperparameter tuning.

Scripts

Generate scale aligned mono-depth estimates

If your dataset has no sensor depths, and you have a COLMAP processed dataset, we provide a script to generate scale aligned monocular depth estimates. Scale alignment refers to solving for the scale ambiquity between estimated monocular depths and the scale of your input COLMAP poses. This script generates sfm_depths/ and mono_depth/ directories in the data root: ``` |---image_path | |--- | |--- | |---... |---sfm_depths | |--- | |--- | |---... |---mono_depth | |---.png | |---_aligned.npy ``` The dataset is expected to be in COLMAP format (contains a colmap/sparse/0 folder in data root) since SfM points are required. ```bash python dn_splatter/scripts/align_depth.py --data [path_to_data_root] \ --skip-colmap-to-depths, --no-skip-colmap-to-depths \ --skip-mono-depth-creation, --no-skip-mono-depth-creation \ ``` NOTE: if faced with the following error: ``` TypeError: expected size to be one of int or Tuple[int] or Tuple[int, int] or Tuple[int, int, int], but got size with types [, ] ``` Downgrading from Torch 2.1.2 to 2.0.1 solves the issue.

Custom RGB-D Smartphone (Android/iPhone) Data

For casually captured RGB-D streams, consider using SpectacularAI SDK for iPhone/Android or Oak/RealSense/Kinect sensor streams. For LiDaR enabled smartphones, download the app from the Apple/Play store and capture your data.

Once you have gathered the data, process the inputs into a Nerfstudio suitable format (calculate VIO poses and create a transforms.json file with poses and depth frames):

pip install spectacularAI
python dn_splatter/scripts/process_sai.py [PATH_TO_SAI_INPUT_FOLDER] [PATH_TO_OUTPUT_FOLDER]

To train with the custom data:

ns-train dn-splatter --data PATH_TO_DATA \
                 --pipeline.model.use-depth-loss True \
                 --pipeline.model.depth-lambda 0.2 \
                 --pipeline.model.use-normal-loss True \
                 --pipeline.model.use-normal-tv-loss True \
                 --pipeline.model.normal-supervision depth \

For other custom datasets, use the Nerfstudio conventions and train with the above command.

Datasets

Other preprocessed datasets are supported by dataparsers with the keywords mushroom, replica, scannetpp, nrgbd, dtu, coolermap. To train with a dataset use the following:

ns-train dn-splatter [OPTIONS] [mushroom/replica/scannet/nrgbd/dtu/coolermap] --data [DATASET_PATH]

Dataparsers have their own options, to see the full list use ns-train dn-splatter [mushroom/replica/scannet/nrgbd/dtu/coolermap] --help. Some useful ones are:

  --depth-mode        : ["sensor","mono","all", "none"] determines what depths to load.
  --load-normals      : [True/False] whether to load normals or not.
  --normals-from      : ["depth", "pretrained"] generate pseudo-ground truth normals from depth maps or from pretrained omnimodel.
  --normal-format     : ["opengl", "opencv"] What coordinate system normals are saved in camera frame.
  --load-pcd-normals  : [True/False] initialise gaussian scales/rotations based on estimated SfM normals.

Supported dataparsers:

COLMAP datasets

For arbitrary COLMAP processed datasets, we expect the following directory structure ``` |---image_path | |--- | |--- | |---... |---colmap |---sparse |---0 |---cameras.bin |---images.bin |---points3D.bin ``` Use the `coolermap` dataparser with COLMAP datasets as follows: ```bash ns-train dn-splatter [OPTIONS] coolermap --data [DATASET_PATH] ```

Evaluation

Please see dn_splatter/eval/eval_instructions.md for more details.

To run DN-Splatter on an entire dataset of sequences (potentially in parallel with multi-GPU cluster), you can use the dn_splatter/eval/batch_run.py script.

For evaluating rgb, depth, and pointcloud metrics (optional), run the following command:

ns-eval --load-config [PATH_TO_CONFIG] --output-path [JSON_OUTPUT_PATH]

To render train/eval images also add the flag --render-output-path [PATH_TO_IMAGES]

To get mesh metrics for the MuSHRoom dataset, run the following command:

python dn_splatter/eval/eval_mesh_mushroom_vis_cull.py --gt_mesh_path [GT_Mesh_Path] --pred_mesh_path [Pred_Mesh_Path] --output --device [iphone/kinect] 

To get mesh metrics for other datasets ScanNet++/Replica or custom datasets, run the following command:

python dn_splatter/eval/eval_mesh_vis_cull.py --gt-mesh-path [GT_Mesh_Path] --pred-mesh-path [Pred_Mesh_Path] --transformation_file [Path_to_transform_file] --dataset_path [Dataset path]

--transformation_file path is the path of the transform.json generated when training scannetpp here. --dataset_path is the path to the dataset folder, e.g. datasets/scannetpp/data/b20a261fdf/iphone

Acknowledgements

I want to thank Tobias Fischer, Songyou Peng and Philipp Lindenberger for their fruitful discussions and guidance, especially concerning mesh reconstruction. This project is built on various open-source software, and I want to thank the Nerfstudio team for their great efforts maintaining and extending a large project allowing for these kinds of extensions to exist.

Citation

If you find this work useful in your research, consider citing it:

@misc{turkulainen2024dnsplatter,
        title={DN-Splatter: Depth and Normal Priors for Gaussian Splatting and Meshing}, 
        author={Matias Turkulainen and Xuqian Ren and Iaroslav Melekhov and Otto Seiskari and Esa Rahtu and Juho Kannala},
        year={2024},
        eprint={2403.17822},
        archivePrefix={arXiv},
        primaryClass={cs.CV}
}

Contributing

We welcome any bug fixes, issues/comments, or contributions. Also, if you have any suggestions or improvements, let me know!

I want to thank Pablo Vela for contributing the DSINE normal predictor into this project and allowing for an alternative (much easier) installation with Pixi.

Developers

• maturk
• XuqianRen