# 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

- 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 it.

Each instance also *may* 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.

## 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 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

Currently there's no support for reading/writing camera models from the C API. I will write this when I need it or when somebody bugs me about it, whichever comes first.