1 <!-- Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved. -->
3 @defgroup nvx_demo_feature_tracker Feature Tracker Demo App
4 @brief Feature Tracker Demo user guide.
8 <a name=
"Introduction">
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).
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.
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.
30 +-------------------+-------------------+
32 [GaussianPyramid] [CornerTrack]
34 (initial pyramid) (initial points)
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.
49 (previous pyramid) (current pyramid) (points to track in the previous frame)
51 +------------------------------+--------------------------------------+
59 (points to track in the next frame)
62 @note In the figure above, the entities inside () denote data and the entities
63 inside [] denote the vision functions.
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$.
68 ## Installation and Usage ##
70 `nvx_demo_feature_tracker` is installed in the following directory:
72 /usr/share/visionworks/sources/demos/feature_tracker
74 For the steps to build sample applications, see the @ref nvx_samples_and_demos_user_guides
78 ## Executing the Feature Tracker Demo ##
80 ./nvx_demo_feature_tracker [options]
82 ### Command Line Options ###
84 This topic provides a list of supported options and the values they consume.
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),
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
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`.
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.
108 This file contains the following parameters:
111 - Parameter: [integer value greater than or equal to 1 and less than or
113 - Description: The number of levels in Gaussian pyramid. Default is 6.
116 - Parameter: [integer value greater than or equal to 1 and less than or
118 - Description: The number of iterations in the Lucas-Kanade method. Default
122 - Parameter: [integer value greater than or equal to 3 and less than or
124 - Description: The window size in the Lucas-Kanade method. Default is 6.
127 - Parameter: [integer value greater than or equal to 1]
128 - Description: The capacity of points array. Default is 2000.
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.
136 - Parameter: [harris or fast]
137 - Description: The corner detector algorithm. Default is
"harris".
140 - Parameter: [floating point value greater than zero]
141 - Description: The Harris corner detector
"k" parameter. Default is 0.04.
144 - Parameter: [floating point value greater than zero]
145 - Description: The Harris corner detector threshold. Default is 2000.
148 - Parameter: [9, 10, 11 or 12]
149 - Description: The type of FAST corner detector. Default is 9.
152 - Parameter: [integer value less than 255]
153 - Description: The FAST corner detector threshold. Default is 25.
157 `./nvx_demo_feature_tracker --source=/path/to/video.avi --config=/path/to/config_file.ini`
159 - If the argument is omitted, the
default configuration file is used.
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.
168 #### \-h, \--help ####
170 - Description: Prints the help message.
172 ### Operational Keys ###
173 - Use `Space` to pause/resume the demo.
174 - Use `ESC` to close the demo.