From 06e59ed1ec147c1b6357b9a2195cb12822ebdd33 Mon Sep 17 00:00:00 2001 From: drewgilliam Date: Fri, 8 Sep 2023 12:14:16 -0400 Subject: [PATCH] camera/plugin docs (#2412) * api docs for cameras & plugins * fix docstrings --- docs/reference/api/cameras.rst | 46 ++++++++++++++++++++++++++++++ docs/reference/api/index.rst | 2 ++ docs/reference/api/plugins.rst | 25 ++++++++++++++++ nerfstudio/cameras/camera_utils.py | 15 ++++++---- nerfstudio/cameras/cameras.py | 28 +++++++++--------- 5 files changed, 97 insertions(+), 19 deletions(-) create mode 100644 docs/reference/api/cameras.rst create mode 100644 docs/reference/api/plugins.rst diff --git a/docs/reference/api/cameras.rst b/docs/reference/api/cameras.rst new file mode 100644 index 000000000..7653852c7 --- /dev/null +++ b/docs/reference/api/cameras.rst @@ -0,0 +1,46 @@ +.. _cameras: + +Cameras +============ + +Cameras +---------------- + +.. automodule:: nerfstudio.cameras.cameras + :members: + :show-inheritance: + +Camera Optimizers +----------------- + +.. automodule:: nerfstudio.cameras.camera_optimizers + :members: + :show-inheritance: + +Camera Paths +---------------- + +.. automodule:: nerfstudio.cameras.camera_paths + :members: + :show-inheritance: + +Camera Utils +---------------- + +.. automodule:: nerfstudio.cameras.camera_utils + :members: + :show-inheritance: + +Lie Groups +---------------- + +.. automodule:: nerfstudio.cameras.lie_groups + :members: + :show-inheritance: + +Rays +---------------- + +.. automodule:: nerfstudio.cameras.rays + :members: + :show-inheritance: diff --git a/docs/reference/api/index.rst b/docs/reference/api/index.rst index 01c7d7fe7..a6691feca 100644 --- a/docs/reference/api/index.rst +++ b/docs/reference/api/index.rst @@ -7,6 +7,7 @@ TODO: Explanation of each component .. toctree:: + cameras config data/index fields @@ -14,5 +15,6 @@ TODO: Explanation of each component models model_components/index optimizers + plugins utils/index viewer diff --git a/docs/reference/api/plugins.rst b/docs/reference/api/plugins.rst new file mode 100644 index 000000000..bb8504559 --- /dev/null +++ b/docs/reference/api/plugins.rst @@ -0,0 +1,25 @@ +.. _plugins: + +Plugins +============ + +Method Registry +---------------------- + +.. automodule:: nerfstudio.plugins.registry + :members: + :show-inheritance: + +DataParser Registry +---------------------- + +.. automodule:: nerfstudio.plugins.registry_dataparser + :members: + :show-inheritance: + +Types +---------------------- + +.. automodule:: nerfstudio.plugins.types + :members: + :show-inheritance: diff --git a/nerfstudio/cameras/camera_utils.py b/nerfstudio/cameras/camera_utils.py index 2c0b746d1..8c527b9db 100644 --- a/nerfstudio/cameras/camera_utils.py +++ b/nerfstudio/cameras/camera_utils.py @@ -519,21 +519,24 @@ def auto_orient_and_center_poses( method: Literal["pca", "up", "vertical", "none"] = "up", center_method: Literal["poses", "focus", "none"] = "poses", ) -> Tuple[Float[Tensor, "*num_poses 3 4"], Float[Tensor, "3 4"]]: - """Orients and centers the poses. We provide two methods for orientation: pca and up. + """Orients and centers the poses. - pca: Orient the poses so that the principal directions of the camera centers are aligned + We provide three methods for orientation: + + - pca: Orient the poses so that the principal directions of the camera centers are aligned with the axes, Z corresponding to the smallest principal component. This method works well when all of the cameras are in the same plane, for example when images are taken using a mobile robot. - up: Orient the poses so that the average up vector is aligned with the z axis. + - up: Orient the poses so that the average up vector is aligned with the z axis. This method works well when images are not at arbitrary angles. - vertical: Orient the poses so that the Z 3D direction projects close to the + - vertical: Orient the poses so that the Z 3D direction projects close to the y axis in images. This method works better if cameras are not all looking in the same 3D direction, which may happen in camera arrays or in LLFF. There are two centering methods: - poses: The poses are centered around the origin. - focus: The origin is set to the focus of attention of all cameras (the + + - poses: The poses are centered around the origin. + - focus: The origin is set to the focus of attention of all cameras (the closest point to cameras optical axes). Recommended for inward-looking camera configurations. diff --git a/nerfstudio/cameras/cameras.py b/nerfstudio/cameras/cameras.py index c2ef887a6..68f7b186f 100644 --- a/nerfstudio/cameras/cameras.py +++ b/nerfstudio/cameras/cameras.py @@ -329,25 +329,27 @@ class Cameras(TensorDataclass): This function will standardize the input arguments and then call the _generate_rays_from_coords function to generate the rays. Our goal is to parse the arguments and then get them into the right shape: - - camera_indices: (num_rays:..., num_cameras_batch_dims) - - coords: (num_rays:..., 2) - - camera_opt_to_camera: (num_rays:..., 3, 4) or None - - distortion_params_delta: (num_rays:..., 6) or None + + - camera_indices: (num_rays:..., num_cameras_batch_dims) + - coords: (num_rays:..., 2) + - camera_opt_to_camera: (num_rays:..., 3, 4) or None + - distortion_params_delta: (num_rays:..., 6) or None Read the docstring for _generate_rays_from_coords for more information on how we generate the rays after we have standardized the arguments. We are only concerned about different combinations of camera_indices and coords matrices, and the following are the 4 cases we have to deal with: - 1. isinstance(camera_indices, int) and coords == None - - In this case we broadcast our camera_indices / coords shape (h, w, 1 / 2 respectively) - 2. isinstance(camera_indices, int) and coords != None - - In this case, we broadcast camera_indices to the same batch dim as coords - 3. not isinstance(camera_indices, int) and coords == None - - In this case, we will need to set coords so that it is of shape (h, w, num_rays, 2), and broadcast - all our other args to match the new definition of num_rays := (h, w) + num_rays - 4. not isinstance(camera_indices, int) and coords != None - - In this case, we have nothing to do, only check that the arguments are of the correct shape + + 1. isinstance(camera_indices, int) and coords == None + - In this case we broadcast our camera_indices / coords shape (h, w, 1 / 2 respectively) + 2. isinstance(camera_indices, int) and coords != None + - In this case, we broadcast camera_indices to the same batch dim as coords + 3. not isinstance(camera_indices, int) and coords == None + - In this case, we will need to set coords so that it is of shape (h, w, num_rays, 2), and broadcast + all our other args to match the new definition of num_rays := (h, w) + num_rays + 4. not isinstance(camera_indices, int) and coords != None + - In this case, we have nothing to do, only check that the arguments are of the correct shape There is one more edge case we need to be careful with: when we have "jagged cameras" (ie: different heights and widths for each camera). This isn't problematic when we specify coords, since coords is already a tensor.