mirror of
https://github.com/nerfstudio-project/nerfstudio.git
synced 2026-11-22 07:35:26 +08:00
update docstrings and random cleanups (#387)
* fixing docstrings and small nits; up to fileds * finished adding and fixing docstrings
This commit is contained in:
1 parent
bd5967461d
commit
d50c71ac43
52 files changed
+846
-646
No files matched your search
+12
-14
@@ -30,8 +30,12 @@ from nerfactory.fields.modules.field_heads import FieldHeadNames
|
||||
class Field(nn.Module):
|
||||
"""Base class for fields."""
|
||||
|
||||
def density_fn(self, positions):
|
||||
"""Returns only the density. Used primarily with the density grid."""
|
||||
def density_fn(self, positions: TensorType["bs":..., 3]):
|
||||
"""Returns only the density. Used primarily with the density grid.
|
||||
|
||||
Args:
|
||||
positions: the origin of the samples/frustums
|
||||
"""
|
||||
# Need to figure out a better way to descibe positions with a ray.
|
||||
ray_samples = RaySamples(
|
||||
frustums=Frustums(
|
||||
@@ -47,34 +51,28 @@ class Field(nn.Module):
|
||||
|
||||
@abstractmethod
|
||||
def get_density(self, ray_samples: RaySamples) -> Tuple[TensorType[..., 1], TensorType[..., "num_features"]]:
|
||||
"""Computes and returns the densities.
|
||||
"""Computes and returns the densities. Returns a tensor of densities and a tensor of features.
|
||||
|
||||
Args:
|
||||
ray_samples (RaySamples): Samples locations to compute density.
|
||||
|
||||
Returns:
|
||||
Tuple[TensorType[...,1], TensorType[...,"num_features"]]: A tensor of densities and a tensor of features.
|
||||
ray_samples: Samples locations to compute density.
|
||||
"""
|
||||
|
||||
@abstractmethod
|
||||
def get_outputs(
|
||||
self, ray_samples: RaySamples, density_embedding: Optional[TensorType] = None
|
||||
) -> Dict[FieldHeadNames, TensorType]:
|
||||
"""Computes and returns the colors.
|
||||
"""Computes and returns the colors. Returns output field values.
|
||||
|
||||
Args:
|
||||
ray_samples (RaySamples): Samples locations to compute outputs.
|
||||
density_embedding (TensorType, optional): Density embeddings to condition on.
|
||||
|
||||
Returns:
|
||||
Dict[FieldHeadNames, TensorType]: Output field values.
|
||||
ray_samples: Samples locations to compute outputs.
|
||||
density_embedding: Density embeddings to condition on.
|
||||
"""
|
||||
|
||||
def forward(self, ray_samples: RaySamples):
|
||||
"""Evaluates the field at points along the ray.
|
||||
|
||||
Args:
|
||||
ray_samples (RaySamples): Samples to evaluate field on.
|
||||
ray_samples: Samples to evaluate field on.
|
||||
"""
|
||||
valid_mask = ray_samples.valid_mask
|
||||
|
||||
|
||||
@@ -29,14 +29,11 @@ from nerfactory.cameras.rays import RaySamples
|
||||
|
||||
|
||||
def _create_grid_coords(resolution: int, device: Union[torch.device, str] = "cpu") -> TensorType["n_coords", 3]:
|
||||
"""Create 3D grid coordinates
|
||||
"""Create 3D grid coordinates. Returns all grid coordinates with shape [res * res * res, 3].
|
||||
|
||||
Args:
|
||||
resolution (int): The 3D resolution of the grid.
|
||||
device (torch.device): Which device you want the returned tensor to live on.
|
||||
|
||||
Returns:
|
||||
TensorType["n_coords", 3]: All grid coordinates with shape [res * res * res, 3].
|
||||
resolution: The 3D resolution of the grid.
|
||||
device: Which device you want the returned tensor to live on.
|
||||
"""
|
||||
arrange = torch.arange(resolution, device=device)
|
||||
grid_x, grid_y, grid_z = torch.meshgrid([arrange, arrange, arrange], indexing="ij")
|
||||
@@ -73,11 +70,11 @@ class DensityGrid(nn.Module):
|
||||
TODO(ruilongli): support `center` and `base_scale` with 3-dim.
|
||||
|
||||
Args:
|
||||
center (float): Center of all the grids in the world space. Defaults to 0.
|
||||
base_scale (float): Center of the scale of the base level grid. Defaults to 1.
|
||||
num_cascades (int): Number of the cascaded multi-res levels. Defaults to 1.
|
||||
resolution (int): Resolution of the grid. Defaults to 128.
|
||||
update_every_num_iters (int): How frequently to update the grid values. Defaults to 16.
|
||||
center: Center of all the grids in the world space. Defaults to 0.
|
||||
base_scale: Center of the scale of the base level grid. Defaults to 1.
|
||||
num_cascades: Number of the cascaded multi-res levels. Defaults to 1.
|
||||
resolution: Resolution of the grid. Defaults to 128.
|
||||
update_every_num_iters: How frequently to update the grid values. Defaults to 16.
|
||||
"""
|
||||
|
||||
density_grid: TensorType["num_cascades", "resolution_cubed"]
|
||||
@@ -111,24 +108,16 @@ class DensityGrid(nn.Module):
|
||||
|
||||
@torch.no_grad()
|
||||
def get_all_cells(self) -> List[Tuple[TensorType["n_cells"], TensorType["n_cells", 3]]]:
|
||||
"""Returns all cells of the grid.
|
||||
|
||||
Returns:
|
||||
List[Tuple[TensorType["n_cells"], TensorType["n_cells", 3]]]: All grid indices and grid
|
||||
coordinates of all cascade levels.
|
||||
"""
|
||||
"""Returns a list of all grid indices and grid coordinates of all cascade levels."""
|
||||
return [(self.grid_indices, self.grid_coords)] * self.num_cascades
|
||||
|
||||
@torch.no_grad()
|
||||
def sample_uniform_and_occupied_cells(self, n: int) -> List[Tuple[TensorType["n"], TensorType["n", 3]]]:
|
||||
"""Samples both n uniform and occupied cells (per cascade)
|
||||
"""Samples both n uniform and occupied cells (per cascade).
|
||||
Returns a tuple of (sampled grid indices, grid coordinates of all cascade levels).
|
||||
|
||||
Args:
|
||||
n: Number of cells to be sampled.
|
||||
|
||||
Returns:
|
||||
List[Tuple[TensorType["n"], TensorType["n", 3]]]: Sampled grid indices and grid
|
||||
coordinates of all cascade levels.
|
||||
"""
|
||||
device = self.density_grid.device
|
||||
|
||||
@@ -164,11 +153,11 @@ class DensityGrid(nn.Module):
|
||||
returns densities (N, 1).
|
||||
step: The current training step. Instant-NGP has a warmup stage where all cells are updated.
|
||||
After certain amount of steps (256), it speeds up by only update sampled cells.
|
||||
density_threshold (float): The threshold to prune cells. Recommended to calculate it using this rule:
|
||||
density_threshold: The threshold to prune cells. Recommended to calculate it using this rule:
|
||||
`weight_threshold / dt`. For example for Instant-NGP on Lego, the minimum step size `dt` is
|
||||
`3` (scale of the scene) * `sqrt(3)` / `1024` (number of samples). And if we want to the weight
|
||||
threshold to be `0.01`, we will get `0.01 / (3 * sqrt(3) / 1024) ~= 2.` for density threshold.
|
||||
decay (float): EMA decay for density updating.
|
||||
decay: EMA decay for density updating.
|
||||
"""
|
||||
# create temporary grid
|
||||
tmp_grid = -torch.ones_like(self.density_grid)
|
||||
@@ -206,10 +195,9 @@ class DensityGrid(nn.Module):
|
||||
@torch.no_grad()
|
||||
def get_densities(self, ray_samples: RaySamples) -> TensorType[..., 1]:
|
||||
"""Get the density values stored in the density grid.
|
||||
|
||||
Args:
|
||||
ray_samples RaySamples: ray samples
|
||||
Returns:
|
||||
TensorType[..., 1]: Density values
|
||||
ray_samples: ray samples to get density for
|
||||
"""
|
||||
positions = ray_samples.frustums.get_positions()
|
||||
deltas = ray_samples.frustums.ends - ray_samples.frustums.starts
|
||||
|
||||
@@ -38,16 +38,35 @@ except ImportError:
|
||||
pass
|
||||
|
||||
|
||||
def get_normalized_directions(directions):
|
||||
"""SH encoding must be in the range [0, 1]"""
|
||||
def get_normalized_directions(directions: TensorType["bs":..., 3]):
|
||||
"""SH encoding must be in the range [0, 1]
|
||||
|
||||
Args:
|
||||
directions: batch of directions
|
||||
"""
|
||||
return (directions + 1.0) / 2.0
|
||||
|
||||
|
||||
class TCNNInstantNGPField(Field):
|
||||
"""NeRF Field"""
|
||||
"""NeRF Field
|
||||
|
||||
Args:
|
||||
aabb: parameters of scene aabb bounds
|
||||
num_layers: number of hidden layers
|
||||
hidden_dim: dimension of hidden layers
|
||||
geo_feat_dim: output geo feat dimensions
|
||||
num_layers_color: number of hidden layers for color network
|
||||
hidden_dim_color: dimension of hidden layers for color network
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self, aabb, num_layers=2, hidden_dim=64, geo_feat_dim=15, num_layers_color=3, hidden_dim_color=64
|
||||
self,
|
||||
aabb,
|
||||
num_layers: int = 2,
|
||||
hidden_dim: int = 64,
|
||||
geo_feat_dim: int = 15,
|
||||
num_layers_color: int = 3,
|
||||
hidden_dim_color: int = 64,
|
||||
) -> None:
|
||||
super().__init__()
|
||||
|
||||
@@ -99,7 +118,6 @@ class TCNNInstantNGPField(Field):
|
||||
)
|
||||
|
||||
def get_density(self, ray_samples: RaySamples):
|
||||
"""Computes and returns the densities."""
|
||||
positions = SceneBounds.get_normalized_positions(ray_samples.frustums.get_positions(), self.aabb)
|
||||
positions_flat = positions.view(-1, 3)
|
||||
h = self.mlp_base(positions_flat).view(*ray_samples.frustums.shape, -1)
|
||||
|
||||
@@ -26,8 +26,8 @@ class FieldModule(nn.Module):
|
||||
"""Field modules that can be combined to store and compute the fields.
|
||||
|
||||
Args:
|
||||
in_dim (int, optional): Input dimension to module.
|
||||
out_dim (int, optional): Ouput dimension to module.
|
||||
in_dim: Input dimension to module.
|
||||
out_dim: Ouput dimension to module.
|
||||
"""
|
||||
|
||||
def __init__(self, in_dim: Optional[int] = None, out_dim: Optional[int] = None) -> None:
|
||||
@@ -43,18 +43,14 @@ class FieldModule(nn.Module):
|
||||
"""Sets input dimension of encoding
|
||||
|
||||
Args:
|
||||
in_dim (int): input dimension
|
||||
in_dim: input dimension
|
||||
"""
|
||||
if in_dim <= 0:
|
||||
raise ValueError("Input dimension should be greater than zero")
|
||||
self.in_dim = in_dim
|
||||
|
||||
def get_out_dim(self) -> int:
|
||||
"""Calculates output dimension of encoding.
|
||||
|
||||
Returns:
|
||||
int: output dimension
|
||||
"""
|
||||
"""Calculates output dimension of encoding."""
|
||||
if self.out_dim is None:
|
||||
raise ValueError("Output dimension has not been set")
|
||||
return self.out_dim
|
||||
@@ -62,10 +58,9 @@ class FieldModule(nn.Module):
|
||||
@abstractmethod
|
||||
def forward(self, in_tensor: TensorType["bs":..., "input_dim"]) -> TensorType["bs":..., "output_dim"]:
|
||||
"""
|
||||
Returns processed tensor
|
||||
|
||||
Args:
|
||||
in_tensor: Input tensor to process
|
||||
|
||||
Returns:
|
||||
Processed tensor
|
||||
"""
|
||||
raise NotImplementedError
|
||||
@@ -28,8 +28,8 @@ class Embedding(FieldModule):
|
||||
# TODO: add different types of initializations
|
||||
|
||||
Args:
|
||||
in_dim (int): Number of embeddings
|
||||
out_dim (int): Dimension of the embedding vectors
|
||||
in_dim: Number of embeddings
|
||||
out_dim: Dimension of the embedding vectors
|
||||
"""
|
||||
|
||||
def __init__(self, in_dim: int, out_dim: int) -> None:
|
||||
@@ -42,5 +42,9 @@ class Embedding(FieldModule):
|
||||
self.embedding = torch.nn.Embedding(self.in_dim, self.out_dim)
|
||||
|
||||
def forward(self, in_tensor: TensorType[..., "input_dim"]) -> TensorType[..., "output_dim"]:
|
||||
"""Call forward"""
|
||||
"""Call forward
|
||||
|
||||
Args:
|
||||
in_tensor: input tensor to process
|
||||
"""
|
||||
return self.embedding(in_tensor)
|
||||
@@ -43,6 +43,11 @@ class Encoding(FieldModule):
|
||||
|
||||
@abstractmethod
|
||||
def forward(self, in_tensor: TensorType["bs":..., "input_dim"]) -> TensorType["bs":..., "output_dim"]:
|
||||
"""Call forward and returns and processed tensor
|
||||
|
||||
Args:
|
||||
in_tensor: the input tensor to process
|
||||
"""
|
||||
raise NotImplementedError
|
||||
|
||||
|
||||
@@ -243,13 +248,10 @@ class HashEncoding(Encoding):
|
||||
return self.num_levels * self.features_per_level
|
||||
|
||||
def hash_fn(self, in_tensor: TensorType["bs":..., "num_levels", 3]) -> TensorType["bs":..., "num_levels"]:
|
||||
"""Hash tensor using method described in Instant-NGP
|
||||
"""Returns hash tensor using method described in Instant-NGP
|
||||
|
||||
Args:
|
||||
in_tensor: Tensor to be hashed
|
||||
|
||||
Returns:
|
||||
Hashed tensor
|
||||
"""
|
||||
|
||||
# min_val = torch.min(in_tensor)
|
||||
|
||||
@@ -38,15 +38,15 @@ class NeRFField(Field):
|
||||
"""NeRF Field
|
||||
|
||||
Args:
|
||||
position_encoding (Encoding, optional): Position encoder. Defaults to Identity(in_dim=3).
|
||||
direction_encoding (Encoding, optional): Direction encoder. Defaults to Identity(in_dim=3).
|
||||
base_mlp_num_layers (int, optional): Number of layers for base MLP. Defaults to 8.
|
||||
base_mlp_layer_width (int, optional): Width of base MLP layers. Defaults to 256.
|
||||
head_mlp_num_layers (int, optional): Number of layer for ourput head MLP. Defaults to 2.
|
||||
head_mlp_layer_width (int, optional): Width of output head MLP layers. Defaults to 128.
|
||||
skip_connections (Tuple, optional): Where to add skip connection in base MLP. Defaults to (4,).
|
||||
use_integrated_encoding (bool, optional): Used integrated samples as encoding input, Defaults to False.
|
||||
spatial_distortion (SpatialDistortion, optional): Spatial distortion. Defaults to None.
|
||||
position_encoding: Position encoder. Defaults to Identity(in_dim=3).
|
||||
direction_encoding: Direction encoder. Defaults to Identity(in_dim=3).
|
||||
base_mlp_num_layers: Number of layers for base MLP. Defaults to 8.
|
||||
base_mlp_layer_width: Width of base MLP layers. Defaults to 256.
|
||||
head_mlp_num_layers: Number of layer for ourput head MLP. Defaults to 2.
|
||||
head_mlp_layer_width: Width of output head MLP layers. Defaults to 128.
|
||||
skip_connections: Where to add skip connection in base MLP. Defaults to (4,).
|
||||
use_integrated_encoding: Used integrated samples as encoding input, Defaults to False.
|
||||
spatial_distortion: Spatial distortion. Defaults to None.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
|
||||
@@ -39,16 +39,16 @@ class VanillaNerfWField(Field):
|
||||
"""The NeRF-W field which has appearance and transient conditioning.
|
||||
|
||||
Args:
|
||||
num_images (int): How many images exist in the dataset.
|
||||
position_encoding (Encoding, optional): Position encoder. Defaults to Identity(in_dim=3).
|
||||
direction_encoding (Encoding, optional): Direction encoder. Defaults to Identity(in_dim=3).
|
||||
base_mlp_num_layers (int, optional): Number of layers for base MLP. Defaults to 8.
|
||||
base_mlp_layer_width (int, optional): Width of base MLP layers. Defaults to 256.
|
||||
head_mlp_num_layers (int, optional): Number of layer for ourput head MLP. Defaults to 2.
|
||||
head_mlp_layer_width (int, optional): Width of output head MLP layers. Defaults to 128.
|
||||
appearance_embedding_dim: (int, optional): Dimension of appearance embedding. Defaults to 48.
|
||||
transient_embedding_dim: (int, optional): Dimension of transient embedding. Defaults to 16.
|
||||
skip_connections (Tuple, optional): Where to add skip connection in base MLP. Defaults to (4,).
|
||||
num_images: How many images exist in the dataset.
|
||||
position_encoding: Position encoder. Defaults to Identity(in_dim=3).
|
||||
direction_encoding: Direction encoder. Defaults to Identity(in_dim=3).
|
||||
base_mlp_num_layers: Number of layers for base MLP. Defaults to 8.
|
||||
base_mlp_layer_width: Width of base MLP layers. Defaults to 256.
|
||||
head_mlp_num_layers: Number of layer for ourput head MLP. Defaults to 2.
|
||||
head_mlp_layer_width: Width of output head MLP layers. Defaults to 128.
|
||||
appearance_embedding_dim:: Dimension of appearance embedding. Defaults to 48.
|
||||
transient_embedding_dim:: Dimension of transient embedding. Defaults to 16.
|
||||
skip_connections: Where to add skip connection in base MLP. Defaults to (4,).
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
|
||||
@@ -34,7 +34,18 @@ from nerfactory.fields.modules.mlp import MLP
|
||||
|
||||
|
||||
class SemanticNerfField(Field):
|
||||
"""Semantic-NeRF field"""
|
||||
"""Semantic-NeRF field
|
||||
|
||||
Args:
|
||||
num_semantic_classes: Number of distinct semantic classes.
|
||||
position_encoding: Position encoder. Defaults to Identity(in_dim=3).
|
||||
direction_encoding: Direction encoder. Defaults to Identity(in_dim=3).
|
||||
base_mlp_num_layers: Number of layers for base MLP. Defaults to 8.
|
||||
base_mlp_layer_width: Width of base MLP layers. Defaults to 256.
|
||||
head_mlp_num_layers: Number of layer for ourput head MLP. Defaults to 2.
|
||||
head_mlp_layer_width: Width of output head MLP layers. Defaults to 128.
|
||||
skip_connections: Where to add skip connection in base MLP. Defaults to (4,).
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
|
||||
Reference in new issue
Block a user