From 50b9ee83a15bc4cc3ce2d5fa856aa359c4c77817 Mon Sep 17 00:00:00 2001 From: evonneng Date: Tue, 4 Oct 2022 01:02:26 -0700 Subject: [PATCH] added config docs (#644) * added config docs * fixed first_nerf --- docs/developer_guides/config.md | 106 +++++++++++++++++++++++++++++- docs/quickstart/first_nerf.md | 61 +++++++++++++---- docs/reference/contributing.md | 28 ++++++-- nerfstudio/configs/base_config.py | 7 +- 4 files changed, 181 insertions(+), 21 deletions(-) diff --git a/docs/developer_guides/config.md b/docs/developer_guides/config.md index 1a3c6d86e..f2d07b0b4 100644 --- a/docs/developer_guides/config.md +++ b/docs/developer_guides/config.md @@ -1 +1,105 @@ -# Customizable Configs \ No newline at end of file +# Customizable configs + +Our python dataclass configs allow you to easily plug in different permutations of models, dataloaders, modules, etc. +and modify all parameters from a typed CLI supported by [dcargs](https://pypi.org/project/dcargs/). + +### Base components + +All basic, reusable config components can be found in `nerfstudio/configs/base_config.py`. The `Config` class at the bottom of the file is the upper-most config level and stores all of the sub-configs needed to get started with training. + +You can browse this file and read the attribute annotations to see what configs are available and what each specifies. + +### Creating new configs + +If you are interested in creating a brand new model or data format, you will need to create a corresponding config with associated parameters you want to expose as configurable. + +Let's say you want to create a new model called Nerfacto. You can create a new `Model` class that extends the base class as described [here](pipelines/models.ipynb). Before the model definition, you define the actual `NerfactoModelConfig` which points to the `NerfactoModel` class (make sure to wrap the `_target` classes in a `field` as shown below). + +:::{admonition} Tip +:class: info + +You can then enable type/auto complete on the config passed into the `NerfactoModel` by specifying the config type below the class definition. + ::: + +```python +"""nerfstudio/models/nerfacto.py""" + +@dataclass +class NerfactoModelConfig(ModelConfig): + """Nerfacto Model Config""" + + _target: Type = field(default_factory=lambda: NerfactoModel) + ... + +class NerfactoModel(Model): + """Nerfacto model + + Args: + config: Nerfacto configuration to instantiate model + """ + + config: NerfactoModelConfig + ... +``` + +The same logic applies to all other custom configs you want to create. For more examples, you can see `nerfstudio/data/dataparsers/nerfstudio_dataparsers.py`, `nerfstudio/data/datamanagers.py`. + +:::{admonition} See Also +:class: seealso + +For how to create the actual data and model classes that follow the configs, please refer to [pipeline overview](pipelines/index.rst). + ::: + +### Updating model configs + +If you are interested in creating a new model config, you will have to modify the `nerfstudio/configs/model_configs.py` file. This is where all of the configs for implemented models are housed. You can browse this file to see how we construct various existing models by modifying the `Config` class and specifying new or modified default components. + +For instance, say we created a brand new model called Nerfacto that has an associated `NerfactoModelConfig`, we can specify the following new Config by overriding the pipeline and optimizers attributes appropriately. + +```python +"""nerfstudio/configs/model_configs.py""" + +model_configs["nerfacto"] = Config( + method_name="nerfacto", + pipeline=VanillaPipelineConfig( + model=NerfactoModelConfig(eval_num_rays_per_chunk=1 << 14), + ), + optimizers={ + "proposal_networks": { + "optimizer": AdamOptimizerConfig(lr=1e-2, eps=1e-15), + "scheduler": None, + }, + "fields": { + "optimizer": AdamOptimizerConfig(lr=1e-2, eps=1e-15), + "scheduler": None, + }, + }, +) +``` + +After placing your new `Config` class into the `model_configs` dictionary, you can provide a description for the model by updating the `descriptions` dictionary at the top of the file. + + +### Modifying from CLI +Often times, you just want to play with the parameters of an existing model without having to specify a new one. You can easily do so via CLI. Below, we showcase some useful CLI commands. + +```bash +# list out all existing models +ns-train --help + +# list out all exist configurable parameters for {MODEL_NAME} +ns-train {MODEL_NAME} --help + +# change the train/eval dataset +ns-train {MODEL_NAME} --data DATA_PATH + +# enable the viewer +ns-train {MODEL_NAME} --vis viewer + +# see what options are available for the specified dataparser (e.g. blender-data) +ns-train {MODEL_NAME} {DATA_PARSER} --help + +# run with changed dataparser attributes and viewer on +# NOTE: the dataparser and associated configurations go at the end of the command +ns-train {MODEL_NAME} --vis viewer {DATA_PARSER} --scale-factor 0.5 +``` diff --git a/docs/quickstart/first_nerf.md b/docs/quickstart/first_nerf.md index e45cc2d53..3c3cc6167 100644 --- a/docs/quickstart/first_nerf.md +++ b/docs/quickstart/first_nerf.md @@ -2,14 +2,20 @@ ## 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 TODO]. +Download datasets provided by nerfstudio. We support the major datasets and allow users to create their own dataset, described in detail [here](./custom_dataset.md). ``` 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: +:::{admonition} Tip +:class: info + +Use `ns-download-data --help` to view all currently available datasets. + ::: + +The resulting script should download and unpack the dataset as follows: ``` |─ nerfstudio/ @@ -25,7 +31,10 @@ Use `--help` to view all currently available datasets. The resulting script shou ## Training a model -To run with all the defaults, e.g. vanilla nerf method with the blender lego image +See which models are available. +```bash +ns-train --help +``` Run a vanilla nerf model. @@ -39,28 +48,56 @@ 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". - +Run with nerfstudio data with our web-based viewer enabled. ``` ns-train nerfacto --vis viewer --viewer.zmq-port 8001 --viewer.websocket-port 8002 nerfstudio-data --pipeline.datamanager.dataparser.data-directory data/nerfstudio/poster --pipeline.datamanager.dataparser.downscale-factor 4 ``` +:::{admonition} Warning +:class: warning + +* You may have to change the ports, and be sure to forward the "websocket-port". +* All data configurations must go at the end. In this case, `nerfstudio-data` and all of its corresponding configurations come at the end after the model and viewer specification. + ::: + ## Visualizing training runs -If you are using a fast NeRF variant (ie. Instant-NGP), we recommend using our viewer. See our [viewer docs](viewer_quickstart.md) for more details. The viewer will allow interactive visualization of training in realtime. +If you are using a fast NeRF variant (ie. Nerfacto/Instant-NGP), we recommend using our viewer. See our [viewer docs](viewer_quickstart.md) for a tutorial on using the viewer. The viewer will allow interactive, real-time visualization of training. -Additionally, if you run everything with the default configuration, by default, we use [TensorBoard](https://www.tensorflow.org/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//`. +For slower methods where the viewer is not recommended, we default to [Wandb](https://wandb.ai/site) to log all training curves, test images, and other stats. We also support logging with [Tensorboard](https://www.tensorflow.org/tensorboard). We pre-specify default `--vis` options depending on the model. + +:::{admonition} Attention +:class: attention + +- Currently we only support using a single viewer at a time. +- To toggle between Wandb, Tensorboard, or our Web-based Viewer, you can specify `--vis VIS_OPTION`, where `VIS_OPTION` is one of {viewer,wandb,tensorboard}. + ::: + +#### Rendering videos +We also provide options to render out the scene of a trained model with a custom trajectory and save the output to a video. ```bash -tensorboard --logdir outputs +ns-render --load-config={PATH_TO_CONFIG} --traj=spiral --output-path=output.mp4 ``` -## Rendering a Trajectory +While we provide pre-specified trajectory options, `--traj={spiral, interp, filename}` we can also specify a custom trajectory if we specify `--traj=filename --camera-path-filename {PATH}`. -To evaluate the trained NeRF, we provide an evaluation script that allows you to do benchmarking (see our [benchmarking workflow](../developer_guides/benchmarking.md)) or to render out the scene with a custom trajectory and save the output to a video. +:::{admonition} Tip +:class: info +After running the training, the config path is logged to the terminal under "[base_config.py:263] Saving config to:" + ::: +:::{admonition} See Also +:class: seealso +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 custom trajectories. +See our [viewer docs](viewer_quickstart.md) for more. + ::: + +## Evaluating Runs +Calculate the psnr of your trained model and save to a json file. ```bash -ns-render --load-config=outputs/blender_lego/instant_ngp/2022-07-07_230905/config.yml --traj=spiral --output-path=output.mp4 +ns-eval --load-config={PATH_TO_CONFIG} --output-path=output.json ``` -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. +We also provide a train and evaluation script that allows you to do benchmarking on the classical Blender dataset (see our [benchmarking workflow](../developer_guides/benchmarking.md)). \ No newline at end of file diff --git a/docs/reference/contributing.md b/docs/reference/contributing.md index 5dd972336..0599cd7c6 100644 --- a/docs/reference/contributing.md +++ b/docs/reference/contributing.md @@ -33,8 +33,8 @@ conda install -c conda-forge pandoc ## 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: @@ -48,10 +48,13 @@ conda install -c conda-forge pandoc - 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. + + :::{admonition} Attention + :class: attention + 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! 💌 ## Maintaining documentation @@ -63,12 +66,23 @@ Run the following to build the documentation: python scripts/docs/build_docs.py ``` -Rerun `make html` when documentation changes are made, `make clean` is necessary if the documentation structure changes. +:::{admonition} Tip +:class: info + +- Rerun `make html` when documentation changes are made +- make clean` is necessary if the documentation structure changes. + ::: ### 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. +If you want the code to build on save you can use [sphinx autobuild](https://github.com/executablebooks/sphinx-autobuild). + +:::{admonition} Tip +:class: info + +If changes to the structure are made, the build files may be incorrect. + ::: ```bash pip install sphinx-autobuild diff --git a/nerfstudio/configs/base_config.py b/nerfstudio/configs/base_config.py index 8da7a6849..58785a13f 100644 --- a/nerfstudio/configs/base_config.py +++ b/nerfstudio/configs/base_config.py @@ -192,10 +192,15 @@ class Config(PrintableConfig): timestamp: str = "{timestamp}" """Experiment timestamp.""" machine: MachineConfig = MachineConfig() + """Machine configuration""" logging: LoggingConfig = LoggingConfig() + """Logging configuration""" viewer: ViewerConfig = ViewerConfig() + """Viewer configuration""" trainer: TrainerConfig = TrainerConfig() + """Trainer configuration""" pipeline: VanillaPipelineConfig = VanillaPipelineConfig() + """Pipeline configuration""" optimizers: Dict[str, Any] = to_immutable_dict( { "fields": { @@ -204,7 +209,7 @@ class Config(PrintableConfig): } } ) - """optionally specify a pre-defined config to load from""" + """Dictionary of optimizer groups and their schedulers""" vis: Literal["viewer", "wandb", "tensorboard"] = "wandb" """Which visualizer to use.""" data: Optional[Path] = None