Table of Contents
Shortcuts

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 by nerfacc.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