VisionWorks Toolkit Reference

December 18, 2015 | 1.2 Release

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
stable/stereo_matching/stereo_matching_user_guide.md
Go to the documentation of this file.
1 <!-- Copyright (c) 2015, NVIDIA CORPORATION. All rights reserved. -->
2 
3 @defgroup nvx_sample_stereo_matching Stereo Matching Demo App
4 @brief Stereo Matching Demo user guide.
5 @ingroup nvx_demos
6 @{
7 
8 <a name="Introduction">
9 ## Introduction ##
10 
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).
16 
17 ## Pipeline Details ##
18 
19 The pipeline can be illustrated by the following diagram:
20 
21  (left frame) (right frame)
22  | |
23  [ScaleImage] (down) [ScaleImage] (down)
24  | |
25  [ColorConvert] (to gray) [ColorConvert] (to gray)
26  | |
27  +---------+ +----------+
28  | |
29  [SemiGlobalMatching]
30  |
31  [ConvertDepth] (to 8-bit)
32  |
33  [ScaleImage] (up)
34  |
35  [Multiply]
36  |
37  (disparity image)
38 
39 In the second step, the demo converts the disparity image into color output using
40 the following pipeline:
41 
42  (disparity image)
43  |
44  +------------------+------------------+
45  | | |
46  [TableLookup] [TableLookup] [TableLookup]
47  | | |
48  (Red Channel) (Blue Channel) (Green Channel)
49  | | |
50  +------------------+------------------+
51  |
52  [ChannelCombine]
53  |
54  (output image)
55 
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.
61 
62 ## Installation and Usage ##
63 
64 `nvx_demo_stereo_matching` is installed in the following directory:
65 
66  /usr/share/visionworks/sources/demos/stereo_matching
67 
68 For the steps to build sample applications, see the @ref nvx_samples_and_demos
69 section for your OS.
70 
71 <a name="Executing">
72 ## Executing the Stereo Matching Demo ##
73 
74  ./nvx_demo_stereo_matching [options]
75 
76 ### Command Line Options ###
77 
78 This topic provides a list of supported options and the values they consume.
79 
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.
84 - Usage:
85 
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
89 
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`.
92 
93 #### \-c, \--config ####
94 - Parameter: [config file path]
95 - Description: Specifies the path to the configuration file.
96 
97  The file contains the parameters of the stereo matching algorithm.
98  - **min_disparity**
99  - **max_disparity**
100  - Parameter: [integer value greater or equal to zero and less or equal
101  to 256]
102  - Description: Minimum and maximum disparity values. Defaults are 0 and
103  64. Maximum disparity must be divisible by 4.
104 
105  - **P1**
106  - **P2**
107  - Parameter: [integer value greater than or equal to zero and less than
108  or equal to 256]
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.
113 
114  - **sad**
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.
117 
118  - **bt_clip_value**
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.
123 
124  - **max_diff**
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.
128 
129  - **uniqueness_ratio**
130  - Parameter: [integer value greater than or equal to zero and less than
131  or equal to 100]
132  - Description: Margin in percents by which the best (minimum) computed
133  cost function value must beat the second best value to consider the
134  found match correct.
135 
136  - **scanlines_mask**
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.
143 
144 - Usage:
145 
146  `./nvx_demo_stereo_matching --config=/path/to/config_file.ini`
147 
148 - If the argument is omitted, the default config file will be used.
149 
150 #### -h, \--help ####
151 - Description: Prints the help message.
152 
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.
157 
158 @}