NAME

       mrcal-show-splined-model-correction - Visualizes the surface represented in a splined lens
       model

SYNOPSIS

         $ mrcal-show-splined-model-correction cam.cameramodel
         ... a plot pops up showing the correction magnitude heatmap

DESCRIPTION

       Splined models are parametrized by flexible surfaces that define the projection
       corrections (off some baseline model), and visualizing these corrections is useful for
       understanding the projection behavior. Details of these models are described in the
       documentation:

       <http://mrcal.secretsauce.net/lensmodels.html#splined-stereographic-lens-model>

       At this time LENSMODEL_SPLINED_STEREOGRAPHIC is the only splined model mrcal has, so the
       baseline model is always LENSMODEL_STEREOGRAPHIC.

       This tool produces a plot in the domain either of the input or the output of the spline
       functions.

       By default:
           The plot is presented based on the spline index. With
           LENSMODEL_SPLINED_STEREOGRAPHIC, this is the stereographic projection u.
           This is the "forward" direction, what the projection operation actually
           computes. In this view the knots form a regular grid, and the edge of the
           imager forms a (possibly very irregular) curve

       if --imager-domain:
           The plot is presented based on the pixels in the imager. This is the
           backward direction: the domain is the OUTPUT of the splined functions. In
           this view the knot layout is (possibly highly) irregular. The edge of the
           imager is a perfect rectangle.

       Separate from the domain, the data can be presented in 3 different ways:

       - Magnitude heatmap. This is the default. We plot mag(deltauxy). This displays
         the deviation from the baseline model as a heat map.

       - Individual heatmap. Selected by passing an "xy" argument. We plot deltaux or
         deltauy, depending on the value of xy. This displays the value of one of the
         two splined surfaces individually, as a heat map.

       - Vector field. Selected by --vectorfield. Displays the correction (deltaux,
         deltauy) as a vector field.

       The splined surfaces are defined by control points we call "knots". These knots are
       arranged in a fixed grid (defined by the model configuration) with the value at each knot
       set in the intrinsics vector.

       The configuration selects the control point density and the expected field of view of the
       lens. If the fov_x_deg configuration value is too big, many of the knots will lie well
       outside the visible area, and will not be used. This is wasteful. If fov_x_deg is too
       small, then some parts of the imager will lie outside of the spline-in-bounds region,
       resulting in less-flexible projection behavior at the edges of the imager. So the field of
       view should roughly match the actual lens+camera we're using, and we can evaluate that
       with this tool.  This tool displays the spline-in-bounds region together with the usable
       projection region (either the valid-intrinsics region or the imager bounds).  Ideally, the
       spline-in-bounds region is slightly bigger than the usable projection region.

       The usable projection region visualized by this tool is controlled by
       --show-imager-bounds. If omitted, we display the valid-intrinsics region. This is
       recommended, but keep in mind that this region is smaller than the full imager, so a
       fov_x_deg that aligns well for one calibration may be too small in a subsequent
       calibration of the same lens. If the subsequent calibration has better coverage, and thus
       a bigger valid-intrinsics region. If --show-imager-bounds: we use the imager bounds
       instead. The issue here is that the projection near the edges of the imager is usually
       poorly-defined because usually there isn't a lot of calibration data there. This makes the
       projection behavior at the imager edges unknowable. Consequently, plotting the projection
       at the imager edges is usually too alarming or not alarming enough. Passing
       --show-imager-bounds is thus recommended only if we have very good calibration coverage at
       the edge of the imager.

OPTIONS

   POSITIONAL ARGUMENTS
         model                 Input camera model. If "-' is given, we read standard
                               input
         {x,y}                 Optional 'x' or 'y': which surface we're looking at.
                               MUST be omitted if --vectorfield. If omitted and not
                               --vectorfield: we plot the magnitude of the
                               (deltaux,deltauy) corretion vector

   OPTIONAL ARGUMENTS
         -h, --help            show this help message and exit
         --gridn GRIDN GRIDN   The density of the plotted grid. By default we use a
                               60x40 grid
         --vectorfield         Display the spline correction as a vector field. if
                               --vectorfield: the 'xy' argument MUST be omitted
         --vectorscale VECTORSCALE
                               If plotting a vector field, scale all the vectors by
                               this factor. Useful to improve legibility if the
                               vectors are too small to see
         --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
         --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
         --imager-domain       By default, this produces a visualization in the
                               domain of the spline-index (normalized stereographic
                               coordinates). Sometimes it's more informative to look
                               at the imager domain instead, by passing this option
         --show-imager-bounds  By default we communicate the usable projection region
                               to the user by displaying the valid-intrinsics region.
                               This isn't available in all models. To fall back on
                               the boundary of the full imager, pass --show-imager-
                               bounds. In the usual case of incomplete calibration-
                               time coverage at the edges, this results in a very
                               unrealistic representation of reality. Leaving this at
                               the default is recommended
         --observations        If given, I show where the chessboard corners were
                               observed at calibration time. This is useful to
                               evaluate the reported unprojectable regions.

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