MRCAL(1)

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

💖 MRCAL(1) — mrcal: camera projection, calibration toolkit 💖

okay bestie, sit DOWN, because this is mrcal-show-distortion-off-pinhole from the mrcal toolkit, and it's literally about to show you what your lens model is actually doing. no cap. 🦋

✨ NAME ✨

mrcal-show-distortion-off-pinhole — visualize the behavior of a lens model 👑 (yes that's the whole name, she's long but she's worth it)

🌈 SYNOPSIS 🌈

$ mrcal-show-distortion-off-pinhole --vectorfield left.cameramodel

... a plot pops up showing the vector field of the difference from a pinhole
projection

🎀 DESCRIPTION 🎀

So like, this tool exists to examine how a lens model behaves. That's the whole vibe. Depending on the model, the vectors could be very large or very small, and if they're tiny and sad you can scale them by passing --vectorscale s. By default we sample in a 60x40 grid, but bestie, you can control that spacing by passing --gridn w h. 💅

By default we render a heat map</> of the lens effects. You can also see the vectorfield by passing in --vectorfield. Or, alternate flavor, you can see the radial distortion curve by passing --radial. Pick your fighter. ✨

This tool treats a pinhole projection as a baseline, and visualizes deviations from this baseline. So wide lenses will have a LOT of reported "distortion". Which means pinhole models aren't a good baseline, lowkey. BUT — and here's the plot twist — pretty much every non-mrcal tool in common use treats lenses as pinhole+distortion, and that's exactly what makes this visualization useful. iykyk. 🫶

The plots produced with --radial show the magnitude of the radial distortion as a function of the distance to the center. For opencv models the radial distortion is plotted directly from the projection equations: these represent radial distortion explicitly. For other models, we empirically sample the imager from the optical center given by intrinsics[2:4] to the 4 corners and the 4 centers of the imager edges. 📐

Note that the splined models often shift the projection center from intrinsics[2:4], causing unnatural-looking curves near the center. This isn't a a bug: intrinsics[2:4] isn't really in the center, which isn't a problem for anything except this visualization. 💀 (not me getting jump-scared by a curve that was fine the whole time)

✨ OPTIONS ✨

🌸 POSITIONAL ARGUMENTS 🌸

  • model — Input camera model. If - is given, we read standard input. (yes queen, piped-in models are valid)

🦋 OPTIONAL ARGUMENTS 🦋

  • -h, --help — show this help message and exit
  • --gridn GRIDN GRIDN — How densely we should sample the imager. By default we report a 60x40 grid
  • --vectorscale VECTORSCALE — Scale the vectors by this factor. Default is 1.0 (report the truth), but this is often too small to see 👀
  • --radial — Show the radial distortion scale factor instead of a colormap/vectorfield
  • --vectorfield — Plot the diff as a vector field instead of as a heat map. The vector field contains more information (magnitude AND direction), but is less clear at a glance. (ngl it's giving "more data, more confusion" and we respect it)
  • --show-fisheye-projections — Applies to radial plots only. if given, the radial plots include the behavior of common fisheye projections, in addition to the behavior of THIS lens 🐟
  • --cbmax CBMAX — Maximum range of the colorbar
  • --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 pass to gnuplotlib. May be given multiple times
  • --unset UNSET — Extra unset directives to pass to gnuplotlib. May be given multiple times

🌟 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're officially calibrated 💖✨ this was mrcal 2.5.2-4build1, dated 2026-03-20, and it's still MRCAL(1) energy through and through. go plot something iconic. 🎀🦋🌸

📦 where this page comes from