5.0 KiB
Installation
Create environment
We reccomend using conda to manage dependencies. Make sure to install Conda before preceding.
conda create --name nerfstudio -y python=3.8.13
conda activate nerfstudio
python -m pip install --upgrade pip
Dependencies
Install pytorch with CUDA (this repo has been tested with CUDA 11.3) and tiny-cuda-nn
pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 -f https://download.pytorch.org/whl/torch_stable.html
pip install git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch
Installing nerfstudio
Easy option:
pip install nerfstudio
If you would want the latest and greatest:
git clone git@github.com:plenoptix/nerfstudio.git
cd nerfstudio
pip install -e .
Optional Installs
Tab completion (bash & zsh)
This needs to be rerun when the CLI changes, for example if nerfstudio is updated.
ns-install-cli
Development packages
pip install -e.[dev]
pip install -e.[docs]
Downloading data
Download the original NeRF Blender dataset. We support the major datasets and allow users to create their own dataset, described in detail here.
ns-download-data --dataset=blender
ns-download-data --dataset=nerfstudio --capture=poster
Use --help to view all currently available datasets. The resulting script should download and unpack the dataset as follows:
|─ nerfstudio/
├─ data/
| ├─ blender/
| ├─ fern/
| ├─ lego/
...
|- <dataset_format>/
|- <scene>
...
Training a model
To run with all the defaults, e.g. vanilla nerf method with the blender lego image
Run a vanilla nerf model.
ns-train vanilla-nerf
Run a nerfacto model.
ns-train nerfacto
Run with nerfstudio data. You'll may have to change the ports, and be sure to forward the "websocket-port".
ns-train nerfacto --vis viewer --viewer.zmq-port 8001 --viewer.websocket-port 8002 nerfactory-data --pipeline.datamanager.dataparser.data-directory data/nerfstudio/poster --pipeline.datamanager.dataparser.downscale-factor 4
Visualizing training runs
If you using a fast NeRF variant (ie. Instant-NGP), we reccomend using our viewer. See our viewer docs for more details. The viewer will allow interactive visualization of training in realtime.
Additionally, if you run everything with the default configuration, by default, we use TensorBoard to log all training curves, test images, and other stats. Once the job is launched, you will be able to track training by launching the tensorboard in outputs/blender_lego/vanilla_nerf/<timestamp>/<events.tfevents>.
tensorboard --logdir outputs
Rendering a Trajectory
To evaluate the trained NeRF, we provide an evaluation script that allows you to do benchmarking (see our benchmarking workflow) or to render out the scene with a custom trajectory and save the output to a video.
ns-eval render-trajectory --load-config=outputs/blender_lego/instant_ngp/2022-07-07_230905/config.yml --traj=spiral --output-path=output.mp4
Please note, this quickstart allows you to preform everything in a headless manner. We also provide a web-based viewer that allows you to easily monitor training or render out trajectories. See our viewer docs for more.
FAQ
(tiny-cuda-error)=
TinyCUDA installation errors out with cuda mismatch
While installing tiny-cuda, you run into: The detected CUDA version mismatches the version that was used to compile PyTorch (10.2). Please make sure to use the same CUDA versions.
Solution:
pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 -f https://download.pytorch.org/whl/torch_stable.html
(pip-install-error)=
Installation errors, File "setup.py" not found
When installing dependencies and nerfstudio with pip install -e ., you run into: ERROR: File "setup.py" not found. Directory cannot be installed in editable mode
Solution: This can be fixed by upgrading pip to the latest version:
python -m pip install --upgrade pip
(cuda-sources-error)=
Runtime errors, "len(sources) > 0".
When running train.py , an error occurs when installing cuda files in the backend code.
Solution: This is a problem with not being able to detect the correct CUDA version, and can be fixed by updating the CUDA path environment variables:
export CUDA_HOME=/usr/local/cuda
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/cuda/lib64:/usr/local/cuda/extras/CUPTI/lib64
export PATH=$PATH:$CUDA_HOME/bin