.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "MRCAL 1" .TH MRCAL 1 "2023-01-30" "mrcal 2.2" "mrcal: camera projection, calibration toolkit" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" mrcal\-show\-splined\-model\-correction \- Visualizes the surface represented in a splined lens model .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& $ mrcal\-show\-splined\-model\-correction cam.cameramodel \& ... a plot pops up showing the correction magnitude heatmap .Ve .SH "DESCRIPTION" .IX Header "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: .PP .Vb 1 \& L .Ve .PP At this time \s-1LENSMODEL_SPLINED_STEREOGRAPHIC\s0 is the only splined model mrcal has, so the baseline model is always \s-1LENSMODEL_STEREOGRAPHIC.\s0 .PP This tool produces a plot in the domain either of the input or the output of the spline functions. .PP By default: The plot is presented based on the spline index. With \s-1LENSMODEL_SPLINED_STEREOGRAPHIC,\s0 this is the stereographic projection u. This is the \*(L"forward\*(R" 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 .PP if \-\-imager\-domain: The plot is presented based on the pixels in the imager. This is the backward direction: the domain is the \s-1OUTPUT\s0 of the splined functions. In this view the knot layout is (possibly highly) irregular. The edge of the imager is a perfect rectangle. .PP Separate from the domain, the data can be presented in 3 different ways: .PP \&\- Magnitude heatmap. This is the default. We plot mag(deltauxy). This displays the deviation from the baseline model as a heat map. .PP \&\- Individual heatmap. Selected by passing an \*(L"xy\*(R" 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. .PP \&\- Vector field. Selected by \-\-vectorfield. Displays the correction (deltaux, deltauy) as a vector field. .PP The splined surfaces are defined by control points we call \*(L"knots\*(R". These knots are arranged in a fixed grid (defined by the model configuration) with the value at each knot set in the intrinsics vector. .PP 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. .PP 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. .SH "OPTIONS" .IX Header "OPTIONS" .SS "\s-1POSITIONAL ARGUMENTS\s0" .IX Subsection "POSITIONAL ARGUMENTS" .Vb 6 \& model Input camera model. If "\-\*(Aq is given, we read standard \& input \& {x,y} Optional \*(Aqx\*(Aq or \*(Aqy\*(Aq: which surface we\*(Aqre looking at. \& MUST be omitted if \-\-vectorfield. If omitted and not \& \-\-vectorfield: we plot the magnitude of the \& (deltaux,deltauy) corretion vector .Ve .SS "\s-1OPTIONAL ARGUMENTS\s0" .IX Subsection "OPTIONAL ARGUMENTS" .Vb 10 \& \-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 \*(Aqxy\*(Aq 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\*(Aqt need this option \& \-\-set SET Extra \*(Aqset\*(Aq directives to gnuplotlib. Can be given \& multiple times \& \-\-unset UNSET Extra \*(Aqunset\*(Aq 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\*(Aqs 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\*(Aqt 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. .Ve .SH "REPOSITORY" .IX Header "REPOSITORY" .SH "AUTHOR" .IX Header "AUTHOR" Dima Kogan, \f(CW\*(C`\*(C'\fR .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (c) 2017\-2021 California Institute of Technology (\*(L"Caltech\*(R"). U.S. Government sponsorship acknowledged. All rights reserved. .PP Licensed under the Apache License, Version 2.0 (the \*(L"License\*(R"); You may obtain a copy of the License at .PP .Vb 1 \& http://www.apache.org/licenses/LICENSE\-2.0 .Ve