LINEMOD BOP 转 PVN3D 测试实操指南

本文面向当前仓库 /workspace/workflow/self/PVN3D 的实际代码路径，梳理一条从 BOP 格式 LineMOD 数据下载、转换、验证，到运行 PVN3D 测试 demo 和评估结果解读的完整流程。

文档目标不是讲论文原理，而是帮助你把 LINEMOD 测试链路真正跑通。

一、适用范围

本文针对的是：

数据源使用 BOP 格式的 LineMOD 数据集
BOP 数据放在容器内 /workspace/bop
PVN3D 代码位于 /workspace/workflow/self/PVN3D
测试目标是跑通 LineMOD 的单类 demo / eval

本文重点覆盖：

下载哪些 BOP 数据包
如何整理到 /workspace/bop
如何转换成 PVN3D 需要的目录布局
转换完成后还要做哪些处理
如何运行 demo 与 eval
如何理解指标和判断结果是否正常

二、整体流程总览

跑通 LINEMOD 测试 demo 的最小闭环如下：

准备环境
下载 BOP 的 LineMOD 测试数据和模型文件
解压到 /workspace/bop
用仓库内脚本把 BOP 格式转换成 PVN3D 期望的 Linemod_preprocessed 结构
校验转换结果是否完整
准备对应类别的 checkpoint
在 pvn3d 目录下运行评测或可视化 demo
查看终端指标、结果文件和可视化输出

如果你只是想先验证链路是否通，建议优先跑：

类别：ape

原因是当前仓库里已经存在：

pvn3d/train_log/linemod/checkpoints/ape/ape_pvn3d_best.pth.tar

这意味着 ape 可以直接作为最小验证对象。

三、数据准备

3.1 BOP 侧最少需要下载哪些包

如果目标只是跑通 LineMOD 的测试和 demo，最少需要：

lm_models.zip
lm_test_all.zip

建议同时保留：

lm_base.zip

当前容器 /workspace/bop 中实际已经存在：

lm_base.zip
lm_models.zip
lm_test_all.zip
lm_test_bop19.zip
lm_train.zip
lm_train_pbr.zip

其中：

lm_models.zip：提供物体模型 .ply
lm_test_all.zip：提供测试图像、深度图、mask、标注
lm_base.zip：提供 BOP 任务基础信息，虽然当前转换脚本不直接依赖，但建议保留
lm_train.zip、lm_train_pbr.zip：主要用于训练，不是跑纯测试 demo 的必需项

3.2 解压后的目录结构

当前脚本要求的 BOP 根目录应至少包含：

text 复制代码

/workspace/bop/
├── lm_models/
│   └── models/
├── lm_test_all/
│   └── test/
└── lm_base/

当前容器里已经验证存在：

text 复制代码

/workspace/bop/lm_models/models
/workspace/bop/lm_test_all/test

3.3 注意事项

仓库内转换脚本默认的 --bop-root 不是 /workspace/bop，而是：

text 复制代码

/home/xxxaa/project/bop

所以在当前环境里运行时，必须显式传：

bash 复制代码

--bop-root /workspace/bop

否则脚本会去错误路径找数据。

四、PVN3D 期望的数据布局

PVN3D 的 LineMOD 测试数据最终要放到：

text 复制代码

/workspace/workflow/self/PVN3D/pvn3d/datasets/linemod/Linemod_preprocessed

核心结构如下：

text 复制代码

Linemod_preprocessed/
├── data/
│   ├── 01/
│   │   ├── rgb/
│   │   ├── depth/
│   │   ├── mask/
│   │   ├── gt.yml
│   │   └── test.txt
│   ├── 02/
│   └── ...
└── models/
    ├── obj_01.ply
    ├── obj_02.ply
    └── ...

其中每个类别目录里：

rgb/*.png：彩色图
depth/*.png：深度图
mask/*.png：物体 mask
gt.yml：该类别每帧的位姿标注
test.txt：测试帧列表

当前仓库已经内置了 lm_obj_kps 目录：

text 复制代码

pvn3d/datasets/linemod/lm_obj_kps/

这里包含每个类别的：

corners.txt
farthest.txt
farthest4.txt
farthest12.txt
farthest16.txt
farthest20.txt

所以从 BOP 转换到 PVN3D 时，不需要你再额外生成关键点文件。

五、类别映射关系

当前仓库支持的 LineMOD 类别与 BOP scene/object id 对应关系如下：

类别名	obj_id
ape	1
benchvise	2
cam	4
can	5
cat	6
driller	8
duck	9
eggbox	10
glue	11
holepuncher	12
iron	13
lamp	14
phone	15

这份映射来自仓库中的 pvn3d/common.py。

六、BOP 转换为 PVN3D 的步骤

6.1 进入正确目录

建议在仓库根目录执行：

bash 复制代码

cd /workspace/workflow/self/PVN3D

6.2 执行转换脚本

当前仓库内已经有现成转换脚本：

pvn3d/datasets/convert_bop_lm_to_pvn3d.py

推荐命令：

bash 复制代码

python pvn3d/datasets/convert_bop_lm_to_pvn3d.py \
  --bop-root /workspace/bop \
  --output-root /workspace/workflow/self/PVN3D/pvn3d/datasets/linemod/Linemod_preprocessed \
  --overwrite

如果你只想先转换 ape，可以只跑单类：

bash 复制代码

python pvn3d/datasets/convert_bop_lm_to_pvn3d.py \
  --bop-root /workspace/bop \
  --output-root /workspace/workflow/self/PVN3D/pvn3d/datasets/linemod/Linemod_preprocessed \
  --scene-ids 1 \
  --overwrite

6.3 转换脚本具体做了什么

该脚本当前只做测试链路所需的最小转换：

把 lm_test_all/test 中各类别的测试数据拷贝到 Linemod_preprocessed/data/%02d
生成 gt.yml
生成 test.txt
把 lm_models/models/obj_XXXXXX.ply 复制并重命名为 Linemod_preprocessed/models/obj_%02d.ply

该脚本不会做的事情：

不会帮你训练模型
不会生成 checkpoint
不会生成训练集 train.txt
不会自动做测试集 pickle 打包

这意味着它的目标是：

先把 eval/demo 的数据布局准备好

不是：

直接把训练链路也全部补齐

七、转换后必须做的检查

7.1 用布局检查脚本验证

仓库里已经有布局检查脚本：

pvn3d/datasets/check_linemod_pvn3d_layout.py

推荐命令：

bash 复制代码

cd /workspace/workflow/self/PVN3D/pvn3d
python -m datasets.check_linemod_pvn3d_layout \
  --data-root datasets/linemod/Linemod_preprocessed \
  --obj-ids 1

当前环境里已经实际验证过 ape(obj_01)，输出为：

text 复制代码

[OK]   obj_01

Validation passed.

如果你要全量检查，可去掉 --obj-ids 1。

7.2 检查转换后的文件是否齐全

以 ape 为例，目录应至少包含：

text 复制代码

pvn3d/datasets/linemod/Linemod_preprocessed/data/01/rgb/*.png
pvn3d/datasets/linemod/Linemod_preprocessed/data/01/depth/*.png
pvn3d/datasets/linemod/Linemod_preprocessed/data/01/mask/*.png
pvn3d/datasets/linemod/Linemod_preprocessed/data/01/gt.yml
pvn3d/datasets/linemod/Linemod_preprocessed/data/01/test.txt
pvn3d/datasets/linemod/Linemod_preprocessed/models/obj_01.ply

当前环境中 ape 的 test.txt 已验证共有：

1236 帧

7.3 确认 checkpoint 是否存在

数据转换完成后，仍然不能直接跑 demo，原因是还需要对应模型权重。

当前仓库内的状态是：

ape 已有 checkpoint
其它类别目录目前只有空目录或 .gitkeep

已有可直接使用的权重：

text 复制代码

/workspace/workflow/self/PVN3D/pvn3d/train_log/linemod/checkpoints/ape/ape_pvn3d_best.pth.tar

如果你要跑其它类别，需要额外准备对应 checkpoint。

八、转换后还需要做什么处理才能正常运行

这是最容易遗漏的部分。

8.1 必需项

转换后要能正常运行 demo / eval，至少还需要满足下面几项：

python-pcl 已安装
Linemod_preprocessed 结构通过校验
对应类别的 checkpoint 已就位
在正确工作目录执行命令

8.2 关于 `python-pcl`

LineMOD 数据集加载时，代码会尝试导入 pcl 用于法向量估计：

文件：pvn3d/datasets/linemod/linemod_dataset.py

当前仓库已经做了 fallback：

如果 python-pcl 导入失败，会退化为零法向量

但从稳妥角度，建议依然安装好 python-pcl，避免数据质量下降或和原始实现行为不一致。

我们已经在容器 pvn3d-dev 的 pvn3d conda 环境中成功安装过 python-pcl。

8.3 关于 `preprocess_testset`

仓库里有：

pvn3d/datasets/linemod/preprocess_testset.py

它的作用是把测试集先打包成 pickle，加速重复评测。

但是当前代码里：

Config.use_preprocess = False

所以默认情况下：

不需要先跑这个脚本，也能正常 eval/demo

也就是说，preprocess_testset.py 不是跑通测试 demo 的必需步骤。

你只有在下面这种场景下，才需要考虑它：

要重复大量跑测试，希望减少数据准备开销
愿意同步调整 common.py 中的 use_preprocess

8.4 关于工作目录

LineMOD 的训练、评测、demo 命令都建议在下面目录执行：

bash 复制代码

cd /workspace/workflow/self/PVN3D/pvn3d

原因是代码里大量使用了相对导入和相对路径，比如：

from common import Config
datasets/linemod/...
train_log/linemod/...

如果你在错误目录执行，最常见问题是：

模块导入失败
找不到数据目录
找不到 checkpoint

九、如何运行 LINEMOD 测试与 demo

9.1 最小验证方案：先跑 ape

因为当前仓库已带 ape checkpoint，建议先跑：

ape

9.2 运行评测

在容器的 pvn3d 环境中：

bash 复制代码

cd /workspace/workflow/self/PVN3D/pvn3d
cls='ape'
tst_mdl=train_log/linemod/checkpoints/${cls}/${cls}_pvn3d_best.pth.tar
python -m train.train_linemod_pvn3d -checkpoint $tst_mdl -eval_net --test --cls $cls

这也是仓库中 eval_linemod.sh 的实际内容。

9.3 运行可视化 demo

bash 复制代码

cd /workspace/workflow/self/PVN3D/pvn3d
cls='ape'
tst_mdl=train_log/linemod/checkpoints/${cls}/${cls}_pvn3d_best.pth.tar
python -m demo -dataset linemod -checkpoint $tst_mdl -cls $cls

这也是仓库中 demo_linemod.sh 的实际内容。

9.4 输出结果在哪里

评测结果会落到：

text 复制代码

train_log/linemod/eval_results/

例如当前仓库中已有：

text 复制代码

pvn3d/train_log/linemod/eval_results/pvn3d_eval_cuda_ape__97.57281553398059_99.75728155339806.pkl

demo 可视化结果会落到：

text 复制代码

train_log/linemod/eval_results/{cls}/pose_vis

例如 ape 的输出目录是：

text 复制代码

train_log/linemod/eval_results/ape/pose_vis

十、如何判断是否跑通

跑通不等于只看程序不报错。

建议按下面 4 个层次判断：

10.1 数据层

满足以下条件：

Linemod_preprocessed/data/%02d 存在
gt.yml 和 test.txt 存在
models/obj_%02d.ply 存在
布局检查脚本通过

10.2 模型层

满足以下条件：

能正确加载 checkpoint
没有报 Checkpoint not found

10.3 推理层

满足以下条件：

demo / eval 能跑完整个 dataloader
没有在数据读取或 pose 估计阶段中断

10.4 结果层

满足以下条件：

终端打印了 ADD / ADDS / AUC 等指标
生成了 pvn3d_eval_cuda_*.pkl
demo 生成了 pose_vis/*.jpg

只有这 4 层都通过，才算真正把链路跑通。

十一、指标介绍

当前仓库里和 LineMOD 评测最直接相关的逻辑在：

pvn3d/lib/utils/pvn3d_eval_utils.py
pvn3d/lib/utils/evaluation_utils.py

11.1 ADD

ADD 用于衡量预测位姿和真实位姿之间的 3D 模型点平均距离。

直观理解：

把物体模型用预测位姿和真实位姿各变换一次
计算对应点之间的平均欧氏距离
距离越小越好

在代码中，ADD < 0.1 * diameter 会被记为一次成功。

11.2 ADDS / ADD-S

对对称物体，普通 ADD 不够合理，因为旋转后不同点可能几何上等价。

因此对称物体常用 ADDS：

不再要求点一一对应
而是用最近邻距离来度量

直观上：

对称物体只要几何上对齐得好，即使点对应关系不同，也应视为正确

11.3 AUC

仓库中的 AUC 是对误差分布曲线做积分得到的面积指标，数值越高越好。

当前实现里：

cal_auc() 默认以 0.1m 作为积分上限
最终输出范围通常按百分制表示

所以：

ADD AUC 越高越好
ADDS AUC 越高越好
ADD(-S) AUC 越高越好

11.4 0.1 diameter 成功率

仓库还会打印：

add < 0.1 diameter
adds < 0.1 diameter

这表示：

预测位姿误差是否小于物体直径的 10%

这是 LineMOD 上很常见的成功率指标，数值越高越好。

十二、结果文件如何解读

评测完成后，终端会打印类似：

text 复制代码

***************add auc:      ...
***************adds auc:     ...
***************add(-s) auc:  ...
***************add < 0.1 diameter: ...
***************adds < 0.1 diameter: ...

同时会保存 pkl 文件，文件名中直接编码了两个关键成功率：

text 复制代码

pvn3d_eval_cuda_{cls}__{add}_{adds}.pkl

以当前仓库已有结果为例：

text 复制代码

pvn3d_eval_cuda_ape__97.57281553398059_99.75728155339806.pkl

它对应的核心内容为：

add_auc_lst: [96.17499077318885]
adds_auc_lst: [97.68790649961994]
add_s_auc_lst: [96.17499077318885]
add: 97.57281553398059
adds: 99.75728155339806

可以这样理解：

ADD AUC 约 96.17
ADDS AUC 约 97.69
ADD < 0.1 diameter 成功率约 97.57%
ADDS < 0.1 diameter 成功率约 99.76%

从工程角度看，这是一组明显正常的结果，不像是"数据错位"或"模型完全没对上"的表现。

十三、如何做结果评估

13.1 先看程序是否真的输出了结果

如果只跑完但没有：

指标打印
.pkl 文件
pose_vis 图片

那么不能算完整成功。

13.2 再看成功率是否在合理范围

对使用正确数据、正确 checkpoint 的同类对象来说：

ADD/ADDS AUC 一般应明显高于随机水平
ADD < 0.1 diameter、ADDS < 0.1 diameter 不应接近 0

如果结果极低，优先排查：

数据类别和 checkpoint 是否匹配
obj_id 与类别是否对应错了
转换后的 mask / gt.yml 是否错位
模型文件是否放错编号

13.3 最后看可视化是否贴合物体边界

打开 pose_vis 中的图片，观察投影点云或模型边缘是否与物体轮廓基本重合。

如果终端指标正常但可视化明显错位，需要重点怀疑：

相机内参不一致
深度尺度或单位不对
模型单位未统一到米/毫米

十四、常见问题与排查建议

14.1 转换脚本报缺少 BOP 目录

常见原因：

忘了传 --bop-root /workspace/bop
/workspace/bop/lm_models/models 不存在
/workspace/bop/lm_test_all/test 不存在

14.2 布局检查失败

优先检查：

gt.yml 是否生成
test.txt 是否为空
rgb/depth/mask 帧号是否一致
models/obj_%02d.ply 是否存在

14.3 demo 或 eval 报找不到 checkpoint

当前仓库里只有 ape 已具备可直接使用的权重。

如果你跑 benchvise、cam 等其它类别，需要先准备：

text 复制代码

train_log/linemod/checkpoints/{cls}/{cls}_pvn3d_best.pth.tar

14.4 运行命令时报模块导入错误

大概率是工作目录不对。

建议统一进入：

bash 复制代码

cd /workspace/workflow/self/PVN3D/pvn3d

再运行：

python -m train.train_linemod_pvn3d ...
python -m demo ...

14.5 运行时出现 `pcl` 相关问题

优先检查 python-pcl 是否已安装在容器 pvn3d 环境中。

如果没有，先修复 python-pcl，再继续评测，避免法向量计算行为退化。

十五、推荐的最小实操命令清单

下面这组命令可以作为最短闭环。

15.1 转换 ape 数据

bash 复制代码

cd /workspace/workflow/self/PVN3D
python pvn3d/datasets/convert_bop_lm_to_pvn3d.py \
  --bop-root /workspace/bop \
  --output-root /workspace/workflow/self/PVN3D/pvn3d/datasets/linemod/Linemod_preprocessed \
  --scene-ids 1 \
  --overwrite

15.2 校验 ape 数据布局

bash 复制代码

cd /workspace/workflow/self/PVN3D/pvn3d
python -m datasets.check_linemod_pvn3d_layout \
  --data-root datasets/linemod/Linemod_preprocessed \
  --obj-ids 1

15.3 跑 ape 评测

bash 复制代码

cd /workspace/workflow/self/PVN3D/pvn3d
cls='ape'
tst_mdl=train_log/linemod/checkpoints/${cls}/${cls}_pvn3d_best.pth.tar
python -m train.train_linemod_pvn3d -checkpoint $tst_mdl -eval_net --test --cls $cls

15.4 跑 ape 可视化 demo

bash 复制代码

cd /workspace/workflow/self/PVN3D/pvn3d
cls='ape'
tst_mdl=train_log/linemod/checkpoints/${cls}/${cls}_pvn3d_best.pth.tar
python -m demo -dataset linemod -checkpoint $tst_mdl -cls $cls

十六、结论

针对当前仓库，跑通 LINEMOD 测试 demo 的关键点有 4 个：

BOP 数据要准备成 /workspace/bop/lm_models/models 和 /workspace/bop/lm_test_all/test
必须用仓库自带脚本转换成 pvn3d/datasets/linemod/Linemod_preprocessed
转换后必须校验目录，并确保有匹配类别的 checkpoint
实际运行时要在 pvn3d 目录下执行评测和 demo 命令

如果只是先验证整条链路是否通，建议直接从 ape 开始，因为当前仓库已经有现成的 ape checkpoint，可最快形成闭环。

LINEMOD BOP 转 PVN3D 测试实操指南