Kaolin Wisp：用于神经场研究的 PyTorch 库和引擎

NVIDIA Kaolin Wisp 是一个基于 NVIDIA Kaolin Core 的 PyTorch 库，用于处理神经场（包括 NeRF、NGLOD、instant-ngp 和 VQAD 等）。

NVIDIA Kaolin Wisp 的目标是为神经场研究提供一组通用的实用工具函数。这包括数据集、图像输入输出、网格处理以及光线相关的实用函数。Wisp 还提供了可微分渲染器和可微分数据结构（如八叉树、哈希网格、三平面特征）等构建模块，这些对于构建复杂的神经场非常有用。此外，它还包含调试可视化工具、交互式渲染与训练、日志记录以及训练器类。

请访问我们的文档站点获取更多信息！

若想了解神经场的概述，我们推荐您阅读 EG STAR 报告：Neural Fields for Visual Computing and Beyond。

最新更新

wisp 1.0.3 <-- main

• 2023年4月17日 配置系统已被替换！请查看 配置页面，了解使用说明及向后兼容性问题（重大变更）。请注意，wisp 核心库仍保持兼容，但主程序和训练器需要更新。

wisp 1.0.2 <-- stable

• 2023年4月15日 新增了 Jupyter Notebook 支持，这对于没有显示器的机器非常有用。
• 2023年2月1日 作为新数据集框架的一部分，添加了 attrdict 依赖项。如果您拉取最新代码，请确保运行 pip install attrdict。
• 2023年1月17日 将 pycuda 替换为 cuda-python。现在可以通过 pip 安装 Wisp（如果您拉取最新代码，请运行 pip install -r requirements_app.txt）。
• 2023年1月5日 主程序现以独立应用程序的形式引入，以便更轻松地支持新的工作流（重大变更）。

安装

安装说明请参见 此处。

外部贡献

我们欢迎并鼓励对代码库的外部贡献！有关详细信息，请阅读 常见问题解答 和 许可证页面。

许可证与引用

本代码库采用 NVIDIA 源代码许可证授权。我们也提供免费的商业许可证。请通过此链接申请（选择“其他”并注明 Kaolin Wisp）：https://www.nvidia.com/en-us/research/inquiries/

如果您发现 NVIDIA Kaolin Wisp 库对您的研究有所帮助，请引用以下内容：

@misc{KaolinWispLibrary,
      author = {Towaki Takikawa and Or Perel and Clement Fuji Tsang and Charles Loop and Joey Litalien and Jonathan Tremblay and Sanja Fidler and Maria Shugrina},
      title = {Kaolin Wisp: A PyTorch Library and Engine for Neural Fields Research},
      year = {2022},
      howpublished={\url{https://github.com/NVIDIAGameWorks/kaolin-wisp}}
}

致谢

我们感谢 James Lucas、Jonathan Tremblay、Valts Blukis、Anita Hu 和 Nishkrit Desai 在开发过程中各个阶段给予的早期反馈和测试。同时，我们也感谢 Rogelio Olguin 和 Jonathan Tremblay 提供的 Wisp 参考数据。

特别感谢社区成员：

• lightfield botanist
• Soumik Rakshit

什么是“wisp”？

我们的库以大气中的幽灵之光——鬼火命名。鬼火是一种体积型的“幽灵”，用常见的几何表示方法（如网格）难以建模。我们提供了一个关于鬼火的 多视角数据集，作为体积对象的参考数据集。此外，我们还提供了 Blender 文件和渲染脚本。如果您希望使用该场景生成特定数据，请参阅 readme.md，以获取更多关于如何生成数据的详细信息。

Kaolin Wisp 快速上手指南

Kaolin Wisp 是由 NVIDIA 开发的基于 PyTorch 的库与引擎，专为神经场（Neural Fields）研究设计。它支持 NeRF、NGLOD、instant-ngp 和 VQAD 等模型，提供可微渲染器、数据结构（如八叉树、哈希网格）、数据集工具及训练框架。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 18.04/20.04) 或 Windows (WSL2 支持良好)。
• GPU: 支持 CUDA 的 NVIDIA 显卡。
• Python: 版本 3.7 或更高。
• PyTorch: 需预先安装与您的 CUDA 版本匹配的 PyTorch。
• 前置依赖:
  • cuda-python (替代了旧版的 pycuda)
  • attrdict (用于新的数据集框架)

注意：如果您从最新源码拉取代码，请务必安装应用层依赖：

pip install -r requirements_app.txt

安装步骤

方法一：通过 Pip 安装（推荐）

自 2023 年 1 月更新后，Wisp 支持直接通过 pip 安装，这是最简便的方式。

pip install kaolin-wisp

方法二：从源码安装

如果您需要最新的功能或进行二次开发，可以从 GitHub 克隆源码安装。

1. 克隆仓库：

   git clone https://github.com/NVIDIAGameWorks/kaolin-wisp.git
   cd kaolin-wisp
   

2. 安装依赖并构建：

   # 安装核心依赖和应用依赖
   pip install -r requirements.txt
   pip install -r requirements_app.txt
   
   # 以编辑模式安装（方便开发调试）
   pip install -e .
   

国内加速提示：如果下载依赖较慢，建议使用国内镜像源。例如：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

Kaolin Wisp 采用了模块化的应用程序（Mains）架构。以下是运行一个基础神经场训练任务的通用流程。

1. 准备配置文件

Wisp 使用配置文件来定义模型架构、数据集和优化器参数。您通常可以在 apps/configs 目录下找到示例配置（如 nerf_blender.yaml）。

2. 运行训练

使用 wisp_train 命令启动训练。以下是一个最简单的示例，假设您有一个名为 my_config.yaml 的配置文件：

wisp_train --config apps/configs/nerf_blender.yaml

3. 交互式可视化与推理

训练完成后（或在训练过程中），您可以使用 wisp_render 进行交互式渲染或生成结果视频：

wisp_render --config apps/configs/nerf_blender.yaml --checkpoint logs/experiment_name/checkpoints/latest.pth

4. Jupyter Notebook 支持

对于没有显示输出（headless）的服务器环境，Wisp 提供了 Jupyter Notebook 支持，方便进行调试和可视化：

# 在 Notebook 单元格中
from wisp.framework.interactive import InteractiveRenderer

# 初始化并加载您的模型进行预览
renderer = InteractiveRenderer()
renderer.load_checkpoint("path/to/checkpoint.pth")
renderer.show()

重要提示：自 v1.0.3 版本起，配置系统已重构。如果您使用的是旧版配置文件，请参考官方文档的配置页面进行迁移，因为这是一个破坏性更新（breaking change）。