RomeInADay

基于 Rome16K 数据集，探索城市场景三维理解的三条技术路线。

---

环境安装

所有脚本统一使用 rome3d conda 环境（Python 3.11）。

# 1. 创建环境
conda create -n rome3d python=3.11 -y
conda activate rome3d

# 2. 核心依赖（定位 + 可视化）
pip install faiss-cpu opencv-python numpy tqdm \
            matplotlib requests plotly pyvista open3d

# 3. NeRF / 3DGS 训练（可选，需要图片才能使用）
pip install nerfstudio gsplat

注意：open3d 不支持 Python 3.13+，需通过上述 conda 环境使用。

---

数据集

Rome16K 由 Cornell 大学发布（Li et al., ECCV 2010），包含罗马城市约 16,000 张 Flickr 图片的 SfM 重建结果，常用于大规模图像定位与三维重建研究。

Rome16K/
├── bundle/          # SfM 重建（相机位姿 + 4,067,119 个三维点）
├── db/              # 15,179 张数据库图的 SIFT 特征（.key.gz）
├── query/           # 1,000 张查询图的 SIFT 特征（.key.gz）
├── list.db.txt      # 数据库图像列表
└── list.query.txt   # 查询图像列表

注意：数据集不含实际 JPEG 图片，仅包含从图片提取的 SIFT 特征文件。

---

Flickr 图片获取问题

Rome16K 的原始图片托管在 Flickr，需通过 Flickr API 下载。

2024 年后，Flickr 已停止向免费账户开放 API Key 申请，仅 Flickr PRO 订阅用户可创建 API Key。

这一限制直接影响了依赖实际图片的两条技术路线：

路线	是否受影响	当前状态
图像定位（Image Localization）	否	✅ 可直接运行，使用现有 SIFT 特征
NeRF（神经辐射场）	是	❌ 需要 RGB 图片，无法绕过
3D Gaussian Splatting	是	❌ 需要 RGB 图片，无法绕过

若有其他途径获取图片（PRO 账户、向数据集作者申请原始存档），NeRF 和 3DGS 路线可正常运行，相关脚本已准备就绪。

---

路线一：图像定位（当前可运行）

原理

给定一张未知位置的查询图片，在已知三维模型中找到它的拍摄位置和相机姿态。

查询 SIFT 特征 → 2D-3D 匹配 → RANSAC + EPnP → 相机位姿（R, t）

算法选型

模块	算法	说明
特征索引	FAISS IVF-PQ	4M+ 高维向量近似最近邻，速度比暴力匹配快 100×
位姿估计	EPnP + RANSAC	线性时间 PnP，OpenCV 实现，鲁棒对抗外点
整体框架	优先级特征匹配	参考原论文，按 3D 点可见性排序加速匹配

FAISS IVF-PQ 是当前大规模 SIFT 匹配的工业标准（Meta AI），在 4M 向量规模下单次查询 < 10ms。

运行

python scripts/localize.py \
  --bundle     Rome16K/bundle/bundle.db.out \
  --db-list    Rome16K/list.db.txt \
  --db-keys    Rome16K/db \
  --query-keys Rome16K/query \
  --query-list Rome16K/list.query.txt \
  --out        results/

# 调试：限制规模快速验证
python scripts/localize.py --max-pts 50000 --max-query 50

输出

results/localization_results.txt   # 每张查询图的定位结果（SUCCESS / FAIL）
results/poses.json                 # 成功定位的相机位姿（R, t, center）

可视化

python scripts/visualize.py \
  --bundle Rome16K/bundle/bundle.db.out \
  --poses  results/poses.json \
  --out    results/

生成三张图：

文件	内容
viz_topdown.png	点云俯视图：左为数据库相机分布，右为查询定位结果（绿色三角=成功）
viz_stats.png	定位成功率饼图 + 相机高度分布直方图
viz_3d.png	三维散点图（点云 + 相机位置）

visualize.py 仅依赖 matplotlib，无需额外安装。localize.py 运行后才会生成 poses.json。

多角度点云静图

python scripts/pointclouds.py   # 生成 11 张角度图到 pointclouds/

文件	视角
top.png	正俯视
front/back.png	正前/后
left/right.png	左/右侧
iso_ne/nw/se/sw.png	四个等轴测方向
low_front.png / high_oblique.png	低角度 / 高斜视

交互式点云浏览器（浏览器）

python scripts/explore.py --out results/explore.html
# 用 Chrome / Firefox 打开 results/explore.html

默认只显示城市点云（真实 RGB）。点击图例可叠加数据库相机或定位结果。

交互式点云浏览器（原生窗口，全量无采样）

conda activate rome3d

# 启动菜单（列出所有景点 + 预计加载时间）
python scripts/open3d_viewer.py

# 直接指定景点
python scripts/open3d_viewer.py --scene colosseum   # 斗兽场（约 30 万点）
python scripts/open3d_viewer.py --scene trevi       # 特莱维喷泉
python scripts/open3d_viewer.py --scene vatican     # 圣彼得大教堂
python scripts/open3d_viewer.py --scene all         # 全量 400 万点

窗口内操作：左键旋转 / 右键平移 / 滚轮缩放 / +-- 调点大小 / R 重置 / Q 退出

---

路线二：NeRF（需要图片）

原理

从多视角图片和已知相机位姿，训练神经网络隐式表达场景，渲染任意新视角。

算法选型

• nerfstudio nerfacto：Instant-NGP 风格，MPS（Apple Silicon）原生支持
• 训练时间：约 1-2 小时（M 系列芯片，30k 步）

运行（获取图片后）

pip install nerfstudio

# 1. 准备数据（Flickr API Key 或其他图片来源）
bash scripts/prepare_component.sh 0 <FLICKR_API_KEY> <FLICKR_SECRET>

# 2. 训练
bash nerf/train.sh 0

---

路线三：3D Gaussian Splatting（需要图片）

原理

用数百万个可学习的三维高斯分布显式表达场景，通过可微光栅化渲染，速度远快于 NeRF，支持实时预览。

算法选型

• nerfstudio splatfacto（底层为 gsplat）：纯 PyTorch，MPS 兼容，无需 CUDA
• 训练时间：约 30-60 分钟（30k 步）

运行（获取图片后）

# 与 NeRF 共用同一份数据
bash 3dgs/train.sh 0

---

目录结构

RomeInADay-Scratch/
├── Rome16K/               # 数据集
├── scripts/
│   ├── localize.py         # 图像定位（FAISS IVF-PQ + EPnP/RANSAC）
│   ├── visualize.py        # 静态可视化（点云俯视 + 统计图）
│   ├── pointclouds.py      # 多角度点云静图（11 个视角）
│   ├── explore.py          # 交互式 HTML 点云（plotly，需 Chrome）
│   ├── open3d_viewer.py    # 交互式原生窗口（open3d，全量无采样）
│   ├── download_images.py  # Flickr 图片下载（需 PRO API Key）
│   ├── bundle_to_colmap.py # Bundle → COLMAP 格式转换
│   └── prepare_component.sh
├── nerf/
│   └── train.sh           # NeRF 训练
├── 3dgs/
│   └── train.sh           # 3DGS 训练
├── setup.sh               # 环境安装
├── algo.md                # 算法选型说明
└── README.md              # 本文件

---

参考文献

• Li et al., Location Recognition using Prioritized Feature Matching, ECCV 2010
• Johnson et al., Nerfstudio: A Modular Framework for Neural Radiance Field Development, SIGGRAPH 2023
• Kerbl et al., 3D Gaussian Splatting for Real-Time Radiance Field Rendering, SIGGRAPH 2023
• Ye et al., gsplat: An Open-Source Library for Gaussian Splatting, 2024
• Johnson et al., Billion-scale similarity search with GPUs (FAISS), IEEE TBIG 2021