Camera model representation in memory and on disk

Reading/writing camera models is done in Python with the mrcal.cameramodel class. The class and its representation on disk describe one camera; a calibrated set of cameras is represented by multiple instances. Each instance always contains

Each instance also may contain

File formats

The mrcal.cameramodel class supports reading and writing two different file formats:

  • .cameramodel: the mrcal-native format. This is a plain text representation of a Python dict describing all the fields. This is the preferred format.
  • .cahvor: the legacy format available for compatibility with existing JPL tools. If you don't need to interoperate with tools that require this format, there's little reason to use it. This format cannot store splined models or optimization_inputs, so it cannot be used for the uncertainty computations.

Note that both file formats can describe lenses using the LENSMODEL_CAHVOR model.

The mrcal.cameramodel class will intelligently pick the correct file format based on the filename being read/written. If the filename is unknown when reading (if we're reading a pipe, say) then both formats will be tried. If the filename is unknown when writing, the .cameramodel format will be used. The mrcal-to-cahvor and mrcal-to-cameramodel tools can be used to convert between the two file formats.

Sample usages

See the API documentation for usage details.

Grafting two models

A trivial example to

  • read two models from disk
  • recombine into a joint model that uses the lens parameters from one model with geometry from the other
  • write to disk
import mrcal

model_for_intrinsics = mrcal.cameramodel('model0.cameramodel')
model_for_extrinsics = mrcal.cameramodel('model1.cameramodel')

model_joint = mrcal.cameramodel( model_for_intrinsics )

extrinsics = model_for_extrinsics.extrinsics_rt_fromref()
model_joint.extrinsics_rt_fromref(extrinsics)

model_joint.write('model-joint.cameramodel')

This is the basic operation of the mrcal-graft-models tool.

Re-optimizing a model

To re-optimize a model from its optimization_inputs:

import mrcal

m = mrcal.cameramodel('camera.cameramodel')
optimization_inputs = m.optimization_inputs()
mrcal.optimize(**optimization_inputs)
model_reoptimized = \
  mrcal.cameramodel( optimization_inputs = m.optimization_inputs(), 
                     icam_intrinsics     = m.icam_intrinsics() )

Here we asked mrcal to re-optimize the data used to compute the given model originally. We didn't make any changes to the inputs, and we should already have an optimal solution, so this re-optimized model would be the same as the initial one. But we could tweak optimization problem before reoptimizing, and this would give us an nice way to observe the effects of those changes. We can add input noise or change the lens model or regularization terms or anything else.

C interface

The C API has a simple interface for reading/writing .cameramodel data:

mrcal_cameramodel_t* mrcal_read_cameramodel_string(const char* string, int len);
mrcal_cameramodel_t* mrcal_read_cameramodel_file  (const char* filename);
void                 mrcal_free_cameramodel(mrcal_cameramodel_t** cameramodel);

bool mrcal_write_cameramodel_file(const char* filename,
                                  const mrcal_cameramodel_t* cameramodel);

The .cahvor file format is not supported in C.