C++ library for computing homographies with support in Python.
import numpy as np
import homlib
# Estimate homography with one-sided radial distortion
solver = homlib.Wadenback3DV2026OneSided()
poses = solver.estimate(x, y) # returns list[PoseData]
# Robust estimation with LOMSAC
lomsac = homlib.LOMSAC(solver, squared_inlier_threshold=0.005)
estimate, stats = lomsac.estimate(x_noisy, y_noisy)If built with SupeRANSAC support:
sa = homlib.SupeRANSAC(solver, inlier_threshold=0.07)
estimate, stats = sa.estimate(x_noisy, y_noisy)This repository contains the following solvers for computing homographies with simultaneous radial distortion correction and/or incorporating IMU data.
We further support affine-covariant and orientation-covariant solvers, requiring fewer correspondences than their point-based counterparts by leveraging the geometric information of the corresponding descriptors.
| Authors (year) | #Corrs | Minimal | Radial distortion coeff. | IMU data | General homography | Descriptor |
|---|---|---|---|---|---|---|
| Hartley and Zisserman (2003) / DLT | 4+ | ✔️ | ✔️ | P | ||
| Guo (2019) | 4 | ✔️ | ✔️ | P | ||
| Cai et al. (2025) | 4 | ✔️ | ✔️ | P | ||
| Fitzgibbon (2001) | 5+ | ✔️ (e) | ✔️ | P | ||
| 5+ | ✔️ (1) | ✔️ | P | |||
| Kukelova et al. (2015) | 5 | ✔️ | ✔️ (2) | ✔️ | P | |
| 6 | ✔️ (2) | ✔️ | P | |||
| Valtonen Örnhag et al. (2020) | 4 | ✔️ | ✔️ | P | ||
| Valtonen Örnhag et al. (2021) | 3 | ✔️ | ✔️ | P | ||
| 4 | ✔️ | ✔️ (e) | ✔️ | P | ||
| Nakano (2024) | 5+ | ✔️ | ✔️ (1) | ✔️ | P | |
| Wadenbäck et al. (2026) | 5 | ✔️ | ✔️ (1) | ✔️ | P | |
| 5 | ✔️ | ✔️ (e) | ✔️ | P | ||
| 5 | ✔️ | ✔️ (2) | ✔️ | P | ||
| Barath and Hajder (2016) | 2+ | ✔️ | A | |||
| Valtonen Örnhag and Adalbjörnsson (2026) | 2+ | ✔️ (1) | ✔️ | A | ||
| 3+ | ✔️ | ✔️ (1) | ✔️ | O |
We use the following convention for the different distortion cases: (1) - single-sided, (e) two-sided and equal, and (2) two-sided. The following descriptor types: (P) - point-based, (A) affine-covariant, and (O) orientation-covariant.
The solvers by Valtonen Örnhag et al. and Wadenbäck et al. are original implementations, the others are re-implementations. If you use the code in your work, please cite the respective article:
@Book{hartley-zisserman-2003,
author = {Hartley, Richard and Zisserman, Andrew},
title = {Multiple View Geometry in Computer Vision},
edition = {2nd},
publisher = {Cambridge University Press},
year = {2003},
}
@Article{guo-2019-prl,
author = {Guo, Yang},
title = {A Minimal Solution for Plane Motion and Structure from Two Perspective Views},
journal = {Pattern Recognition Letters},
volume = {120},
pages = {96--103},
year = {2019},
}
@Article{cai-etal-2025-pami,
author = {Cai, Songwei and Wu, Zhijian and Guo, Li and Wang, Jian and Zhang, Shuzhi and Yan, Junchi and Shen, Shaojie},
title = {Fast and Interpretable 2D Homography Decomposition: Similarity-Kernel-Similarity and Affine-Core-Affine Transformations},
journal = {IEEE Transactions on Pattern Analysis and Machine Intelligence (PAMI)},
year = {2025},
}
@InProceedings{fitzgibbon-etal-2001-cvpr,
author = {Fitzgibbon, Andrew},
title = {Simultaneous linear estimation of multiple view geometry and lens distortion},
booktitle = {Proceedings of the IEEE Computer Society Conference on Computer Vision and Pattern Recognitioni (CVPR)},
year = {2001},
}
@InProceedings{kukelova-etal-2015-cvpr,
author = {Kukelova, Zuzana and Heller, Jan and Bujnak, Martin and Pajdla, Tomas},
title = {Radial Distortion Homography},
booktitle = {Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},
month = {June},
year = {2015}
}
@InProceedings{valtonen-ornhag-etal-2020-icpr,
author = {Valtonen~{\"O}rnhag, Marcus and Persson, Patrik and Wadenb{\"a}ck, M{\aa}rten and {\AA}str{\"o}m, Kalle and Heyden, Anders},
title = {Minimal Solvers for Indoor {UAV} Positioning},
booktitle = {Proceedings of the International Conference on Pattern Recognition (ICPR)},
month = {January},
year = {2021},
pages = {1136-1143}
}
@InProceedings{valtonen-ornhag-etal-2021-wacv,
author = {Valtonen~{\"O}rnhag, Marcus and Persson, Patrik and Wadenb{\"a}ck, M{\aa}rten and {\AA}str{\"o}m, Kalle and Heyden, Anders},
title = {Efficient Real-Time Radial Distortion Correction for {UAV}s},
booktitle = {Proceedings of the IEEE/CVF Winter Conference on Applications of Computer Vision (WACV)},
month = {January},
year = {2021},
pages = {1751-1760}
}
@InProceedings{nakano-2024-icpr,
author = {Nakano, Gaku},
title = {Inverse DLT Method for One-Sided Radial Distortion Homography},
booktitle = {Proceedings of the International Conference on Pattern Recognition (ICPR)},
year = {2024},
pages = {448-462}
}
@InProceedings{wadenback-etal-2026-3dv,
author = {Wadenb{\"a}ck, M{\aa}rten and Valtonen~{\"O}rnhag, Marcus and Edstedt, Johan},
title = {Radially Distorted Homographies, Revisited},
booktitle = {Proceedings of the International Conference on 3D Vision (3DV)},
year = {2026},
}
@InProceedings{valtonen-ornhag-adalbjornsson-2026-icpr,
author = {Valtonen~{\"O}rnhag, Marcus and Adalbj{\"o}rnsson, Stefan},
title = {Radial Distortion Homography Estimation from Affine-Covariant or Orientation-Covariant Features},
booktitle = {Proceedings of the International Conference on Pattern Recognition (ICPR)},
year = {2026},
}
@Article{barath-2025-superansac,
author = {Barath, Daniel},
title = {{SupeRANSAC}: One {RANSAC} to Rule Them All},
journal = {arXiv preprint arXiv:2506.04803},
year = {2025},
}
Pre-built wheels for all standard platforms and supported Python versions:
pip install homlibRequires PoseLib and Eigen 3.
pip install .Requires Boost and OpenCV in addition to the above.
git submodule update --init thirdparty/superansac
CMAKE_ARGS="-DHOMLIB_USE_SUPERANSAC=ON" pip install .The GC-RANSAC, MAGSAC and SupeRANSAC backends need Boost, OpenCV 4, gflags and OpenMP. With Homebrew
(its libomp is found automatically):
git submodule update --init --recursive
brew install eigen boost opencv@4 gflags libomp
CMAKE_ARGS="-DCMAKE_PREFIX_PATH=<PoseLib prefix> -DOpenCV_DIR=$(brew --prefix opencv@4)/lib/cmake/opencv4" pip install .For a C++ build, pass the same -DOpenCV_DIR to cmake.
Dependencies:
- Eigen 3:
apt-get install libeigen3-dev - PoseLib: build and install from source
- RansacLib (submodule):
git submodule update --init --recursive
mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --config ReleaseThe code is built in C++17 by default; it also builds in C++20 and C++23 (configure with -DCMAKE_CXX_STANDARD=20 or 23).
import homlib
# Point-based solver
solver = homlib.Wadenback3DV2026OneSided()
poses = solver.estimate(x, y) # x, y are 2xN numpy arrays
# Affine-covariant solver (fewer correspondences needed)
aff_solver = homlib.ValtonenOrnhagICPR2026AffineOneSided()
poses = aff_solver.estimate(x, y, A=affine_matrices) # A is 4xN
# Orientation-covariant solver
ori_solver = homlib.ValtonenOrnhagICPR2026OrientationOneSided()
poses = ori_solver.estimate(x, y, ori=orientations) # ori is 2xNsolver = homlib.Wadenback3DV2026OneSided()
lomsac = homlib.LOMSAC(solver, squared_inlier_threshold=0.005)
estimate, stats = lomsac.estimate(x, y)
print(estimate.homography)
print(estimate.distortion_parameter)
print(f"{len(stats.inlier_indices)} inliers")Requires building with -DHOMLIB_USE_GCRANSAC=ON.
solver = homlib.Wadenback3DV2026OneSided()
gc = homlib.GCRANSAC(solver, threshold=3.0)
estimate, stats = gc.estimate(x, y)
print(f"{len(stats.inliers)} inliers, {stats.num_iterations} iterations")Requires building with -DHOMLIB_USE_SUPERANSAC=ON.
solver = homlib.Wadenback3DV2026OneSided()
sa = homlib.SupeRANSAC(solver, inlier_threshold=0.07)
estimate, stats = sa.estimate(x, y)
print(f"{len(stats.inliers)} inliers, {stats.num_iterations} iterations")Any solver can be used with any RANSAC backend:
for solver in [homlib.FitzgibbonCVPR2001OneSided(),
homlib.NakanoICPR2025OneSided(),
homlib.Wadenback3DV2026OneSided()]:
lomsac = homlib.LOMSAC(solver, squared_inlier_threshold=0.005)
estimate, stats = lomsac.estimate(x, y)Many of the solvers were generated using the automatic generator proposed by Larsson et al. "Efficient Solvers for Minimal Problems by Syzygy-based Reduction" (CVPR 2017)