NerfAcc

0.5.3 verified Fri May 01 auth: no python

A general NeRF acceleration toolbox that provides efficient occupancy grid-based ray marching and sampling for neural radiance fields. Current version 0.5.3, with rapid development and breaking changes between minor versions.

pip install nerfacc

Common errors

error ModuleNotFoundError: No module named 'nerfacc.estimators' ↓

cause Import path changed in v0.5.0; estimators are now top-level.

fix

Use 'from nerfacc import OccGridEstimator' instead of 'from nerfacc.estimators import OccGridEstimator'.

error AttributeError: module 'nerfacc' has no attribute 'ContractionType' ↓

cause ContractionType was moved to nerfacc.grid; but in v0.5.0 it's at top-level.

fix

Use 'from nerfacc import ContractionType' (v0.5.0+) or 'from nerfacc.grid import ContractionType' (older versions).

error RuntimeError: Expected all tensors to be on the same device... ↓

cause Mixing CPU and CUDA tensors in estimator methods; estimator and rays must be on same device.

fix

Move estimator and rays to same device: estimator.to(device); rays_o = rays_o.to(device).

Warnings

breaking v0.5.0 rewrote 90% of the codebase: ContractionType removed from grid module, OccGridEstimator API changed (multi-level). Old code using single-level grid or contraction must be updated. ↓

fix Use OccGridEstimator with levels parameter; replace ContractionType imports from nerfacc.grid with nerfacc.ContractionType.

breaking Contraction for Occupancy Grid is no longer supported in v0.5.0 due to inefficiency for ray traversal. Attempting to use contraction with OccGridEstimator will raise error. ↓

fix Remove contraction argument; for unbounded scenes use multi-level grid or ProposalNetworkEstimator instead.

gotcha CUDA kernels are JIT compiled on first import; missing CUDA toolkit or incompatible PyTorch version will cause silent fallback to CPU or crash. ↓

fix Install compatible PyTorch + CUDA toolkit. Ensure torch.cuda.is_available() returns True.

gotcha OccGridEstimator.binaries expects a boolean tensor of shape (levels, 1, res_x, res_y, res_z) after v0.5.0; single-level shape changed. ↓

fix Use estimator.binaries = occ.unsqueeze(0).unsqueeze(0) for single-level or initialize with levels=1.

Imports

OccGridEstimator

wrong

from nerfacc.estimators import OccGridEstimator

correct

from nerfacc import OccGridEstimator

Old import path changed in v0.5.0

ContractionType

wrong

from nerfacc.grid import ContractionType

correct

from nerfacc import ContractionType

ContractionType moved to top-level in v0.5.0

Quickstart

Initialize a multi-level occupancy grid and perform ray marching on a dummy grid.

import torch
from nerfacc import OccGridEstimator

device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
# Initialize an occupancy grid estimator for an unbounded scene (e.g., nerfstudio style)
estimator = OccGridEstimator(
    roi_aabb=[-2.0, -2.0, -2.0, 2.0, 2.0, 2.0],
    resolution=256,
    levels=2,
).to(device)

# Dummy occupancy update: random binary grid
random_occ = torch.randint(0, 2, (estimator.binaries.shape[0], *estimator.binaries.shape[2:]), device=device, dtype=torch.bool)
estimator.binaries = random_occ

# Ray marching: generate rays and compute step sizes
rays_o = torch.tensor([[0.0, 0.0, 0.0]], device=device)
rays_d = torch.tensor([[1.0, 0.0, 0.0]], device=device)
ray_indices, starts, ends, hits = estimator.marching(rays_o, rays_d, near_plane=0.0, far_plane=10.0)
print(f"Number of ray steps: {starts.shape[0]}")