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_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()
: 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_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 map
Visualization
Driver routines
These are all backends for the corresponding commandline tools.
mrcal.show_geometry()
: Visualize the world resulting from a calibration runmrcal.show_projection_diff()
: Visualize the difference in projection between N modelsmrcal.show_projection_uncertainty()
: Visualize the uncertainty in camera projectionmrcal.show_projection_uncertainty_xydist()
: Visualize in 3D 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 projectionmrcal.show_valid_intrinsics_region()
: Visualize a model's valid-intrinsics regionmrcal.show_splined_model_surface()
: Visualize the surface represented by a splined model
Utilities
mrcal.annotate_image__valid_intrinsics_region()
: Annotate an image with a model's valid-intrinsics regionmrcal.imagergrid_using()
: Get a 'using' expression for imager colormap plotsmrcal.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_pinhole()
: 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
mrcal.stereo_rectify_prepare()
: Precompute everything needed for stereo rectification and matchingmrcal.stereo_unproject()
: Unprojection in the rectified stereo systemmrcal.stereo_range()
: Compute ranges from observed disparities
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.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 problem
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_corner_positions()
: Reports the 3D chessboard points observed by a camera at calibration timemrcal.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_intrinsics