#+title: 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
- [[file:tour.org][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.
- [[file:conventions.org][Terminology and conventions]]

** Details about the internals
- [[file:formulation.org][Problem formulation]]: at the core of a calibration routine is an optimization
  problem. The details are important to interpret the results
- [[file:lensmodels.org][Lens models supported by mrcal]]
- [[file:splined-models.org][Splined-stereographic lens model]]: this very rich lens model is available for
  high-fidelity modeling of projection and quantification of uncertainty. It is
  the recommended model, and is novel in mrcal, so it's described in detail
  here.
- [[file:cameramodels.org][Camera model representation in memory and on disk]]
- [[file:differencing.org][Projection differencing]]: mrcal can compute the projection difference between
  several models. This is useful to evaluate calibration quality and lens
  stability and a multitude of other things.
- [[File:uncertainty.org][Projection uncertainties]]: mrcal can compute the projection uncertainty of a
  calibration. This quantifies the effect of sampling error, and is an excellent
  gauge of the quality of a model.
- [[file:stereo.org][Dense stereo processing]]
- [[file:triangulation.org][Triangulation]]

** Practical guides
- [[file:how-to-calibrate.org][How to calibrate a camera system: practical details]]
- [[file:recipes.org][Recipes: various scenarios that need special attention]]

** Toolkit usage
- [[file:install.org][Installation, build instructions]]
- [[file:commandline-tools.org][Command-line tools]]
- [[file:python-api.org][The Python API]]
- [[file:c-api.org][The C API]]

** [[file:versions.org][Releases: a version history, release notes, and the planned roadmap]]

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

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

* Dev communication
For now let's use the [[https://github.com/dkogan/mrcal/issues][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 [[file:copyrights.org][their own page]].
