cvg/GeoCalib

GeoCalib – Single‑image Camera Calibration

What it does – GeoCalib takes a single RGB image and predicts the camera’s intrinsic parameters (focal length, optional distortion) and the direction of gravity (i.e., the up‑vector) in the scene. It combines a deep neural network that extracts geometric cues with a lightweight geometric optimisation step, giving more accurate results than previous learning‑only methods.

Key capabilities

• Supports several classic camera models: pinhole, simple_radial, radial, and simple_divisional (fisheye).
• Can work with partial priors (known focal length or known gravity).
• Handles batches of images captured with the same camera, and even rigs of multiple rigidly‑mounted cameras sharing a common gravity direction.
• Provides a tiny inference‑only Python package (geocalib) with only a few dependencies (Python ≥ 3.9, PyTorch).
• Comes with a Gradio web demo, a Colab notebook, and a real‑time webcam demo.

Installation & quick start

# clone and install the inference package
git clone https://github.com/cvg/GeoCalib.git && cd GeoCalib
python -m pip install -e .   # or install directly from the repo URL

import torch
from geocalib import GeoCalib

model = GeoCalib().to('cuda' if torch.cuda.is_available() else 'cpu')
img = model.load_image('my_picture.jpg').to(model.device)
result = model.calibrate(img)
print('camera intrinsics →', result['camera'])
print('gravity direction →', result['gravity'])

The package also works via torch.hub:

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

Demo & interactive use

• Colab notebook – runs the whole pipeline in the browser.
• Gradio demo – hosted at https://veichta‑geocalib.hf.space, lets you upload an image and see the estimated horizon, up‑vectors, and optional visualisations (grid, virtual box, etc.).
• Webcam demo – python -m geocalib.interactive_demo --camera_id 0 opens a live window; keys toggle visualisations and switch camera models.

Training & evaluation

• The core training code lives in the companion library siclib. Install it with pip install -e siclib.
• Pre‑trained models are trained on OpenPano, a newly released dataset of ~2.8 k HDR panoramas (converted to ~37 k perspective crops).
• Evaluation scripts cover several benchmarks (LaMAR, MegaDepth, TartanAir, Stanford2D3D). Commands such as python -m siclib.eval.lamar2k --conf geocalib-pinhole --tag geocalib run the full test and write results to outputs/results/.
• Results tables in the README show GeoCalib achieving the highest AUC scores for roll, pitch, and field‑of‑view errors across all listed datasets, outperforming DeepCalib, ParamNet, and UVP.

Dataset – OpenPano

• Combines HDR panoramas from HDRMAPS, PolyHaven, and the Laval indoor HDR collection.
• A script (siclib.datasets.utils.download_openpano) downloads the public panoramas; another script creates the training split with optional tonemapping for HDR images.
• After processing you get ~37 k training images, plus ~2 k each for validation and test.

Why it matters Accurate intrinsics and gravity estimation from a single image is useful for many downstream tasks: 3‑D reconstruction, AR/VR alignment, robotics navigation, and any application that needs to reason about scene orientation without multi‑view data. GeoCalib’s blend of learning and classic optimisation makes it both flexible (handles distortion) and precise.

---

All information above is taken directly from the repository’s README; no additional features have been inferred.