.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "MRCAL 1" .TH MRCAL 1 2024-02-04 "mrcal 2.3-4.1~exp1" "mrcal: camera projection, calibration toolkit" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME mrcal\-stereo \- Stereo processing .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 10 \& $ mrcal\-stereo \e \& \-\-az\-fov\-deg 90 \e \& \-\-el\-fov\-deg 90 \e \& \-\-sgbm\-block\-size 5 \e \& \-\-sgbm\-p1 600 \e \& \-\-sgbm\-p2 2400 \e \& \-\-sgbm\-uniqueness\-ratio 5 \e \& \-\-sgbm\-disp12\-max\-diff 1 \e \& \-\-sgbm\-speckle\-window\-size 200 \e \& \-\-sgbm\-speckle\-range 2 \e \& \-\-outdir /tmp \e \& left.cameramodel right.cameramodel \e \& left.jpg right.jpg \& \& Processing left.jpg and right.jpg \& Wrote \*(Aq/tmp/rectified0.cameramodel\*(Aq \& Wrote \*(Aq/tmp/rectified1.cameramodel\*(Aq \& Wrote \*(Aq/tmp/left\-rectified.png\*(Aq \& Wrote \*(Aq/tmp/right\-rectified.png\*(Aq \& Wrote \*(Aq/tmp/left\-disparity.png\*(Aq \& Wrote \*(Aq/tmp/left\-range.png\*(Aq \& Wrote \*(Aq/tmp/points\-cam0.vnl\*(Aq .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" Given a pair of calibrated cameras and pairs of images captured by these cameras, this tool runs the whole stereo processing sequence to produce disparity and range images and a point cloud array. .PP mrcal functions are used to construct the rectified system. Currently only the OpenCV SGBM routine is available to perform stereo matching, but more .SH OPTIONS .IX Header "OPTIONS" .SS "OPTIONAL ARGUMENTS" .IX Subsection "OPTIONAL ARGUMENTS" will be made available with time. .SS "OPTIONAL ARGUMENTS" .IX Subsection "OPTIONAL ARGUMENTS" .Vb 10 \& \-h, \-\-help show this help message and exit \& \-\-az\-fov\-deg AZ_FOV_DEG \& The field of view in the azimuth direction, in \& degrees. There\*(Aqs no auto\-detection at this time, so \& this argument is required (unless \-\-already\-rectified) \& \-\-el\-fov\-deg EL_FOV_DEG \& The field of view in the elevation direction, in \& degrees. There\*(Aqs no auto\-detection at this time, so \& this argument is required (unless \-\-already\-rectified) \& \-\-az0\-deg AZ0_DEG The azimuth center of the rectified images. "0" means \& "the horizontal center of the rectified system is the \& mean forward direction of the two cameras projected to \& lie perpendicular to the baseline". If omitted, we \& align the center of the rectified system with the \& center of the two cameras\*(Aq views \& \-\-el0\-deg EL0_DEG The elevation center of the rectified system. "0" \& means "the vertical center of the rectified system \& lies along the mean forward direction of the two \& cameras" Defaults to 0. \& \-\-pixels\-per\-deg PIXELS_PER_DEG \& The resolution of the rectified images. This is either \& a whitespace\-less, comma\-separated list of two values \& (az,el) or a single value to be applied to both axes. \& If a resolution of >0 is requested, the value is used \& as is. If a resolution of <0 is requested, we use this \& as a scale factor on the resolution of the first input \& image. For instance, to downsample by a factor of 2, \& pass \-0.5. By default, we use \-1 for both axes: the \& resolution of the input image at the center of the \& rectified system. \& \-\-rectification {LENSMODEL_PINHOLE,LENSMODEL_LATLON} \& The lens model to use for rectification. Currently two \& models are supported: LENSMODEL_LATLON (the default) \& and LENSMODEL_PINHOLE. Pinhole stereo works badly for \& wide lenses and suffers from varying angular \& resolution across the image. LENSMODEL_LATLON \& rectification uses a transverse equirectangular \& projection, and does not suffer from these effects. It \& is thus the recommended model \& \-\-already\-rectified If given, assume the given models and images already \& represent a rectified system. This will be checked, \& and the models will be used as\-is if the checks pass \& \-\-clahe If given, apply CLAHE equalization to the images prior \& to the stereo matching. If \-\-already\-rectified, we \& still apply this equalization, if requested. Requires \& \-\-force\-grayscale \& \-\-force\-grayscale If given, convert the images to grayscale prior to \& doing anything else with them. By default, read the \& images in their default format, and pass those \& posibly\-color images to all the processing steps. \& Required if \-\-clahe \& \-\-viz {geometry,stereo} \& If given, we visualize either the rectified geometry \& or the stereo results. If \-\-viz geometry: we construct \& the rectified stereo system, but instead of continuing \& with the stereo processing, we render the geometry of \& the stereo world; the images are ignored in this mode. \& If \-\-viz stereo: we launch an interactive graphical \& tool to examine the rectification and stereo matching \& results; the Fl_Gl_Image_Widget Python library must be \& available \& \-\-axis\-scale AXIS_SCALE \& Used if \-\-viz geometry. Scale for the camera axes. By \& default a reasonable default is chosen (see \& mrcal.show_geometry() for the logic) \& \-\-title TITLE Used if \-\-viz geometry. Title string for the plot \& \-\-hardcopy HARDCOPY Used if \-\-viz geometry. Write the output to disk, \& instead of making an interactive plot. The output \& filename is given in the option \& \-\-terminal TERMINAL Used if \-\-viz geometry. The gnuplotlib terminal. The \& default is almost always right, so most people don\*(Aqt \& need this option \& \-\-set SET Used if \-\-viz geometry. Extra \*(Aqset\*(Aq directives to pass \& to gnuplotlib. May be given multiple times \& \-\-unset UNSET Used if \-\-viz geometry. Extra \*(Aqunset\*(Aq directives to \& pass to gnuplotlib. May be given multiple times \& \-\-force, \-f By default existing files are not overwritten. Pass \& \-\-force to overwrite them without complaint \& \-\-outdir OUTDIR Directory to write the output into. If omitted, we \& user the current directory \& \-\-tag TAG String to use in the output filenames. Non\-specific \& output filenames if omitted \& \-\-disparity\-range DISPARITY_RANGE DISPARITY_RANGE \& The disparity limits to use in the search, in pixels. \& Two integers are expected: MIN_DISPARITY \& MAX_DISPARITY. Completely arbitrarily, we default to \& MIN_DISPARITY=0 and MAX_DISPARITY=100 \& \-\-valid\-intrinsics\-region \& If given, annotate the image with its valid\-intrinsics \& region. This will end up in the rectified images, and \& make it clear where successful matching shouldn\*(Aqt be \& expected \& \-\-range\-image\-limits RANGE_IMAGE_LIMITS RANGE_IMAGE_LIMITS \& The nearest,furthest range to encode in the range \& image. Defaults to 1,1000, arbitrarily \& \-\-stereo\-matcher {SGBM,ELAS} \& The stereo\-matching method. By default we use the \& "SGBM" method from OpenCV. libelas isn\*(Aqt always \& available, and must be enabled at compile\-time by \& setting USE_LIBELAS=1 during the build \& \-\-sgbm\-block\-size SGBM_BLOCK_SIZE \& A parameter for the OpenCV SGBM matcher. If omitted, 5 \& is used \& \-\-sgbm\-p1 SGBM_P1 A parameter for the OpenCV SGBM matcher. If omitted, \& the OpenCV default is used \& \-\-sgbm\-p2 SGBM_P2 A parameter for the OpenCV SGBM matcher. If omitted, \& the OpenCV default is used \& \-\-sgbm\-disp12\-max\-diff SGBM_DISP12_MAX_DIFF \& A parameter for the OpenCV SGBM matcher. If omitted, \& the OpenCV default is used \& \-\-sgbm\-pre\-filter\-cap SGBM_PRE_FILTER_CAP \& A parameter for the OpenCV SGBM matcher. If omitted, \& the OpenCV default is used \& \-\-sgbm\-uniqueness\-ratio SGBM_UNIQUENESS_RATIO \& A parameter for the OpenCV SGBM matcher. If omitted, \& the OpenCV default is used \& \-\-sgbm\-speckle\-window\-size SGBM_SPECKLE_WINDOW_SIZE \& A parameter for the OpenCV SGBM matcher. If omitted, \& the OpenCV default is used \& \-\-sgbm\-speckle\-range SGBM_SPECKLE_RANGE \& A parameter for the OpenCV SGBM matcher. If omitted, \& the OpenCV default is used \& \-\-sgbm\-mode {SGBM,HH,HH4,SGBM_3WAY} \& A parameter for the OpenCV SGBM matcher. Must be one \& of (\*(AqSGBM\*(Aq,\*(AqHH\*(Aq,\*(AqHH4\*(Aq,\*(AqSGBM_3WAY\*(Aq). If omitted, the \& OpenCV default (SGBM) is used \& \-\-write\-point\-cloud If given, we write out the point cloud as a .ply file. \& Each point is reported in the reference coordinate \& system, colored with the nearest\-neighbor color of the \& camera0 image. This is disabled by default because \& this is potentially a very large file \& \-\-jobs JOBS, \-j JOBS parallelize the processing JOBS\-ways. This is like \& Make, except you\*(Aqre required to explicitly specify a \& job count. This applies when processing multiple sets \& of images with the same set of models .Ve .SH REPOSITORY .IX Header "REPOSITORY" .SH AUTHOR .IX Header "AUTHOR" Dima Kogan, \f(CW\*(C`\*(C'\fR .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (c) 2017\-2021 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. All rights reserved. .PP Licensed under the Apache License, Version 2.0 (the "License"); You may obtain a copy of the License at .PP .Vb 1 \& http://www.apache.org/licenses/LICENSE\-2.0 .Ve