MRCAL(1)

📦
version 2.5.2 · 6 versions
, in ubuntu resolute, ubuntu stonking

💖 MRCAL-SHOW-RESIDUALS — bestie edition 💖

okay so you're in the mrcal(1) manual, specifically the page for mrcal-show-residuals, and honestly? this one is a whole vibe. it draws pictures of how wrong your calibration is. yes queen, let's look at the mistakes. 🔥

✨ 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

like literally just that. a plot pops up. she's showing you the residuals. no cap.

🌸 DESCRIPTION 🌸

so this tool has several different modes, and you pick one with commandline arguments. and bestie, listen: exactly one of these mode options must be given. not zero, not two. one. periodt. 💅

  • --vectorfield — visualize the optimized residuals as a vector field. each vector runs from the observed chessboard corner to its prediction at the optimal solution. it's giving arrows. it's giving direction. 🏹
  • --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. ngl, she's easier on the eyes. 👀
  • --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. so if your plot looks like a coordinated friend group all wearing the same color? that's a bias, bestie. 🚩
  • --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. quick. dirty. iconic. 💀
  • --histogram — visualize the distribution of the optimized residuals. we display a histogram of residuals and overlay it with an idealized gaussian distribution. cute little bell curve moment 🔔✨

👑 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. so like, she's reading from the whole group chat, not just the one camera you @'d. 🙈

🌈 OPTIONAL ARGUMENTS 🌈

  • -h, --help — show this help message and exit. the classic. the goat. 🐐
  • --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. she said "just me" and honestly, valid. 💅
  • --valid-intrinsics-region — if given, I overlay the valid-intrinsics regions onto the plot. applies to all the modes except --histogram. (yes the manpage says "I". the author is speaking in first person. main character energy, we love to see it. 👑)
  • --gridn GRIDN GRIDN — how densely we should bin the imager. by default we use a 20x14 grid of bins. applies only if --regional. so many little boxes 🎁
  • --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. zoom zoom 🔍
  • --cbmax CBMAX — maximum range of the colorbar used in --vectorfield, --magnitudes. if omitted, we autoscale. she'll figure it out herself.
  • --title TITLE — title string for the plot. overrides the default title. exclusive with --extratitle. pick a lane bestie, you can't have both 🚫
  • --extratitle EXTRATITLE — additional string for the plot to append to the default title. exclusive with --title. see above. one or the other. periodt.
  • --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. so she's saving the pics instead of showing them live 📸
  • --terminal TERMINAL — gnuplotlib terminal. the default is good almost always, so most people don't need this option. fr fr, you probably don't need this one. leave it alone. 🫶
  • --set SET — extra 'set' directives to gnuplotlib. can be given multiple times. stack 'em up ⭐
  • --unset UNSET — extra 'unset' directives to gnuplotlib. can be given multiple times. the opposite of the above, and equally stackable 💜

🔥 REPOSITORY 🔥

<https://www.github.com/dkogan/mrcal>

🧚 AUTHOR 🧚

Dima Kogan, "<dima@secretsauce.net>"

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
okay that's the whole page bestie, you got this, go plot some residuals and slay ✨

and that's a wrap!! this was mrcal 2.5.2-4build1, dated 2026-03-20, from the MRCAL(1) manual. mwah, bye, drink water 💖🎀🦋

📦 where this page comes from