mrcal Python API

Table of Contents

A Python API is available to go beyond what the pre-made commandline tools can do. These tools themselves are written using the Python API, so their sources are are a good guide.

All the Python functions have complete docstrings, so the pydoc3 tool is effective at displaying the relevant documentation. For convenience, all the docstrings have been extracted and formatted into the Python API reference.

The available functions, by category:

Geometry

Primitives

Functions to manipulate rotations and poses.

Alignment

Lens models

Routines for manipulating lens models.

Projections

Visualization

Driver routines

These are all backends for the corresponding commandline tools.

Utilities

Calibration helpers

These are used by routines implementing a camera calibration system. Most users will run the mrcal-calibrate-cameras tool instead of calling these.

Image transforms

Model analysis

Stereo, triangulation, feature-matching

Synthetic data

CHOLMOD interface

The mrcal solver is an optimization routine based on sparse nonlinear least squares. The optimization loop is implemented in libdogleg, which uses the CHOLMOD solver to compute the Cholesky factorization. With a Cholesky factorization we can efficiently solve the linear system \(J^T J \vec a = \vec b\) where the jacobian matrix \(J\) is large and sparse.

CHOLMOD is a C routine, and mrcal provides a Python interface. This is used internally for the projection uncertainty computations, and is convenient for general analysis. The sparse \(J\) matrix is available from the optimizer via the mrcal.optimizer_callback() function, as a scipy.sparse.csr_matrix sparse array.

The factorization can be computed by instantiating a mrcal.CHOLMOD_factorization class, and the linear system can then be solved by calling mrcal.CHOLMOD_factorization.solve_xt_JtJ_bt(). See these two docstrings for usage details and examples.

Layout of the measurement and state vectors

Functions to interpret the contentes of the state and measurement vectors.

State packing

The optimization routine works in the space of scaled parameters, and several functions are available to pack/unpack the state vector \(\vec b\).

Optimization

Direct interfaces to the mrcal optimizer.

Camera model reading/writing

The mrcal.cameramodel class provides functionality to read/write models from/to files on disk. Both the .cameramodel and .cahvor file formats are supported, choosing the proper one, depending on the given filename. When reading a pipe (no filename known), both formats are tried. If writing to a pipe, the .cameramodel format is chosen, unless .cahvor is requested via the arguments. The available methods:

Image reading/writing

mrcal includes simple functions for reading/writing images. These aren't interesting, or better than any other functions you may have already. These exist because they're faster than loading the opencv module and to make life easy for those that don't already have other functions handy.

Miscellaneous utilities