Camera model representation in memory and on disk

Interfacing with camera models is done in Python with the mrcal.cameramodel class. This describes one camera; a calibrated set of cameras is represented by multiple objects. Each object always contains

• The intrinsics: lens parameters describing one of the lens models
• The extrinsics: a pose of the camera in space. This pose is represented as a transformation between some common reference coordinate system and the camera coordinate system. The specific meaning of the reference coordinate system is arbitrary, but all the cameras in a calibrated set must be defined in respect to the one common reference.

Each camera model object may also contain:

• The optimization_inputs: all the data used to compute the model initially. Used for the uncertainty computations and any after-the-fact analysis.
• The valid_intrinsics_region: a contour in the imager where the projection behavior is "reliable". This is usually derived from the uncertainty plot, and used as a shorthand. It isn't as informative as the uncertainty plot, but such a valid-intrinsics contour is often convenient to have and to visualize.

The C API uses the mrcal_cameramodel_t structure to represent a model. This contains just the bare minimum:

• intrinsics (mrcal_lensmodel_t lensmodel, double intrinsics[0])
• extrinsics (double rt_cam_ref[6])
• imager size (unsigned int imagersize[2])

Note that the intrinsics data has size 0 because the size of this array depends on the specific lens model being used, and is unknown at compile time.

So it is an error to define this on the stack. Do not do this:

void f(void)
{
    mrcal_cameramodel_t model; // ERROR
}

If you need to define a known-at-compile-time model on the stack you can use the lensmodel-specific cameramodel types:

void f(void)
{
    mrcal_cameramodel_LENSMODEL_OPENCV8_t model; // OK
}

This only exists for models that have a constant number of parameters; notably there is no mrcal_cameramodel_LENSMODEL_SPLINED_STEREOGRAPHIC_t. When reading a model from disk, mrcal dynamically allocates the right amount of memory, and returns a mrcal_cameramodel_t*.

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);

Two different file formats are available:

• .cameramodel: the mrcal-native format. This is a plain text representation of a Python dict describing all the fields. This is the preferred format, and the only format supported by the C API
• .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. Not supported in C

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 data (if reading) and the filename (if writing). The mrcal-to-cahvor and mrcal-from-cahvor tools can be used to convert between the two file formats.

See the API documentation for usage details.