Ubuntu Manpage: mrcal-triangulate - 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

DESCRIPTION

       Given a pair of images, a pair of camera models and a feature coordinate in the first
       image, finds the corresponding feature in the second image, and reports the range. This is
       similar to the stereo processing of a single pixel, but reports much more diagnostic
       information than stereo tools do.

       This is useful to evaluate ranging results.

OPTIONS

POSITIONAL ARGUMENTS
models Camera models for the images. Both intrinsics and
extrinsics are used
images_and_features The images and/or feature pixes coordinates to use for
the triangulation. This is either IMAGE0 IMAGE1
FEATURE0X FEATURE0Y or FEATURE0X FEATURE0Y FEATURE1X
FEATURE1Y. If images are given, the given pixel is a
feature in image0, and we search for the corresponding
feature in image1.

OPTIONAL ARGUMENTS
-h, --help show this help message and exit
--make-corrected-model1
If given, we assume the --range-estimate is correct,
and output to standard output a rotated camera1 to
produce this range
--template-size TEMPLATE_SIZE TEMPLATE_SIZE
The size of the template used for feature matching, in
pixel coordinates of the second image. Two arguments
are required: width height. This is passed directly to
mrcal.match_feature(). We default to 13x13
--search-radius SEARCH_RADIUS
How far the feature-matching routine should search, in
pixel coordinates of the second image. This should be
larger if the range estimate is poor, especially, at
near ranges. This is passed directly to
mrcal.match_feature(). We default to 20 pixels
--range-estimate RANGE_ESTIMATE
Initial estimate of the range of the observed feature.
This is used for the initial guess in the feature-
matching. If omitted, I pick 50m, completely
arbitrarily
--plane-n PLANE_N PLANE_N PLANE_N
If given, assume that we're looking at a plane in
space, and take this into account when matching the
template. The normal vector to this plane is given
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, assume that we're looking at a plane in
space, and take this into account when matching the
template. The distance-along-the-normal to the plane,
in from-camera coordinates is given here. 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. This isn't
entirely realistic: observations of the same feature
in multiple cameras originate from an imager
correlation operation, so they will have some amount
of correlation. If given, this argument specifies how
much correlation. This is a value in [0,1] scaling the
stdev. 0 means "independent" (the default). 1.0 means
"100% correlated".
--stabilize-coords, --stabilize
If 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
This is used to reject mrcal.match_feature() results.
The default is 0.9: accept only very good matches. A
lower threshold may still result in usable matches,
but do interactively check the feature-matcher results
by passing "--viz match"
--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>"

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