hongchen/door_detect

入户门位置检测与导出工具

基于 YOLOE 实例分割和 RGB-D 点云的入户门位置检测工具，支持从全景图像序列中检测入户门并导出其 3D 位置。

功能特性

• 门实例检测：使用 YOLOE 模型检测全景图中的各类门
• 3D 点云重建：从 RGB-D 图像生成世界坐标系点云
• 3D 门框估计：基于实例分割 mask 估计门的 3D 包围盒
• 入户门识别：通过多特征评分识别入户门
• fallback 机制：未检测到门时基于点位可见性估计入户门位置
• 可视化输出：支持导出带颜色的点云 + 红色球体标记的 PLY 文件

环境要求

• Python 3.10+
• CUDA 12+ (可选，用于 GPU 加速)
• conda 环境：yolo26

主要依赖

torch
ultralytics (YOLOE)
open3d
opencv-python
numpy
scipy
tqdm

目录结构

high_temp/
├── export_entrance_position.py    # 主脚本
├── camera_spherical.py            # 球面相机内参模型
├── yoloe-26x-seg.pt               # YOLOE 实例分割模型
├── scene0001/                     # 场景示例
│   ├── pano_img/                  # 全景 RGB 图像
│   ├── depth_img/                 # 深度图像
│   ├── vision.txt                 # 点位姿态和可见性信息
│   └── output/                    # 输出目录
└── README.md

使用方法

基础用法

# 激活环境
conda activate yolo26

# 处理单个场景
python export_entrance_position.py -s scene0001

# 指定输出路径
python export_entrance_position.py -s scene0001 -o output/entrance.json

# 带可视化输出
python export_entrance_position.py -s scene0001 --vis_ply

参数说明

参数	简写	默认值	说明
--scene	-s	必需	场景文件夹路径
--output	-o	None	输出 JSON 文件路径
--model	-m	yoloe-26x-seg.pt	YOLOE 模型路径
--conf		0.35	检测置信度阈值
--iou		0.45	NMS IoU 阈值
--voxel-size		0.03	点云体素下采样尺寸
--imgsz		1024 2048	YOLOE 输入图像尺寸 (高 宽)
--vis_ply		False	是否导出可视化 PLY 文件

使用示例

# 使用更高置信度阈值
python export_entrance_position.py -s scene0001 --conf 0.5

# 使用更小的图像尺寸（加快处理速度）
python export_entrance_position.py -s scene0001 --imgsz 640 1280

# 完整参数示例
python export_entrance_position.py \
    -s scene0001 \
    -o results/entrance.json \
    --conf 0.4 \
    --iou 0.5 \
    --voxel-size 0.05 \
    --vis_ply

输入数据格式

场景文件夹结构

scene0001/
├── pano_img/          # 全景 RGB 图像（JPG 格式，以点位 ID 命名）
│   ├── 1.jpg
│   ├── 2.jpg
│   └── ...
├── depth_img/         # 深度图像（PNG 格式，16 位深度）
│   ├── 1.png
│   ├── 2.png
│   └── ...
└── vision.txt         # JSON 格式，包含点位姿态和可见性信息

vision.txt 格式

{
  "sweepLocations": [
    {
      "uuid": "1",
      "id": 1,
      "pose": {
        "rotation": { "w": 1, "x": 0, "y": 0, "z": 0 },
        "translation": { "x": 0, "y": 0, "z": 0 }
      },
      "puck": { "z": -1.56 },
      "visibles": [2, 3, 4]
    }
  ]
}

输出格式

entrance_position.json

{
  "scene_name": "scene0001",
  "entrance_position": {
    "x": 5.24,
    "y": -1.84,
    "z": -0.34
  },
  "source": "door_detection",
  "is_estimated": false,
  "door_info": {
    "door_id": 0,
    "confidence": 0.68,
    "dimensions": {
      "width": 1.04,
      "height": 2.56,
      "thickness": 0.06
    },
    "center": { "x": 5.24, "y": -1.84, "z": -0.34 },
    "bbox_min": { "x": 4.73, "y": -1.87, "z": -1.62 },
    "bbox_max": { "x": 5.76, "y": -1.81, "z": 0.95 }
  },
  "source_detections": [
    {
      "pose_uuid": "8",
      "detection_confidence": 0.68,
      "image": "8.jpg"
    }
  ],
  "metadata": {
    "all_poses_count": 12,
    "processing_info": {
      "total_candidates": 1,
      "merged_doors": 1,
      "valid_doors": 1
    }
  }
}

vis.ply（可视化文件）

• 格式：ASCII PLY（兼容 MeshLab、CloudCompare）
• 内容：场景点云（真实 RGB 颜色）+ 红色球体（入户门位置）
• 球体：半径 0.2m，红色 (255, 0, 0)

代码结构解析

核心类：EntranceDoorDetector

EntranceDoorDetector
├── __init__()              # 初始化：加载位姿、模型、参数
├── detect_and_identify()   # 主流程：检测门并识别入户门
├── export_json()           # 导出 JSON 结果
└── export_vis_ply()        # 导出可视化 PLY

关键方法

方法	功能
_load_poses()	从 vision.txt 加载点位姿态
_build_pose_matrix()	构建 4x4 位姿变换矩阵
_mask_to_3d_points()	将 2D mask 映射到世界坐标 3D 点
_merge_3d_doors()	使用并查集合并重叠的 3D 门候选
_filter_door_by_properties()	根据物理特性过滤门（尺寸等）
_filter_door_by_ground_puck()	根据地面距离过滤门
_identify_entrance_door()	识别入户门（多特征评分）
_estimate_entrance_from_poses()	基于点位可见性估计入户门

算法流程

1. 加载数据
   ├── 读取 vision.txt 获取点位姿态
   ├── 加载 YOLOE 模型
   └── 准备 RGB 和深度图像

2. 门检测与 3D 重建
   ├── YOLOE 实例分割检测门
   ├── mask + depth → 3D 点云
   ├── 过滤离群点和深度不一致点
   └── 计算 3D 包围盒

3. 多帧融合
   ├── 融合所有点位的点云
   ├── 体素下采样
   ├── 使用并查集合并重叠的 3D 门
   └── 过滤无效门（尺寸、地面距离）

4. 入户门识别
   ├── 尺寸评分（接近标准门尺寸）
   ├── 边缘评分（远离其他门）
   ├── 视角评分（多帧可见）
   ├── 边界评分（靠近空间轮廓边界）
   └── 选择综合评分最高的门

5. Fallback：点位估计
   ├── 可见性一致性过滤室内点位
   ├── 计算边界距离和中心距离评分
   └── 选择最佳点位作为入户门估计位置

6. 输出结果
   ├── 导出 JSON 文件
   └── （可选）导出可视化 PLY

入户门评分系统

评分项	权重	计算方式
尺寸评分	30 分	接近高 2.1m×宽 1.0m 得分高
边缘评分	25 分	远离其他门中心得分高
视角评分	10 分	被更多帧拍摄到得分高
边界评分	30 分	靠近空间轮廓边界得分高

可视化查看

MeshLab 中查看

1. 打开 MeshLab
2. File → Import Mesh
3. 选择 output/vis.ply
4. 灰色点云为场景，红色球体为入户门位置

CloudCompare 中查看

1. 打开 CloudCompare
2. File → Open
3. 选择 output/vis.ply
4. 启用颜色渲染模式

常见问题

Q: 未检测到任何门？

A: 检查以下项：

• 降低 --conf 阈值（如 0.25）
• 确认 RGB 和深度图像匹配
• 检查 vision.txt 格式是否正确

Q: 入户门识别错误？

A: 可能是评分权重问题，可调整：

• 修改 _identify_entrance_door() 中的评分权重
• 增加边界评分权重可提高边缘门的选择概率

Q: PLY 文件在 MeshLab 中无法显示？

A: 确保使用 ASCII 格式输出，当前代码已默认使用 ASCII 格式。

许可证

MIT License