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-2021 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