#+TITLE: mrcal 2.4 release notes
#+OPTIONS: toc:nil

* New in mrcal 2.4
This is yet another mostly-maintenance release. A number of bugs are fixed, and
a number of new features have been added. The biggest new features:

- mrcal can be built with clang. Try it out like this: =CC=clang CXX=clang++
  make=. This opens up some portability improvements, such as making it easier
  to run on Windows.
- Full dense stereo pipeline in C.

** General fixes
- All the tools use =/usr/bin/env= in the =#!= line. People who live life on
  hard mode now have it slightly easier

- Tools to support more file formats:
  - [[file:mrcal-from-kalibr.html][=mrcal-from-kalibr=]]
  - [[file:mrcal-to-kalibr.html][=mrcal-to-kalibr=]]
  - [[file:mrcal-from-ros.html][=mrcal-from-ros=]]
  These are experimental. /Please/ let me know if these are or aren't useful

- [[file:mrcal-stereo.html][=mrcal-stereo=]], [[file:mrcal-python-api-reference.html#-stereo_range][=mrcal.stereo_range()=]] work properly if =disparity_min>0=

- The [[file:mrcal-stereo.html][=mrcal-stereo=]] GUI displays the pixel coordinates for /both/ cameras, not
  just the one under the cursor

** Build
- mrcal builds with clang

- The sources do not use =_GNU_SOURCE=: mrcal does not depend on glibc

- The sources support the updated CHOLMOD APIs in the recent distros

** Python API
- The Procrustes fit functions ([[file:mrcal-python-api-reference.html#-align_procrustes_vectors_R01][=mrcal.align_procrustes_vectors_R01()=]],
  [[file:mrcal-python-api-reference.html#-align_procrustes_vectors_Rt01][=mrcal.align_procrustes_vectors_Rt01()=]]) detect and report errors in the input
  data

- [[file:mrcal-python-api-reference.html#-show_projection_diff][=mrcal.show_projection_diff()=]] has similar contour-generating options as what
  [[file:mrcal-python-api-reference.html#-show_projection_uncertainty][=mrcal.show_projection_uncertainty()=]] has

- renamed =mrcal.residuals_chessboard()= to [[file:mrcal-python-api-reference.html#-residuals_board][=mrcal.residuals_board()=]]. Both
  names are available for backwards compatibility

- =mrcal.show_residuals_...()= functions and =mrcal-show-residuals-...= tools
  now /all/ have =cbmax= and =--cbmax= options respectively to set the upper
  bound for the mapping in the heat map display

- Added [[file:mrcal-python-api-reference.html#CHOLMOD_factorization-rcond][=mrcal.CHOLMOD_factorization.rcond()=]] as an interface to
  =cholmod_rcond()=

- [[file:mrcal-python-api-reference.html#-worst_direction_stdev][=mrcal.worst_direction_stdev()=]] works with NxN arrays, not just 2x2

- [[file:mrcal-python-api-reference.html#-ref_calibration_object][=mrcal.ref_calibration_object()=]] has a new =optimization_inputs= argument.
  This provides a convenient shorthand to get the object used in a particular
  calibration

- Added [[file:mrcal-python-api-reference.html#-R_aligned_to_vector][=mrcal.R_aligned_to_vector()=]] to produce a non-unique rotation to map a
  given vector to [0,0,1]

- Added [[file:mrcal-python-api-reference.html#-sorted_eig][=mrcal.sorted_eig()=]] to compute an eigenvalue decomposition with
  /sorted/ eigenvalues

- Added [[file:mrcal-python-api-reference.html#-write_point_cloud_as_ply][=mrcal.write_point_cloud_as_ply()=]] to write a point cloud as a =.ply=
  file

- [[file:mrcal-python-api-reference.html#-apply_color_map][=mrcal.apply_color_map()=]] supports /all/ gnuplot rgbformulae, above the 7,5,15
  default

- [[file:mrcal-python-api-reference.html#-stereo_range][=mrcal.stereo_range()=]] has more optional arguments:
  - =disparity_max= to set the upper valid-disparity bound
  - =disparity_scaled_min=, =disparity_scaled_max= to act on the raw disparity
    data produced by the stereo matcher

** C API
- Better error handling: lensmodel-parsing functions return an error code
  instead of asserting, if given invalid input. Affected functions:

  - =mrcal_lensmodel_name_unconfigured()=
  - =mrcal_lensmodel_name()=
  - =mrcal_lensmodel_type_from_name()=
  - =mrcal_lensmodel_from_name()=

- More image types supported. We now have:
  - =mrcal_image_int8_t=
  - =mrcal_image_uint8_t=
  - =mrcal_image_int16_t=
  - =mrcal_image_uint16_t=
  - =mrcal_image_int32_t=
  - =mrcal_image_uint32_t=
  - =mrcal_image_int64_t=
  - =mrcal_image_uint64_t=
  - =mrcal_image_float_t=
  - =mrcal_image_double_t=
  - =mrcal_image_bgr_t=

- Renamed the =bgr_t= type to =mrcal_bgr_t=. For namespacing.

- =mrcal_rectification_maps()= supports =LENSMODEL_LATLON= /and/
  =LENSMODEL_PINHOLE= rectification

- The remaining pieces for a [[file:c-api.org::#dense-stereo-in-c][full dense-stereo pipeline in C]] were implemented.
  The new functions are

  - =mrcal_stereo_range_sparse()= to convert a set of disparity values to ranges
  - =mrcal_stereo_range_dense()= to convert a disparity /image/ to a range
    /image/
  - =mrcal_apply_color_map()= to convert a disparity or range image to a heat
    map for human consumption

  A [[https://github.com/dkogan/mrcal/blob/master/doc/examples/dense-stereo-demo/dense-stereo-demo.cc][dense-stereo-in-C sample]] is provided.

* Migration notes 2.3 -> 2.4
- C API/ABI breaking change: these functions now take an extra =int
  Nobservations_board= argument:
  - =mrcal_pack_solver_state_vector()=
  - =mrcal_unpack_solver_state_vector()=
- C API breaking change: =bgr_t= structure renamed to =mrcal_bgr_t=
- Python API: a function was renamed: =mrcal.residuals_chessboard()= ->
  [[file:mrcal-python-api-reference.html#-residuals_board][=mrcal.residuals_board()=]]. Both names are available for backwards
  compatibility, but moving to the new name is recommended.
- Python [[file:mrcal-python-api-reference.html#-apply_color_map][=mrcal.apply_color_map()=]] function: =a_min=, =a_max= arguments now
  /must/ be passed in as kwargs, and not as positionals.
