#+TITLE: mrcal Python API
#+OPTIONS: toc:t

A Python API is available to go beyond what the [[file:commandline-tools.org][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 [[file:mrcal-python-api-reference.html][Python API reference]].

The available functions, by category:

* Geometry
** Primitives
Functions to manipulate [[file:conventions.org::#pose-representation][rotations and poses]].

- [[file:mrcal-python-api-reference.html#-identity_R][=mrcal.identity_R()=]]: Return an identity rotation matrix
- [[file:mrcal-python-api-reference.html#-identity_r][=mrcal.identity_r()=]]: Return an identity Rodrigues rotation
- [[file:mrcal-python-api-reference.html#-identity_Rt][=mrcal.identity_Rt()=]]: Return an identity Rt transformation
- [[file:mrcal-python-api-reference.html#-identity_rt][=mrcal.identity_rt()=]]: Return an identity rt transformation
- [[file:mrcal-python-api-reference.html#-r_from_R][=mrcal.r_from_R()=]]: Compute a Rodrigues vector from a rotation matrix
- [[file:mrcal-python-api-reference.html#-R_from_r][=mrcal.R_from_r()=]]: Compute a rotation matrix from a Rodrigues vector
- [[file:mrcal-python-api-reference.html#-rt_from_Rt][=mrcal.rt_from_Rt()=]]: Compute an rt transformation from a Rt transformation
- [[file:mrcal-python-api-reference.html#-Rt_from_rt][=mrcal.Rt_from_rt()=]]: Compute an Rt transformation from a rt transformation
- [[file:mrcal-python-api-reference.html#-invert_R][=mrcal.invert_R()=]]: Invert an (3,3) matrix rotation. This is a transpose
- [[file:mrcal-python-api-reference.html#-invert_Rt][=mrcal.invert_Rt()=]]: Invert an Rt transformation
- [[file:mrcal-python-api-reference.html#-invert_rt][=mrcal.invert_rt()=]]: Invert an rt transformation
- [[file:mrcal-python-api-reference.html#-compose_r][=mrcal.compose_r()=]]: Compose Rodrigues rotations
- [[file:mrcal-python-api-reference.html#-compose_Rt][=mrcal.compose_Rt()=]]: Compose Rt transformations
- [[file:mrcal-python-api-reference.html#-compose_rt][=mrcal.compose_rt()=]]: Compose rt transformations
- [[file:mrcal-python-api-reference.html#-compose_r_tinyr0_gradientr0][=mrcal.compose_r_tinyr0_gradientr0()=:]] Special-case rotation composition,
  assuming the first rotation is near identity
- [[file:mrcal-python-api-reference.html#-compose_r_tinyr1_gradientr1][=mrcal.compose_r_tinyr1_gradientr1()=:]] Special-case rotation composition,
  assuming the second rotation is near identity
- [[file:mrcal-python-api-reference.html#-compose_rt_tinyrt0_gradientrt0][=mrcal.compose_rt_tinyrt0_gradientrt0()=]]: Special-case composition assuming
  the first transform is near identity
- [[file:mrcal-python-api-reference.html#-rotate_point_r][=mrcal.rotate_point_r()=]]: Rotate point(s) using a Rodrigues vector
- [[file:mrcal-python-api-reference.html#-rotate_point_R][=mrcal.rotate_point_R()=]]: Rotate point(s) using a rotation matrix
- [[file:mrcal-python-api-reference.html#-transform_point_rt][=mrcal.transform_point_rt()=]]: Transform point(s) using an rt transformation
- [[file:mrcal-python-api-reference.html#-transform_point_Rt][=mrcal.transform_point_Rt()=]]: Transform point(s) using an Rt transformation
- [[file:mrcal-python-api-reference.html#-R_from_quat][=mrcal.R_from_quat()=]]: Convert a rotation defined as a unit quaternion rotation to a rotation matrix
- [[file:mrcal-python-api-reference.html#-quat_from_R][=mrcal.quat_from_R()=]]: Convert a rotation defined as a rotation matrix to a unit quaternion
- [[file:mrcal-python-api-reference.html#-Rt_from_qt][=mrcal.Rt_from_qt()=]]: Compute an Rt transformation from a qt transformation
- [[file:mrcal-python-api-reference.html#-qt_from_Rt][=mrcal.qt_from_Rt()=]]: Compute a qt transformation from an Rt transformation

** Alignment
- [[file:mrcal-python-api-reference.html#-align_procrustes_points_Rt01][=mrcal.align_procrustes_points_Rt01()=]]: Compute a rigid transformation to align two point clouds
- [[file:mrcal-python-api-reference.html#-align_procrustes_vectors_R01][=mrcal.align_procrustes_vectors_R01()=]]: Compute a rotation to align two sets of direction vectors
- [[file:mrcal-python-api-reference.html#-R_aligned_to_vector][=mrcal.R_aligned_to_vector()=]]: Compute a non-unique rotation to map a given
  vector to [0,0,1]

* Lens models
Routines for manipulating [[file:lensmodels.org][lens models]].

- [[file:mrcal-python-api-reference.html#-supported_lensmodels][=mrcal.supported_lensmodels()=]]: Returns a tuple of strings for the various lens models we support
- [[file:mrcal-python-api-reference.html#-lensmodel_num_params][=mrcal.lensmodel_num_params()=]]: Get the number of lens parameters for a particular model type
- [[file:mrcal-python-api-reference.html#-lensmodel_metadata_and_config][=mrcal.lensmodel_metadata_and_config()=]]: Returns [[file:lensmodels.org::#representation][meta-information about a model]]
- [[file:mrcal-python-api-reference.html#-knots_for_splined_models][=mrcal.knots_for_splined_models()=]]: Return a tuple of locations of x and y spline knots

* Projections
- [[file:mrcal-python-api-reference.html#-project][=mrcal.project()=]]: Projects a set of 3D camera-frame points to the imager
- [[file:mrcal-python-api-reference.html#-unproject][=mrcal.unproject()=]]: Unprojects pixel coordinates to observation vectors
- [[file:mrcal-python-api-reference.html#-project_pinhole][=mrcal.project_pinhole()=]]: Projects a set of 3D camera-frame points using a pinhole model
- [[file:mrcal-python-api-reference.html#-unproject_pinhole][=mrcal.unproject_pinhole()=]]: Unprojects a set of 2D pixel coordinates using a pinhole model
- [[file:mrcal-python-api-reference.html#-project_stereographic][=mrcal.project_stereographic()=]]: Projects a set of 3D camera-frame points using a stereographic map
- [[file:mrcal-python-api-reference.html#-unproject_stereographic][=mrcal.unproject_stereographic()=]]: Unprojects a set of 2D pixel coordinates using a stereographic map
- [[file:mrcal-python-api-reference.html#-project_latlon][=mrcal.project_latlon()=]]: Projects a set of 3D camera-frame points using a
  transverse equirectangular projection (used primarily for wide-angle stereo)
- [[file:mrcal-python-api-reference.html#-unproject_latlon][=mrcal.unproject_latlon()=]]: Unprojects a set of 2D pixel coordinates using a
  transverse equirectangular projection (used primarily for wide-angle stereo)
- [[file:mrcal-python-api-reference.html#-project_lonlat][=mrcal.project_lonlat()=]]: Projects a set of 3D camera-frame points using an
  equirectangular projection (useful for representing 360-degree panoramas)
- [[file:mrcal-python-api-reference.html#-unproject_lonlat][=mrcal.unproject_lonlat()=]]: Unprojects a set of 2D pixel coordinates using an
  equirectangular projection (useful for representing 360-degree panoramas)

* Visualization
** Driver routines
These are all backends for the corresponding [[file:commandline-tools.org][commandline tools]].

- [[file:mrcal-python-api-reference.html#-show_geometry][=mrcal.show_geometry()=]]: Visualize the world represented by some number of
  cameras and chessboards and points. For instance, result of a calibration run.
- [[file:mrcal-python-api-reference.html#-show_projection_diff][=mrcal.show_projection_diff()=]]: Visualize the difference in projection between N models
- [[file:mrcal-python-api-reference.html#-show_stereo_pair_diff][=mrcal.show_stereo_pair_diff()=]]: Visualize the difference in reprojection in 2 stereo pairs
- [[file:mrcal-python-api-reference.html#-show_projection_uncertainty][=mrcal.show_projection_uncertainty()=]]: Visualize the uncertainty in camera projection
- [[file:mrcal-python-api-reference.html#-show_projection_uncertainty_vs_distance][=mrcal.show_projection_uncertainty_vs_distance()=]]: Visualize the uncertainty in camera projection along one observation ray
- [[file:mrcal-python-api-reference.html#-show_distortion_off_pinhole][=mrcal.show_distortion_off_pinhole()=]]: Visualize a lens's deviation from a pinhole projection: examine the difference across the imager
- [[file:mrcal-python-api-reference.html#-show_distortion_off_pinhole_radial][=mrcal.show_distortion_off_pinhole_radial()=]]: Visualize a lens's deviation from a pinhole projection: examine the radial distortion curve
- [[file:mrcal-python-api-reference.html#-show_valid_intrinsics_region][=mrcal.show_valid_intrinsics_region()=]]: Visualize a model's valid-intrinsics region
- [[file:mrcal-python-api-reference.html#-show_splined_model_correction][=mrcal.show_splined_model_correction()=]]: Visualize the projections
  corrections represented by a splined model
- [[file:mrcal-python-api-reference.html#-show_residuals_board_observation][=mrcal.show_residuals_board_observation()=]]: Visualize calibration measurements
  (weighted reprojection errors) for a single observation
- [[file:mrcal-python-api-reference.html#-show_residuals_histogram][=mrcal.show_residuals_histogram()=]]: Visualize the distribution of the optimized measurements
- [[file:mrcal-python-api-reference.html#-show_residuals_vectorfield][=mrcal.show_residuals_vectorfield()=]]: Visualize the optimized measurements as a vector field
- [[file:mrcal-python-api-reference.html#-show_residuals_magnitudes][=mrcal.show_residuals_magnitudes()=]]: Visualize the optimized measurement magnitudes as color-coded points
- [[file:mrcal-python-api-reference.html#-show_residuals_directions][=mrcal.show_residuals_directions()=]]: Visualize the optimized measurement directions as color-coded points
- [[file:mrcal-python-api-reference.html#-show_residuals_regional][=mrcal.show_residuals_regional()=]]: Visualize the optimized measurements, broken up by region

** Utilities
- [[file:mrcal-python-api-reference.html#-annotate_image__valid_intrinsics_region][=mrcal.annotate_image__valid_intrinsics_region()=]]: Annotate an image with a model's valid-intrinsics region
- [[file:mrcal-python-api-reference.html#-imagergrid_using][=mrcal.imagergrid_using()=]]: Get a 'using' gnuplotlib expression for imager colormap plots
- [[file:mrcal-python-api-reference.html#-fitted_gaussian_equation][=mrcal.fitted_gaussian_equation()=]]: Get an 'equation' gnuplotlib expression for a gaussian curve fitting some data
- [[file:mrcal-python-api-reference.html#-sample_imager][=mrcal.sample_imager()=]]: Returns regularly-sampled, gridded pixels coordinates across the imager
- [[file:mrcal-python-api-reference.html#-sample_imager_unproject][=mrcal.sample_imager_unproject()=]]: Reports 3D observation vectors that regularly sample the imager
- [[file:mrcal-python-api-reference.html#-plotoptions_state_boundaries][=mrcal.plotoptions_state_boundaries()=]]: Return the 'set' plot options for gnuplotlib to show the state boundaries
- [[file:mrcal-python-api-reference.html#-plotoptions_measurement_boundaries][=mrcal.plotoptions_measurement_boundaries()=]]: Return the 'set' plot options for gnuplotlib to show the measurement boundaries
- [[file:mrcal-python-api-reference.html#-apply_color_map][=mrcal.apply_color_map()=]]: Color-code an array
- [[file:mrcal-python-api-reference.html#-write_point_cloud_as_ply][=mrcal.write_point_cloud_as_ply()=]]: Write a point cloud to a .ply file

* Calibration helpers
These are used by routines implementing a [[file:formulation.org][camera calibration]] system. Most users
will run the [[file:mrcal-calibrate-cameras.html][=mrcal-calibrate-cameras=]] tool instead of calling these.

- [[file:mrcal-python-api-reference.html#-compute_chessboard_corners][=mrcal.compute_chessboard_corners()=]]: Compute or read the chessboard observations, and return them in a usable form
- [[file:mrcal-python-api-reference.html#-estimate_monocular_calobject_poses_Rt_tocam][=mrcal.estimate_monocular_calobject_poses_Rt_tocam()=]]: Estimate camera-referenced poses of the calibration object from monocular views
- [[file:mrcal-python-api-reference.html#-estimate_joint_frame_poses][=mrcal.estimate_joint_frame_poses()=]]: Estimate world-referenced poses of the calibration object
- [[file:mrcal-python-api-reference.html#-seed_stereographic][=mrcal.seed_stereographic()=]]: Compute an optimization seed for a camera calibration
- [[file:mrcal-python-api-reference.html#-traverse_sensor_links][=mrcal.traverse_sensor_links()=]]: Compute the best path through a graph of
  sensors, trying to maximize the common observations between each successive
  pair of sensors in the path. This is used in the calibration seeding routine
  to initialize a solve where every sensor's observations don't overlap with
  every other sensor's observations.

* Image transforms
- [[file:mrcal-python-api-reference.html#-scale_focal__best_pinhole_fit][=mrcal.scale_focal__best_pinhole_fit()=]]: Compute the optimal focal-length scale for reprojection to a pinhole lens
- [[file:mrcal-python-api-reference.html#-pinhole_model_for_reprojection][=mrcal.pinhole_model_for_reprojection()=]]: Generate a pinhole model suitable for reprojecting an image
- [[file:mrcal-python-api-reference.html#-image_transformation_map][=mrcal.image_transformation_map()=]]: Compute a reprojection map between two models
- [[file:mrcal-python-api-reference.html#-transform_image][=mrcal.transform_image()=]]: Transforms a given image using a given map

* Model analysis
- [[file:mrcal-python-api-reference.html#-implied_Rt10__from_unprojections][=mrcal.implied_Rt10__from_unprojections()=]]: Compute the implied-by-the-intrinsics transformation to fit two cameras' projections
- [[file:mrcal-python-api-reference.html#-worst_direction_stdev][=mrcal.worst_direction_stdev()=]]: Compute the worst-direction standard deviation from a 2x2 covariance matrix
- [[file:mrcal-python-api-reference.html#-projection_uncertainty][=mrcal.projection_uncertainty()=]]: Compute the [[file:uncertainty.org][projection uncertainty]] of a camera-referenced point
- [[file:mrcal-python-api-reference.html#-projection_diff][=mrcal.projection_diff()=]]: Compute the [[file:differencing.org][difference in projection]] between N models
- [[file:mrcal-python-api-reference.html#-stereo_pair_diff][=mrcal.stereo_pair_diff()=]]: Compute the [[file:differencing.org][difference in reprojection]] between 2 stereo pairs
- [[file:mrcal-python-api-reference.html#-is_within_valid_intrinsics_region][=mrcal.is_within_valid_intrinsics_region()=]]: Which of the pixel coordinates fall within the valid-intrinsics region?
- [[file:mrcal-python-api-reference.html#-model_resolution__deg_pixel][=mrcal.model_resolution__deg_pixel()=]]: Report the model resolution in deg/pixel

* Stereo, triangulation, feature-matching
:PROPERTIES:
:CUSTOM_ID: python-api-stereo
:END:

- [[file:mrcal-python-api-reference.html#-rectified_system][=mrcal.rectified_system()=]]: Generate rectified stereo models, which we can use
  to rectify images for stereo matching
- [[file:mrcal-python-api-reference.html#-rectified_resolution][=mrcal.rectified_resolution()=]]: Compute the resolution to be used for the
  rectified system. Usually this is called by [[file:mrcal-python-api-reference.html#-rectified_system][=mrcal.rectified_system()=]], but
  it's available standalone as well
- [[file:mrcal-python-api-reference.html#-rectification_maps][=mrcal.rectification_maps()=]]: Construct pixel mappings to transform captured
  images into rectified images
- [[file:mrcal-python-api-reference.html#-stereo_range][=mrcal.stereo_range()=]]: Compute ranges from observed disparities
- [[file:mrcal-python-api-reference.html#-stereo_unproject][=mrcal.stereo_unproject()=]]: Compute a point cloud from observed disparities
- [[file:mrcal-python-api-reference.html#-match_feature][=mrcal.match_feature()=]]: Find a pixel correspondence in a pair of images
- [[file:mrcal-python-api-reference.html#-triangulate][=mrcal.triangulate()=]]: Triangulate N points with uncertainty propagation. This
  is a higher-level function than the other =mrcal.triangulate_...()= routines
- [[file:mrcal-python-api-reference.html#-triangulate_geometric][=mrcal.triangulate_geometric()=]]: Simple geometric triangulation
- [[file:mrcal-python-api-reference.html#-triangulate_lindstrom][=mrcal.triangulate_lindstrom()=]]: Triangulation minimizing the 2-norm of pinhole reprojection errors
- [[file:mrcal-python-api-reference.html#-triangulate_leecivera_l1][=mrcal.triangulate_leecivera_l1()=]]: Triangulation minimizing the L1-norm of angle differences
- [[file:mrcal-python-api-reference.html#-triangulate_leecivera_linf][=mrcal.triangulate_leecivera_linf()=]]: Triangulation minimizing the infinity-norm of angle differences
- [[file:mrcal-python-api-reference.html#-triangulate_leecivera_mid2][=mrcal.triangulate_leecivera_mid2()=]]: Triangulation using Lee and Civera's
  alternative midpoint method. Recommended.
- [[file:mrcal-python-api-reference.html#-triangulate_leecivera_wmid2][=mrcal.triangulate_leecivera_wmid2()=]]: Triangulation using Lee and Civera's
  inverse-depth-weighted alternative midpoint method. Recommended in favor of
  [[file:mrcal-python-api-reference.html#-triangulate_leecivera_mid2][=mrcal.triangulate_leecivera_mid2()=]] if we're looking at objects very close to
  either camera.

* Synthetic data
- [[file:mrcal-python-api-reference.html#-ref_calibration_object][=mrcal.ref_calibration_object()=]]: Return the geometry of the calibration object
- [[file:mrcal-python-api-reference.html#-synthesize_board_observations][=mrcal.synthesize_board_observations()=]]: Produce synthetic chessboard observations
- [[file:mrcal-python-api-reference.html#-make_perfect_observations][=mrcal.make_perfect_observations()=]]: Write perfect observations with perfect
  noise into the optimization_inputs

* CHOLMOD interface
The mrcal solver is an optimization routine based on sparse nonlinear least
squares. The optimization loop is implemented in [[https://www.github.com/dkogan/libdogleg][=libdogleg=]], which uses the
[[https://people.engr.tamu.edu/davis/suitesparse.html][CHOLMOD solver]] to compute the [[https://en.wikipedia.org/wiki/Cholesky_decomposition][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 [[file:uncertainty.org][projection uncertainty]] computations, and is convenient for
general analysis. The sparse $J$ matrix is available from the optimizer via the
[[file:mrcal-python-api-reference.html#-optimizer_callback][=mrcal.optimizer_callback()=]] function, as a [[https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csr_matrix.html][=scipy.sparse.csr_matrix=]] sparse
array.

The factorization can be computed by instantiating a
[[file:mrcal-python-api-reference.html#CHOLMOD_factorization][=mrcal.CHOLMOD_factorization=]] class, and the linear system can then be solved by
calling [[file:mrcal-python-api-reference.html#CHOLMOD_factorization-solve_xt_JtJ_bt][=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 [[file:formulation.org][state and measurement vectors]].

- [[file:mrcal-python-api-reference.html#-state_index_intrinsics][=mrcal.state_index_intrinsics()=]]: Return the index in the optimization vector of the intrinsics of camera i
- [[file:mrcal-python-api-reference.html#-state_index_extrinsics][=mrcal.state_index_extrinsics()=]]: Return the index in the optimization vector of the extrinsics of camera i
- [[file:mrcal-python-api-reference.html#-state_index_frames][=mrcal.state_index_frames()=]]: Return the index in the optimization vector of the pose of frame i
- [[file:mrcal-python-api-reference.html#-state_index_points][=mrcal.state_index_points()=]]: Return the index in the optimization vector of the position of point i
- [[file:mrcal-python-api-reference.html#-state_index_calobject_warp][=mrcal.state_index_calobject_warp()=]]: Return the index in the optimization vector of the calibration object warp
- [[file:mrcal-python-api-reference.html#-num_states_intrinsics][=mrcal.num_states_intrinsics()=]]: Get the number of intrinsics parameters in the optimization vector
- [[file:mrcal-python-api-reference.html#-num_states_extrinsics][=mrcal.num_states_extrinsics()=]]: Get the number of extrinsics parameters in the optimization vector
- [[file:mrcal-python-api-reference.html#-num_states_frames][=mrcal.num_states_frames()=]]: Get the number of calibration object pose parameters in the optimization vector
- [[file:mrcal-python-api-reference.html#-num_states_points][=mrcal.num_states_points()=]]: Get the number of point-position parameters in the optimization vector
- [[file:mrcal-python-api-reference.html#-num_states_calobject_warp][=mrcal.num_states_calobject_warp()=]]: Get the number of parameters in the optimization vector for the board warp
- [[file:mrcal-python-api-reference.html#-num_intrinsics_optimization_params][=mrcal.num_intrinsics_optimization_params()=]]: Get the number of intrinsics parameters to describe /one/ camera
- [[file:mrcal-python-api-reference.html#-measurement_index_boards][=mrcal.measurement_index_boards()=]]: Return the measurement index of the start of a given board observation
- [[file:mrcal-python-api-reference.html#-measurement_index_points][=mrcal.measurement_index_points()=]]: Return the measurement index of the start of a given point observation
- [[file:mrcal-python-api-reference.html#-measurement_index_regularization][=mrcal.measurement_index_regularization()=]]: Return the index of the start of the regularization measurements
- [[file:mrcal-python-api-reference.html#-num_measurements_boards][=mrcal.num_measurements_boards()=]]: Return how many measurements we have from calibration object observations
- [[file:mrcal-python-api-reference.html#-num_measurements_points][=mrcal.num_measurements_points()=]]: Return how many measurements we have from point observations
- [[file:mrcal-python-api-reference.html#-num_measurements_regularization][=mrcal.num_measurements_regularization()=]]: Return how many measurements we have from regularization
- [[file:mrcal-python-api-reference.html#-num_measurements][=mrcal.num_measurements()=]]: Return how many measurements we have in the full optimization problem
- [[file:mrcal-python-api-reference.html#-num_states][=mrcal.num_states()=]]: Get the total number of parameters in the optimization vector

* State packing
The optimization routine works in the [[file:formulation.org::#state-packing][space of scaled parameters]], and several
functions are available to pack/unpack the state vector $\vec b$.

- [[file:mrcal-python-api-reference.html#-pack_state][=mrcal.pack_state()=]]: Scales a state vector to the packed, unitless form used by the optimizer
- [[file:mrcal-python-api-reference.html#-unpack_state][=mrcal.unpack_state()=]]: Scales a state vector from the packed, unitless form used by the optimizer
- [[file:mrcal-python-api-reference.html#-ingest_packed_state][=mrcal.ingest_packed_state()=]]: Read a given packed state into optimization_inputs

* Optimization
Direct interfaces to the [[file:formulation.org][mrcal optimizer]].

- [[file:mrcal-python-api-reference.html#-optimize][=mrcal.optimize()=]]: Invoke the calibration routine
- [[file:mrcal-python-api-reference.html#-optimizer_callback][=mrcal.optimizer_callback()=]]: Call the optimization callback function

* Camera model reading/writing
The [[file:mrcal-python-api-reference.html#cameramodel][=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:

- [[file:mrcal-python-api-reference.html#cameramodel-__init__][=mrcal.cameramodel.__init__()=]]: Read a model from a file on disk, or construct
  from the data given in the arguments.
- [[file:mrcal-python-api-reference.html#cameramodel-write][=mrcal.cameramodel.write()=]]: Write out this camera-model to a file
- [[file:mrcal-python-api-reference.html#cameramodel-intrinsics][=mrcal.cameramodel.intrinsics()=]]: Get or set the intrinsics in this model
- [[file:mrcal-python-api-reference.html#cameramodel-rt_ref_cam][=mrcal.cameramodel.rt_ref_cam()=]]: Get or set the extrinsics in this model
- [[file:mrcal-python-api-reference.html#cameramodel-rt_cam_ref][=mrcal.cameramodel.rt_cam_ref()=]]: Get or set the extrinsics in this model
- [[file:mrcal-python-api-reference.html#cameramodel-Rt_ref_cam][=mrcal.cameramodel.Rt_ref_cam()=]]: Get or set the extrinsics in this model
- [[file:mrcal-python-api-reference.html#cameramodel-Rt_cam_ref][=mrcal.cameramodel.Rt_cam_ref()=]]: Get or set the extrinsics in this model
- [[file:mrcal-python-api-reference.html#cameramodel-extrinsics_rt_toref][=mrcal.cameramodel.extrinsics_rt_toref()=]]: Get or set the extrinsics in this model (legacy alias for the above)
- [[file:mrcal-python-api-reference.html#cameramodel-extrinsics_rt_fromref][=mrcal.cameramodel.extrinsics_rt_fromref()=]]: Get or set the extrinsics in this model (legacy alias for the above)
- [[file:mrcal-python-api-reference.html#cameramodel-extrinsics_Rt_toref][=mrcal.cameramodel.extrinsics_Rt_toref()=]]: Get or set the extrinsics in this model (legacy alias for the above)
- [[file:mrcal-python-api-reference.html#cameramodel-extrinsics_Rt_fromref][=mrcal.cameramodel.extrinsics_Rt_fromref()=]]: Get or set the extrinsics in this model (legacy alias for the above)
- [[file:mrcal-python-api-reference.html#cameramodel-imagersize][=mrcal.cameramodel.imagersize()=]]: Get the imagersize in this model
- [[file:mrcal-python-api-reference.html#cameramodel-valid_intrinsics_region][=mrcal.cameramodel.valid_intrinsics_region()=]]: Get or set the valid intrinsics region
- [[file:mrcal-python-api-reference.html#cameramodel-valid_intrinsics_region_reset][=mrcal.cameramodel.valid_intrinsics_region_reset()=]]: Reset the valid-intrinsics region to "none defined"
- [[file:mrcal-python-api-reference.html#cameramodel-optimization_inputs][=mrcal.cameramodel.optimization_inputs()=]]: Get the original optimization
  inputs. Used for uncertainty evaluation or other analysis
- [[file:mrcal-python-api-reference.html#cameramodel-optimization_inputs_reset][=mrcal.cameramodel.optimization_inputs_reset()=]]: Reset the optimization inputs to "none defined"
- [[file:mrcal-python-api-reference.html#cameramodel-icam_intrinsics][=mrcal.cameramodel.icam_intrinsics()=]]: Get the camera index indentifying this
  camera at optimization time. Used in conjunction with
  [[file:mrcal-python-api-reference.html#cameramodel-optimization_inputs][=mrcal.cameramodel.optimization_inputs()=]]

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

- [[file:mrcal-python-api-reference.html#-load_image][=mrcal.load_image()=]]: load an image from a file on disk into a numpy array
- [[file:mrcal-python-api-reference.html#-save_image][=mrcal.save_image()=]]: save an image in a numpy array to a file on disk

* Miscellaneous utilities
- [[file:mrcal-python-api-reference.html#-hypothesis_board_corner_positions][=mrcal.hypothesis_board_corner_positions()=]]: Reports the coordinates of chessboard
  points, as predicted by the optimization state
- [[file:mrcal-python-api-reference.html#-polygon_difference][=mrcal.polygon_difference()=]]: Return the difference of two closed polygons
- [[file:mrcal-python-api-reference.html#-mapping_file_framenocameraindex][=mrcal.mapping_file_framenocameraindex()=]]: Parse image filenames to get the frame numbers
- [[file:mrcal-python-api-reference.html#-close_contour][=mrcal.close_contour()=]]: Close a polyline, if it isn't already closed
- [[file:mrcal-python-api-reference.html#-apply_homography][=mrcal.apply_homography()=]]: Apply a homogeneous-coordinate homography to a set of 2D points
- [[file:mrcal-python-api-reference.html#-corresponding_icam_extrinsics][=mrcal.corresponding_icam_extrinsics()=]]: Return the icam_extrinsics corresponding to a given icam_intrinsics
- [[file:mrcal-python-api-reference.html#-measurements_board][=mrcal.measurements_board()=]]: Compute and return the chessboard measurements (weighted reprojection errors)
- [[file:mrcal-python-api-reference.html#-measurements_point][=mrcal.measurements_point()=]]: Compute and return the discrete point measurements (weighted reprojection errors)
- [[file:mrcal-python-api-reference.html#-sorted_eig][=mrcal.sorted_eig()=]]: Compute eigenvalues, eigenvectors; sorted results returned