tink/nerfstudio
4
0 Fork 0
mirror of https://github.com/nerfstudio-project/nerfstudio.git synced 2026-11-14 03:44:02 +08:00
Code Activity

Reorganizing docs for pipeline restructure (#279)

Browse Source 
* starting docs for pipelines

* working on an example

* clearing output

* starting to implement config changes and add documentation

* removing diff

* format

* templated pipeline notebook a bit

* black
This commit is contained in:
Ethan Weber authored and GitHub committed 2022-08-16 12:10:24 -07:00
1 parent cdacfdaf2e
commit 6879a8a9bd
29 files changed
+619 -416
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/tutorials/pipelines/creating_models.ipynb
+229
View File
@@ -0,0 +1,229 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Developing Custom Models\n",
"\n",
"In this quick tour, we will walk you through the core of training and building any NeRFs with nerfactory.\n",
"\n",
"The entry point for training starts at `scripts/run_train.py`, which spawns instances of our `Trainer()` class (in `engine/trainer.py`). The `Trainer()` is responsible for setting up the datasets and NeRF graph depending on the config specified. It will then run the usual train/val routine for a config-specified number of iterations. If you are planning on using our codebase to build a new NeRF method or to use an existing implementation, we've abstracted away the training routine in these two files and chances are you will not need to think of them again.\n",
"\n",
"### Graphs, Modules, and Fields\n",
"\n",
"If you are looking to implemnet a new NeRF method or extend an existing one, you may need to set up a new graph (in `graphs/`).\n",
"\n",
"All NeRF graph definitions can be found in `graphs/`. The graph encapsulates all the modules in the NeRF method- from the MLP's to the samplers to the losses and optimizers. All graphs are composed of modules and fields.\n",
"\n",
"### Modules\n",
"\n",
"We can decompose all graphs into respective modules. For instance, we have {ref}`optimizers` which contains modules related to the loss, {ref}`renderers` which contains all rendering modules, {`graph/modules/`}, which includes samplers and ray generators. Additionally, we have {ref}`field_modules`, which will be discussed below.\n",
"In general, modules can be thought of as individual component parts of the graph that can be swapped in/out. We provide most of the standard modules, but if you are creating a new NeRF graph, you may have to define new modules.\n",
"\n",
"### Fields\n",
"\n",
"{ref}`fields` represents the \"space\", aka. the radiance field of the NeRF. Here, we define the field as the part of the network that takes in point samples and any other conditioning, and outputs any of the `FieldHeadNames` (`nerf/field_modules/field_heads.py`).\n",
"\n",
"All fields are composed of modules continained within the `fields/` directory (e.g. `fields/modules/` or `fields/density_fields/`). We can think of field modules as modules that actually define or interact with the field.\n",
"\n",
"To build a NeRF field, we therefore follow these steps:\n",
"\n",
"1. define any relevant field modules\n",
"2. create a new class that extends the {ref}`fields` base class and use these field modules to compose the full field\n",
"3. implement the abstract functions `get_density()` and `get_outputs()`."
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"ename": "SyntaxError",
"evalue": "invalid syntax (383175768.py, line 4)",
"output_type": "error",
"traceback": [
"\u001b[0;36m Input \u001b[0;32mIn [1]\u001b[0;36m\u001b[0m\n\u001b[0;31m def __init__(self, ...) -> None:\u001b[0m\n\u001b[0m ^\u001b[0m\n\u001b[0;31mSyntaxError\u001b[0m\u001b[0;31m:\u001b[0m invalid syntax\n"
]
}
],
"source": [
"class NeRFField(Field):\n",
" \"\"\"NeRF Field\"\"\"\n",
"\n",
" def __init__(self, ...) -> None:\n",
" \"\"\"Create boilerplate NeRF field.\"\"\"\n",
"\n",
" super().__init__()\n",
"\n",
" # In the init method, we are instantiating all relevant field modules\n",
" self.position_encoding = position_encoding\n",
" self.direction_encoding = direction_encoding\n",
"\n",
" self.mlp_base = MLP(\n",
" in_dim=self.position_encoding.get_out_dim(),\n",
" num_layers=base_mlp_num_layers,\n",
" layer_width=base_mlp_layer_width,\n",
" skip_connections=skip_connections,\n",
" )\n",
" ...\n",
"\n",
" def get_density(self, point_samples: PointSamples):\n",
" \"\"\"\n",
" Computes and returns the densities.\n",
" \"\"\"\n",
"\n",
" def get_outputs(\n",
" self, point_samples: PointSamples, density_embedding: Optional[TensorType] = None\n",
" ) -> Dict[FieldHeadNames, TensorType]:\n",
" \"\"\"\n",
" Computes and returns the outputs.\n",
" \"\"\""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Putting it together\n",
"\n",
"Now that we've gone over what modules and fields are, we are ready to create the graph!\n",
"\n",
"To implement the vanilla NeRF, we create a new class that inherits the abstract Graph class. Similar to composing a new field, we can pull from all pre-defined fields and modules and use them to compose a new Graph.\n",
"We will then need to define the following abstract methods as seen in the skeleton code below. See also `graphs/vanilla_nerf.py` for the full implementation."
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [
{
"ename": "NameError",
"evalue": "name 'Graph' is not defined",
"output_type": "error",
"traceback": [
"\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
"\u001b[0;31mNameError\u001b[0m Traceback (most recent call last)",
"\u001b[1;32m/shared/ethanweber/nerfactory/docs/tutorials/pipelines/creating_models.ipynb Cell 4\u001b[0m in \u001b[0;36m<cell line: 1>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> <a href='vscode-notebook-cell://ssh-remote%2Bbirman/shared/ethanweber/nerfactory/docs/tutorials/pipelines/creating_models.ipynb#W6sdnNjb2RlLXJlbW90ZQ%3D%3D?line=0'>1</a>\u001b[0m \u001b[39mclass\u001b[39;00m \u001b[39mNeRFGraph\u001b[39;00m(Graph):\n\u001b[1;32m <a href='vscode-notebook-cell://ssh-remote%2Bbirman/shared/ethanweber/nerfactory/docs/tutorials/pipelines/creating_models.ipynb#W6sdnNjb2RlLXJlbW90ZQ%3D%3D?line=1'>2</a>\u001b[0m \u001b[39m\"\"\"Vanilla NeRF graph\"\"\"\u001b[39;00m\n\u001b[1;32m <a href='vscode-notebook-cell://ssh-remote%2Bbirman/shared/ethanweber/nerfactory/docs/tutorials/pipelines/creating_models.ipynb#W6sdnNjb2RlLXJlbW90ZQ%3D%3D?line=3'>4</a>\u001b[0m \u001b[39mdef\u001b[39;00m \u001b[39m__init__\u001b[39m(\u001b[39mself\u001b[39m, intrinsics\u001b[39m=\u001b[39m\u001b[39mNone\u001b[39;00m, camera_to_world\u001b[39m=\u001b[39m\u001b[39mNone\u001b[39;00m, \u001b[39m*\u001b[39m\u001b[39m*\u001b[39mkwargs) \u001b[39m-\u001b[39m\u001b[39m>\u001b[39m \u001b[39mNone\u001b[39;00m:\n",
"\u001b[0;31mNameError\u001b[0m: name 'Graph' is not defined"
]
}
],
"source": [
"class NeRFGraph(Graph):\n",
" \"\"\"Vanilla NeRF graph\"\"\"\n",
"\n",
" def __init__(self, intrinsics=None, camera_to_world=None, **kwargs) -> None:\n",
" super().__init__(intrinsics=intrinsics, camera_to_world=camera_to_world, **kwargs)\n",
"\n",
" def populate_fields(self):\n",
" \"\"\"\n",
" Set all field related modules here\n",
" \"\"\"\n",
"\n",
" def populate_misc_modules(self):\n",
" \"\"\"\n",
" Set all remaining modules here including: samplers, renderers, losses, and metrics\n",
" \"\"\"\n",
"\n",
" def get_param_groups(self) -> Dict[str, List[Parameter]]:\n",
" \"\"\"\n",
" Create a dictionary of parameters that are grouped according to different optimizers\n",
" \"\"\"\n",
"\n",
" def get_outputs(self, ray_bundle: RayBundle):\n",
" \"\"\"\n",
" Takes in a Ray Bundle and returns a dictionary of outputs.\n",
" \"\"\"\n",
"\n",
" def get_loss_dict(self, outputs, batch):\n",
" \"\"\"\n",
" Computes and returns the losses.\n",
" \"\"\"\n",
"\n",
" def log_test_image_outputs(self, image_idx, step, batch, outputs):\n",
" \"\"\"\n",
" Writes the test image outputs.\n",
" \"\"\""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Creating the config\n",
"\n",
"Now that you have the graph and dataset all set up, you'll need to create the config that you pass into our run train routine. Our config system is powered by [Hydra](https://hydra.cc/). All Hydra and machine related arguments are stored in `configs/default_setup.yaml`, as well as the defaults list.\n",
"To set up the graph config, create a new yaml under `configs/`.\n",
"\n",
"```yaml\n",
"# configs/vanilla_nerf.yaml\n",
"\n",
"defaults:\n",
" - graph_default # inherit the basic yaml heirarchy\n",
" - _self_\n",
"\n",
"logging:\n",
" # <insert logging definitions here>\n",
"\n",
"trainer:\n",
" # <override configurations for loading/training/saving model here>\n",
"\n",
"experiment_name: blender_lego\n",
"method_name: vanilla_nerf\n",
"\n",
"data:\n",
" # <insert any dataset related overrides here>\n",
"\n",
"graph:\n",
" _target_: nerfactory.graph.vanilla_nerf.NeRFGraph # set the target to the graph you defined\n",
" # <insert any graph related overrides here>\n",
"\n",
"optimizers:\n",
" # <insert any optimizer related overrides here>\n",
"```\n",
"\n",
"### Training and testing\n",
"\n",
"Once you have the config properly set up, you can begin training! To begin the training process, just pass in the name of your new config to the training script:\n",
"\n",
"```bash\n",
"python scripts/run_train.py --config-name vanilla_nerf\n",
"```\n",
"\n",
"And now you have a brand-new NeRF in training! For testing and visualizing, simply refer to steps 4-5 in the [quickstart guide](https://github.com/plenoptix/nerfactory#quickstart).\n",
"\n",
"To help you get started, we also provide additional training tools such as profiling, logging, and debugging. Please refer to our [features guide](../../tooling/index.rst)."
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3.8.13 ('nerfactory')",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.8.13"
},
"orig_nbformat": 4,
"vscode": {
"interpreter": {
"hash": "e691f033e0f2f1b9c0a11e7e81375a1e27aec87a71fd1b1eaa545f7a5e61b3f6"
}
}
},
"nbformat": 4,
"nbformat_minor": 2
}
docs/tutorials/pipelines/creating_pipelines.ipynb
+276
View File
@@ -0,0 +1,276 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Creating Custom Pipelines\n",
"\n",
"Here we explain how to create custom pipelines in nerfactory. Pipelines are composed of two components, namely a Dataloader and a Model. We'll show how to make an incremental dataloader with multiple scenes, a model with scene conditioning, and importance sampling at pixels with high loss.\n",
"\n",
"The extensible features that we show in this tutorial are the following:\n",
"- a Dataloader that incrementally adds cameras\n",
"- a Dataloader that uses multiple scenes\n",
"- a Model that is conditioned on the scene\n",
"- a Dataloader PixelSampler that samples more densely in regions with high loss\n",
"\n",
"Our goal is to enable Nerfactory users to create an entire custom Pipeline by only editing one file.\n",
"\n",
"```text\n",
"#TODO(ethan): show a figure depicting the different modules that go into a pipeline\n",
"```"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"tags": [
"remove-cell",
"hide-input"
]
},
"outputs": [],
"source": [
"# COLLAPSED\n",
"%load_ext autoreload\n",
"%autoreload 2\n",
"\n",
"from __future__ import annotations\n",
"\n",
"from typing import Dict, Optional, Tuple, List\n",
"import torch\n",
"\n",
"from nerfactory.utils.config import DataloaderConfig, ModelConfig, PipelineConfig, ViewerConfig\n",
"\n",
"from nerfactory.dataloaders.base import Dataloader\n",
"from nerfactory.dataloaders.structs import DatasetInputs\n",
"from nerfactory.models.base import Model\n",
"from nerfactory.pipelines.base import Pipeline\n",
"\n",
"from nerfactory.models.instant_ngp import NGPModel\n",
"from nerfactory.cameras.rays import RayBundle"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### RayBundle class\n",
"\n",
"In the RayBundle class, we allow uses to add non-default attributes for conditioning.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"class CustomDataloaderConfig(DataloaderConfig):\n",
" _target = CustomDataloader\n",
" scene_names: List[str] = [\"chair\", \"drums\", \"fern\", \"lego\"]\n",
" steps_per_add_cameras: int = 100 # every X iterations, add more cameras\n",
" num_cameras_per_add: int = 10 # number of cameras to add\n",
"\n",
"\n",
"class CustomDataloader(Dataloader):\n",
" \"\"\"A custom dataloader that incrementally adds cameras and has multiple scenes.\"\"\"\n",
"\n",
" config: CustomDataloaderConfig\n",
"\n",
" def populate_train_modules(self):\n",
" \"\"\"Populate the train dataloader modules.\"\"\"\n",
" self.scene_name_to_image_sampler = {}\n",
" self.scene_name_to_collider = {} # TODO(ethan): move colliders to the dataloader\n",
" for scene_name in self.config.scene_names:\n",
" dataset_inputs: DatasetInputs = None # TODO\n",
" image_dataset = ImageDataset(dataset_inputs)\n",
" image_sampler = CacheImageSampler(image_dataset=image_dataset) # a torch dataloader\n",
" self.scene_name_to_image_sampler[scene_name] = image_sampler\n",
" self.train_pixel_sampler = PixelSampler\n",
" self.train_ray_generator = RayGenerator # nn.Module\n",
"\n",
" def populate_eval_modules(self):\n",
" \"\"\"Populate the eval dataloader modules.\"\"\"\n",
" # we'll mostly rely on the train dataloader modules\n",
" self.eval_pixel_sampler = EvalPixelSampler # this will sample entire images\n",
"\n",
" def sample_images(self) -> List[Image]:\n",
" images = []\n",
" for scene_name in self.scene_name_to_image_sampler.keys():\n",
" image_sampler = self.scene_name_to_image_sampler[scene_name]\n",
" x = image_sampler.forward() # note that empty forward calls next()\n",
" images.append(x)\n",
" return images\n",
"\n",
" def next_train(self, step: int) -> Tuple[RayBundle, Dict]:\n",
" \"\"\"Get the next batch of training data by stringing together the train modules.\"\"\"\n",
" # grab some images from each scene\n",
" images = self.sample_images()\n",
" pixels = self.train_pixel_sampler.forward(images)\n",
" ray_bundle = self.train_ray_generator(pixels)\n",
" # shape should be (H, W, :)\n",
" ray_bundle.metadata[\"scene_indices\"] = None # TODO(ethan): populate this with a tensor of scene indices\n",
" dict_ = {}\n",
" return ray_bundle, dict_\n",
"\n",
" def next_eval(self, step: int) -> Tuple[RayBundle, Dict]:\n",
" \"\"\"Get the next batch of eval data by stringing together the eval modules.\"\"\"\n",
" # grab some images from each scene\n",
" images = self.sample_images()\n",
" pixels = self.train_pixel_sampler.forward(images)\n",
" ray_bundle = self.eval_ray_generator(pixels) # notice this is eval and not train\n",
" # shape should be (H, W, :)\n",
" ray_bundle.metadata[\"scene_indices\"] = None # TODO(ethan): populate this with a tensor of scene indices\n",
" dict_ = {}\n",
" return ray_bundle, dict_\n",
"\n",
"\n",
"class CustomNGPModelConfig(ModelConfig):\n",
" _target = CustomNGPModel\n",
" coarse_field: str = \"temp\"\n",
" fine_field: str = \"temp2\"\n",
"\n",
"\n",
"class CustomNGPModel(Model):\n",
" \"\"\"An instant ngp model modified slightly to output semantics.\"\"\"\n",
"\n",
" config: SceneConditionNGPModelConfig\n",
"\n",
" def populate_modules(self):\n",
" self.ngp_model = NGPModel(coarse_field=self.config.coarse_field, fine_field=self.config.fine_field)\n",
"\n",
" def get_outputs(self, ray_bundle: RayBundle) -> Dict[str, torch.Tensor]:\n",
" # TODO(ethan): pass in batch from the forward function\n",
" # TODO(ethan): rename batch to something else\n",
" outputs = self.ngp_model.forward(ray_bundle)\n",
" outputs[\"semantics\"] = torch.rand_like(outputs[\"rgb\"])\n",
" return outputs\n",
"\n",
" def get_loss_dict(self):\n",
" return {}\n",
"\n",
"\n",
"class CustomPipeline(Pipeline):\n",
" \"\"\"The Instant NGP pipeline.\"\"\"\n",
"\n",
" config: PipelineConfig\n",
"\n",
" def train_step(self, step: int):\n",
" ray_bundle, batch = self.dataloader.next_train(step=step)\n",
" # TODO: maybe run a CNN on the data before passing into model\n",
" model_outputs, loss_dict, metrics_dict = self.model(ray_bundle, batch)\n",
" # TODO: update pixel sampler state with loss map to show the flexibilty of our Pipeline\n",
" self.dataloader.pixel_sampler.update_loss_map()\n",
" return model_outputs, loss_dict, metrics_dict\n",
"\n",
" def eval_step(self):\n",
" ray_bundle, batch = self.dataloader.next_eval(step=step)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"dataloader = Dataloader()\n",
"model = SceneConditionNGPModel()\n",
"pipeline = CustomPipeline.from_dataloader_and_model(dataloader=dataloader, model=model)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Creating pipelines from a config\n",
"\n",
"Now we show how to create a pipeline from a config, which has the following form:\n",
"\n",
"```python\n",
"@dataclass\n",
"class PipelineConfig:\n",
" \"\"\"Configuration for pipeline instantiation\"\"\"\n",
"\n",
" _target: ClassVar[Type] = Pipeline\n",
" dataloader: DataloaderConfig = MISSING\n",
" model: ModelConfig = MISSING\n",
"```\n",
"\n",
"See `nerfactory/utils/config.py` for more details. In this example, we will simply load from an existing configuration from `configs/graph_instant_ngp.yaml`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import pprint\n",
"import hydra\n",
"\n",
"hydra.core.global_hydra.GlobalHydra.instance().clear()\n",
"from hydra import compose, initialize\n",
"\n",
"initialize(version_base=\"1.2\", config_path=\"../configs/\")\n",
"config_name = \"graph_instant_ngp.yaml\"\n",
"config = compose(config_name)\n",
"pipeline_config = config.pipeline\n",
"pprint.pprint(pipeline_config)\n",
"print(\"----------------------------------------------------\")\n",
"\n",
"# from nerfactory.pipelines.base import setup_pipeline\n",
"# pipeline = setup_pipeline(pipeline_config, device=\"cuda\")\n",
"pipeline = pipeline_config.setup()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": []
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"pipeline.get_train_loss_dict()"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3.8.13 ('nerfactory')",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.8.13"
},
"vscode": {
"interpreter": {
"hash": "e691f033e0f2f1b9c0a11e7e81375a1e27aec87a71fd1b1eaa545f7a5e61b3f6"
}
}
},
"nbformat": 4,
"nbformat_minor": 2
}
docs/tutorials/pipelines/index.rst
+10
View File
@@ -0,0 +1,10 @@
Creating Custom Pipelines
-------------------------
Here we show you how to create a custom pipeline.
.. toctree::
:maxdepth: 1
creating_pipelines.ipynb
creating_models.ipynb