NAME

mrcal-show-projection-uncertainty - Visualize the expected projection error due to noise in calibration-time input

SYNOPSIS

$ mrcal-show-projection-uncertainty left.cameramodel
... a plot pops up showing the projection uncertainty of the intrinsics in
... this model

DESCRIPTION

The operation of this tool is documented at http://mrcal.secretsauce.net/uncertainty.html

A calibration process produces the best-fitting camera parameters. To be able to use these parameters we must know how trustworthy they are. This tool examines the uncertainty of projection using a given camera model. The projection operation uses the intrinsics only, but the uncertainty must take into account the calibration-time extrinsics and the calibration-time observed object poses as well. This tool visualizes the expected value of projection error across the imager. Areas with a high expected projection error are unreliable, and observations in those regions cannot be used for further work (localization, mapping, etc).

There are several modes of operation:

- By default we look at projection of points some distance away from the camera (given by --distance). We evaluate the uncertainty of these projections everywhere across the imager, and display the results as a heatmap with overlaid contours

- With --vs-distance-at we evaluate the uncertainty along an observation ray mapping to a single pixel. We show the uncertainty vs distances from the camera along this ray

See http://mrcal.secretsauce.net/uncertainty.html for a full description of the computation performed here

OPTIONS

POSITIONAL ARGUMENTS

model                 Input camera model. If "-' is given, we read standard
                      input

OPTIONAL ARGUMENTS

-h, --help            show this help message and exit
--vs-distance-at VS_DISTANCE_AT
                      If given, we don't compute the uncertainty everywhere
                      in the image at a constant distance from the camera,
                      but instead we look at different distances at one
                      pixel. This option takes a single argument: the "X,Y"
                      pixel coordinate we care about, or "center" to look at
                      the center of the imager or "centroid" to look at the
                      center of the calibration-time chessboards. This is
                      exclusive with --gridn and --distance and
                      --observations and --cbmax
--gridn GRIDN GRIDN   How densely we should sample the imager. By default we
                      use a 60x40 grid
--distance DISTANCE   By default we display the projection uncertainty
                      infinitely far away from the camera. If we want to
                      look closer in, the desired observation distance can
                      be given in this argument
--isotropic           By default I display the expected value of the
                      projection error in the worst possible direction of
                      this error. If we want to plot the RMS of the worst
                      and best directions, pass --isotropic. If we assume
                      the errors will apply evenly in all directions, then
                      we can use this metric, which is potentially easier to
                      compute
--method {mean-frames,cross-reprojection--rrp-Jfp}
                      Multiple uncertainty quantification methods are
                      available. We default to 'mean-frames'
--observations        If given, I display the pixel observations at
                      calibration time. This should correspond to the low-
                      uncertainty regions.
--valid-intrinsics-region
                      If given, I overlay the valid-intrinsics region 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
--hardcopy HARDCOPY   Write the output to disk, instead of 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