VisionWorks Toolkit Reference

September 29, 2015 | 1.0 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 
16 The pipeline can be illustrated by the following diagram:
17 
18  (left frame) (right frame)
19  | |
20  [ScaleImage] (down) [ScaleImage] (down)
21  | |
22  [ColorConvert] (to gray) [ColorConvert] (to gray)
23  | |
24  +---------+ +----------+
25  | |
26  [SemiGlobalMatching]
27  |
28  [ConvertDepth] (to 8-bit)
29  |
30  [ScaleImage] (up)
31  |
32  [Multiply]
33  |
34  (disparity image)
35 
36 In the second step, the demo converts the disparity image into color output using the following pipeline:
37 
38  (disparity image)
39  |
40  +------------------+------------------+
41  | | |
42  [TableLookup] [TableLookup] [TableLookup]
43  | | |
44  (Red Channel) (Blue Channel) (Green Channel)
45  | | |
46  +------------------+------------------+
47  |
48  [ChannelCombine]
49  |
50  (output image)
51 
52 Color output is created using linear conversion of disparity values from [0..ndisp) interval into the HSV color space,
53 where the smallest disparity (far objects) corresponds to [H=240, S=1, V=1] (blue color) and the
54 largest disparity (near objects) corresponds to [H=0, S=1, V=1] (red color).
55 The resulting HSV value is then converted to RGB color space for visualization.
56 
57 `nvx_demo_stereo_matching` is installed in the following directory:
58 
59  /usr/share/visionworks/sources/demos/stereo_matching
60 
61 For the steps to build sample applications, see the @ref nvx_samples_and_demos
62 section for your OS.
63 
64 <a name="Executing">
65 ## Executing the Stereo Matching Demo ##
66 
67  ./nvx_demo_stereo_matching [options]
68 
69 ### Command Line Options ###
70 
71 This topic provides a list of supported options and the values they consume.
72 
73 #### \-s, \--source ####
74 - Parameter: [input URI]
75 - Description: Specifies the input URI. Video, image, or image sequence must contain both
76  channels in top-bottom layout.
77 - Usage:
78 
79  - `--source=/path/to/image` for image
80  - `--source=/path/to/video.avi` for video
81  - `--source=/path/to/image_%04d_sequence.png` for image sequence
82 
83 @note On Vibrante V3Le, V4L platforms hardware accelerated video playback is supported for H.264
84 elementary streams only.
85 
86 @note The V4L platform has a permissions issue. If input data are an H.264 elementary stream, hardware decoder
87 is used and sample must be executed with super user permissions, i.e., with `sudo`.
88 
89 #### \-c, \--config ####
90 - Parameter: [config file path]
91 - Description: Specifies the path to the configuration file.
92 
93  The file contains the parameters of the stereo matching algorithm.
94  - **min_disparity**
95  - **max_disparity**
96  - Parameter: [integer value greater or equal to zero and less or equal to 256]
97  - Description: Minimum and maximum disparity values. Defaults are 0 and 64. Maximum disparity must be
98  divisible by 4.
99 
100  - **P1**
101  - **P2**
102  - Parameter: [integer value greater than or equal to zero and less than or equal to 256]
103  - Description: Penalty parameters for SGBM algorithm. The larger the values are, the smoother the disparity.
104  P1 is the penalty on the disparity change by plus or minus 1 between neighbor pixels; P2 - by more than 1.
105  The algorithm requires P2 > P1. Defaults are 8 and 109.
106 
107  - **sad**
108  - Parameter: [odd integer greater than zero and less than or equal to 31]
109  - Description: The size of the SAD window. Default is 5.
110 
111  - **bt_clip_value**
112  - Parameter: [odd integer in range 15 to 95]
113  - Description: Truncation value for pre-filtering algorithm. It first computes x-derivative at each pixel and clips
114  its value to [-bt_clip_value, bt_clip_value] interval. Default is 31.
115 
116  - **max_diff**
117  - Parameter: [integer value greater than or equal to zero]
118  - Description: Maximum allowed difference (in integer pixel units) in the left-right disparity check.
119  Default is 32000.
120 
121  - **uniqueness_ratio**
122  - Parameter: [integer value greater than or equal to zero and less than or equal to 100]
123  - Description: Margin in percents by which the best (minimum) computed cost function value must beat the second
124  best value to consider the found match correct.
125 
126  - **scanlines_mask**
127  - Parameter: [integer value in range 0 to 255]
128  - Description: Bit-mask for enabling any combination of 8 possible directions. The lowest bit corresponds to
129  "from-left-to-right" direction (NVX_SCANLINE_LEFT_RIGHT enumeration value). The second lowest bit corresponds to
130  "from-top-left-to-bottom-right" direction (NVX_SCANLINE_TOP_LEFT_BOTTOM_RIGHT enumeration value), and so on.
131  Default is 255.
132 
133 - Usage:
134 
135  `./nvx_demo_stereo_matching --config=/path/to/config_file.ini`
136 
137 - If the argument is omitted, the default config file will be used.
138 
139 #### -h, \--help ####
140 - Description: Prints the help message.
141 
142 ### Operational Keys ###
143 - Use `S` to switch between displaying the original frame, disparity image, and color output.
144 - Use `Space` to pause/resume the demo.
145 - Use `ESC` to close the demo.
146 
147 @}
aggregate cost from left to right diagonally starting from the top.
Definition: nvx.h:732
aggregate cost from left to right horizontally.
Definition: nvx.h:731