update docstrings and random cleanups (#387)

* fixing docstrings and small nits; up to fileds

* finished adding and fixing docstrings
This commit is contained in:
evonneng authored and GitHub committed 2022-09-10 23:09:44 -07:00
1 parent bd5967461d
commit d50c71ac43
52 files changed
+846 -646

No files matched your search

+12 -14
View File
@@ -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
+23 -5
View File
@@ -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)
+6 -11
View File
@@ -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
+7 -3
View File
@@ -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)
+6 -4
View File
@@ -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)
+9 -9
View File
@@ -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__(
+10 -10
View File
@@ -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__(
+12 -1
View File
@@ -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,