physical-ai-neural-reconstruction

Physical AI Neural Reconstruction（NuRec）路由器

用途

这是一个用于 NVIDIA Neural Reconstruction（NuRec）请求的轻量路由器。它指向上游的 nurec-index 技能，地址为 https://github.com/NVIDIA/nurec-skills，以及其五个同级技能 （physical-ai-datasets、ncore、nre、asset-harvester、 nurec-fixer）。使用此技能来：

• 确定哪个上游同级技能可以解答 NuRec 问题。
• 定位、克隆或更新规范的 nurec-skills 检出副本。
• 在打开上游配方前，安排多步骤 NuRec 工作流（数据 → 转换 → 训练 → 渲染 → 清理）。

规范配方（训练、渲染、数据转换、数据集下载、对象采集、帧清理）位于上游同级技能中。切勿在此处复制或重构其命令。

请勿将此技能用于：

• CAD 或源网格的 SimReady 打包 → 使用 omniverse-cad-to-simready。
• 与 NuRec 无关的通用 USD 性能调优 → 使用 omniverse-usd-performance-tuning。
• AKS / OSMO / NIM Operator 基础设施设置 → 使用 physical-ai-infrastructure-setup-and-resilient-scaling。

适用场景

每当用户提到以下任一内容时，请先阅读此技能：

nurec、nurec router、nurec index、neural reconstruction、 neural reconstruction engine、NRE、3DGUT、3DGRT、USDZ、 NCore V4、sensor sim、novel view synthesis、 PhysicalAI-Autonomous-Vehicles-NuRec、PhysicalAI-NuRec-PPISP、 Cosmos-Drive-Dreams、asset harvester、nurec fixer、 DiffusionHarmonizer、harmonizer、difix、difix3d、serve-grpc、 render-grpc、warm serve-grpc、nre thin client、batch_render_rgb、 nurec teardown、“从哪里开始使用 NuRec”、“针对 X 应该使用哪个 NuRec 技能？”。

判断哪个上游同级技能可以解答问题，获取该技能（参见定位并获取上游技能），然后遵循该技能正文中的说明。

前置条件

路由器技能本身除获取上游内容所需的 git 外，没有其他运行时前置条件。下游同级技能需要：

• Docker + NVIDIA Container Toolkit + GPU — 用于 nre、nre-tools 和 nurec-fixer 容器 （nvcr.io/nvidia/nre/nre、nvcr.io/nvidia/nre/nre-tools、 nvcr.io/nvidia/cosmos/cosmos-predict2-container:1.2）。
• NGC API 密钥（NGC_API_KEY）— 用于拉取 NGC 容器。
• Hugging Face 令牌（HF_TOKEN），并且已在 Hugging Face 上预先接受 nvidia/PhysicalAI-*、nvidia/DiffusionHarmonizer 和 nvidia/asset-harvester 的受限许可。
• 安装了 huggingface_hub 的 Python 3.10+。
• （可选） CARLA、Isaac Sim 5.1 或 AlpaSim，用于通过 serve-grpc 集成模拟器。

安全地验证密钥（不要回显其值）：

hf auth whoami
[ -n "${HF_TOKEN:-}" ]      && echo "HF_TOKEN length=${#HF_TOKEN}"      || echo "HF_TOKEN unset"
[ -n "${NGC_API_KEY:-}" ]   && echo "NGC_API_KEY length=${#NGC_API_KEY}" || echo "NGC_API_KEY unset"

关于应避免的 bash 反模式，请参阅 references/secrets-handling.md。

什么是 NuRec？

NuRec（NVIDIA Omniverse Neural Reconstruction）可将摄像头、LiDAR、 雷达或立体摄像头录制的数据（通常来自自动驾驶汽车或 机器人）转换为 3D 场景，并可从任意视点重新渲染。常见名称包括：

• NRE — “Neural Reconstruction Engine”。NuRec 是产品；NRE 是用于训练和渲染的引擎。两者都指向上游的 nre 技能。
• USDZ — 训练后场景的文件格式。这是一种 zip 存档， Omniverse、Isaac Sim 和 CARLA 均可打开。
• NCore V4 — NRE 使用的输入格式。原始录制数据必须先转换为 NCore V4，才能进行训练。
• 3DGUT / 3DGRT — NRE 内部使用的两种 3D Gaussian Splatting 类型。 默认 Hydra 配方会选择其中一种；大多数用户无需手动设置。

典型的 NuRec 项目分为三个阶段：

1. 获取输入数据 — 将自己的录制数据转换为 NCore V4 （ncore），或下载预先转换好的数据集 （physical-ai-datasets）。
2. 训练重建结果 — 将 NCore V4 输入 NRE；输出为 USDZ（nre）。
3. 渲染新视图 — 从 USDZ 渲染图像、视频或 LiDAR 扫描数据 （nre）。

只想使用现有 NVIDIA 发布场景的项目可以跳过第 2 步。

选择技能

根据用户的目标匹配左列内容，并打开右列所列的上游 技能。箭头表示“按此顺序执行”。

我想要……	上游技能
查找或下载 NVIDIA 已发布的 NuRec 数据集	physical-ai-datasets
将自己的摄像头 / LiDAR / 雷达 / 深度 / 立体摄像头录制数据转换为 NCore V4	ncore
为不受支持的传感器配置（无人机、RGB-D、ROS 2 bag、COLMAP、ScanNet++）编写新的转换器	ncore
根据 NCore 片段训练 3D 重建	ncore → nre
生成 NRE 所需的额外输入（分割掩码、深度、自车掩码）	nre（使用 nre-tools 容器）
沿原始摄像头位置渲染 USDZ	nre
以全分辨率 / 最高质量渲染	nre（参见“质量预设”）
沿偏移后的轨迹渲染（例如汽车向左移动 3 m）	nre
通过服务渲染，让 CARLA / Isaac Sim / AlpaSim / 自定义模拟器可以请求帧	nre（serve-grpc）
在 Python 中从同一个 USDZ 连续多次渲染，尽量降低每次调用的延迟	nre（预热 serve-grpc + 精简 Python 客户端 / batch_render_rgb）
从 USDZ 渲染 LiDAR 扫描数据（点云）	nre（render-grpc --lidar）
跳过训练，直接渲染 NVIDIA 已构建的 NuRec 场景	physical-ai-datasets → nre
从驾驶片段中提取单个 3D 对象（汽车、行人）	asset-harvester
在 NuRec 场景中添加、移除或替换汽车 / 行人	asset-harvester → nre
清理或协调渲染帧（重影、漂浮物、闪烁、光照 / 阴影）	nurec-fixer，或在 nre 中使用 --enable-difix 进行内联渲染
将场景导出为 PLY、网格、深度图、自车掩码等	nre
升级旧版 USDZ，以便较新版本的 NRE 更快加载	nre（upgrade-artifact）
在浏览器查看器中打开 USDZ 或 PLY	nre（viewer / ply_viewer）
根据真实数据测量渲染质量（PSNR、SSIM、LPIPS）	nre（eval-rendering-metrics）
在相同场景上对不同的重建方法进行基准测试	physical-ai-datasets（PhysicalAI-NuRec-PPISP）→ nre
使用多 GPU 或 SLURM 进行训练	nre（工作流 D）

常见工作流

references/workflows.md 中记录了六种端到端工作流：

• A. 根据自己的录制数据创建 NuRec 场景。
• B. 使用 NVIDIA 已训练好的 NuRec 场景。
• C. 在场景中添加、移除或替换 3D 对象。
• D. 清理渲染帧。
• E. 对重建质量进行基准测试。
• F. 将 NuRec 接入模拟器。

如果用户的任务涉及多个同级技能，请打开该文件。

同级技能（上游）

名称	上游文件夹	功能
physical-ai-datasets	.agents/skills/physical-ai-datasets/	汇总并提供下载配方，涵盖 Hugging Face 上所有 NVIDIA Physical AI 数据集（驾驶、机器人、操作、NuRec 场景、基准测试）。
ncore	.agents/skills/ncore/	将任意传感器记录转换为 NCore V4（NRE 所需的格式）。还介绍如何编写新的转换器。
nre	.agents/skills/nre/	Neural Reconstruction Engine 本身。用于训练、渲染（本地渲染、通过预热的 serve-grpc + 精简 Python 客户端 / batch_render_rgb 渲染，或渲染到外部模拟器）、导出网格 / 点云 / 深度、编辑 Actor、评估质量。
asset-harvester	.agents/skills/asset-harvester/	开源的 Apache-2.0 流水线，可从驾驶片段的稀疏视角中提取单个 3D 对象，并将其保存为带元数据的 .ply Gaussian splats。
nurec-fixer	.agents/skills/nurec-fixer/	独立的 NVIDIA DiffusionHarmonizer 工作流——是旧版 Fixer / Difix3D+ 配方的公开后继方案——用于清理渲染帧、协调插入的 Actor、评估 PSNR/LPIPS，并可选择微调模型。

关于名称相近的项目（NRE 与 Fixer、ncore 与 nre、AV-NuRec 与 Cosmos-Drive-Dreams、NuRec 与 SimReady），请参阅 references/mix-ups.md。

定位并获取上游技能

快速配方（完整版本见 references/upstream-fetch.md）：

UPSTREAM_ROOT="${NUREC_SKILLS_UPSTREAM_ROOT:-${PHYSICAL_AI_SKILL_HUB_UPSTREAM_ROOT:-$HOME/.physical-ai-skill-hub/upstreams}}"
mkdir -p "$UPSTREAM_ROOT"
if [ -d "$UPSTREAM_ROOT/nurec-skills/.git" ]; then
  git -C "$UPSTREAM_ROOT/nurec-skills" fetch --tags
  git -C "$UPSTREAM_ROOT/nurec-skills" checkout main
  git -C "$UPSTREAM_ROOT/nurec-skills" pull --ff-only
else
  git clone --depth 1 https://github.com/NVIDIA/nurec-skills.git \
    "$UPSTREAM_ROOT/nurec-skills"
fi
test -f "$UPSTREAM_ROOT/nurec-skills/.agents/skills/SKILL.md"

然后，在运行任何会修改内容的命令之前，先阅读上游技能：

cat "$UPSTREAM_ROOT/nurec-skills/.agents/skills/SKILL.md"          # router
cat "$UPSTREAM_ROOT/nurec-skills/.agents/skills/<folder>/SKILL.md" # sibling

本地查找顺序（尝试完毕后再克隆上游仓库）：

1. .agents/skills/<name>/SKILL.md（Cursor、Codex、NemoClaw）
2. .claude/skills/<name>/SKILL.md（Claude Code）
3. .cursor/skills/<name>/SKILL.md（项目级）
4. ~/.cursor/skills/<name>/SKILL.md（个人技能）

硬性规则

• 这里只负责路由，不要在此重复上游 NuRec 配方。运行任何会修改内容的命令之前，先阅读上游同级技能正文。
• 通过同级技能的 name: 引用它们（例如 nre），而不是使用仓库路径。文件夹布局可能会改变；名称具有可移植性。
• 在共享上游根目录下克隆或刷新 https://github.com/NVIDIA/nurec-skills（${NUREC_SKILLS_UPSTREAM_ROOT:-${PHYSICAL_AI_SKILL_HUB_UPSTREAM_ROOT:-$HOME/.physical-ai-skill-hub/upstreams}}/nurec-skills）。 不要扫描 ~/Codes 等宽泛的开发者工作区，也不要复用无关的旧克隆。
• physical-ai-datasets 涵盖受限访问的 Hugging Face 数据集。不要绕过数据集许可条款；用户必须先在 Hugging Face 上接受 PhysicalAI-* 受限许可，并提供令牌，然后才能下载。
• Asset Harvester 必须在打包为 USDZ 之前运行。除非用户明确要求跳过 Asset Harvester，否则不要对手动制作的 .ply 文件调用 nre 的 export-external-assets。
• 清理产物时，优先使用 nre 内置的 --enable-difix 路径。仅当用户需要公开代码 / 模型卡、配对评估、微调，或修复先前渲染的帧时，才转到独立的 nurec-fixer。
• 不要凭记忆编造 NRE / NCore / DiffusionHarmonizer 命令。请重新阅读上游同级技能——版本更新很快（NRE 当前固定使用的标签为 release_26.04）。
• 此路由器不负责部署基础设施。AKS / OSMO / NIM Operator 的设置应转到 physical-ai-infrastructure-setup-and-resilient-scaling。

局限

• 仅作路由。 此技能不会执行会更改状态的 NuRec 命令。 所有训练、渲染、转换和协调操作都由上游的同级技能完成。
• 固定上游来源。 配方位于 https://github.com/NVIDIA/nurec-skills，其更新独立于 此仓库。过时的克隆可能会出现偏差；依赖同级技能前，务必先对上游执行 git pull。
• 受限内容。 nvidia/PhysicalAI-*、nvidia/DiffusionHarmonizer 和 nvidia/asset-harvester 要求用户先在 Hugging Face 接受许可条款。此路由器无法绕过此要求。
• 占用空间大。 完整的 NuRec 工作流可能占用 150 GB 以上 的磁盘空间。请参阅 references/teardown.md。
• 仅支持 NVIDIA 技术栈。 需要 NVIDIA GPU 和 NVIDIA Container Toolkit。不支持 AMD / Intel / Apple Silicon。
• 不是 SimReady 流水线。 NuRec 根据录制内容生成可渲染的 USDZ；CAD 或源网格的 SimReady 打包属于不同的流水线（请参阅 omniverse-cad-to-simready）。

故障排除

错误 / 症状	可能原因	解决方案
nurec-skills 克隆缺失或为空	尚未获取上游内容	运行定位并获取上游技能中的克隆代码块
从 HF 拉取 nvidia/PhysicalAI-* 时出现 403/401	尚未接受受限许可，或未设置 HF_TOKEN / 令牌权限范围不正确	在 Hugging Face 接受受限许可，然后使用具有 read 访问权限的令牌执行 hf auth login
从 nvcr.io/nvidia/nre/* 收到 denied: requested access to the resource is denied	缺少或过期的 NGC_API_KEY	使用 $oauthtoken / NGC_API_KEY 执行 docker login nvcr.io；如有需要，请在 org.ngc.nvidia.com/setup/api-key 轮换密钥
NRE 拒绝加载片段（“not valid NCore V4”）	录制内容尚未转换	调用 nre 前先运行 ncore 技能
serve-grpc 冷启动延迟在 Python 循环中占主导	每次渲染都单独调用一次 Docker	使用 nre 的预热 serve-grpc + 精简 Python 客户端（batch_render_rgb）配方
docker run 后输出文件的所有者是 root	未提供 -u $(id -u):$(id -g)	执行 sudo chown -R "$(id -u):$(id -g)" <output_dir>；下次添加 -u 标志
渲染后帧出现重影 / 悬浮物 / 闪烁	未启用内联清理	使用 nre --enable-difix 重新渲染，或使用 nurec-fixer（DiffusionHarmonizer）进行后处理
Agent 输出中出现过时的技能名称（ncore-data-conversion、旧版 nvidia/Fixer）	缓存的技能已过时	将引用更新为 ncore 和 nurec-fixer（DiffusionHarmonizer）；请参阅 references/maintenance.md
Bash 反模式 ${HF_TOKEN:+yes}${HF_TOKEN:-no} 输出了令牌值	错误使用 Bash 参数展开	轮换令牌；使用 hf auth whoami 或仅检查长度（请参阅 references/secrets-handling.md）

跨技能清理

完整的 NuRec 工作流可能会因容器映像、模型权重、代码克隆、conda 环境和输出目录而占用 150 GB 以上 的磁盘空间。每个同级技能都有专门的 Teardown 部分；当用户不再需要此工作流时，请按 references/teardown.md 中记录的顺序阅读。

保持此路由器为最新版本

添加新的同级技能、重命名技能或更改上游 URL 的流程见 references/maintenance.md。 请将上游的 nurec-index 视为权威来源： https://github.com/NVIDIA/nurec-skills/blob/main/.agents/skills/SKILL.md 此技能仅同步选择器表格、工作流顺序和上游获取配方。