Reference

mrcal-show-residuals(1)

Visualize calibration residuals in an imager

NAME

mrcal-show-residuals - Visualize calibration residuals in an imager

SYNOPSIS

  $ mrcal-show-residuals --vectorfield left.cameramodel
  ... a plot pops up showing the vector field of residuals for this camera

DESCRIPTION

This tool supports several different modes, selected by the commandline arguments. Exactly one of these mode options must be given:

  --vectorfield Visualize the optimized residuals as a vector field. Each
                vector runs from the observed chessboard corner to its
                prediction at the optimal solution.
  --magnitudes  Visualize the optimized residual magnitudes as color-coded
                points. Similar to --vectorfield, but instead of a vector, each
                residual is plotted as a colored circle, coded by the MAGNITUDE
                of the error. This is usually more legible.
  --directions  Visualize the optimized residual directions as color-coded
                points. Similar to --vectorfield, but instead of a vector, each
                residual is plotted as a colored circle, coded by the DIRECTION
                of the error. This is very useful in detecting biases caused by
                a poorly-fitting lens model: these show up as clusters of
                similar color, instead of a random distribution.
  --regional    Visualize the optimized residuals, broken up by region. The imager
                of a camera is subdivided into bins. The residual statistics are
                then computed for each bin separately. We can then clearly see
                areas of insufficient data (observation counts will be low). And
                we can clearly see lens-model-induced biases (non-zero mean) and
                we can see heteroscedasticity (uneven standard deviation). The
                mrcal-calibrate-cameras tool uses these metrics to construct a
                valid-intrinsics region for the models it computes. This serves as
                a quick/dirty method of modeling projection reliability, which can
                be used even if projection uncertainty cannot be computed.
  --histogram   Visualize the distribution of the optimized residuals. We display
                a histogram of residuals and overlay it with an idealized
                gaussian distribution.

OPTIONS

POSITIONAL ARGUMENTS

  model                 Camera model that contains the optimization_inputs
                        that describe the solve. The displayed observations
                        may come from ANY of the cameras in the solve, not
                        necessarily the one given by this model

OPTIONAL ARGUMENTS

  -h, --help            show this help message and exit
  --vectorfield         Visualize the optimized residuals as a vector field
  --magnitudes          Visualize the optimized residual magnitudes as color-
                        coded points
  --directions          Visualize the optimized residual directions as color-
                        coded points
  --regional            Visualize the optimized residuals, broken up by region
  --histogram           Visualize the distribution of the optimized residuals
  --histogram-this-camera
                        If given, we show the histogram for residuals for THIS
                        camera only. Otherwise (by default) we display the
                        residuals for all the cameras in this solve. Implies
                        --histogram
  --valid-intrinsics-region
                        If given, I overlay the valid-intrinsics regions onto
                        the plot. Applies to all the modes except --histogram
  --gridn GRIDN GRIDN   How densely we should bin the imager. By default we
                        use a 20x14 grid of bins. Applies only if --regional
  --binwidth BINWIDTH   The width of binds used for the histogram. Defaults to
                        0.02 pixels. Applies only if --histogram
  --vectorscale VECTORSCALE
                        Scale all the vectors by this factor. Useful to
                        improve legibility if the vectors are too small to
                        see. Applies only if --vectorfield
  --cbmax CBMAX         Maximum range of the colorbar used in --vectorfield,
                        --magnitudes. If omitted, we autoscale
  --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 making an
                        interactive plot. If --regional, then several plots
                        are made, and the --hardcopy argument is a base name:
                        "--hardcopy /a/b/c/d.pdf" will produce plots in
                        "/a/b/c/d.XXX.pdf" where XXX is the type of plot being
                        made
  --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, "<[email protected]>"

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

History