Readme updates

Summary:
Running:
- clearly points users to experiment.py/visualize_reconstruction.py
Reproducing:
- Adds NeRF training on Blender
- Adds CO3Dv2 configs

Reviewed By: bottler

Differential Revision: D41534315

fbshipit-source-id: e85f5f1eafed8c35c9e91d748a04f238509cf8ec
This commit is contained in:
David Novotny 2022-11-30 07:02:01 -08:00 committed by Facebook GitHub Bot
parent a2c6af9250
commit 5add065f8a
3 changed files with 127 additions and 15 deletions

View File

@ -33,6 +33,7 @@ pip install "hydra-core>=1.1" visdom lpips matplotlib accelerate
Runner executable is available as `pytorch3d_implicitron_runner` shell command.
See [Running](#running) section below for examples of training and evaluation commands.
## [Option 2] Supporting custom implementations
To plug in custom implementations, for example, of renderer or implicit-function protocols, you need to create your own runner script and import the plug-in implementations there.
@ -55,11 +56,31 @@ pip install "hydra-core>=1.1" visdom lpips matplotlib accelerate
You are still encouraged to implement custom plugins as above where possible as it makes reusing the code easier.
The executable is located in `pytorch3d/projects/implicitron_trainer`.
> **_NOTE:_** Both `pytorch3d_implicitron_runner` and `pytorch3d_implicitron_visualizer`
executables (mentioned below) are not available when using local clone.
Instead users should use the python scripts `experiment.py` and `visualize_reconstruction.py` (see the [Running](Running) section below).
# Running
This section assumes that you use the executable provided by the installed package.
If you have a custom `experiment.py` script (as in the Option 2 above), replace the executable with the path to your script.
This section assumes that you use the executable provided by the installed package
(Option 1 / Option 2 in [#Installation](Installation) above),
i.e. `pytorch3d_implicitron_runner` and `pytorch3d_implicitron_visualizer` are available.
> **_NOTE:_** If the executables are not available (e.g. when using a local clone - Option 3 in [#Installation](Installation)),
users should directly use the `experiment.py` and `visualize_reconstruction.py` python scripts
which correspond to the executables as follows:
- `pytorch3d_implicitron_runner` corresponds to `<pytorch3d_root>/projects/implicitron_trainer/experiment.py`
- `pytorch3d_implicitron_visualizer` corresponds to `<pytorch3d_root>/projects/implicitron_trainer/visualize_reconstruction.py`
For instance, in order to directly execute training with the python script, users can call:
```shell
cd <pytorch3d_root>/projects/ \
python -m implicitron_trainer.experiment <args>`
```
If you have a custom `experiment.py` or `visualize_reconstruction.py` script
(as in the Option 2 [above](#Installation)), replace the executable with the path to your script.
## Training
@ -80,6 +101,13 @@ and `<CHECKPOINT_DIR>` with a directory where checkpoints will be dumped during
Other configuration parameters can be overridden in the same way.
See [Configuration system](#configuration-system) section for more information on this.
### Visdom logging
Note that the training script logs its progress to Visdom. Make sure to start a visdom server before the training commences:
```
python -m visdom.server
```
> In case a Visdom server is not started, the console will get flooded with `requests.exceptions.ConnectionError` errors signalling that a Visdom server is not available. Note that these errors <b>will NOT interrupt</b> the program and the training will still continue without issues.
## Evaluation
@ -105,14 +133,14 @@ conda install ffmpeg
Here is an example of calling the script:
```shell
projects/implicitron_trainer/visualize_reconstruction.py exp_dir=<CHECKPOINT_DIR> \
pytorch3d_implicitron_visualizer exp_dir=<CHECKPOINT_DIR> \
visdom_show_preds=True n_eval_cameras=40 render_size="[64,64]" video_size="[256,256]"
```
The argument `n_eval_cameras` sets the number of renderring viewpoints sampled on a trajectory, which defaults to a circular fly-around;
`render_size` sets the size of a render passed to the model, which can be resized to `video_size` before writing.
Rendered videos of images, masks, and depth maps will be saved to `<CHECKPOINT_DIR>/vis`.
Rendered videos of images, masks, and depth maps will be saved to `<CHECKPOINT_DIR>/video`.
# Configuration system
@ -127,8 +155,11 @@ Configurables can form hierarchies.
For example, `GenericModel` has a field `raysampler: RaySampler`, which is also Configurable.
In the config, inner parameters can be propagated using `_args` postfix, e.g. to change `raysampler.n_pts_per_ray_training` (the number of sampled points per ray), the node `raysampler_args.n_pts_per_ray_training` should be specified.
The root of the hierarchy is defined by `ExperimentConfig` dataclass.
It has top-level fields like `eval_only` which was used above for running evaluation by adding a CLI override.
### Top-level configuration class: `Experiment`
<b>The root of the hierarchy is defined by `Experiment` Configurable in `<pytorch3d_root>/projects/implicitron_trainer/experiment.py`.</b>
It has top-level fields like `seed`, which seeds the random number generator.
Additionally, it has non-leaf nodes like `model_factory_ImplicitronModelFactory_args.model_GenericModel_args`, which dispatches the config parameters to `GenericModel`.
Thus, changing the model parameters may be achieved in two ways: either by editing the config file, e.g.
```yaml
@ -266,14 +297,66 @@ model_GenericModel_args: GenericModel
Please look at the annotations of the respective classes or functions for the lists of hyperparameters.
`tests/experiment.yaml` shows every possible option if you have no user-defined classes.
# Reproducing CO3D experiments
# Implementations of existing methods
We provide configuration files that implement several existing works.
<b>The configuration files live in `pytorch3d/projects/implicitron_trainer/configs`.</b>
## NeRF
The following config file corresponds to training of a vanilla NeRF on Blender Synthetic dataset
(see https://arxiv.org/abs/2003.08934 for details of the method):
`./configs/repro_singleseq_nerf_blender.yaml`
### Downloading Blender-Synthetic
Training requires the Blender Synthetic dataset.
To download the dataset, visit the [gdrive bucket](https://drive.google.com/file/d/18JxhpWD-4ZmuFKLzKlAw-w5PpzZxXOcG/view?usp=share_link)
and click Download.
Then unpack the downloaded .zip file to a folder which we call `<BLENDER_DATASET_ROOT_FOLDER>`.
### Launching NeRF training
In order to train NeRF on the "drums" scene, execute the following command:
```shell
export BLENDER_DATASET_ROOT="<BLENDER_DATASET_ROOT_FOLDER>" \
export BLENDER_SINGLESEQ_CLASS="drums" \
pytorch3d_implicitron_runner --config-path ./configs/ --config-name repro_singleseq_nerf_blender
```
Note that the training scene is selected by setting the environment variable `BLENDER_SINGLESEQ_CLASS`
appropriately (one of `"chair"`, `"drums"`, `"ficus"`, `"hotdog"`, `"lego"`, `"materials"`, `"mic"`, `"ship"`).
By default, the training outputs will be stored to `"./data/nerf_blender_repro/$BLENDER_SINGLESEQ_CLASS/"`
### Visualizing trained NeRF
```shell
pytorch3d_implicitron_visualizer exp_dir=<CHECKPOINT_DIR> \
visdom_show_preds=True n_eval_cameras=40 render_size="[64,64]" video_size="[256,256]"
```
where `<CHECKPOINT_DIR>` corresponds to the directory with the training outputs (defaults to `"./data/nerf_blender_repro/$BLENDER_SINGLESEQ_CLASS/"`).
The script will output a rendered video of the learned radiance field to `"./data/nerf_blender_repro/$BLENDER_SINGLESEQ_CLASS/"` (requires `ffmpeg`).
> **_NOTE:_** Recall that, if `pytorch3d_implicitron_runner`/`pytorch3d_implicitron_visualizer` are not available, replace the calls
with `cd <pytorch3d_root>/projects/; python -m implicitron_trainer.[experiment|visualize_reconstruction]`
## CO3D experiments
Common Objects in 3D (CO3D) is a large-scale dataset of videos of rigid objects grouped into 50 common categories.
Implicitron provides implementations and config files to reproduce the results from [the paper](https://arxiv.org/abs/2109.00512).
Please follow [the link](https://github.com/facebookresearch/co3d#automatic-batch-download) for the instructions to download the dataset.
In training and evaluation scripts, use the download location as `<DATASET_ROOT>`.
It is also possible to define environment variable `CO3D_DATASET_ROOT` instead of specifying it.
To reproduce the experiments from the paper, use the following configs. For single-sequence experiments:
To reproduce the experiments from the paper, use the following configs.
For single-sequence experiments:
| Method | config file |
|-----------------|-------------------------------------|
@ -286,7 +369,7 @@ To reproduce the experiments from the paper, use the following configs. For sing
| SRN + WCE | repro_singleseq_srn_wce_noharm.yaml |
| SRN + WCE + γ | repro_singleseq_srn_wce_noharm.yaml |
For multi-sequence experiments (without generalisation to new sequences):
For multi-sequence autodecoder experiments (without generalization to new sequences):
| Method | config file |
|-----------------|--------------------------------------------|
@ -294,7 +377,7 @@ For multi-sequence experiments (without generalisation to new sequences):
| SRN + AD | repro_multiseq_srn_ad_hypernet_noharm.yaml |
| SRN + γ + AD | repro_multiseq_srn_ad_hypernet.yaml |
For multi-sequence experiments (with generalisation to new sequences):
For multi-sequence experiments (with generalization to new sequences):
| Method | config file |
|-----------------|--------------------------------------|
@ -302,3 +385,36 @@ For multi-sequence experiments (with generalisation to new sequences):
| NerFormer | repro_multiseq_nerformer.yaml |
| SRN + WCE | repro_multiseq_srn_wce_noharm.yaml |
| SRN + WCE + γ | repro_multiseq_srn_wce.yaml |
## CO3Dv2 experiments
The following config files implement training on the second version of CO3D, `CO3Dv2`.
In order to launch trainings, set the `CO3DV2_DATASET_ROOT` environment variable
to the root folder of the dataset (note that the name of the env. variable differs from the CO3Dv1 version).
Single-sequence experiments:
| Method | config file |
|-----------------|-------------------------------------|
| NeRF | repro_singleseq_v2_nerf.yaml |
| NerFormer | repro_singleseq_v2_nerformer.yaml |
| IDR | repro_singleseq_v2_idr.yaml |
| SRN | repro_singleseq_v2_srn_noharm.yaml |
Multi-sequence autodecoder experiments (without generalization to new sequences):
| Method | config file |
|-----------------|--------------------------------------------|
| NeRF + AD | repro_multiseq_v2_nerf_ad.yaml |
| SRN + γ + AD | repro_multiseq_v2_srn_ad_hypernet.yaml |
Multi-sequence experiments (with generalization to new sequences):
| Method | config file |
|-----------------|----------------------------------------|
| NeRF + WCE | repro_multiseq_v2_nerf_wce.yaml |
| NerFormer | repro_multiseq_v2_nerformer.yaml |
| SRN + WCE | repro_multiseq_v2_srn_wce_noharm.yaml |
| SRN + WCE + γ | repro_multiseq_v2_srn_wce.yaml |

View File

@ -7,7 +7,7 @@ data_source_ImplicitronDataSource_args:
dataset_length_train: 100
dataset_map_provider_class_type: BlenderDatasetMapProvider
dataset_map_provider_BlenderDatasetMapProvider_args:
base_dir: ${oc.env:BLENDER_DATASET_ROOT}
base_dir: ${oc.env:BLENDER_DATASET_ROOT}/${oc.env:BLENDER_SINGLESEQ_CLASS}
n_known_frames_for_test: null
object_name: ${oc.env:BLENDER_SINGLESEQ_CLASS}
path_manager_factory_class_type: PathManagerFactory

View File

@ -19,10 +19,6 @@ from the command line, for example:
./experiment.py --config-name base_config.yaml override.param.one=42 override.param.two=84
```
To run an experiment on a specific GPU, specify the `gpu_idx` key in the
config file / CLI. To run on a different device, specify the device in
`run_training`.
Main functions
---------------
- The Experiment class defines `run` which creates the model, optimizer, and other