mrcal 2.0 release notes

New in mrcal 2.0

Lots and lots of under-the-hood improvements and bug fixes. Most notable ones listed here

High level significant improvements

Reworked the dense stereo processing. This is now documented, with nice APIs. Rectified models can be represented in a .cameramodel file, and saved to disk.
Added sparse triangulation routines. Uncertainty can be propagated through these routines to gauge the effects of calibration-time and observation-time noise.
LENSMODEL_SPLINED_STEREOGRAPHIC models have been thoroughly tested, and are ready for prime time. Solver now applies anisotropic regularization to reduce curl in the correction vector field, so the solved models now act mostly radially. The mrcal-show-splined-model-correction tool extended, and produces clearer plots. These models work well. Use them.
The observed_pixel_uncertainty is now estimated from the optimized residuals instead of being specified explicitly. The reported uncertainties should now be correct in absolute, not just relative terms
mrcal.unproject() can report gradients
Calibration residuals can be visualized from the stored cameramodel, not just from mrcal-calibrate-cameras --explore. Added new tools
- mrcal-show-residuals-board-observation
- mrcal-show-residuals
and new Python API functions
.cameramodel files can be read/written from C
Added simple projection/unprojection functions to the Python and C APIs:
This is added to the existing functions
- mrcal.project_stereographic()
- mrcal.unproject_stereographic()
Added LENSMODEL_LATLON and LENSMODEL_LONLAT models to represent epipolar-aligned and panoramic images respectively

Lower-level improvements for user convenience and/or internal machinery

All Python poseutils functions can now work in-place
Added mrcal.invert_R() function
mrcal.transform_point_Rt() and mrcal.rotate_point_R() can take an inverted argument
mrcal.project_stereographic() and mrcal.unproject_stereographic() and the others now use numpysane_pywrap, so full broadcasting and in-place output are available
Added mrcal.num_states(), mrcal.num_intrinsics_optimization_params()
New lensmodel metadata property: has_gradients. Currently only LENSMODEL_CAHVORE has this at False
mrcal.transform_image() supports more of the opencv api, like inplace output
mrcal-reproject-image tool has new --distance argument
mrcal-show-.... visualization tools (and mrcal.show_...() functions) have new --title (and title) argument. These replace the default title instead of extending the default, which --extratitle does
mrcal.projection_uncertainty() function can take observed_pixel_uncertainty argument, to override the value inferred from the residuals at the optimum
The visualization functions can plot observations with dots instead of points:
Added mrcal.fitted_gaussian_equation()

Migration notes 1.0 -> 2.0

mrcal is being actively developed, and some improvements change the interfaces in incompatible ways, requiring small amounts of work to port older code. I try to avoid breaking changes, but sometimes doing this is necessary. The C API is mostly unstable. If you use the mrcal C library, read this section carefully. The Python API and the commandline tools are mostly stable, but some things did change, so please still read this section.

The observed_pixel_uncertainty is now estimated from the optimized residuals instead of being specified explicitly. mrcal_optimize() and mrcal_optimizer_callback() in the C API don't have this argument anymore. The Python analogues mrcal.optimize() and mrcal.optimizer_callback() still accept the argument (to keep old .cameramodel files working), but this argument is now ignored
seed_pinhole() function reworked and renamed to mrcal.seed_stereographic()
mrcal.transform_image() API extended. Calls are backwards-compatible, but the defaults have changed
show_splined_model_surface() function renamed to mrcal.show_splined_model_correction(). Similarly, The mrcal-show-splined-model-surface tool renamed to mrcal-show-splined-model-correction. New function and tool can display the data in new ways (the correction vector field and correction magnitude), and the defaults have changed
mrcal-show-distortion-off-pinhole cmdline tool: --scale argument renamed to --vectorscale for consistency
mrcal.show_distortion_off_pinhole(): radial functionality split into mrcal.show_distortion_off_pinhole_radial()
mrcal.show_projection_uncertainty_xydist() was removed. It wasn't useful
LENSMODEL_CAHVORE lens models: linearity is a configuration parameter, not an optimization parameter. All existing .cameramodel files containing LENSMODEL_CAHVORE models must be ported. I doubt there's a single one of those out there.
mrcal.hypothesis_corner_positions() renamed to mrcal.hypothesis_board_corner_positions() and the API was updated in a breaking way
mrcal.lensmodel_metadata() renamed to mrcal.lensmodel_metadata_and_config()
All the existing stereo processing functions were redone. Calls to
- mrcal.stereo_rectify_prepare()
- mrcal.stereo_unproject()
- mrcal.stereo_range()
- mrcal.stereo_range()
must be ported. See the documentation for the new functions.
- mrcal_transform_point_Rt() and mrcal_rotate_point_R() C functions now take an inverted argument. This is an API, ABI break
mrcal.synthesize_board_observations() returns Rt_ref_boardref, not Rt_cam0_boardref. The API didn't change, but the meaning of the output did
mrcal_project_...() and mrcal_unproject_...() functions now take const double* fxycxy instead of 4 discrete double values
Similarly, the mrcal.project_...() and mrcal.unproject_...() functions now take an fxycxy array instead of 4 discrete values
mrcal_state_index_THING() and mrcal_num_states_THING() (and their Python flavors) return <0 and 0 respectively in C (and None and 0 respectively in Python) in case the THING isn't actually being optimized
mrcal-show-geometry tool: --scale-axes argument renamed to --axis-scale
mrcal-show-valid-intrinsics-region tool: --writeimage renamed to --write-image
mrcal.apply_color_map() uses BGR, not RGB
mrcal.image_transformation_map(): API extended in non-backwards-compatible way
Some tools, functions have more consistent, better arguments at the expense of breaking the API:
- mrcal.show_projection_diff()
- mrcal-show-projection-diff
- mrcal.projection_diff()
- mrcal-graft-models
mrcal-show-geometry tool: default is flipped, so --hide-boards option was removed and a --show-calobjects option added
mrcal.synthesize_board_observations() uses different strings for the which argument: _ -> -