From a26a62966d3d2a6e370fab06990e4699ce12597c Mon Sep 17 00:00:00 2001 From: bkerbl Date: Wed, 5 Jul 2023 15:42:08 +0200 Subject: [PATCH] Added flag description to readme --- README.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 111 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index ded3077..85f543b 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ The optimizer uses PyTorch and CUDA extensions in a Python environment to produc - 24 GB VRAM to train the largest scenes in our test suite ### Software Requirements -- C++ Compiler (Visual Studio 2019 for Windows) +- C++ Compiler (we *recommend* Visual Studio 2019 for Windows) - CUDA 11 SDK for PyTorch extensions (we used 11.8) - Conda (recommended for easy setup) @@ -96,8 +96,76 @@ To run the optimizer, simply use python train.py -s ``` +
+ Command Line Arguments for train.py + + ### --source_path / -s + Path to the source directory containing a COLMAP or Synthetic NeRF data set. + ### --model_path / -m + Path where the trained model should be stored (```output/``` by default). + ### --images / -i + Alternative subdirectory for COLMAP images (```images``` by default). + ### --eval + Add this flag to use a MipNeRF360-style training/test split for evaluation. + ### --resolution / -r + Changes the resolution of the loaded images before training. If provided ```1, 2, 4``` or ```8```, uses original, 1/2, 1/4 or 1/8 resolution, respectively. For all other values, rescales the width to the given number while maintaining image aspect. ```1``` by default. + ### --white_background / -w + Add this flag to use white background instead of black (default), e.g., for evaluation of NeRF Synthetic dataset. + ### --sh_degree + Order of spherical harmonics to be used (no larger than 3). ```3``` by default. + ### --convert_SHs_python + Flag to make pipeline compute forward and backward of SHs with PyTorch instead of ours. + ### --convert_cov3D_python + Flag to make pipeline compute forward and backward of the 3D covariance with PyTorch instead of ours. + ### --iterations + Number of total iterations to train for, ```30_000``` by default. + ### --feature_lr + Spherical harmonics features learning rate, ```0.0025``` by default. + ### --opacity_lr + Opacity learning rate, ```0.05``` by default. + ### --scaling_lr + Scaling learning rate, ```0.001``` by default. + ### --rotation_lr + Rotation learning rate, ```0.001``` by default. + ### --position_lr_max_steps + Number of steps (from 0) where position learning rate goes from ```initial``` to ```final```. ```30_000``` by default. + ### --position_lr_init + Initial 3D position learning rate, ```0.00016``` by default. + ### --position_lr_final + Final 3D position learning rate, ```0.0000016``` by default. + ### --position_lr_delay_mult + Position learning rate multiplier (cf. Plenoxels), ```0.01``` by default. + ### --densify_from_iter + Iteration where densification starts, ```500``` by default. + ### --densify_until_iter + Iteration where densification stops, ```15_000``` by default. + ### --densify_grad_threshold + Limit that decides if points should be densified based on 2D position gradient, ```0.0002``` by default. + ### --densification_interal + How frequently to densify, ```100``` (every 100 iterations) by default. + ### --opacity_reset_interval + How frequently to reset opacity, ```3_000``` by default. + ### --lambda_dssim + Influence of SSIM on total loss from 0 to 1, ```0.2``` by default. + ### --percent_dense + Percentage of scene extent (0--1) a point must exceed to be forcibly densified, ```0.1``` by default. + ### --ip + IP to start GUI server on, ```127.0.0.1``` by default. + ### --port + Port to use for GUI server, ```6009``` by default. + ### --test_iterations + Space-separated iterations at which the training script computes L1 and PSNR over test set, ```7000 30000``` by default. + ### --save_iterations + Space-separated iterations at which the training script saves the Gaussian model, ```7000 30000 ``` by default. + ### --quiet + Flag to omit any text written to standard out pipe. + +
+
+ The MipNeRF360 scenes are hosted by the paper authors [here](https://jonbarron.info/mipnerf360/). You can find our SfM data sets for Tanks&Temples and Deep Blending [here](https://repo-sam.inria.fr/fungraph/3d-gaussian-splatting/datasets/input/tandt+db.zip). If you do not provide an output model directory (```-m```), trained models are written to folders with randomized unique names inside the ```output``` directory. At this point, the trained models may be viewed with the real-time viewer (see further below). + ### Evaluation By default, the trained models use all available images in the dataset. To train them while withholding a test set for evaluation, use the ```--eval``` flag. This way, you can render training/test sets and produce error metrics as follows: ```shell @@ -106,6 +174,45 @@ python render.py -m # Generate renderings python metrics.py -m # Compute error metrics on renderings ``` +
+ Command Line Arguments for render.py + + ### --model_path / -m + Path where the trained model should be stored (```output/``` by default). + ### --skip_train + Flag to skip rendering the training set. + ### --skip_test + Flag to skip rendering the test set. + ### --quiet + Flag to omit any text written to standard out pipe. + + **The below parameters will be read automatically from the model path, based on what was used for training. However, you may override them by providing them explicitly on the command line.** + + ### --source_path / -s + Path to the source directory containing a COLMAP or Synthetic NeRF data set. + ### --images / -i + Alternative subdirectory for COLMAP images (```images``` by default). + ### --eval + Add this flag to use a MipNeRF360-style training/test split for evaluation. + ### --resolution / -r + Changes the resolution of the loaded images before training. If provided ```1, 2, 4``` or ```8```, uses original, 1/2, 1/4 or 1/8 resolution, respectively. For all other values, rescales the width to the given number while maintaining image aspect. ```1``` by default. + ### --white_background / -w + Add this flag to use white background instead of black (default), e.g., for evaluation of NeRF Synthetic dataset. + ### --convert_SHs_python + Flag to make pipeline render with computed SHs from PyTorch instead of ours. + ### --convert_cov3D_python + Flag to make pipeline render with computed 3D covariance from PyTorch instead of ours. + +
+ +
+ Command Line Arguments for metrics.py + + ### --model_paths / -m + Space-separated list of model paths for which metrics should be computed. +
+
+ We further provide the ```full_eval.py``` script. This script specifies the routine used in our evaluation and demonstrates the use of some additional parameters, e.g., ```--images (-i)``` to define alternative image directories within COLMAP data sets. If you have downloaded and extracted all the training data, you can run it like this: ```shell python full_eval.py -m360 -tat -db @@ -122,7 +229,7 @@ The Network Viewer can be used to observe the training process and watch the mod - 8 GB VRAM ### Software Requirements -- C++ Compiler (Visual Studio 2019 for Windows) +- C++ Compiler (we *recommend* Visual Studio 2019 for Windows) - CUDA 11 Developer SDK (we used 11.8) - CMake (recent version, we used 3.24) - 7zip (Windows) @@ -161,7 +268,6 @@ You may run the compiled ```SIBR_remoteGaussian_app_``` either by openin The network viewer allows you to connect to a running training process on the same or a different machine. If you are training on the same machine and OS, no command line parameters should be required: the optimizer communicates the location of the training data to the network viewer. By default, optimizer and network viewer will try to establish a connection on **localhost** on port **6009**. You can change this behavior by providing matching ```--ip``` and ```--port``` parameters to both the optimizer and the network viewer. If for some reason the path used by the optimizer to find the training data is not reachable by the network viewer (e.g., due to them running on different (virtual) machines), you may specify an override location to the viewer by using ```--path ```. ### Navigation - The SIBR interface provides several methods of navigating the scene. By default, you will be started with an FPS navigator, which you can control with ```W, A, S, D``` for camera translation and ```Q, E, I, K, J, L``` for rotation. Alternatively, you may want to use a Trackball-style navigator (select from the floating menu). You can also snap to a camera from the data set with the ```Snap to``` button or find the closest camera with ```Snap to closest```. The floating menues also allow you to change the navigation speed. You can use the ```Scaling Modifier``` to control the size of the displayed Gaussians, or show the initial point cloud. ## Real-Time Viewer @@ -175,10 +281,7 @@ The Real-Time Viewer can be used to render trained models with real-time frame r - 8 GB VRAM ### Software Requirements -- C++ Compiler (Visual Studio 2019 for Windows) -- CUDA 11 Developer SDK -- CMake (recent version) -- 7zip (Windows) +The requirements are the same as for the remote viewer. ### Setup @@ -202,7 +305,7 @@ We provide a converter script ```convert.py```, which uses COLMAP to extract SfM ```shell python convert.py -s [--resize] #If not resizing, ImageMagick is not needed ``` -Alternatively, you can use the optional parameters ```--colmap_executable``` and ```--magick_executable``` to point to the respective paths. Please not that on Windows, the executable should point to the COLMAP ```.bat``` file that takes care of setting the execution environment. Once done, `````` will contain the expected COLMAP data set structure with undistorted, differently sized input images, in addition to your original images and temporary data in the directory ```distorted```. +Alternatively, you can use the optional parameters ```--colmap_executable``` and ```--magick_executable``` to point to the respective paths. Please note that on Windows, the executable should point to the COLMAP ```.bat``` file that takes care of setting the execution environment. Once done, `````` will contain the expected COLMAP data set structure with undistorted, differently sized input images, in addition to your original images and temporary data in the directory ```distorted```. ## FAQ - *Where do I get data sets, e.g., those referenced in ```full_eval.py```?* The MipNeRF360 data set is provided by the authors of the original paper on the project site. Note that two of the data sets cannot be openly shared and require you to consult the authors directly. For Tanks&Temples and Deep Blending, please use the download links provided at the top of the page.