mrcal - camera calibrations and more!

mrcal is a toolkit that provides improved methods for making and using camera models (calibration, tracking, mapping, photogrammetry, etc). It was originally built at NASA/JPL to generate the high-accuracy calibrations demanded by long-range stereo, so it provides facilities to calibrate cameras, thoroughly analyze the accuracy of the result, and to propagate and report uncertainties.

Why mrcal?

Because all other tools are terrible if you care about accuracy. They make basic questions like "how much data should I gather for a calibration?" and "how good is this calibration I just computed?" and "how different are these two models?" unanswerable. The previous state-of-the-art was good-enough for low-resolution cameras and long-focal-length lenses and low-range stereo. But today, the existing tools are insufficient, and we can do better.

This toolkit allows the user to confidently produce calibrations that are as good as possible. It provides lots of visualization capabilities to evaluate various properties of a model solution. And it provides powerful analysis methods, such as model differencing and quantification of projection and triangulation uncertainty. To fit the real-world lens behavior mrcal loosens many assumptions common in other toolkits, and does things differently:

  • Homogeneous coordinates are not used anywhere for anything. These use a pinhole projection, which is a very poor representation of real-world lenses
  • There is no concept of "distortion", and we never "undistort" anything. No projection function can preserve object shapes and object sizes and the straightness of lines, and you're always distorting something. The common idea that you "undistort" into a pinhole projection introduces all sorts of problems into sizes and shapes for all but the longest of lenses.
  • Rectified stereo isn't done with a pinhole model either, for the same reason. A better projection function is available that is friendlier to wider lenses
  • Lenses aren't assumed to follow simple parametric models, because if you actually look, as mrcal tools allow you to do, you can see that they all do not fit well. A rich model is available.
  • Reprojection error is not used as a gauge of calibration quality. Because this doesn't work. Uncertainty and cross-validation tools are provided instead
  • The calibration chessboard isn't assumed to be flat, with a parabolic deformation model available.

And so on.

mrcal consists of

  • a C library for core functionality
  • a Python library for higher-level functions
  • pre-made commandline tools to handle common tasks

Documentation index

Overview, background

  • The tour of mrcal: if this is your first exposure to mrcal, start here. This goes over the high-level capabilities of the toolkit, to give a good sense of what mrcal can do that's different and better than other tools.
  • Terminology and conventions

Details about the internals

Citing

To cite this work in a publication, use this bibtex stanza: 

@misc{mrcal,
  author = "Dima Kogan",
  title = "mrcal",
  howpublished = "\url{https://mrcal.secretsauce.net}",
}

Dev communication

For now let's use the github issue tracker for bug reporting and for communication in general. At some point I will probably set up a mailing list as well.

Author

Dima Kogan <dima@secretsauce.net>

License and copyright

These are listed on their own page.