MRCAL(1)

NAME
mrcal-show-stereo-pair-diff - Visualize the difference in projection between 2 camera pairs

SYNOPSIS
  $ mrcal-show-stereo-pair-diff      \
      --distance 2                   \
      before/camera-[01].cameramodel \
      after/camera-[01].cameramodel

  ... a plot pops up showing how these two pairs differ in their projections

DESCRIPTION
THIS TOOL IS EXPERIMENTAL, AND LIKELY WILL BE CHANGED AND EXTENDED. MORE COMPLETE DOCUMENTATION WILL BE WRITTEN LATER

It is useful to evaluate the stability and uncertainty of a multi-camera system, looking at the intrinsics,extrinsics either separately or jointly. For instance, when deployed in the field a calibration may shift in the extrinsics (camera units moved) and/or intrinsics (lens moved), and it would be useful to quantify them individually. Up to now (version 2.5) mrcal has been concerned mostly with the intrinsics: the mean-pcam uncertainty method and implied_Rt10__from_unprojections() try to compensate for and eliminate the effect of extrinsic shifts in uncertainty and diff methods respectively.

This stereo_pair_diff() tool extends this in one way: in a multi-camera calibration, it quantifies the joint intrinsics+extrinsics shift of a camera pair. At a given distance this tool reprojects pixels in camera0 to camera1, and compares the results of this reprojection. This is actually far simpler than the earlier intrinsics-only methods: no implied transform or reference-frame shift need to be considered. As of mrcal 2.5 we also have an extrinsics-only stereo-pair diff in an unreleased analyses/extrinsics-stability.py tool. No corresponding uncertainty method is implemented yet, but that is straightforward. All the methods will be implemented in a future mrcal release. They can then be studied to see what is useful to look at in practice.

This tool visualizes the results of mrcal.stereo_pair_diff()

OPTIONS

  POSITIONAL ARGUMENTS
  models                4 camera models: 2 cameras from the first camera pair,
                        followed by 2 cameras from the other pair

  OPTIONAL ARGUMENTS
  -h, --help            show this help message and exit
  --gridn GRIDN GRIDN   How densely we should sample the imager. By default we
                        use a 60x40 grid
  --distance DISTANCE   The projection difference varies depending on the
                        range to the observed world points, with the queried
                        range set in this argument. If omitted we look out to
                        infinity.
  --observations        If given, I show where the chessboard corners were
                        observed at calibration time. These should correspond
                        to the low-diff regions.
  --valid-intrinsics-region
                        If given, I overlay the valid-intrinsics regions onto
                        the plot
  --cbmax CBMAX         Maximum range of the colorbar
  --title TITLE         Title string for the plot. Overrides the default
                        title. Exclusive with --extratitle
  --extratitle EXTRATITLE
                        Additional string for the plot to append to the
                        default title. Exclusive with --title
  --vectorfield         Plot the diff as a vector field instead of as a heat
                        map. The vector field contains more information
                        (magnitude AND direction), but is less clear at a
                        glance
  --vectorscale VECTORSCALE
                        If plotting a vectorfield, scale all the vectors by
                        this factor. Useful to improve legibility if the
                        vectors are too small to see
  --hardcopy HARDCOPY   Write the output to disk, instead of making an
                        interactive plot
  --terminal TERMINAL   gnuplotlib terminal. The default is good almost
                        always, so most people don't need this option
  --set SET             Extra 'set' directives to gnuplotlib. Can be given
                        multiple times
  --unset UNSET         Extra 'unset' directives to gnuplotlib. Can be given
                        multiple times

REPOSITORY
<https://www.github.com/dkogan/mrcal>

AUTHOR
Dima Kogan, "<dima@secretsauce.net>"

LICENSE AND COPYRIGHT
Copyright (c) 2017-2023 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0