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 use these parameters
       intelligently we must have some sense of uncertainty in these parameters. This tool
       examines the uncertainty of projection of points 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 chessboard poses as well. This
       tool visualizes the expected value of projection error across the imager. Areas with a
       high expected projection error are unreliable for further work.

       There are 3 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 operate in a different mode: we look at
                               the projection uncertainty at one pixel, at different
                               distances along that observation ray. This is
                               different from the 2D uncertainty contours we get
                               normally. 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
         --observations        If given, I show where the chessboard corners were
                               observed 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-2021 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