Provided by: mrcal_2.4.1-4build1_amd64 
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-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
mrcal 2.4.1-4build1 2025-03-04 MRCAL(1)