Occupancy Grid¶
- class nerfacc.ContractionType(value)¶
Space contraction options.
This is an enum class that describes how a
nerfacc.Grid
covers the 3D space. It is also used bynerfacc.ray_marching()
to determine how to perform ray marching within the grid.The options in this enum class are:
- AABB¶
Linearly map the region of interest \([x_0, x_1]\) to a unit cube in \([0, 1]\).
\[f(x) = \frac{x - x_0}{x_1 - x_0}\]
- UN_BOUNDED_TANH¶
Contract an unbounded space into a unit cube in \([0, 1]\) using tanh. The region of interest \([x_0, x_1]\) is first mapped into \([-0.5, +0.5]\) before applying tanh.
\[f(x) = \frac{1}{2}(tanh(\frac{x - x_0}{x_1 - x_0} - \frac{1}{2}) + 1)\]
- UN_BOUNDED_SPHERE¶
Contract an unbounded space into a unit sphere. Used in Mip-Nerf 360: Unbounded Anti-Aliased Neural Radiance Fields.
\[\begin{split}f(x) = \begin{cases} z(x) & ||z(x)|| \leq 1 \\ (2 - \frac{1}{||z(x)||})(\frac{z(x)}{||z(x)||}) & ||z(x)|| > 1 \end{cases}\end{split}\]\[z(x) = \frac{x - x_0}{x_1 - x_0} * 2 - 1\]
- to_cpp_version()¶
Convert to the C++ version of the enum class.
- Returns:
The C++ version of the enum class.
- class nerfacc.Grid(*args, **kwargs)¶
An abstract Grid class.
The grid is used as a cache of the 3D space to indicate whether each voxel area is important or not for the differentiable rendering process. The ray marching function (see
nerfacc.ray_marching()
) would use the grid to skip the unimportant voxel areas.To work with
nerfacc.ray_marching()
, three attributes must exist:roi_aabb
: The axis-aligned bounding box of the region of interest.binary
: A 3D binarized tensor of shape {resx, resy, resz}, with torch.bool data type.contraction_type
: The contraction type of the grid, indicating how the 3D space is mapped to the grid.
- property binary: Tensor¶
A 3D binarized tensor with torch.bool data type.
The tensor is of shape (resx, resy, resz), in which each boolen value represents whether the corresponding voxel should be kept or not.
- property contraction_type: ContractionType¶
The contraction type of the grid.
The contraction type is an indicator of how the 3D space is contracted to this voxel grid. See
nerfacc.ContractionType
for more details.
- property roi_aabb: Tensor¶
The axis-aligned bounding box of the region of interest.
Its is a shape (6,) tensor in the format of {minx, miny, minz, maxx, maxy, maxz}.
- class nerfacc.OccupancyGrid(roi_aabb, resolution=128, contraction_type=ContractionType.AABB)¶
Occupancy grid: whether each voxel area is occupied or not.
- Parameters:
roi_aabb (Union[List[int], Tensor]) – The axis-aligned bounding box of the region of interest. Useful for mapping the 3D space to the grid.
resolution (Union[int, List[int], Tensor]) – The resolution of the grid. If an integer is given, the grid is assumed to be a cube. Otherwise, a list or a tensor of shape (3,) is expected. Default: 128.
contraction_type (ContractionType) – The contraction type of the grid. See
nerfacc.ContractionType
for more details. Default:nerfacc.ContractionType.AABB
.
- every_n_step(step, occ_eval_fn, occ_thre=0.01, ema_decay=0.95, warmup_steps=256, n=16)¶
Update the grid every n steps during training.
- Parameters:
step (int) – Current training step.
occ_eval_fn (Callable) – A function that takes in sample locations \((N, 3)\) and returns the occupancy values \((N, 1)\) at those locations.
occ_thre (float) – Threshold used to binarize the occupancy grid. Default: 1e-2.
ema_decay (float) – The decay rate for EMA updates. Default: 0.95.
warmup_steps (int) – Sample all cells during the warmup stage. After the warmup stage we change the sampling strategy to 1/4 uniformly sampled cells together with 1/4 occupied cells. Default: 256.
n (int) – Update the grid every n steps. Default: 16.
- Return type:
None
- query_occ(samples)¶
Query the occupancy field at the given samples.
- Parameters:
samples (Tensor) – Samples in the world coordinates. (n_samples, 3)
- Returns:
Occupancy values at the given samples. (n_samples,)
- Return type:
Tensor