VisionWorks Toolkit Reference

December 18, 2015 | 1.2 Release

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
stable/feature_tracker/feature_tracker_user_guide.md
Go to the documentation of this file.
1 <!-- Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved. -->
2 
3 @defgroup nvx_demo_feature_tracker Feature Tracker Demo App
4 @brief Feature Tracker Demo user guide.
5 @ingroup nvx_demos
6 @{
7 
8 <a name="Introduction">
9 
10 ## Introduction ##
11 
12 `nvx_demo_feature_tracker` is a simple local feature tracking demo that
13 uses the Harris or FAST feature detector to get the initial list of features and
14 tracks them using the sparse pyramidal optical flow method (Lucas-Kanade).
15 
16 In the first frame, Gaussian pyramid is created and initial points are detected
17 so that the features can be found quickly at low resolution and can also be located
18 more accurately as you go down the pyramid.
19 
20 The initial points are detected using Harris Corner detector.
21 The NVIDIA extended Harris and FAST Corner functions divide the image into cells
22 of the same size and look for corners independently in each cell. This way,
23 corners are uniformly detected across the image. These corners are the keypoints
24 that are tracked in the next frames.
25 
26  (frame)
27  |
28  [ColorConvert]
29  |
30  +-------------------+-------------------+
31  | |
32  [GaussianPyramid] [CornerTrack]
33  | |
34  (initial pyramid) (initial points)
35 
36 
37 
38 In subsequent frames, points are tracked with the Lucas-Kanade method between two pyramid images.
39 Then, corner detection is performed to restore lost points.
40 
41  (frame)
42  |
43  [ColorConvert]
44  |
45  [ChannelExtract]
46  |
47  [GaussianPyramid]
48  |
49  (previous pyramid) (current pyramid) (points to track in the previous frame)
50  | | |
51  +------------------------------+--------------------------------------+
52  |
53  [OpticalFlowPyrLK]
54  |
55  (tracked points)
56  |
57  [CornerTrack]
58  |
59  (points to track in the next frame)
60 
61 
62 @note In the figure above, the entities inside () denote data and the entities
63 inside [] denote the vision functions.
64 
65 @note Current implementation of Harris and FAST corner detectors supports input
66 frames only with total number of pixels less than \f$2^{32}\f$.
67 
68 ## Installation and Usage ##
69 
70 `nvx_demo_feature_tracker` is installed in the following directory:
71 
72  /usr/share/visionworks/sources/demos/feature_tracker
73 
74 For the steps to build sample applications, see the @ref nvx_samples_and_demos_user_guides
75 section for your OS.
76 
77 <a name="Executing">
78 ## Executing the Feature Tracker Demo ##
79 
80  ./nvx_demo_feature_tracker [options]
81 
82 ### Command Line Options ###
83 
84 This topic provides a list of supported options and the values they consume.
85 
86 #### \-s, \--source ####
87 - Parameter: [inputUri]
88 - Description: Specifies the input URI. Accepted parameters include a video,
89 an image, an image sequence (in .png, .jpg, .jpeg, .bmp, or .tiff format),
90 or camera.
91 - Usage:
92 
93  - `--source=/path/to/video.avi` for video
94  - `--source=/path/to/image.png` for image
95  - `--source=/path/to/image_%04d_sequence.png` for image sequence
96  - `--source=device://camera0` for the first camera
97  - `--source=device://camera1` for the second camera.
98 
99 @note The V4L platform has a permissions issue. The hardware decoder is used and
100 the sample must be executed with super user permissions, i.e., with `sudo`.
101 
102 
103 #### \-c, \--config ####
104 - Parameter: [Config file path]
105 - Description: Specifies the path to the configuration file. The file contains the
106  parameters of the algorithm stored in key=value format.
107 
108  This file contains the following parameters:
109 
110  - **pyr_levels**
111  - Parameter: [integer value greater than or equal to 1 and less than or
112  equal to 8]
113  - Description: The number of levels in Gaussian pyramid. Default is 6.
114 
115  - **lk_num_iters**
116  - Parameter: [integer value greater than or equal to 1 and less than or
117  equal to 100]
118  - Description: The number of iterations in the Lucas-Kanade method. Default
119  is 5.
120 
121  - **lk_win_size**
122  - Parameter: [integer value greater than or equal to 3 and less than or
123  equal to 32]
124  - Description: The window size in the Lucas-Kanade method. Default is 6.
125 
126  - **array_capacity**
127  - Parameter: [integer value greater than or equal to 1]
128  - Description: The capacity of points array. Default is 2000.
129 
130  - **detector_cell_size**
131  - Parameter: [integer value greater than or equal to 1]
132  - Description: The size of non-maximum suppression cell for corner detector.
133  Default is 18.
134 
135  - **detector**
136  - Parameter: [harris or fast]
137  - Description: The corner detector algorithm. Default is "harris".
138 
139  - **harris_k**
140  - Parameter: [floating point value greater than zero]
141  - Description: The Harris corner detector "k" parameter. Default is 0.04.
142 
143  - **harris_thresh**
144  - Parameter: [floating point value greater than zero]
145  - Description: The Harris corner detector threshold. Default is 2000.
146 
147  - **fast_type**
148  - Parameter: [9, 10, 11 or 12]
149  - Description: The type of FAST corner detector. Default is 9.
150 
151  - **fast_thresh**
152  - Parameter: [integer value less than 255]
153  - Description: The FAST corner detector threshold. Default is 25.
154 
155 - Usage:
156 
157  `./nvx_demo_feature_tracker --source=/path/to/video.avi --config=/path/to/config_file.ini`
158 
159 - If the argument is omitted, the default configuration file is used.
160 
161 #### \-m, \--mask ####
162 - Parameter: [path to image]
163 - Description: Specifies an optional mask to filter out features. This must be
164 a grayscale image that is the same size as the input source. The demo uses features
165 only in the non-zero regions on the mask. The parameter is available only if the
166 demo is built with either OpenCV or GStreamer support.
167 
168 #### \-h, \--help ####
169 - Parameter: true
170 - Description: Prints the help message.
171 
172 ### Operational Keys ###
173 - Use `Space` to pause/resume the demo.
174 - Use `ESC` to close the demo.
175 
176 @}