#+title: mrcal - camera calibrations and more!

mrcal is a photogrammetry toolkit that provides improved methods for making and
using camera models (calibration, tracking, mapping, etc). Currently the focus
is on calibration and uncertainty propagation, but more methods will be added
with time. It was originally built at NASA/JPL to generate the high-accuracy
calibrations demanded by long-range stereo, so it provides facilities to analyze
calibration accuracy 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.

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: the calibration chessboard isn't
assumed to be flat, lenses aren't assumed to follow simple parametric models,
rectified stereo isn't done with a pinhole model, and so on.

* Documentation index
** Overview
Please see [[file:tour.org][a tour of mrcal]] for a high-level overview of the capabilities of the
toolkit.

** Building, installing
First, the tools should be [[file:install.org][built or installed]].

** Background
Before using the tools, it is helpful to read about the [[file:conventions.org][terminology and
conventions]] used in the sources and documentation.

At the core of a calibration routine is an optimization problem. Details about
its [[file:formulation.org][formulation]] are useful to be able to interpret the results.

A lens can be represented by any of a number of [[file:lensmodels.org][lens models]], and a model can be
written to a [[file:cameramodels.org][file on disk]].

A separate page describes various details about [[file:splined-models.org][splined models]].

** Applications
A [[file:how-to-calibrate.org][how-to-calibrate]] page describes this very common task.

Given a model, we can compute its [[file:uncertainty.org][projection uncertainties]]. Given more than one
model, we can [[file:differencing.org][compare their intrinsics (projection behaviors)]].

If we have a calibrated pair of cameras, we can generate a depth map with [[file:stereo.org][dense
stereo processing]]. Or we can compute sparse ranges by calling a [[file:triangulation.org][triangulation
routine]].

** Interfaces
Many common tasks can be accomplished by invoking one of a number of
[[file:commandline-tools.org][command-line tools]].

If we need to do something more than what the pre-made tools can do, there're
two sets programmatic interfaces available:

- [[file:c-api.org][The C API to provide a set of core functionality]]
- [[file:python-api.org][The Python API to do that and a whole lot more]]

** Releases
A version history, release notes, and the planned roadmap are available on the
[[file:versions.org][releases]] page.

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

#+begin_example
@misc{mrcal,
  author = "Dima Kogan",
  title = "mrcal",
  howpublished = "\url{http://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]].
