From 1bb0c88fb57fa9300a5b32c4e9fe765fbac32447 Mon Sep 17 00:00:00 2001 From: Matthew Tancik Date: Fri, 30 Sep 2022 09:48:52 -0700 Subject: [PATCH] More renaming (#590) --- README.md | 86 ++++++++++--------- docs/tutorials/quickstart.md | 71 ++++++++------- nerfstudio/configs/base_configs.py | 8 +- .../models/{proposal.py => nerfacto.py} | 16 ++-- pyproject.toml | 10 ++- scripts/completions/install.py | 2 +- scripts/debugging/run_actions.py | 7 +- scripts/downloads/download_data.py | 14 +-- tests/test_run_train.py | 2 +- 9 files changed, 115 insertions(+), 101 deletions(-) rename nerfstudio/models/{proposal.py => nerfacto.py} (96%) diff --git a/README.md b/README.md index 022edac41..90ec6e6b0 100644 --- a/README.md +++ b/README.md @@ -60,13 +60,11 @@ We hope nerfstudio enables you to build faster :hammer: learn together :books: a The quickstart will help you get started with the default vanilla nerf trained on the classic blender lego scene. For more complex changes (e.g. running with your own data/ setting up a new NeRF graph, please refer to our [references](#learn-more). -#### 1. Installation: Setup the environment +## 1. Installation: Setup the environment -This repository is tested with CUDA 11.3. Make sure to install [Conda](https://docs.conda.io/en/latest/miniconda.html#linux-installers) before preceding. +### Create environment - - -Create the python environment +We reccomend using conda to manage dependencies. Make sure to install [Conda](https://docs.conda.io/en/latest/miniconda.html) before preceding. ``` conda create --name nerfstudio python=3.8.13 @@ -74,36 +72,46 @@ conda activate nerfstudio python -m pip install --upgrade pip ``` -Clone the repo +### Dependencies -``` -git clone git@github.com:plenoptix/nerfstudio.git -``` - -Install dependencies and nerfstudio as a library - -``` -cd nerfstudio -pip install -e . -``` - -Install tiny-cuda-nn (tcnn) to run instant_ngp +Install pytorch with CUDA (this repo has been tested with CUDA 11.3) and [tiny-cuda-nn](https://github.com/NVlabs/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 ``` -Install tab completion for nerfstudio (bash & zsh) +### Installing nerfstudio + +Easy option: ``` -nf-install-cli +pip install nerfstudio ``` -Run the test cases +If you would want the latest and greatest: ``` -pytest tests +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. + +```bash +ns-install-cli +``` + +**Development packages** + +```bash +pip install -e.[dev] +pip install -e.[docs] ``` #### 2. Getting the data @@ -111,7 +119,7 @@ pytest tests Download the original NeRF Blender dataset. We support the major datasets and allow users to create their own dataset, described in detail [here](https://plenoptix-nerfstudio.readthedocs-hosted.com/en/latest/tutorials/data/index.html). ``` -python scripts/downloads/download_data.py --dataset=blender +ns-download-data --dataset=blender ``` Use `--help` to view all currently available datasets. The resulting script should download and unpack the dataset as follows: @@ -128,40 +136,34 @@ Use `--help` to view all currently available datasets. The resulting script shou ... ``` -#### 3. Training a model +## 3. Training a model To run with all the defaults, e.g. vanilla nerf method with the blender lego image ``` # To see what models are available. -python scripts/train.py --help +ns-train --help # Run a vanilla nerf model. -python scripts/train.py vanilla_nerf +ns-train vanilla-nerf -# Run a faster version with instant ngp using tcnn (without the viewer). -python scripts/train.py instant_ngp +# +ns-train nerfacto ``` -#### 3.x Training a model with the viewer +### 3.x Training a model with the viewer Make sure to forward a port for the websocket to localhost. The default port is 7007, which you should be expose to localhost:7007. ```bash # with the default port -python scripts/train.py instant_ngp --viewer.enable +ns-train nerfacto --vis viewer # with a specified websocket port -python scripts/train.py instant_ngp --viewer.enable --viewer.websocket-port=7008 - -# with the viewer bridge server as a separate process -# in one terminal, start the bridge server: -viewer-bridge-server # or equivalently, python scripts/run_viewer_bridge_server.py -# in another terminal, start training: -python scripts/train.py instant_ngp --viewer.enable --viewer.no-launch-bridge-server +ns-train nerfacto --vis viewer --viewer.websocket-port=7008 ``` -#### 4. Visualizing training runs +### 4. Visualizing training runs We support multiple methods to visualize training, the default configuration uses Tensorboard. More information on logging can be found [here](https://plenoptix-nerfactory.readthedocs-hosted.com/en/latest/tooling/logging_profiling.html). @@ -170,7 +172,7 @@ We support multiple methods to visualize training, the default configuration use We have developed our own Real-time web viewer, more information can be found [here](https://plenoptix-nerfactory.readthedocs-hosted.com/en/latest/tutorials/viewer/index.html). This viewer runs during training and is designed to work with models that have fast rendering pipelines. -To turn on the viewer, simply add the flag `--viewer.enable`. +To turn on the viewer, simply add the flag `--vis viewer`. @@ -192,13 +194,13 @@ We support logging to weights and biases. To enable wandb logging, add the flag -#### 5. Rendering a trajectories during inference +## 5. Rendering a trajectories during inference ``` -python scripts/eval.py render-trajectory --load-config=outputs/blender_lego/instant_ngp/2022-07-07_230905/config.yml--traj=spiral --output-path=output.mp4 +ns-eval render-trajectory --load-config=outputs/blender_lego/instant_ngp/2022-07-07_230905/config.yml--traj=spiral --output-path=output.mp4 ``` -#### 6. In-depth guide +## 6. In-depth guide For a more in-depth tutorial on how to modify/implement your own NeRF Graph, please see our [walk-through](https://plenoptix-nerfactory.readthedocs-hosted.com/en/latest/tutorials/pipelines/index.html). diff --git a/docs/tutorials/quickstart.md b/docs/tutorials/quickstart.md index 0d7432977..e74efc9c6 100644 --- a/docs/tutorials/quickstart.md +++ b/docs/tutorials/quickstart.md @@ -1,10 +1,8 @@ # Installation -This repository is tested with CUDA 11.3. Make sure to install [Conda](https://docs.conda.io/en/latest/miniconda.html#linux-installers) before preceding. +### Create environment - - -Create the python environment +We reccomend 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 python=3.8.13 @@ -12,31 +10,46 @@ conda activate nerfstudio python -m pip install --upgrade pip ``` -Clone the repo +### Dependencies -```bash -git clone git@github.com:plenoptix/nerfstudio.git -``` - -Install dependencies and nerfstudio as a library - -```bash -cd nerfstudio -pip install -e . -``` - -Install tiny-cuda-nn (tcnn) to run instant_ngp +Install pytorch with CUDA (this repo has been tested with CUDA 11.3) and [tiny-cuda-nn](https://github.com/NVlabs/tiny-cuda-nn) ```bash 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 ``` -Install tab completion for nerfstudio (bash and zsh) +### Installing nerfstudio + +Easy option: ```bash -# If the CLI changes, we can also re-install to synchronize completions -nf-install-cli +pip install nerfstudio +``` + +If you would want the latest and greatest: + +```bash +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. + +```bash +ns-install-cli +``` + +### Development packages + +```bash +pip install -e.[dev] +pip install -e.[docs] ``` # Downloading data @@ -44,7 +57,7 @@ nf-install-cli Download the original NeRF Blender dataset. We support the major datasets and allow users to create their own dataset, described in detail [here](https://plenoptix-nerfactory.readthedocs-hosted.com/en/latest/tutorials/data/index.html). ``` -python scripts/downloads/download_data.py --dataset=blender +ns-download-data --dataset=blender ``` Use `--help` to view all currently available datasets. The resulting script should download and unpack the dataset as follows: @@ -68,23 +81,15 @@ To run with all the defaults, e.g. vanilla nerf method with the blender lego ima Run a vanilla nerf model. ```bash -python scripts/train.py +ns-train vanilla-nerf ``` -Run a faster version with instant ngp using tcnn (without the viewer). +Run a vanilla nerf model. ```bash -python scripts/train.py --config-name=graph_instant_ngp.yaml +ns-train nerfacto ``` -Run with the viewer. However, you'll have to start the viewer server first. (See [viewer docs](../tutorials/viewer/viewer_quickstart.md)) - -```bash -python scripts/train.py --config-name=graph_instant_ngp.yaml viewer.enable=true -``` - -With support for [Hydra](https://hydra.cc/), you can run with other configurations by changing appropriate configs defined in `configs/` or by setting flags via command-line arguments. - # Visualizing training runs If you using a fast NeRF variant (ie. Instant-NGP), we reccomend using our viewer. See our [viewer docs](../tutorials/viewer/viewer_quickstart.md) for more details. The viewer will allow interactive visualization of training in realtime. @@ -100,7 +105,7 @@ tensorboard --logdir outputs To evaluate the trained NeRF, we provide an evaluation script that allows you to do benchmarking (see our [benchmarking workflow](../tooling/benchmarking.md)) or to render out the scene with a custom trajectory and save the output to a video. ```bash -python scripts/eval.py render-trajectory --load-config=outputs/blender_lego/instant_ngp/2022-07-07_230905/config.yml --traj=spiral --output-path=output.mp4 +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](../tutorials/viewer/viewer_quickstart.md) for more. diff --git a/nerfstudio/configs/base_configs.py b/nerfstudio/configs/base_configs.py index 4da600de6..d6ed8fae6 100644 --- a/nerfstudio/configs/base_configs.py +++ b/nerfstudio/configs/base_configs.py @@ -40,8 +40,8 @@ from nerfstudio.models.base import VanillaModelConfig from nerfstudio.models.instant_ngp import InstantNGPModelConfig from nerfstudio.models.mipnerf import MipNerfModel from nerfstudio.models.mipnerf_360 import MipNerf360Model +from nerfstudio.models.nerfacto import NerfactoModelConfig from nerfstudio.models.nerfw import NerfWModelConfig -from nerfstudio.models.proposal import ProposalModelConfig from nerfstudio.models.semantic_nerf import SemanticNerfModel from nerfstudio.models.tensorf import TensoRFModelConfig from nerfstudio.models.vanilla_nerf import NeRFModel @@ -50,14 +50,14 @@ from nerfstudio.pipelines.dynamic_batch import DynamicBatchPipelineConfig base_configs: Dict[str, Config] = {} -base_configs["proposal"] = Config( - method_name="proposal", +base_configs["nerfacto"] = Config( + method_name="nerfacto", trainer=TrainerConfig(steps_per_eval_batch=500, steps_per_save=2000, mixed_precision=True), pipeline=VanillaPipelineConfig( datamanager=VanillaDataManagerConfig( dataparser=BlenderDataParserConfig(), train_num_rays_per_batch=4096, eval_num_rays_per_batch=8192 ), - model=ProposalModelConfig(eval_num_rays_per_chunk=1 << 16), + model=NerfactoModelConfig(eval_num_rays_per_chunk=1 << 16), ), optimizers={ "proposal_networks": { diff --git a/nerfstudio/models/proposal.py b/nerfstudio/models/nerfacto.py similarity index 96% rename from nerfstudio/models/proposal.py rename to nerfstudio/models/nerfacto.py index a329409ac..cf4730dc3 100644 --- a/nerfstudio/models/proposal.py +++ b/nerfstudio/models/nerfacto.py @@ -13,7 +13,7 @@ # limitations under the License. """ -Implementation of Instant NGP. +NeRF implementation that combines many recent advancements. """ from __future__ import annotations @@ -51,10 +51,10 @@ from nerfstudio.utils.callbacks import ( @dataclass -class ProposalModelConfig(ModelConfig): - """Proposal Model Config""" +class NerfactoModelConfig(ModelConfig): + """Nerfacto Model Config""" - _target: Type = field(default_factory=lambda: ProposalModel) + _target: Type = field(default_factory=lambda: NerfactoModel) near_plane: float = 0.05 """How far along the ray to start sampling.""" far_plane: float = 1000.0 @@ -87,14 +87,14 @@ class ProposalModelConfig(ModelConfig): """Whether use single jitter or not for first proposal network.""" -class ProposalModel(Model): - """Instant NGP model +class NerfactoModel(Model): + """Nerfacto model Args: - config: instant NGP configuration to instantiate model + config: Nerfacto configuration to instantiate model """ - config: ProposalModelConfig + config: NerfactoModelConfig def populate_modules(self): """Set the fields and modules.""" diff --git a/pyproject.toml b/pyproject.toml index 813ae74cd..7e7041805 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -74,10 +74,12 @@ docs = [ ] [project.scripts] -nf-install-cli = "scripts.completions.install:entrypoint" -nf-process-data = "scripts.process_data:entrypoint" -nf-train = "scripts.train:entrypoint" -nf-eval = "scripts.eval:entrypoint" +ns-install-cli = "scripts.completions.install:entrypoint" +ns-process-data = "scripts.process_data:entrypoint" +ns-download-data = "scripts.downloads.download_data:entrypoint" +ns-train = "scripts.train:entrypoint" +ns-eval = "scripts.eval:entrypoint" +ns-dev-test = "scripts.debugging.run_actions:entrypoint" [options] # equivalent to using --extra-index-url with pip, which is needed for specifying the CUDA version torch and torchvision diff --git a/scripts/completions/install.py b/scripts/completions/install.py index e92a46909..8dc5fdaae 100755 --- a/scripts/completions/install.py +++ b/scripts/completions/install.py @@ -224,7 +224,7 @@ def main( .split("\n") ) entry_points = list( - # nf-train = "..." ==> nf-train + # ns-train = "..." ==> ns-train e.partition("=")[0].strip() for e in entry_points ) diff --git a/scripts/debugging/run_actions.py b/scripts/debugging/run_actions.py index 67421ddc1..3ecd622cc 100755 --- a/scripts/debugging/run_actions.py +++ b/scripts/debugging/run_actions.py @@ -86,6 +86,11 @@ def run_code_checks(continue_on_fail: bool = False): # run_github_actions_file(filename=".github/workflows/viewer_build_deploy.yml", continue_on_fail=continue_on_fail) -if __name__ == "__main__": +def entrypoint(): + """Entrypoint for use with pyproject scripts.""" dcargs.extras.set_accent_color("bright_yellow") dcargs.cli(run_code_checks) + + +if __name__ == "__main__": + entrypoint() diff --git a/scripts/downloads/download_data.py b/scripts/downloads/download_data.py index 64758c9e9..a4dafaf9f 100755 --- a/scripts/downloads/download_data.py +++ b/scripts/downloads/download_data.py @@ -100,11 +100,11 @@ def main( download_nerfactory(dataset_name) -if __name__ == "__main__": - try: - # Requires dcargs>=0.3.3. - dcargs.extras.set_accent_color("bright_yellow") - except AttributeError: - pass - +def entrypoint(): + """Entrypoint for use with pyproject scripts.""" + dcargs.extras.set_accent_color("bright_yellow") dcargs.cli(main) + + +if __name__ == "__main__": + entrypoint() diff --git a/tests/test_run_train.py b/tests/test_run_train.py index 87bed765a..cae0906b6 100644 --- a/tests/test_run_train.py +++ b/tests/test_run_train.py @@ -14,7 +14,7 @@ from nerfstudio.configs.base_configs import base_configs from nerfstudio.datamanagers.dataparsers.blender_parser import BlenderDataParserConfig from nerfstudio.engine.trainer import train_loop -BLACKLIST = ["base", "semantic-nerf", "mipnerf-360", "instant-ngp", "proposal"] +BLACKLIST = ["base", "semantic-nerf", "mipnerf-360", "instant-ngp", "nerfacto"] def set_reduced_config(config: Config):