场景地标检测相机定位系统

项目简介

这是一个用于相机定位的场景地标检测项目。该项目提出了一种新的方法来检测场景特定的地标，用于在预映射场景中定位相机。该方法具有以下特点：

• 隐私保护: 只使用场景特定的地标，不需要存储原始图像
• 低存储需求: 模型文件相对较小
• 高精度: 在 Indoor-6 数据集上达到高精度
• 跨平台支持: 支持 Windows、Linux 和 macOS
• 硬件加速: 支持 CUDA、CPU 和 MPS 后端

技术特点

• 基于 EfficientNet-Lite0 的 CNN 网络架构
• 使用热力图预测进行地标检测
• 支持多分辨率输出（1/4 和 1/2 输入分辨率）
• 采用模型集成策略（SLD-star）提高精度
• 使用 PnP 算法进行相机姿态估计

项目展示

我们设计了一种新方法来检测场景特定的地标，用于在预映射场景中定位相机。我们的方法具有隐私保护性，存储需求低且精度高。

[左图] 在查询图像中检测到的场景地标 [中图] 训练基于 CNN 的热力图预测架构
[右图] 显示 3D 场景地标（红色）和估计的相机姿态（蓝色）叠加在 3D 点云（灰色）上

相关论文

改进的场景地标检测用于相机定位
Tien Do 和 Sudipta N. Sinha
国际 3D 视觉会议 (3DV), 2024
论文

学习检测场景地标用于相机定位
Tien Do, Ondrej Miksik, Joseph DeGol, Hyun Soo Park, 和 Sudipta N. Sinha
IEEE/CVF 计算机视觉与模式识别会议 (CVPR), 2022
论文   视频

Indoor-6 数据集
下载

引用格式

如果您的研究中使用了我们的工作，请考虑引用我们的论文：

@InProceedings{Do_Sinha_2024_ImprovedSceneLandmarkLoc,
    author     = {Do, Tien and Sinha, Sudipta N.},
    title      = {Improved Scene Landmark Detection for Camera Localization},
    booktitle  = {Proceedings of the International Conference on 3D Vision (3DV)},
    month      = {March},
    year       = {2024}
}

@InProceedings{Do_2022_SceneLandmarkLoc,
    author     = {Do, Tien and Miksik, Ondrej and DeGol, Joseph and Park, Hyun Soo and Sinha, Sudipta N.},
    title      = {Learning to Detect Scene Landmarks for Camera Localization},
    booktitle  = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
    month      = {June},
    year       = {2022}
}

Indoor-6 数据集

Indoor-6 数据集是从六个室内场景在多个天内捕获的多个会话创建的。每个场景的伪地面真值（pGT）3D 点云和相机姿态使用 COLMAP 计算。

数据集场景:

• scene1 (6289/798/799 图像)
• scene2a (4890/256/257 图像)
• scene3 (4181/313/315 图像)
• scene4a (2285/158/158 图像)
• scene5 (4946/512/424 图像)
• scene6 (1761/322/323 图像)
• colmap (所有场景的 colmap 重建)

环境设置

pip install -r requirements.txt

系统要求

• Python 3.9+
• PyTorch 2.1.0+
• CUDA 11.8+ (可选，用于 GPU 加速)
• 支持 MPS (Apple Silicon Mac)

目录结构

  └── SceneLandmarkLocalization
    └── data
      |	└── outputs          # 训练输出
      |	└── checkpoints      # 预训练模型
      |	└── indoor6          # 数据集
      |		└── scene1
      |		└── scene2a
      |		└── scene3
      |		└── scene4a
      |		└── scene5
      |		└── scene6
		└── src
		└── README.md

快速开始

1. 下载数据

• 下载 Indoor-6 数据集
• 下载 预训练模型

2. 运行推理

cd SceneLandmarkLocalization/src
python run_inference.py

3. 训练模型

cd SceneLandmarkLocalization/src
python run_training.py

API 服务

项目提供了 REST API 服务，支持实时相机定位：

启动 API 服务

cd SceneLandmarkLocalization/src
python api_server.py

API 端点

• GET /health - 健康检查
• POST /localize - 基于 Base64 图像的定位
• POST /localize/upload - 基于文件上传的定位
• GET /scenes - 获取可用场景列表
• GET /scene/<scene_name>/info - 获取场景信息

Docker 部署

项目提供了完整的 Docker 部署方案，支持训练、测试和 API 服务三种模式。

快速开始

# 1. 构建所有镜像
./docker-run.sh build_all

# 2. 启动API服务（后台模式）
./docker-run.sh api_daemon

# 3. 检查服务状态
./docker-run.sh api_status

详细部署说明

1. 镜像构建

# 构建基础镜像（PyTorch + 依赖）
./docker-run.sh build_base

# 构建训练镜像
./docker-run.sh build

# 构建API镜像
./docker-run.sh build_api

# 构建所有镜像
./docker-run.sh build_all

2. 训练和测试

# 快速训练（100个地标，10轮）
./docker-run.sh quick_train

# 快速测试（100个地标）
./docker-run.sh quick_test

# 自定义训练命令
./docker-run.sh custom --action train --scene_id scene6 --num_epochs 50

3. API 服务管理

# 启动API服务（前台模式）
./docker-run.sh api

# 启动API服务（后台模式）
./docker-run.sh api_daemon

# 停止API服务
./docker-run.sh stop_api

# 检查API状态
./docker-run.sh api_status

# 查看API日志
./docker-run.sh api_logs

4. 开发环境

# 启动交互式容器
./docker-run.sh interactive

# 运行自定义命令
./docker-run.sh custom --action test --scene_id scene6

Docker Compose 配置

项目使用多阶段构建和 Docker Compose 进行容器编排：

• 基础镜像 (base_build): PyTorch 2.7.1 + CUDA 12.6 + 系统依赖
• 训练镜像 (main): 基础镜像 + 训练工具
• API 镜像 (api): 基础镜像 + Nginx + Gunicorn + API 服务

服务端口

• Nginx 端口: 8081 (HTTP)
• Flask 端口: 8080 (开发调试)
• 健康检查: GET http://localhost:8081/nginx-health

API 接口

• GET /health - 健康检查
• GET /scenes - 获取可用场景列表
• GET /scene/<scene_name>/info - 获取场景信息
• POST /localize - 基于 Base64 图像的定位
• POST /localize/upload - 基于文件上传的定位

数据目录

• 数据集路径: /app/data/indoor6
• 输出路径: /app/data/outputs
• 模型路径: /app/data/checkpoints

可用场景

• scene1, scene2a, scene3, scene4a, scene5, scene6

地标配置

• landmarks-100v9, landmarks-300v9, landmarks-500v9, landmarks-1000v9

系统要求

• Docker 20.10+
• Docker Compose 2.0+
• NVIDIA Docker (可选，用于 GPU 加速)
• 至少 8GB 内存
• 至少 20GB 磁盘空间

docker-run.sh 脚本说明

docker-run.sh 是项目的 Docker 管理脚本，提供了完整的容器化部署功能。

主要命令:

• build_all - 构建所有镜像
• quick_train - 快速训练（100 地标，10 轮）
• quick_test - 快速测试（100 地标）
• api_daemon - 启动 API 服务（后台）
• api_status - 检查 API 状态
• interactive - 启动交互式容器
• custom - 运行自定义命令

详细说明: 请参考 docker-run.sh 说明.md

主要功能

训练模式

• 标准训练: 使用完整图像进行训练
• 补丁训练: 使用图像块进行训练，提高效率

推理模式

• 单场景测试: 对单个场景进行测试
• 多场景测试: 对所有场景进行批量测试
• 地标统计: 收集地标检测统计信息

评估指标

• 中位数平移误差 (cm)
• 中位数旋转误差 (度)
• 5cm5 度召回率 (%)
• 推理速度 (fps)

技术架构

网络架构

• 骨干网络: EfficientNet-Lite0
• 特征提取: 多尺度特征提取
• 输出层: 热力图预测层
• 模型集成: SLD-star 策略

核心算法

1. 热力图预测和峰值检测
2. 2D 地标位置精确化
3. 3D-2D 对应关系建立
4. RANSAC PnP 姿态求解
5. 旋转和平移误差计算

贡献

本项目欢迎贡献和建议。请遵循以下步骤：

1. Fork 本仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

联系方式

如有问题或建议，请通过以下方式联系：

• 提交 Issue
• 发送邮件至项目维护者

---

注意: 本项目是 Microsoft Research 的开源项目，遵循 Microsoft 开源行为准则。