https://www.nerfacc.com/

[新闻] 2023/04/04. 如果您之前使用的是 nerfacc <= 0.3.5 并希望迁移到我们的最新版本 (nerfacc >= 0.5.0)，请查看 CHANGELOG 了解迁移方法。

NerfAcc 是一个用于训练和推理的 PyTorch NeRF 加速工具箱。它专注于辐射场 (radiance fields) 体渲染 (volumetric rendering) 管线中的高效采样，这对大多数 NeRF 是通用且即插即用 (plug-and-play) 的。 只需对现有代码库进行最小修改，Nerfacc 就能在各种最新的 NeRF 论文训练中提供显著的速度提升。 并且它拥有灵活的 API (应用程序编程接口) 纯 Python 接口！

安装

依赖项: 请先安装 PyTorch。

最简单的方式是从 PyPI 安装。这种方式将在首次运行时构建 CUDA 代码（JIT (即时编译)）。

pip install nerfacc

或者从源代码安装。这种方式将在安装期间构建 CUDA 代码。

pip install git+https://github.com/nerfstudio-project/nerfacc.git

我们还提供了预构建的 wheel 包，覆盖了 官方 PyTorch 支持的主要 PyTorch + CUDA 组合。

# e.g., torch 1.13.0 + cu117
pip install nerfacc -f https://nerfacc-bucket.s3.us-west-2.amazonaws.com/whl/torch-1.13.0_cu117.html

Windows 和 Linux	cu113	cu115	cu116	cu117	cu118
torch 1.11.0	✅	✅
torch 1.12.0	✅		✅
torch 1.13.0			✅	✅
torch 2.0.0				✅	✅

对于 nerfacc 的旧版本，请在此处 here 查看支持的预构建 wheel 包。

用法

NerfAcc 的理念是使用计算开销较小的估计器进行高效的体采样以发现表面。 因此 NerfAcc 可以与任何用户定义的辐射场配合使用。要将 NerfAcc 渲染管线集成到您的代码中并享受加速，您只需要定义两个与您的辐射场相关的函数。

• sigma_fn: 计算每个样本处的密度。它将被估计器（例如 nerfacc.OccGridEstimator (占用网格估计器), nerfacc.PropNetEstimator (提议网络估计器)）用于发现表面。
• rgb_sigma_fn: 计算每个样本处的颜色和密度。它将被 nerfacc.rendering 用于进行可微分体渲染。此函数将接收梯度以更新您的辐射场。

一个简单的示例如下：

import torch
from torch import Tensor
import nerfacc 

radiance_field = ...  # network: a NeRF model
rays_o: Tensor = ...  # ray origins. (n_rays, 3)
rays_d: Tensor = ...  # ray normalized directions. (n_rays, 3)
optimizer = ...       # optimizer

estimator = nerfacc.OccGridEstimator(...)

def sigma_fn(
    t_starts: Tensor, t_ends:Tensor, ray_indices: Tensor
) -> Tensor:
    """ Define how to query density for the estimator."""
    t_origins = rays_o[ray_indices]  # (n_samples, 3)
    t_dirs = rays_d[ray_indices]  # (n_samples, 3)
    positions = t_origins + t_dirs * (t_starts + t_ends)[:, None] / 2.0
    sigmas = radiance_field.query_density(positions) 
    return sigmas  # (n_samples,)

def rgb_sigma_fn(
    t_starts: Tensor, t_ends: Tensor, ray_indices: Tensor
) -> Tuple[Tensor, Tensor]:
    """ Query rgb and density values from a user-defined radiance field. """
    t_origins = rays_o[ray_indices]  # (n_samples, 3)
    t_dirs = rays_d[ray_indices]  # (n_samples, 3)
    positions = t_origins + t_dirs * (t_starts + t_ends)[:, None] / 2.0
    rgbs, sigmas = radiance_field(positions, condition=t_dirs)  
    return rgbs, sigmas  # (n_samples, 3), (n_samples,)

# Efficient Raymarching:
# ray_indices: (n_samples,). t_starts: (n_samples,). t_ends: (n_samples,).
ray_indices, t_starts, t_ends = estimator.sampling(
    rays_o, rays_d, sigma_fn=sigma_fn, near_plane=0.2, far_plane=1.0, early_stop_eps=1e-4, alpha_thre=1e-2, 
)

# Differentiable Volumetric Rendering.
# colors: (n_rays, 3). opacity: (n_rays, 1). depth: (n_rays, 1).
color, opacity, depth, extras = nerfacc.rendering(
    t_starts, t_ends, ray_indices, n_rays=rays_o.shape[0], rgb_sigma_fn=rgb_sigma_fn
)

# Optimize: Both the network and rays will receive gradients
optimizer.zero_grad()
loss = F.mse_loss(color, color_gt)
loss.backward()
optimizer.step()

示例：

在运行这些示例脚本之前，请检查脚本所需的数据集，并先下载该数据集。您可以使用 --data_root 指定路径。

# clone the repo with submodules.
git clone --recursive git://github.com/nerfstudio-project/nerfacc/

静态 NeRFs

完整基准测试请参见：https://www.nerfacc.com/en/stable/examples/static.html

在 NeRF-Synthetic 数据集上使用 Instant-NGP，4.5 分钟内获得更好的性能。

# Occupancy Grid Estimator
python examples/train_ngp_nerf_occ.py --scene lego --data_root data/nerf_synthetic
# Proposal Net Estimator
python examples/train_ngp_nerf_prop.py --scene lego --data_root data/nerf_synthetic

在 Mip-NeRF 360 数据集上使用 Instant-NGP，5 分钟内获得更好的性能。

# Occupancy Grid Estimator
python examples/train_ngp_nerf_occ.py --scene garden --data_root data/360_v2
# Proposal Net Estimator
python examples/train_ngp_nerf_prop.py --scene garden --data_root data/360_v2

在 NeRF-Synthetic 数据集上使用原生 MLP NeRF，耗时一小时。

# Occupancy Grid Estimator
python examples/train_mlp_nerf.py --scene lego --data_root data/nerf_synthetic

在 Tanks&Temple 和 NeRF-Synthetic 数据集上使用 TensoRF（插件形式集成到官方代码库中）。

cd benchmarks/tensorf/

# (set up the environment for that repo)
bash script.sh nerfsyn-nerfacc-occgrid 0
bash script.sh tt-nerfacc-occgrid 0

动态 NeRFs (神经辐射场)

完整基准测试请见：https://www.nerfacc.com/en/stable/examples/dynamic.html

T-NeRF 在 D-NeRF 数据集上仅需一小时。

# Occupancy Grid Estimator
python examples/train_mlp_tnerf.py --scene lego --data_root data/dnerf

K-Planes 在 D-NeRF 数据集上（官方代码库插件）。

cd benchmarks/kplanes/
# (set up the environment for that repo)
bash script.sh dnerf-nerfacc-occgrid 0

TiNeuVox 在 HyperNeRF 和 D-NeRF 数据集上（官方代码库插件）。

cd benchmarks/tineuvox/
# (set up the environment for that repo)
bash script.sh dnerf-nerfacc-occgrid 0
bash script.sh hypernerf-nerfacc-occgrid 0
bash script.sh hypernerf-nerfacc-propnet 0

相机优化 NeRFs

完整基准测试请见：https://www.nerfacc.com/en/stable/examples/camera.html

BARF 在 NeRF-Synthetic 数据集上（官方代码库插件）。

cd benchmarks/barf/
# (set up the environment for that repo)
bash script.sh nerfsyn-nerfacc-occgrid 0

第三方用途：

优秀代码库。

• nerfstudio: 一个对 NeRF 友好的协作工作室。
• sdfstudio: 表面重建的统一框架。
• threestudio: 3D 内容创建的统一框架。
• instant-nsr-pl: 10 分钟实现 NeuS。
• modelscope: 深度学习算法集合。

优秀论文。

• Representing Volumetric Videos as Dynamic MLP Maps, CVPR 2023
• NeRSemble: Multi-view Radiance Field Reconstruction of Human Heads, ArXiv 2023
• HumanRF: High-Fidelity Neural Radiance Fields for Humans in Motion, ArXiv 2023

常见安装问题

ImportError: .../csrc.so: undefined symbol

如果您正在安装预编译的 wheel，请确保 Pytorch 和 CUDA 版本与 nerfacc 版本（nerfacc.__version__）匹配。

引用

@article{li2023nerfacc,
  title={NerfAcc: Efficient Sampling Accelerates NeRFs.},
  author={Li, Ruilong and Gao, Hang and Tancik, Matthew and Kanazawa, Angjoo},
  journal={arXiv preprint arXiv:2305.04966},
  year={2023}
}

NerfAcc 快速上手指南

NerfAcc 是一个基于 PyTorch 的 NeRF 加速工具箱，专注于体渲染管线中的高效采样。它提供纯 Python 接口，可即插即用，能显著加快各种 NeRF 模型的训练和推理速度。

环境准备

• 操作系统: Windows 或 Linux
• 核心依赖: PyTorch (请先安装)
• 硬件要求: 支持 CUDA 的 GPU (用于编译 CUDA 代码)

安装步骤

推荐使用 PyPI 进行安装，首次运行时会即时编译（JIT）CUDA 代码。

pip install nerfacc

如需从源码安装（在编译阶段构建 CUDA 代码）：

pip install git+https://github.com/nerfstudio-project/nerfacc.git

注意：如果您需要特定版本的 PyTorch 与 CUDA 组合，可使用预编译的 wheel 包（例如 torch 1.13.0 + cu117）：

pip install nerfacc -f https://nerfacc-bucket.s3.us-west-2.amazonaws.com/whl/torch-1.13.0_cu117.html

基本使用

NerfAcc 的核心思想是使用计算廉价的估计器进行高效的体积采样以发现表面。您只需定义两个函数即可将 NerfAcc 集成到您的代码中：

1. sigma_fn: 计算每个样本的密度，供估计器（如 OccGridEstimator）使用。
2. rgb_sigma_fn: 计算每个样本的颜色和密度，供 nerfacc.rendering 进行可微分体积渲染。

以下是最简示例代码：

import torch
from torch import Tensor
import nerfacc 

radiance_field = ...  # 网络：一个 NeRF 模型
rays_o: Tensor = ...  # 射线原点。 (n_rays, 3)
rays_d: Tensor = ...  # 射线归一化方向。 (n_rays, 3)
optimizer = ...       # 优化器

estimator = nerfacc.OccGridEstimator(...)

def sigma_fn(
    t_starts: Tensor, t_ends:Tensor, ray_indices: Tensor
) -> Tensor:
    """ 定义如何为估计器查询密度。"""
    t_origins = rays_o[ray_indices]  # (n_samples, 3)
    t_dirs = rays_d[ray_indices]  # (n_samples, 3)
    positions = t_origins + t_dirs * (t_starts + t_ends)[:, None] / 2.0
    sigmas = radiance_field.query_density(positions) 
    return sigmas  # (n_samples,)

def rgb_sigma_fn(
    t_starts: Tensor, t_ends: Tensor, ray_indices: Tensor
) -> Tuple[Tensor, Tensor]:
    """ 从用户定义的辐射场查询 rgb 和密度值。 """
    t_origins = rays_o[ray_indices]  # (n_samples, 3)
    t_dirs = rays_d[ray_indices]  # (n_samples, 3)
    positions = t_origins + t_dirs * (t_starts + t_ends)[:, None] / 2.0
    rgbs, sigmas = radiance_field(positions, condition=t_dirs)  
    return rgbs, sigmas  # (n_samples, 3), (n_samples,)

# 高效光线步进 (Raymarching)
# ray_indices: (n_samples,). t_starts: (n_samples,). t_ends: (n_samples,).
ray_indices, t_starts, t_ends = estimator.sampling(
    rays_o, rays_d, sigma_fn=sigma_fn, near_plane=0.2, far_plane=1.0, early_stop_eps=1e-4, alpha_thre=1e-2, 
)

# 可微分体积渲染
# colors: (n_rays, 3). opacity: (n_rays, 1). depth: (n_rays, 1).
color, opacity, depth, extras = nerfacc.rendering(
    t_starts, t_ends, ray_indices, n_rays=rays_o.shape[0], rgb_sigma_fn=rgb_sigma_fn
)

# 优化：网络和射线都将接收梯度
optimizer.zero_grad()
loss = F.mse_loss(color, color_gt)
loss.backward()
optimizer.step()