1 <!-- Copyright (c) 2015, NVIDIA CORPORATION. All rights reserved. -->
3 @defgroup nvx_sample_stereo_matching Stereo Matching Demo App
4 @brief Stereo Matching Demo user guide.
8 <a name=
"Introduction">
11 `nvx_demo_stereo_matching` is a simple stereo matching demo that uses
12 Semi-Global Matching algorithm to evaluate disparity. It performs color
13 conversion and downscaling prior to evaluating stereo
for better quality and
14 performance. The input images are expected to be undistorted and rectified.
15 For more information on how to rectify the stereo pair, see [OpenCV
's Stereo Rectifation tutorial](http://docs.opencv.org/2.4/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html#stereorectify).
17 ## Pipeline Details ##
19 The pipeline can be illustrated by the following diagram:
21 (left frame) (right frame)
23 [ScaleImage] (down) [ScaleImage] (down)
25 [ColorConvert] (to gray) [ColorConvert] (to gray)
27 +---------+ +----------+
31 [ConvertDepth] (to 8-bit)
39 In the second step, the demo converts the disparity image into color output using
40 the following pipeline:
44 +------------------+------------------+
46 [TableLookup] [TableLookup] [TableLookup]
48 (Red Channel) (Blue Channel) (Green Channel)
50 +------------------+------------------+
56 Color output is created using linear conversion of disparity values from [0..ndisp)
57 interval into the HSV color space, where the smallest disparity (far objects)
58 corresponds to [H=240, S=1, V=1] (blue color) and the largest disparity (near
59 objects) corresponds to [H=0, S=1, V=1] (red color). The resulting HSV value
60 is then converted to RGB color space for visualization.
62 ## Installation and Usage ##
64 `nvx_demo_stereo_matching` is installed in the following directory:
66 /usr/share/visionworks/sources/demos/stereo_matching
68 For the steps to build sample applications, see the @ref nvx_samples_and_demos
72 ## Executing the Stereo Matching Demo ##
74 ./nvx_demo_stereo_matching [options]
76 ### Command Line Options ###
78 This topic provides a list of supported options and the values they consume.
80 #### \-s, \--source ####
81 - Parameter: [input URI]
82 - Description: Specifies the input URI. Video, image, or image sequence must
83 contain both channels in top-bottom layout.
86 - `--source=/path/to/image` for image
87 - `--source=/path/to/video.avi` for video
88 - `--source=/path/to/image_%04d_sequence.png` for image sequence
90 @note The V4L platform has a permissions issue. The hardware decoder is used and
91 the demo must be executed with super user permissions, i.e., with `sudo`.
93 #### \-c, \--config ####
94 - Parameter: [config file path]
95 - Description: Specifies the path to the configuration file.
97 The file contains the parameters of the stereo matching algorithm.
100 - Parameter: [integer value greater or equal to zero and less or equal
102 - Description: Minimum and maximum disparity values. Defaults are 0 and
103 64. Maximum disparity must be divisible by 4.
107 - Parameter: [integer value greater than or equal to zero and less than
109 - Description: Penalty parameters for SGBM algorithm. The larger the values,
110 the smoother the disparity. P1 is the penalty on the disparity change
111 by plus or minus 1 between neighbor pixels; P2 - by more than 1. The
112 algorithm requires P2 > P1. Defaults are 8 and 109.
115 - Parameter: [odd integer greater than zero and less than or equal to 31]
116 - Description: The size of the SAD window. Default is 5.
119 - Parameter: [odd integer in range 15 to 95]
120 - Description: Truncation value for pre-filtering algorithm. It first computes
121 x-derivative at each pixel and clips its value to [-bt_clip_value, bt_clip_value]
122 interval. Default is 31.
125 - Parameter: [integer value greater than or equal to zero]
126 - Description: Maximum allowed difference (in integer pixel units) in the
127 left-right disparity check. Default is 32000.
129 - **uniqueness_ratio**
130 - Parameter: [integer value greater than or equal to zero and less than
132 - Description: Margin in percents by which the best (minimum) computed
133 cost function value must beat the second best value to consider the
137 - Parameter: [integer value in range 0 to 255]
138 - Description: Bit-mask for enabling any combination of 8 possible directions.
139 The lowest bit corresponds to "from-left-to-right" direction
140 (NVX_SCANLINE_LEFT_RIGHT enumeration value). The second lowest bit corresponds
141 to "from-top-left-to-bottom-right" direction (NVX_SCANLINE_TOP_LEFT_BOTTOM_RIGHT
142 enumeration value), and so on. Default is 255.
146 `./nvx_demo_stereo_matching --config=/path/to/config_file.ini`
148 - If the argument is omitted, the default config file will be used.
150 #### -h, \--help ####
151 - Description: Prints the help message.
153 ### Operational Keys ###
154 - Use `S` to switch between displaying the original frame, disparity image, and color output.
155 - Use `Space` to pause/resume the demo.
156 - Use `ESC` to close the demo.