NKSR：实践指南

作者：袖梨 2026-09-11

面对实际交付，我看NKSR的重点不在星标，而在这项能力：【CVPR 2023亮点】神经核表面重建—。实际做日常自动化时，经常会碰到输入边界、依赖和失败处理如果不清楚就很难稳定复用，所以功能列表并不能代替验证。先用一项范围明确的真实任务完成最小试跑更稳妥；过程中要观察配置时间、输出质量、异常信息和维护痕迹，失败也应能解释原因。如果团队属于愿意先做小范围验证并复查原始文档的团队，它有继续测试的理由；否则先看替代方案会更省时间。

神经核表面重建

神经核表面重建

黄家辉, 赞·戈伊西奇, 马坦·阿兹蒙， 或连串， Sanja Fidler， 弗朗西斯·威廉姆斯

论文、项目页面

摘要：我们提出了一种从大规模、稀疏和噪声点云重建 3D 隐式表面的新方法。 我们的方法建立在最近推出的 神经核场 (NKF) 表示的基础上。 它具有与 NKF 类似的泛化能力，同时解决了其主要局限性： (a) 我们可以通过紧凑支持的核函数扩展到大型场景，从而可以使用内存高效的稀疏线性求解器。 (b) 通过梯度拟合求解，我们对噪声具有鲁棒性。 （c）我们最大限度地减少训练要求，使我们能够从任何密集定向点的数据集中学习，甚至混合由不同尺度的对象和场景组成的训练数据。 我们的方法能够在几秒钟内重建数百万个点，并以核外方式处理非常大的场景。 我们在由单个对象、室内场景和室外场景组成的重建基准上取得了最先进的结果。

如需业务咨询，请访问我们的网站并提交表格：NVIDIA 研究许可

新闻动态

  • 2025-09-08：由于预建轮子已过期，我们上传了完整的CUDA代码，以便用户自行编译。新车轮兼容PyTorch 2.7.0和CUDA 12.8。
  • 2023-06-24：想要从 iPhone 扫描构建网格？我们的朋友 Phong Nguyen Ha 分享了他的教程！在这里查看 here。
  • 2023-06-08：代码发布！

环境设置

我们建议使用最新的Python和PyTorch来运行我们的算法。要使用 conda 安装所有依赖项：

# Clone the repository
git clone [email protected]:nv-tlabs/nksr.git
cd nksr

# Create conda environment
conda env create -f environment.yml
conda activate nksr
pip install -r requirements.txt

# Build NKSR
pip install --no-build-isolation package/

在您自己的数据上测试 NKSR

我们已经在多个不同的空间尺度上测试了我们的算法。它可以在 RTX 3090 GPU 上重建跨越数公里、包含数百万个点的场景。 要使用我们的 kitchen-sink 模型（在 CC-BY-SA 4.0 许可证下发布），以下代码片段就足够了：

import torch
import nksr

bunny_geom = load_bunny_example()

input_xyz = torch.from_numpy(np.asarray(bunny_geom.points)).float().to(device)
input_normal = torch.from_numpy(np.asarray(bunny_geom.normals)).float().to(device)

reconstructor = nksr.Reconstructor(device)
field = reconstructor.reconstruct(input_xyz, input_normal, detail_level=1.0)
mesh = field.extract_dual_mesh(mise_iter=1)

我们在 NKSR 文档页面 准备了有关数据准备和不同示例用法的详细说明。

重现论文结果

我们的训练和推理系统基于Zeus深度学习基础设施，支持tensorboard和wandb（推荐）作为记录器。要配置 Zeus，请复制默认的 yaml 文件并修改相关路径：

cp configs/default/zeus.yaml zeus_config.yaml

根据需要修改 zeus_config.yaml 的内容，包括您的 wandb 帐户名和 checkpoint/test 结果保存目录。

培训

资料下载链接：

  • ShapeNet：数据可在此处 here（取自 占用网络）。将解压出来的onet文件夹放在../data/shapenet下。
  • Points2Surf：数据可在此处 here 获得。我们使用 blensor 按照原始脚本重新生成所有数据，以获得输入法线。
  • CARLA：数据可在此处 here 获得。

主要训练脚本为train.py。我们为我们在论文中进行基准测试的不同数据集提供了不同的配置文件：

# ShapeNet small noise 1K input
python train.py configs/shapenet/train_1k_perfect.yaml
# ShapeNet medium noise 3K input
python train.py configs/shapenet/train_3k_noise.yaml
# ShapeNet big noise 3K input
python train.py configs/shapenet/train_3k_noiser.yaml
# Points2Surf dataset noisy input
python train.py configs/points2surf/train.yaml
# CARLA dataset
python train.py configs/carla/train.yaml

此外，您还可以手动指定不同的训练设置，以获得适合您需求的模型。常见的标志包括：

  • --wname：为 wandb 记录器指定的附加实验名称。
  • --voxel_size：最精细级别体素的大小。
  • --feature：编码器的附加功能，none无任何功能，normal（默认）用于正常输入，sensor用于传感器方向输入。
  • --tree_depth：稀疏特征层次结构的深度。默认值为 4。

推理

您可以使用自己训练的模型或我们预先训练的检查点进行推断。

# From pre-trained checkpoints
python test.py configs/shapenet/train_3k_noise.yaml --url https://huggingface.co/heiwang1997/nksr-checkpoints/resolve/main/checkpoints/snet-n3k-wnormal.pth --exec udf.enabled=False
python test.py configs/points2surf/train.yaml --url https://huggingface.co/heiwang1997/nksr-checkpoints/resolve/main/checkpoints/p2s.pth --include configs/points2surf/data_abc_test.yaml
python test.py configs/carla/train.yaml --url https://huggingface.co/heiwang1997/nksr-checkpoints/resolve/main/checkpoints/carla.pth  --include configs/carla/data_no_patch.yaml

# From your own trained models
python test.py none --ckpt wdb:<WANDB_USER_NAME>/<WANDB_PROJECT>/<WANDB_RUN_ID>

test.py 的有用标志包括：

  • -v 或 --visualize：在测试过程中可视化结果。
  • --test_print_metrics：在测试期间打印指标。
  • --test_n_upsample：几何上采样级别。建议值为 4。

相关作品

NKSR 高度基于以下现有作品：

  • 威廉姆斯等人。 2021. 神经场作为 3D 重建的可学习内核。
  • 黄等人。 2022. 用于精确表面重建的神经伽辽金求解器。

相关文章

精彩推荐