MRCAL(1)

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

💖 MRCAL(1) — mrcal-triangulate 💖

okay bestie, welcome to the mrcal manual — camera projection and calibration toolkit energy, but make it a group chat. this page is mrcal-triangulate, and it's giving "triangulate a feature in a pair of images to report a range". 🎀

✨ NAME ✨

mrcal-triangulate — triangulate a feature in a pair of images to report a range 🦋

🌸 SYNOPSIS 🌸

  $ mrcal-triangulate
      --range-estimate 870
      left.cameramodel right.cameramodel
      left.jpg right.jpg
      1234 2234

  ## Feature [1234., 2234.] in the left image corresponds to [2917.9 1772.6] at 870.0m
  ## Feature match found at [2916.51891391 1771.86593517]
  ## q1 - q1_perfect_at_range = [-1.43873946 -0.76196924]
  ## Range: 677.699 m (error: -192.301 m)
  ## Reprojection error between triangulated point and q0: [5.62522473e-10 3.59364094e-09]pixels
  ## Observed-pixel range sensitivity: 103.641m/pixel (q1). Worst direction: [1. 0.]. Linearized correction: 1.855 pixels
  ## Calibration yaw sensitivity: -3760.702m/deg. Linearized correction: -0.051 degrees of yaw
  ## Calibration pitch sensitivity: 0.059m/deg.
  ## Calibration translation sensitivity: 319.484m/m. Worst direction: [1 0 0].
  ## Linearized correction: 0.602 meters of translation
  ## Optimized yaw correction   = -0.03983 degrees
  ## Optimized pitch correction = 0.03255 degrees
  ## Optimized relative yaw (1 <- 0): -1.40137 degrees

no cap, that's the whole vibe right there. 👑

🌈 DESCRIPTION 🌈

So here's the tea: you hand this thing a pair of images, a pair of camera models, and a feature coordinate in the first image. It goes and finds the matching feature in the second image, then reports the range. It's basically stereo processing but for a single pixel — except it spills so much more diagnostic info than your average stereo tool does. it's giving "overachiever" and we love that for it. 💅

It's useful when you wanna evaluate ranging results. periodt. 🫶

🎀 OPTIONS 🎀

🍓 POSITIONAL ARGUMENTS

  • models — the camera models for the images. Both intrinsics and extrinsics get used here, bestie, so bring your whole self ✨
  • images_and_features — the images and/or feature pixel coordinates used for the triangulation. This is either IMAGE0 IMAGE1 FEATURE0X FEATURE0Y or FEATURE0X FEATURE0Y FEATURE1X FEATURE1Y. If you give images, then the given pixel is treated as a feature in image0, and we go searching for the corresponding feature in image1. 🕵️‍♀️

🧚 OPTIONAL ARGUMENTS

  • -h, --help — show this help message and exit. classic. iconic. 💖
  • --make-corrected-model1 — if you give this, we assume --range-estimate is correct, and we output to standard output a rotated camera1 that produces this range. slay 🔥
  • --template-size TEMPLATE_SIZE TEMPLATE_SIZE — the size of the template used for feature matching, in pixel coordinates of the second image. Two arguments required: width height. This gets passed straight to mrcal.match_feature(). Default is 13x13. 🎀
  • --search-radius SEARCH_RADIUS — how far the feature-matching routine should search, in pixel coordinates of the second image. Make it bigger if your range estimate is bad — especially at near ranges. Passed directly to mrcal.match_feature(). We default to 20 pixels. 🔍
  • --range-estimate RANGE_ESTIMATE — initial estimate of the range of the observed feature. Used as the initial guess in the feature matching. If you omit it, I pick 50m, completely arbitrarily. (yes, really, it's a whole vibe. 🙈)
  • --plane-n PLANE_N PLANE_N PLANE_N — if given, we assume we're looking at a plane in space, and take that into account when matching the template. The normal vector to this plane goes here, in camera-0 coordinates. The normal does not need to be normalized; any scaling is compensated in planed. The plane is all points p such that inner(p,planen) = planed. 📐
  • --plane-d PLANE_D — if given, we assume we're looking at a plane in space, and take that into account when matching the template. This is the distance-along-the-normal to the plane, in from-camera coordinates. The plane is all points p such that inner(p,planen) = planed. 🌸
  • --q-calibration-stdev Q_CALIBRATION_STDEV — the uncertainty of the point observations at calibration time. If given, we report the analytically-computed effects of this noise. If a value <0 is passed in, we infer the calibration-time noise from the optimal calibration-time residuals. 😌
  • --q-observation-stdev Q_OBSERVATION_STDEV — the uncertainty of the point observations at observation time. If given, we report the analytically-computed effects of this noise. ✨
  • --q-observation-stdev-correlation Q_OBSERVATION_STDEV_CORRELATION — by default, the noise in the observation-time pixel observations is assumed independent. Which is not entirely realistic, ngl: observations of the same feature in multiple cameras come from an imager correlation operation, so they'll have some amount of correlation. If given, this argument says how much correlation. It's a value in [0,1] scaling the stdev. 0 means "independent" (the default). 1.0 means "100% correlated". 🫶
  • --stabilize-coords, --stabilize — if we're propagating calibration-time noise (--q-calibration-stdev != 0), we report the uncertainty ellipse in a stabilized coordinate system, compensating for the camera-0 coord system motion. 💅
  • --method {geometric,lindstrom,leecivera-l1,leecivera-linf,leecivera-mid2,leecivera-wmid2} — the triangulation method. By default we use the "Mid2" method from Lee-Civera's paper. 📚
  • --corr-floor CORR_FLOOR — used to reject mrcal.match_feature() results. Default is 0.9: accept only very good matches. A lower threshold may still give you usable matches, but do interactively check the feature-matcher results by passing "--viz match". > bestie please actually check them, don't just trust it 🙏
  • --viz {match,uncertainty} — if given, we visualize either the feature-matcher results ("--viz match") or the uncertainty ellipse(s) ("--viz uncertainty"). By default this produces an interactive gnuplot window. The feature-match visualization shows 2 overlaid images: the larger image being searched, and the transformed template placed at its best-fitting location. Each individual image can be hidden/shown by clicking on its legend in the top-right of the plot. It's generally most useful to show/hide the template to visually verify the resulting alignment. 👀
  • --title TITLE — title string for the --viz plot. Overrides the default title. Exclusive with --extratitle. 🌟
  • --extratitle EXTRATITLE — additional string for the --viz plot to append to the default title. Exclusive with --title. 🌟
  • --hardcopy HARDCOPY — write the --viz output to disk, instead of an interactive plot. 📸
  • --terminal TERMINAL — the gnuplotlib terminal used in --viz. The default is good almost always, so most people don't need this option. 😎
  • --set SET — extra set directives to gnuplotlib for --viz. Can be given multiple times. 🔁
  • --unset UNSET — extra unset directives to gnuplotlib --viz. Can be given multiple times. 🔁
  • --clahe — if given, apply CLAHE equalization to the images prior to the matching. 🌈

🦋 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

and that's the whole page, bestie!! this is mrcal version 2.5.2-4build1, dated 2026-03-20, and it's MRCAL(1) energy all the way through. go triangulate something iconic. 💖✨🎀🦋

📦 where this page comes from