mrcal Python API
Table of Contents
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.
mrcal.identity_R(): Return an identity rotation matrixmrcal.identity_r(): Return an identity Rodrigues rotationmrcal.identity_Rt(): Return an identity Rt transformationmrcal.identity_rt(): Return an identity rt transformationmrcal.r_from_R(): Compute a Rodrigues vector from a rotation matrixmrcal.R_from_r(): Compute a rotation matrix from a Rodrigues vectormrcal.rt_from_Rt(): Compute an rt transformation from a Rt transformationmrcal.Rt_from_rt(): Compute an Rt transformation from a rt transformationmrcal.invert_R(): Invert an (3,3) matrix rotation. This is a transposemrcal.invert_Rt(): Invert an Rt transformationmrcal.invert_rt(): Invert an rt transformationmrcal.compose_Rt(): Compose Rt transformationsmrcal.compose_rt(): Compose rt transformationsmrcal.rotate_point_r(): Rotate point(s) using a Rodrigues vectormrcal.rotate_point_R(): Rotate point(s) using a rotation matrixmrcal.transform_point_rt(): Transform point(s) using an rt transformationmrcal.transform_point_Rt(): Transform point(s) using an Rt transformationmrcal.R_from_quat(): Convert a rotation defined as a unit quaternion rotation to a rotation matrixmrcal.quat_from_R(): Convert a rotation defined as a rotation matrix to a unit quaternion
Alignment
mrcal.align_procrustes_points_Rt01(): Compute a rigid transformation to align two point cloudsmrcal.align_procrustes_vectors_R01(): Compute a rotation to align two sets of direction vectors
Lens models
Routines for manipulating lens models.
mrcal.supported_lensmodels(): Returns a tuple of strings for the various lens models we supportmrcal.lensmodel_num_params(): Get the number of lens parameters for a particular model typemrcal.lensmodel_metadata_and_config(): Returns meta-information about a modelmrcal.knots_for_splined_models(): Return a tuple of locations of x and y spline knots
Projections
mrcal.project(): Projects a set of 3D camera-frame points to the imagermrcal.unproject(): Unprojects pixel coordinates to observation vectorsmrcal.project_pinhole(): Projects a set of 3D camera-frame points using a pinhole modelmrcal.unproject_pinhole(): Unprojects a set of 2D pixel coordinates using a pinhole modelmrcal.project_stereographic(): Projects a set of 3D camera-frame points using a stereographic mapmrcal.unproject_stereographic(): Unprojects a set of 2D pixel coordinates using a stereographic mapmrcal.project_latlon(): Projects a set of 3D camera-frame points using a transverse equirectangular projection (used primarily for wide-angle stereo)mrcal.unproject_latlon(): Unprojects a set of 2D pixel coordinates using a transverse equirectangular projection (used primarily for wide-angle stereo)mrcal.project_lonlat(): Projects a set of 3D camera-frame points using an equirectangular projection (useful for representing 360-degree panoramas)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 commandline tools.
mrcal.show_geometry(): Visualize the world represented by some number of cameras and chessboards and points. For instance, result of a calibration run.mrcal.show_projection_diff(): Visualize the difference in projection between N modelsmrcal.show_projection_uncertainty(): Visualize the uncertainty in camera projectionmrcal.show_projection_uncertainty_vs_distance(): Visualize the uncertainty in camera projection along one observation raymrcal.show_distortion_off_pinhole(): Visualize a lens's deviation from a pinhole projection: examine the difference across the imagermrcal.show_distortion_off_pinhole_radial(): Visualize a lens's deviation from a pinhole projection: examine the radial distortion curvemrcal.show_valid_intrinsics_region(): Visualize a model's valid-intrinsics regionmrcal.show_splined_model_correction(): Visualize the projections corrections represented by a splined modelmrcal.show_residuals_board_observation(): Visualize calibration residuals for a single observationmrcal.show_residuals_histogram(): Visualize the distribution of the optimized residualsmrcal.show_residuals_vectorfield(): Visualize the optimized residuals as a vector fieldmrcal.show_residuals_magnitudes(): Visualize the optimized residual magnitudes as color-coded pointsmrcal.show_residuals_directions(): Visualize the optimized residual directions as color-coded pointsmrcal.show_residuals_regional(): Visualize the optimized residuals, broken up by region
Utilities
mrcal.annotate_image__valid_intrinsics_region(): Annotate an image with a model's valid-intrinsics regionmrcal.imagergrid_using(): Get a 'using' gnuplotlib expression for imager colormap plotsmrcal.fitted_gaussian_equation(): Get an 'equation' gnuplotlib expression for a gaussian curve fitting some datamrcal.sample_imager(): Returns regularly-sampled, gridded pixels coordinates across the imagermrcal.sample_imager_unproject(): Reports 3D observation vectors that regularly sample the imagermrcal.plotoptions_state_boundaries(): Return the 'set' plot options for gnuplotlib to show the state boundariesmrcal.plotoptions_measurement_boundaries(): Return the 'set' plot options for gnuplotlib to show the measurement boundariesmrcal.apply_color_map(): Color-code an array
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.
mrcal.compute_chessboard_corners(): Compute the chessboard observations and returns them in a usable formmrcal.estimate_monocular_calobject_poses_Rt_tocam(): Estimate camera-referenced poses of the calibration object from monocular viewsmrcal.estimate_joint_frame_poses(): Estimate world-referenced poses of the calibration objectmrcal.seed_stereographic(): Compute an optimization seed for a camera calibration
Image transforms
mrcal.scale_focal__best_pinhole_fit(): Compute the optimal focal-length scale for reprojection to a pinhole lensmrcal.pinhole_model_for_reprojection(): Generate a pinhole model suitable for reprojecting an imagemrcal.image_transformation_map(): Compute a reprojection map between two modelsmrcal.transform_image(): Transforms a given image using a given map
Model analysis
mrcal.implied_Rt10__from_unprojections(): Compute the implied-by-the-intrinsics transformation to fit two cameras' projectionsmrcal.worst_direction_stdev(): Compute the worst-direction standard deviation from a 2x2 covariance matrixmrcal.projection_uncertainty(): Compute the projection uncertainty of a camera-referenced pointmrcal.projection_diff(): Compute the difference in projection between N modelsmrcal.is_within_valid_intrinsics_region(): Which of the pixel coordinates fall within the valid-intrinsics region?
Stereo, triangulation, feature-matching
mrcal.rectified_system(): Generate rectified stereo models, which we can use to rectify images for stereo matchingmrcal.rectification_maps(): Construct pixel mappings to transform captured images into rectified imagesmrcal.stereo_range(): Compute ranges from observed disparitiesmrcal.match_feature(): Find a pixel correspondence in a pair of imagesmrcal.triangulate(): Triangulate N points with uncertainty propagation. This is a higher-level function than the othermrcal.triangulate_...()routinesmrcal.triangulate_geometric(): Simple geometric triangulationmrcal.triangulate_lindstrom(): Triangulation minimizing the 2-norm of pinhole reprojection errorsmrcal.triangulate_leecivera_l1(): Triangulation minimizing the L1-norm of angle differencesmrcal.triangulate_leecivera_linf(): Triangulation minimizing the infinity-norm of angle differencesmrcal.triangulate_leecivera_mid2(): Triangulation using Lee and Civera's alternative midpoint method. Recommended.mrcal.triangulate_leecivera_wmid2(): Triangulation using Lee and Civera's inverse-depth-weighted alternative midpoint method. Recommended in favor ofmrcal.triangulate_leecivera_mid2()if we're looking at objects very close to either camera.
Synthetic data
mrcal.ref_calibration_object(): Return the geometry of the calibration objectmrcal.synthesize_board_observations(): Produce synthetic chessboard observations
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.
mrcal.state_index_intrinsics(): Return the index in the optimization vector of the intrinsics of camera imrcal.state_index_extrinsics(): Return the index in the optimization vector of the extrinsics of camera imrcal.state_index_frames(): Return the index in the optimization vector of the pose of frame imrcal.state_index_points(): Return the index in the optimization vector of the position of point imrcal.state_index_calobject_warp(): Return the index in the optimization vector of the calibration object warpmrcal.num_states_intrinsics(): Get the number of intrinsics parameters in the optimization vectormrcal.num_states_extrinsics(): Get the number of extrinsics parameters in the optimization vectormrcal.num_states_frames(): Get the number of calibration object pose parameters in the optimization vectormrcal.num_states_points(): Get the number of point-position parameters in the optimization vectormrcal.num_states_calobject_warp(): Get the number of parameters in the optimization vector for the board warpmrcal.num_intrinsics_optimization_params(): Get the number of intrinsics parameters to describe one cameramrcal.measurement_index_boards(): Return the measurement index of the start of a given board observationmrcal.measurement_index_points(): Return the measurement index of the start of a given point observationmrcal.measurement_index_regularization(): Return the index of the start of the regularization measurementsmrcal.num_measurements_boards(): Return how many measurements we have from calibration object observationsmrcal.num_measurements_points(): Return how many measurements we have from point observationsmrcal.num_measurements_regularization(): Return how many measurements we have from regularizationmrcal.num_measurements(): Return how many measurements we have in the full optimization problemmrcal.num_states(): Get the total number of parameters in the optimization vector
State packing
The optimization routine works in the space of scaled parameters, and several functions are available to pack/unpack the state vector \(\vec p\).
mrcal.pack_state(): Scales a state vector to the packed, unitless form used by the optimizermrcal.unpack_state(): Scales a state vector from the packed, unitless form used by the optimizermrcal.ingest_packed_state(): Read a given packed state into optimization_inputs
Optimization
Direct interfaces to the mrcal optimizer.
mrcal.optimize(): Invoke the calibration routinemrcal.optimizer_callback(): Call the optimization callback function
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:
mrcal.cameramodel.__init__(): Read a model from a file on disk, or construct from the data given in the arguments.mrcal.cameramodel.write(): Write out this camera-model to a filemrcal.cameramodel.intrinsics(): Get or set the intrinsics in this modelmrcal.cameramodel.extrinsics_rt_toref(): Get or set the extrinsics in this modelmrcal.cameramodel.extrinsics_rt_fromref(): Get or set the extrinsics in this modelmrcal.cameramodel.extrinsics_Rt_toref(): Get or set the extrinsics in this modelmrcal.cameramodel.extrinsics_Rt_fromref(): Get or set the extrinsics in this modelmrcal.cameramodel.imagersize(): Get the imagersize in this modelmrcal.cameramodel.valid_intrinsics_region(): Get or set the valid intrinsics regionmrcal.cameramodel.optimization_inputs(): Get the original optimization inputs. Used for uncertainty evaluation or other analysismrcal.cameramodel.icam_intrinsics(): Get the camera index indentifying this camera at optimization time. Used in conjunction withmrcal.cameramodel.optimization_inputs()
Miscellaneous utilities
mrcal.hypothesis_board_corner_positions(): Reports the coordinates of chessboard points, as predicted by the optimization statemrcal.polygon_difference(): Return the difference of two closed polygonsmrcal.mapping_file_framenocameraindex(): Parse image filenames to get the frame numbersmrcal.close_contour(): Close a polyline, if it isn't already closedmrcal.apply_homography(): Apply a homogeneous-coordinate homography to a set of 2D pointsmrcal.corresponding_icam_extrinsics(): Return the icam_extrinsics corresponding to a given icam_intrinsicsmrcal.residuals_chessboard(): Compute and return the chessboard residuals