update quickstart + readme (#641)

* updated quickstart and readme

* damn ctrl c on macs
This commit is contained in:
evonneng authored and GitHub committed 2022-10-03 22:38:43 -07:00
1 parent 5c3e1e8bb7
commit 5e56e7b229
7 files changed
+140 -174

No files matched your search

+3 -2
View File
@@ -27,7 +27,8 @@ It's as simple as plug and play with nerfstudio!
Ontop of our API, we are commited to providing learning resources to help you understand the basics of (if you're just getting start), and keep up-to-date with (if you're a seasoned veteran) all things NeRF.
As researchers, we know just how hard it is to get onboarded with this next-gen technology. So we're here to help with tutorials, documentation, and more!
Finally, have feature requests? Want to add your brand-spankin'-new NeRF model? Have a new dataset? **We welcome any and all contributions!** Please do not hesitate to reach out to the nerfstudio team with any questions.
Finally, have feature requests? Want to add your brand-spankin'-new NeRF model? Have a new dataset? **We welcome any and all [contributions](https://docs.nerf.studio/en/latest/reference/contributing.html)!**
Please do not hesitate to reach out to the nerfstudio team with any questions via [Discord](https://discord.gg/NHGtYRAW).
We hope nerfstudio enables you to build faster 🔨 learn together 📚 and contribute to our NeRF community 💖.
@@ -111,7 +112,7 @@ Quicklinks
============================================================ ======================
`Github <https://github.com/nerfstudio-project/nerfstudio>`_ Official Github Repo
`Discord <https://discord.com/invite/NHGtYRAW>`_ Join Discord Community
`Web-based Viewer <https://viewer.nerf.studio/>`_ Web-based Nerf Viewer
`Viewer <https://viewer.nerf.studio/>`_ Web-based Nerf Viewer
============================================================ ======================
+2 -2
View File
@@ -1,8 +1,8 @@
# Using Custom Data
# Using custom data
Training model on existing datasets is only so fun. If you would like to train on self captured data you will need to process the data into an existing format. Specifically we need to know the camera poses for each image. [COLMAP](https://github.com/colmap/colmap) is a standard tool for extracting poses. It is possible to use other methods like [SLAM](https://en.wikipedia.org/wiki/Simultaneous_localization_and_mapping) or hardware recorded poses. We intend to add documentation for these other methods in the future.
## nerfstudio dataset
## Nerfstudio dataset
To assist running on custom data we have a script that will process a video or folder of images into a format that is compatible with nerfstudio. We use [COLMAP](https://colmap.github.io) and [FFmpeg](https://ffmpeg.org/download.html) in our data processing script, please have these installed. We have provided a quickstart to installing COLMAP below, FFmpeg can be downloaded from [here](https://ffmpeg.org/download.html)
+1 -48
View File
@@ -1,4 +1,4 @@
# Training First Model
# Training your first model
## Downloading data
@@ -64,50 +64,3 @@ ns-render --load-config=outputs/blender_lego/instant_ngp/2022-07-07_230905/confi
```
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](viewer_quickstart.md) for more.
## FAQ
- [TinyCUDA installation errors out with cuda mismatch](tiny-cuda-error)
- [Installation errors, File "setup.py" not found](pip-install-error)
- [Runtime errors, "len(sources) > 0".](cuda-sources-error)
(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", "ctype = \_C.ContractionType(type.value) ; TypeError: 'NoneType' object is not callable".
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
```
+54 -7
View File
@@ -1,8 +1,8 @@
# Installation
### Create environment
## Create environment
We reccomend using conda to manage dependencies. Make sure to install [Conda](https://docs.conda.io/en/latest/miniconda.html) before preceding.
We recommend using conda to manage dependencies. Make sure to install [Conda](https://docs.conda.io/en/latest/miniconda.html) before preceding.
```bash
conda create --name nerfstudio -y python=3.8.13
@@ -11,7 +11,7 @@ python -m pip install --upgrade pip
```
### Dependencies
## Dependencies
Install pytorch with CUDA (this repo has been tested with CUDA 11.3) and [tiny-cuda-nn](https://github.com/NVlabs/tiny-cuda-nn)
@@ -21,15 +21,15 @@ pip install git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/to
```
### Installing nerfstudio
## Installing nerfstudio
Easy option:
Pip package:
```bash
pip install nerfstudio
```
If you would want the latest and greatest:
If you want the latest and greatest:
```bash
git clone git@github.com:plenoptix/nerfstudio.git
@@ -38,7 +38,7 @@ pip install -e .
```
### Optional Installs
### Optional
#### Tab completion (bash & zsh)
@@ -54,3 +54,50 @@ ns-install-cli
pip install -e.[dev]
pip install -e.[docs]
```
## Installation FAQ
- [TinyCUDA installation errors out with cuda mismatch](tiny-cuda-error)
- [Installation errors, File "setup.py" not found](pip-install-error)
- [Runtime errors, "len(sources) > 0".](cuda-sources-error)
(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", "ctype = \_C.ContractionType(type.value) ; TypeError: 'NoneType' object is not callable".
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
```
+1 -1
View File
@@ -1 +1 @@
# Setting up Viewer
# Setting up viewer
+33 -31
View File
@@ -1,19 +1,20 @@
# Contributing to nerfstudio workflow
# Contributing
**We're excited to have you join the NerfStudio family!** :love_letter:
**💝 We're excited to have you join the nerfstudio family 💝**
Below, we document the contribution pipeline and good-to-knows for when you're ready to submit a PR. If you have any questions at all, please don't hesitate to reach out to us. We'd love to hear from you!
Below, we document the contribution pipeline and good-to-knows for when you're ready to submit a PR. If you have any questions at all, please don't hesitate to reach out to us on [Discord](https://discord.com/invite/NHGtYRAW). We'd love to hear from you!
The project is set up for development in VSCode, we recommend using it if you plan to contribute.
## TLDR
## Overview
Below are the various tooling features our team uses to maintain this codebase.
| | |
| --------------- | ------ |
| linter | Black |
| Testing | PyTest |
| Docs | Sphinx |
| Docstring style | Google |
| Tooling | Support |
| --------------- | ------------- |
| Linter | [Black](https://black.readthedocs.io/en/stable/) |
| Testing | [PyTest](https://docs.pytest.org/en/7.1.x/) |
| Docs | [Sphinx](https://www.sphinx-doc.org/en/master/) |
| Docstring style | [Google](https://google.github.io/styleguide/pyguide.html) |
## Requirements
@@ -30,10 +31,10 @@ You may also need to install [pandoc](https://pandoc.org/). If you are using `co
conda install -c conda-forge pandoc
```
## Committing
## Committing code
1. Make your modifications
2. Perform local checks
1. ✏️ Make your modifications
2. ✅ Perform local checks
To ensure that you will be passing all tests and checks on github, you will need to run the following command:
@@ -41,18 +42,18 @@ conda install -c conda-forge pandoc
ns-dev-test
```
This will perform the following checks and actions:
This will perform the following checks and actions:
- Black/ Linting style check: Ensure that the code is consistently and properly formatted.
- Pytests: Runs pytests locally to make sure the logic of any added code does not break existing logic.
- Documentation build: Builds the documentation locally to make sure none of the changes result in any warnings or errors in the docs.
- Licensing: automatically adds licensing headers to the correct files.
- Black/ Linting style check: Ensures code is consistently and properly formatted.
- Pytests: Runs pytests locally to make sure added code does not break existing logic.
- Documentation build: Builds docs locally. Ensures changes do not result in warnings/errors.
- Licensing: Automatically adds licensing headers to the correct files.
In order to merge changes to the code base, all of these checks must be passing. If you pass these tests locally, you will likely pass on github servers as well (results in a green checkmark next to your commit).
In order to merge changes to the code base, all of these checks must be passing. If you pass these tests locally, you will likely pass on github servers as well (results in a green checkmark next to your commit).
3. Open pull request
3. 💌 Open pull request!
## Documentation
## Maintaining documentation
### Building
@@ -64,7 +65,17 @@ python scripts/docs/build_docs.py
Rerun `make html` when documentation changes are made, `make clean` is necessary if the documentation structure changes.
### Notebooks
### Auto build
As you change or add models/components, the auto-generated [Reference API](https://docs.nerf.studio/en/latest/reference/api/index.html) may change.
If you want the code to build on save you can use [sphinx autobuild](https://github.com/executablebooks/sphinx-autobuild). If changes to the structure are made, the build files may be incorrect.
```bash
pip install sphinx-autobuild
sphinx-autobuild docs docs/_build/html
```
### Adding notebooks
We support jupyter notbooks in our documentation. To improve the readability, the following custom tags can be added to the top of each code cell to hide or collapse the code.
@@ -73,12 +84,3 @@ We support jupyter notbooks in our documentation. To improve the readability, th
| # HIDDEN | Hide code block and output |
| # COLLAPSED | Collapse the code in a dropdown but show the results |
| # OUTPUT_ONLY | Only show the cell's output |
### Auto build
If you want the code to build on save you can use [sphinx autobuild](https://github.com/executablebooks/sphinx-autobuild). If changes to the structure are made, the build files may be incorrect.
```bash
pip install sphinx-autobuild
sphinx-autobuild docs docs/_build/html
```