NAME

mrcal-show-projection-uncertainty - Visualize the expected projection error due to uncertainty in the 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 --observations-xydist we display a 3D plot showing the uncertainty everywhere across the imager and at various distances. This contains a lot of information, but that makes it challenging to interpret

- 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
  --observations-xydist
                        If given, we operate in a different mode: we make a 3D
                        plot of uncertainties and chessboard observations
                        instead of the 2D uncertainty contours we get
                        normally. This is exclusive with --vs-distance-at,
                        --distance, --isotropic, --observations.
  --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 --observations-xydist and
                        --gridn and --distance and --observations and --cbmax
  --gridn GRIDN GRIDN   How densely we should sample the imager. By default we
                        use a 60x40 grid (or a (15,10) grid if --observations-
                        xydist)
  --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
  --extratitle EXTRATITLE
                        Extra title string for the plot
  --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-2020 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