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¶

  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

  -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-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