GeoCalib 📸
基于几何优化的单张图像标定

Alexander Veicht · Paul-Edouard Sarlin · Philipp Lindenberger · Marc Pollefeys

ECCV 2024

论文 | Demo 🤗 | Colab | 视频

GeoCalib通过将几何优化与深度学习相结合，能够从单张图像中精确估计相机内参和重力方向。

GeoCalib是一种用于单张图像标定的算法：它仅需一张图像即可估计相机内参和重力方向。通过结合几何优化与深度学习，GeoCalib相比以往的方法提供了更灵活、更准确的标定结果。本仓库包含了GeoCalib的推理、评估和训练代码，以及下载我们的训练数据集OpenPano的说明。

设置与演示

我们提供了一个小型的推理包geocalib，它只需要极少的依赖项和Python >= 3.9。首先克隆仓库并安装依赖：

git clone https://github.com/cvg/GeoCalib.git && cd GeoCalib
python -m pip install -e .
# 或者
python -m pip install -e "git+https://github.com/cvg/GeoCalib#egg=geocalib"

以下是一个最小使用示例：

import torch
from geocalib import GeoCalib

device = "cuda" if torch.cuda.is_available() else "cpu"
model = GeoCalib().to(device)

# 加载图像为范围 [0, 1] 的张量，形状为 [C, H, W]
image = model.load_image("path/to/image.jpg").to(device)
result = model.calibrate(image)

print("camera:", result["camera"])
print("gravity:", result["gravity"])

请查看我们的演示笔记本，以获取完整的运行示例。

python -m geocalib.interactive_demo --camera_id 0

model = torch.hub.load("cvg/GeoCalib", "GeoCalib", trust_repo=True)

相机模型

GeoCalib目前通过camera_model参数支持以下相机模型：

1. pinhole（默认）仅建模焦距fx和fy，不考虑镜头畸变。
2. simple_radial用单个多项式畸变参数k1建模弱畸变。
3. radial用多项式畸变参数k1、k2建模较强畸变（感谢RuibinMa #25）。
4. simple_divisional按照Fitzgibbon在Simultaneous linear estimation of multiple view geometry and lens distortion（CVPR 2001）的建议，用单个畸变参数k1建模强鱼眼畸变。

默认模型针对小孔图像进行了优化。若需处理镜头畸变，请使用以下方法：

model = GeoCalib(weights="distorted")  # 默认是“pinhole”
result = model.calibrate(image, camera_model="simple_radial")  # 或 pinhole、simple_divisional

主点被假定位于图像中心，且不会被优化。可以通过扩展Camera对象来实现更多模型。

部分标定

当内参或重力方向已知时，可以按如下方式提供先验信息：

# 已知内参：
result = model.calibrate(image, priors={"focal": focal_length_tensor})

# 已知重力方向：
result = model.calibrate(image, priors={"gravity": gravity_direction_tensor})

多图像标定

要标定由同一台相机拍摄的多张图像，可以将图像列表传递给GeoCalib：

# batch 是一个张量列表，每个张量的形状为 [C, H, W]
result = model.calibrate(batch，shared_intrinsics=True）

评估

完整的评估和训练代码包含在单张图像标定库siclib中，可通过以下方式安装：

python -m pip install -e siclib

运行评估命令后，结果将被写入outputs/results/目录。

LaMAR

运行评估命令会将数据集下载到 data/lamar2k 目录下，大约需要 400 MB 的磁盘空间。

python -m siclib.eval.lamar2k --conf geocalib-pinhole --tag geocalib --overwrite

python -m siclib.eval.lamar2k --conf deepcalib --tag deepcalib --overwrite

python -m siclib.eval.lamar2k --conf perspective-cities data.preprocessing.resize_backend="PIL" --overwrite

python -m siclib.eval.lamar2k --conf perspective-openpano --overwrite

python -m siclib.eval.lamar2k --conf uvp --tag uvp --overwrite data.preprocessing.edge_divisible_by=null

python -m siclib.eval.lamar2k --checkpoint <实验名称> --tag <评估名称> --overwrite

MegaDepth

运行评估命令会将数据集下载到 data/megadepth2k 或 data/memegadepth2k-radial 目录下，分别需要约 2.1 GB 和 1.47 GB 的磁盘空间。

python -m siclib.eval.megadepth2k --conf geocalib-pinhole --tag geocalib --overwrite

python -m siclib.eval.megadepth2k_radial --conf geocalib-pinhole --tag geocalib --overwrite model.camera_model=simple_radial

python -m siclib.eval.megadepth2k --conf deepcalib --tag deepcalib --overwrite

python -m siclib.eval.megadepth2k --conf perspective-cities data.preprocessing.resize_backend="PIL" --overwrite

python -m siclib.eval.megadepth2k --conf perspective-openpano --overwrite

python -m siclib.eval.megadepth2k --conf uvp --tag uvp --overwrite data.preprocessing.edge_divisible_by=null

python -m siclib.eval.megadepth2k --checkpoint <实验名称> --tag <评估名称> --overwrite

TartanAir

运行评估命令会将数据集下载到 data/tartanair 目录下，大约需要 1.85 GB 的磁盘空间。

python -m siclib.eval.tartanair --conf geocalib-pinhole --tag geocalib --overwrite

python -m siclib.eval.tartanair --conf deepcalib --tag deepcalib --overwrite

python -m siclib.eval.tartanair --conf perspective-cities data.preprocessing.resize_backend="PIL" --overwrite

python -m siclib.eval.tartanair --conf perspective-openpano --overwrite

python -m siclib.eval.tartanair --conf uvp --tag uvp --overwrite data.preprocessing.edge_divisible_by=null

python -m siclib.eval.tartanair --checkpoint <实验名称> --tag <评估名称> --overwrite

Stanford2D3D

在下载并运行评估之前，您需要同意 Stanford2D3D 数据集的 使用条款。运行评估命令会将数据集下载到 data/stanford2d3d 目录下，大约需要 885 MB 的磁盘空间。

python -m siclib.eval.stanford2d3d --conf geocalib-pinhole --tag geocalib --overwrite

python -m siclib.eval.stanford2d3d --conf deepcalib --tag deepcalib --overwrite

python -m siclib.eval.stanford2d3d --conf perspective-cities data.preprocessing.resize_backend="PIL" --overwrite

python -m siclib.eval.stanford2d3d --conf perspective-openpano --overwrite

python -m siclib.eval.stanford2d3d --conf uvp --tag uvp --overwrite data.preprocessing.edge_divisible_by=null

python -m siclib.eval.stanford2d3d --checkpoint <实验名称> --tag <评估名称> --overwrite

评估选项

如果您希望在评估过程中提供先验信息，可以添加以下一个或多个标志：

python -m siclib.eval.<benchmark> --conf <config> \
    --tag <tag> \
    data.use_prior_focal=true \
    data.use_prior_gravity=true \
    data.use_prior_k1=true

python -m siclib.eval.inspect <benchmark> <一个或多个标签>

python -m siclib.eval.inspect lamar2k geocalib

OpenPano 数据集

OpenPano 数据集是一个用于单张图像标定的新数据集，包含来自不同来源的约 2,800 张全景图，具体来源包括 HDRMAPS、PolyHaven 以及 Laval 光度学室内 HDR 数据集。尽管该数据集规模小于以往的数据集，但它面向公众开放，并且在室内与室外场景之间提供了更好的平衡。

python -m siclib.datasets.utils.tonemapping --hdr_dir data/indoorDatasetCalibrated --out_dir data/laval-tonemap

python -m siclib.datasets.utils.download_openpano --name openpano --laval_dir data/laval-tonemap

python -m siclib.datasets.create_dataset_from_pano --config-name openpano

python -m siclib.datasets.create_dataset_from_pano --config-name openpano n_workers=10 device=cuda

python -m siclib.datasets.create_dataset_from_pano --config-name openpano_radial

训练

关于评估部分，训练代码已包含在单张图像标定库 siclib 中，可通过以下命令安装：

python -m pip install -e siclib

一旦 OpenPano 数据集 下载并准备好，我们就可以使用它来训练 GeoCalib：

首先下载 MSCAN-B 主干网络的预训练权重：

mkdir weights
wget "https://cloud.tsinghua.edu.cn/d/c15b25a6745946618462/files/?p=%2Fmscan_b.pth&dl=1" -O weights/mscan_b.pth

然后，使用以下命令开始训练：

python -m siclib.train geocalib-pinhole-openpano --conf geocalib --distributed

您可以自由选择其他实验名称。默认情况下，检查点将被写入 outputs/training/ 目录。默认批量大小为 24，需要两块配备 24GB 显存的 4090 GPU。配置由 Hydra 管理，可通过命令行覆盖。 例如，要在单块 2080 GPU 上以 5 的批量大小训练 GeoCalib，可运行：

python -m siclib.train geocalib-pinhole-openpano \
    --conf geocalib \
    data.train_batch_size=5 # 对于 1x 2080 GPU

请注意，这可能会影响整体性能。您可能需要相应地调整学习率和训练步数。

如果您希望将训练进度记录到 tensorboard 或 wandb 中，可以设置 train.writer 选项：

python -m siclib.train geocalib-pinhole-openpano \
    --conf geocalib \
    --distributed \
    train.writer=tensorboard

随后，可以使用实验名称对该模型进行评估：

python -m siclib.eval.<benchmark> --checkpoint geocalib-pinhole-openpano \
    --tag geocalib-retrained

python -m siclib.train deepcalib-openpano --conf deepcalib --distributed

python -m siclib.train perspective-net --conf perspective-net --distributed

python -m siclib.train param-net --conf param-net --distributed

BibTeX 引用

如果您使用了本文中的任何想法或本仓库中的代码，请考虑引用以下文献：

@inproceedings{veicht2024geocalib,
  author    = {Alexander Veicht and
               Paul-Edouard Sarlin and
               Philipp Lindenberger and
               Marc Pollefeys},
  title     = {{GeoCalib: Single-image Calibration with Geometric Optimization}},
  booktitle = {ECCV},
  year      = {2024}
}

许可证

代码采用 Apache-2.0 许可证 发布，而训练后的模型权重则采用 知识共享署名 4.0 国际许可协议 发布。感谢 Laval 室内 HDR 数据集 的作者允许我们使用其数据。

GeoCalib 快速上手指南

GeoCalib 是一个基于单张图像进行相机标定的算法，结合几何优化与深度学习，能够准确估计相机内参（焦距、畸变等）和重力方向。

环境准备

• 操作系统：Linux / macOS / Windows
• Python 版本：>= 3.9
• 依赖库：PyTorch（支持 CUDA 可选，用于 GPU 加速）
• 磁盘空间：基础安装约需 200MB，若需运行评估或训练请预留更多空间

💡 建议在国内使用清华或阿里镜像源加速 PyTorch 及相关依赖安装：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
# 或 CPU 版本
# pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

安装步骤

克隆仓库并安装 geocalib 包：

git clone https://github.com/cvg/GeoCalib.git && cd GeoCalib
python -m pip install -e .

或通过 Git 直接安装（无需克隆）：

python -m pip install -e "git+https://github.com/cvg/GeoCalib#egg=geocalib"

🇨🇳 国内用户如遇 GitHub 访问慢，可尝试使用镜像：

git clone https://gitee.com/mirrors/GeoCalib.git

（注：若官方未同步镜像，请自行查找可靠镜像源或使用代理）

基本使用

以下是最小化使用示例，加载一张图片并获取相机内参与重力方向：

import torch
from geocalib import GeoCalib

device = "cuda" if torch.cuda.is_available() else "cpu"
model = GeoCalib().to(device)

# 加载图像为 [C, H, W] 形状、值域 [0, 1] 的 tensor
image = model.load_image("path/to/image.jpg").to(device)
result = model.calibrate(image)

print("camera:", result["camera"])
print("gravity:", result["gravity"])

支持相机模型

默认使用针孔模型（pinhole），也可指定其他模型处理畸变：

# 使用简单径向畸变模型
model = GeoCalib(weights="distorted")
result = model.calibrate(image, camera_model="simple_radial")

支持的模型包括：

• pinhole（默认）
• simple_radial
• radial
• simple_divisional

批量标定（多张同相机图像）

batch = [image1, image2, image3]  # 每个元素为 [C, H, W] tensor
result = model.calibrate(batch, shared_intrinsics=True)

已知先验信息（部分标定）

若已知焦距或重力方向，可作为先验传入：

# 已知焦距
result = model.calibrate(image, priors={"focal": focal_length_tensor})

# 已知重力方向
result = model.calibrate(image, priors={"gravity": gravity_direction_tensor})

✅ 更多功能（如交互式 Webcam 演示、评估、训练）请参考官方仓库中的 demo.ipynb 或完整文档。