EmbodiedScan多视角3D检测实战：从零训练你的第一个检测模型（附完整命令）

EmbodiedScan多视角3D检测实战：从零训练你的第一个检测模型（附完整命令）

【免费下载链接】EmbodiedScan[CVPR 2024 & NeurIPS 2024] EmbodiedScan: A Holistic Multi-Modal 3D Perception Suite Towards Embodied AI项目地址: https://gitcode.com/gh_mirrors/em/EmbodiedScan

EmbodiedScan 是面向具身智能（Embodied AI）的多模态 3D 感知数据集与基准，而多视角3D检测正是它的核心任务之一：模型从第一人称 RGB-D 序列中还原场景里每个物体的 3D 包围框与类别。这篇实战教程将带你从环境安装、数据准备到3D检测模型训练命令一键跑通，即使你是第一次接触 3D 视觉，也能在 30 分钟内启动自己的训练任务。

EmbodiedScan 是什么：为什么多视角3D检测值得学习

想象一下，机器人戴着一台相机走进客厅，它需要一边移动一边理解"沙发在哪、茶几在哪个方向、它离我多远"——这就是多视角3D检测要解决的问题。传统 3D 检测往往依赖全局点云，而 EmbodiedScan 更贴近真实世界：以第一人称视角输入多帧 RGB-D 图像，输出场景中 760+ 类别的 3D 朝向框。

这个 CVPR 2024 收录的项目包含惊人的数据规模：

最快配置方法：EmbodiedScan 环境搭建完整指南

在开始3D检测模型训练之前，需要先准备环境。官方推荐环境为 Ubuntu 20.04、Python 3.8、CUDA 11.3+，建议准备一张 11GB 以上显存的显卡。

第一步：克隆仓库并创建虚拟环境

git clone https://gitcode.com/gh_mirrors/em/EmbodiedScan cd EmbodiedScan conda create -n embodiedscan python=3.8 -y conda activate embodiedscan

第二步：安装 PyTorch

conda install pytorch==1.11.0 torchvision==0.12.0 torchaudio==0.11.0 cudatoolkit=11.3 -c pytorch

第三步：一键安装全部依赖

项目贴心地提供了自动化安装脚本，会自动处理 MinkEngine、PyTorch3D 等"重灾区"依赖：

python install.py all # 安装全部依赖（含可视化） python install.py run # 只装运行依赖 python install.py visual # 只装可视化依赖

安装过程耗时较长属于正常现象，尤其是 MinkEngine 与 PyTorch3D 需要编译，请耐心等待（脚本逻辑见 install.py）。

数据准备：多视角3D检测数据集下载与组织

训练数据由 ScanNet、3RScan、Matterport3D、ARKitScenes 原始数据 + EmbodiedScan 官方标注组成。数据组织方式详见 data/README.md，核心目录结构如下：

data ├── scannet / 3rscan / matterport3d / arkitscenes ├── embodiedscan_infos_train.pkl ├── embodiedscan_infos_val.pkl ├── embodiedscan_train_vg.json └── embodiedscan_occupancy

下载原始数据并解压到data/后，还需要把.sens等原始格式转换成模型可读的图片，运行仓库自带的转换脚本：

python embodiedscan/converter/generate_image_scannet.py --dataset_folder data/scannet/ python embodiedscan/converter/generate_image_3rscan.py --dataset_folder data/3rscan/ python embodiedscan/converter/extract_occupancy_ann.py --src data/embodiedscan_occupancy --dst data

如果暂时拿不到完整数据集，也可以先下载官方的单场景 demo 数据，配合 demo/demo.py 体验推理效果。

读懂配置文件：mv-det3d 检测模型结构拆解

开工前先花 2 分钟看懂训练配置。多视角 3D 检测的官方基线配置位于 configs/detection/mv-det3d_8xb4_embodiedscan-3d-284class-9dof.py，核心设计如下：

• 模型：SparseFeatureFusionSingleStage3DDetector，2D 与 3D 特征融合的单阶段检测器
• 2D 主干：ResNet50，负责提取 RGB 图像特征
• 3D 主干：MinkResNet34，处理由多视角深度图融合出的点云
• 检测头：FCAF3DHeadRotMat，支持旋转框（9-DoF）回归
• 类别数：284 类，每帧训练取 20 张视图（n_images=20），测试取 50 张
• 训练策略：12 epochs、AdamW（lr=0.001）、MultiStepLR 在 [8, 11] epoch 衰减

正如架构图所示，模型接受任意数量的 RGB-D 视图，2D 图像与 3D 点云特征被异构地融合，最终通过稀疏解码器输出 3D 检测框——这也是 Embodied Perceptron 系列模型的核心思想。

一键启动训练：3D检测模型训练完整命令

环境就绪、数据就位后，训练其实只需一条命令。以下命令会直接调用 tools/train.py，将日志和权重保存到work_dirs/mv-3ddet：

单 GPU 训练（推荐新手先试）

python tools/train.py configs/detection/mv-det3d_8xb4_embodiedscan-3d-284class-9dof.py --work-dir=work_dirs/mv-3ddet

多 GPU 分布式训练

python tools/train.py configs/detection/mv-det3d_8xb4_embodiedscan-3d-284class-9dof.py --work-dir=work_dirs/mv-3ddet --launcher="pytorch"

训练过程中，CheckpointHook每个 epoch 都会保存一次权重（最多保留 4 份），12 个 epoch 跑完后你会得到epoch_12.pth。官方基线的最终成绩为AP@0.25 = 15.22，可以作为你验证训练是否成功的参照线。如果显存不足，可通过--amp开启混合精度训练。

测试与评估：验证多视角3D检测效果

训练完成后，用 tools/test.py 在验证集上评估模型的 AP/AR 指标：

python tools/test.py configs/detection/mv-det3d_8xb4_embodiedscan-3d-284class-9dof.py work_dirs/mv-3ddet/epoch_12.pth

评估使用IndoorDetMetric（室内检测指标），会输出不同 IoU 阈值下的 AP 与 AR。想要可视化检测结果，还可以配合 embodiedscan/visualizer 中的可视化器，把预测的 3D 框直接渲染到场景中，直观感受模型表现。

进阶玩法：不止多视角3D检测

跑通第一个检测模型后，EmbodiedScan 还有更多任务等你解锁，所有配置都在 configs/ 目录下：

其中多视角视觉接地（根据自然语言描述定位 3D 物体）是 CVPR 2024 自动驾驶挑战赛的赛道之一，训练前记得先加载 3D 检测的预训练权重作为初始化，能显著加速收敛。

常见问题与排错速查

• MinkEngine 装不上：先pip install ninja，再通过python install.py run重试，注意 CUDA 版本需与 PyTorch 匹配。
• 训练时显存溢出：使用--amp开启混合精度，或调低配置中的n_points（默认 100000）。
• 图片加载失败：确认data/下原始数据已解压，且已运行generate_image_scannet.py等转换脚本生成posed_images。
• 想快速验证流程：先下载 demo 数据，用 demo/demo.py 跑一遍推理可视化再上全量数据。

从克隆仓库到跑完 12 个 epoch，EmbodiedScan 的多视角3D检测全流程就是这么简单。现在就动手训练你的第一个 3D 检测模型吧——这也是通往具身智能（Embodied AI）感知能力最扎实的第一步！🚀

【免费下载链接】EmbodiedScan[CVPR 2024 & NeurIPS 2024] EmbodiedScan: A Holistic Multi-Modal 3D Perception Suite Towards Embodied AI项目地址: https://gitcode.com/gh_mirrors/em/EmbodiedScan