VisionWorks Toolkit Reference

September 29, 2015 | 1.0 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 ## Introduction ##
10 
11 `nvx_demo_feature_tracker` is a simple local feature tracking demo that
12 uses the Harris feature detector to get the initial list of features and
13 tracks them using the sparse pyramidal optical flow method (Lucas-Kanade).
14 
15 In the first frame, Gaussian pyramid is created and initial points are detected:
16 
17  (frame)
18  |
19  [ColorConvert]
20  |
21  +-------------------+-------------------+
22  | |
23  [GaussianPyramid] [HarrisTrack]
24  | |
25  (initial pyramid) (initial points)
26 
27 In subsequent frames, points are tracked with the Lucas-Kanade method between two pyramid images.
28 Then, corner detection is performed to restore lost points.
29 
30 The NVIDIA extended Harris Corner function divides the image into cells
31 of the same size and looks for corners independently in each cell. In this way,
32 corners are uniformly detected across the image. These corners are the keypoints
33 that are tracked in the next frames.
34 
35  (frame)
36  |
37  [ColorConvert]
38  |
39  [ChannelExtract]
40  |
41  [GaussianPyramid]
42  |
43  (previous pyramid) (current pyramid) (points to track in the previous frame)
44  | | |
45  +------------------------------+--------------------------------------+
46  |
47  [OpticalFlowPyrLK]
48  |
49  (tracked points)
50  |
51  [HarrisTrack]
52  |
53  (points to track in the next frame)
54 
55 @note Current implementation of Harris corner detector supports input frames only with total number of pixels
56 less than \f$2^{20}\f$.
57 
58 `nvx_demo_feature_tracker` is installed in the following directory:
59 
60  /usr/share/visionworks/sources/demos/feature_tracker
61 
62 For the steps to build sample applications, see the @ref nvx_samples_and_demos_user_guides section for your OS.
63 
64 <a name="Executing">
65 ## Executing the Feature Tracker Demo ##
66 
67  ./nvx_demo_feature_tracker [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: [inputUri]
75 - Description: Specifies the input URI. Accepted parameters include a video, an image, or an image sequence
76 (in .png, .jpg, .jpeg, .bmp, or .tiff format), or camera.
77 - Usage:
78 
79  - `--source=/path/to/video.avi` for video
80  - `--source=/path/to/image.png` for image
81  - `--source=/path/to/image_%04d_sequence.png` for image sequence
82  - `--source=device://camera0` for the first camera
83  - `--source=device://camera1` for the second camera.
84 
85 @note On Vibrante V3Le, V4L platforms hardware accelerated video playback is supported for H.264
86 elementary streams only.
87 
88 @note The V4L platform has a permissions issue. If input data are an H.264 elementary stream, hardware decoder
89 is used and sample must be executed with super user permissions, i.e., with `sudo`.
90 
91 
92 #### \-c, \--config ####
93 - Parameter: [Config file path]
94 - Description: Specifies the path to the configuration file. The file contains the parameters
95  of the algorithm stored in key=value format. Note that the config file contains information
96  on the intrinsic parameters of the camera, so using the default config file for different
97  videos may sometimes give a result with insufficient quality.
98 
99  This file contains the following parameters:
100 
101  - **pyr_levels**
102  - Parameter: [integer value greater than or equal to 1 and less than or equal to 8]
103  - Description: The number of levels in Gaussian pyramid. Default is 6.
104 
105  - **lk_num_iters**
106  - Parameter: [integer value greater than or equal to 1 and less than or equal to 100]
107  - Description: The number of iterations in the Lucas-Kanade method. Default is 5.
108 
109  - **lk_win_size**
110  - Parameter: [integer value greater than or equal to 3 and less than or equal to 32]
111  - Description: The window size in the Lucas-Kanade method. Default is 6.
112 
113  - **array_capacity**
114  - Parameter: [integer value greater than or equal to 1]
115  - Description: The capacity of points array. Default is 2000.
116 
117  - **harris_cell_size**
118  - Parameter: [integer value greater than or equal to 1]
119  - Description: The size of non-maximum suppression cell for corner detector. Default is 18.
120 
121  - **harris_k**
122  - Parameter: [floating point value greater than zero]
123  - Description: The Harris corner detector "k" parameter. Default is 0.04.
124 
125  - **harris_thresh**
126  - Parameter: [floating point value greater than zero]
127  - Description: The Harris corner detector threshold. Default is 2000.
128 
129 - Usage:
130 
131  `./nvx_demo_feature_tracker --source=/path/to/video.avi --config=/path/to/config_file.yml`
132 
133 - If the argument is omitted, the default configuration file is used.
134 
135 #### \-m, \--mask ####
136 - Parameter: [path to image]
137 - Description: Specifies an optional mask to filter out features. This must be a grayscale image
138 that is the same size as the input source. The demo uses features only in the non-zero
139 regions on the mask. The parameter is available only if the demo is built with either OpenCV or GStreamer support.
140 
141 #### \-h, \--help ####
142 - Parameter: true
143 - Description: Prints the help message.
144 
145 ### Operational Keys ###
146 - Use `Space` to pause/resume the demo.
147 - Use `ESC` to close the demo.
148 
149 @}