SpatialLM模型评估工具：自定义数据集性能测试流程
项目地址: https://gitcode.com/GitHub_Trending/sp/SpatialLM 在3D场景理解领域，模型性能评估是验证算法有效性的关键环节。SpatialLM作为专注于空间理解的大型语言模型，其评估工具eval.py支持对自定义数据集的精确测试，帮助开发者量化分析模型在布局估计和物体检测任务上的表现。本文将详细介绍如何使用该工具完成从数据准备到结果解读的全流程。
评估工具核心功能解析
SpatialLM评估工具通过计算预测结果与真实值之间的3D交并比（Intersection over Union, IoU）来衡量模型性能，核心实现位于eval.py。该工具支持两类评估任务：
- 布局元素评估：针对墙体（wall）、门（door）、窗（window）等建筑结构，采用2D平面IoU计算
- 物体检测评估：针对家具类物体（如沙发、床、椅子等），采用3D bounding box IoU计算
评估指标采用F1分数（F1-score），同时提供IoU阈值为0.25和0.5时的双重评估结果，满足不同精度需求。
自定义数据集准备指南
数据组织结构
评估需准备三类核心文件，建议按以下结构组织：
custom_dataset/
├── metadata.csv # 场景信息表，包含id、pcd路径、layout路径
├── gt_dir/ # 真实布局文件目录，格式为{TASK_ID}.txt
├── pred_dir/ # 模型预测结果目录，格式为{TASK_ID}.txt
└── label_mapping.tsv # 类别映射文件，定义预测类别与评估类别的对应关系
文件格式规范
1. 元数据文件（metadata.csv）
需包含三列：id（场景唯一标识）、pcd（点云文件路径）、layout（布局文件路径），示例：
id,pcd,layout
scene001,./pcd/scene001.ply,./layout/scene001.txt
scene002,./pcd/scene002.ply,./layout/scene002.txt
2. 布局文件格式
真实布局与预测结果均采用SpatialLM定义的文本格式，包含墙体、门窗和物体的空间参数。详细格式说明可参考README.md中的输出示例。
3. 类别映射文件（label_mapping.tsv）
采用制表符分隔，定义模型输出类别到评估标准类别的映射关系，示例：
spatiallm59 spatiallm20
double_door door
sliding_window window
评估流程分步实施
1. 环境准备
确保已按README.md完成环境配置，关键依赖包括：
- Python 3.11+
- PyTorch 2.4.1+
- 额外依赖：
scipy、shapely、bbox、terminaltables
2. 生成预测结果
使用inference.py对自定义数据集执行推理，生成预测布局文件：
python inference.py \
--point_cloud custom_dataset/pcd \
--output custom_dataset/pred \
--model_path manycore-research/SpatialLM1.1-Qwen-0.5B
3. 执行评估命令
运行eval.py进行性能测试，核心参数说明：
--metadata：元数据CSV文件路径--gt_dir：真实布局文件目录--pred_dir：预测结果目录--label_mapping：类别映射TSV文件
完整命令示例：
python eval.py \
--metadata custom_dataset/metadata.csv \
--gt_dir custom_dataset/gt_dir \
--pred_dir custom_dataset/pred_dir \
--label_mapping custom_dataset/label_mapping.tsv
评估结果解读与可视化
结果输出格式
评估完成后，工具会输出两类ASCII表格：
布局元素评估结果
+----------+-------------+-------------+
| Layouts | F1 @.25 IoU | F1 @.50 IoU |
+----------+-------------+-------------+
| wall | 0.892 | 0.876 |
| door | 0.764 | 0.721 |
| window | 0.718 | 0.683 |
+----------+-------------+-------------+
物体检测评估结果
+--------------+-------------+-------------+
| Objects | F1 @.25 IoU | F1 @.50 IoU |
+--------------+-------------+-------------+
| bed | 0.968 | 0.952 |
| sofa | 0.691 | 0.624 |
| chair | 0.323 | 0.287 |
+--------------+-------------+-------------+
可视化分析
结合visualize.py工具可将评估结果可视化，对比预测与真实布局的空间差异：
python visualize.py \
--point_cloud custom_dataset/pcd/scene001.ply \
--layout custom_dataset/pred_dir/scene001.txt \
--save scene001.rrd
rerun scene001.rrd # 使用rerun工具查看3D可视化结果
常见问题与优化建议
数据兼容性问题
- 点云坐标系不一致：确保所有点云遵循z轴向上的右手坐标系，可使用SpatialLM/pcd/transform.py进行坐标转换
- 布局文件格式错误：验证文件是否符合EXAMPLE.md中的格式规范
评估精度优化
- 提高点云质量：对于低精度点云，可尝试使用MASt3R-SLAM重新构建
- 类别映射优化：细化label_mapping.tsv中的类别对应关系，减少类别模糊性
性能提升技巧
- 对大规模数据集，可修改eval.py中的循环逻辑，添加多进程并行评估
- 降低点云分辨率（通过
--voxel_size参数）可加速评估过程，但可能影响小物体检测精度
评估工具扩展开发
自定义评估指标
通过修改eval.py中的EvalTuple类（L52-72），可添加自定义评估指标（如Precision-Recall曲线）。关键扩展点包括：
- 在
EvalTuple中添加新指标计算属性 - 修改结果汇总逻辑（L504-534），输出新增指标
支持新数据格式
如需支持其他3D标注格式（如COCO-3D），可扩展spatiallm/layout/layout.py中的解析器，添加新格式的读写接口。
通过本文介绍的流程，开发者可快速搭建SpatialLM模型的自定义评估 pipeline，量化分析模型在特定场景下的性能表现。结合工具提供的可视化功能，能够直观定位模型短板，为算法优化提供数据支持。更多高级用法可参考官方提供的FINETUNE.md和测试集评估示例。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
