Tracker Configuration Parameters
<pointcloud_filename>
Description: the file name of the pointcloud data generated for the object to track. If you have several pointclouds you can write their names here to try them, anyway, usually, you download a default tracking configuration that already has this value set with the correct name.
<pointcloud_checksum>
Description: the integrity checksum used to verify that the pointcloud data is not corrupted (you are not supposed to modify the value in anyway unless you also change the actual pointcloud file.
<max_number_of_pointcloud_keyframes>
Description: the maximum number of keyframes that will be used to init the tracker. Keyframes are the photos you uploaded and used to create the object pointcloud, beyond the 3D reconstruction of the object they are used to get an initial pose for the tracker (i.e. to initialize). For the purpose of 3D reconstruction more photos you provide the better the reconstruction will be, but when they are treated as keyframes, i.e. when they are used to estimate an initial pose for the tracker, the less keyframes you use the faster the initialization will be. Using this parameter you can choose to use a smaller number of keyframes to initialize the tracker, you just set the number and the SDK will choose the best keyframes to use. Set 0 to use all available keyframes.
<features_detector>
Description: the OpenCV features detector to be used.
Possible detectors are the following detectors supported by opencv (specifically by FeatureDetector::create method, refer to: OpenCV Documentation for details):
- ORB: ORB (oriented BRIEF)
- FAST: FastFeatureDetector
- GFTT: GoodFeaturesToTrackDetector
- HARRIS: GoodFeaturesToTrackDetector with Harris detector enabled
- BRISK: BRISK
- MSER: MserFeatureDetector
- STAR: StarFeatureDetector
- Dense: DenseFeatureDetector
- SimpleBlob: SimpleBlobDetector
You can specify parameters for the used detectors, those parameters are the same you can provide to the corresponding OpenCV constructor and are provided by separating them by a '-', for example ORB-650 will use the ORB detector and will detect at maximum 650 features.In case you do not specify some values, defaults will be used. Yet another more complex example could be ORB-650-1.1-12-57-0-2-0-55. Again refer to: OpenCV Documentation for details.
Usually beyond the detector name you will specify at least the maximum number of features to detect from each keyframe (or a threshold that directly affect that number), indeed the more features are detected the more easily the initialization will be (typically this number is the first parameter of the detector in use, or is related to a threshold that is specified as first parameter). The number that will be actually detected from the keyframes set largely depends on the keyframes by themselves, be sure to have quite a large number of detected features (something like 400 for low resolution frames and 600 and more for high resolution frames) otherwise the tracker won't initialize.
You can check the average number of detected features by querying the tracker instance using one of the available method of the tracker class (refer to the tracker API's documentation for details).
NOTE: that in some cases a very high number of features could make the initialization too slow (for example if thousands of features are found).
Suggested detector is ORB with the number of features to detect 650: ORB-650
<features_extractor>
Description: the OpenCV features extractor to be used. Possible extractors are the following extractor supported by OpenCV (specifically by DescriptorExtractor::create method, refer to: OpenCV documentation for details):
- "BRIEF" – BriefDescriptorExtractor
- "BRISK" – BRISK
- "ORB" – ORB (oriented BRIEF)
- "FREAK" – FREAK (Fast Retina Keypoint)
Note that, contrary to the case of detectors, you do not specify any parameters for the chosen extractor. Suggested extractor is BRIEF.
<max_number_of_features_for_initialization>
Description: the maximum number of features that are used to start tracking (i.e. to initialize). Small values mean faster initialization times but also low pose's quality. Note that you can use different/independent values for this parameter and for the maximum number of features used for tracking.
<max_number_of_features_neighbours_for_initialization>
Description: the number of nearest neighbours that are searched for each feature. Usually the higher the value the better the estimated pose (but the initialization will take more time).
<max_number_of_keyframes_for_initialization>
Description: the maximum number of matching keyframes that will be used to estimate the initial pose (i.e. to initialize). Higher values mean better pose but longer initialization times.
<number_of_pose_refinement_iterations>
Description: the number of iterations used to refine or update the estimated pose.
<features_search_resolution>
Description: the resolution of image patches (size of search window) used by the tracker. Smaller means faster, larger means more robust tracking.
<features_search_levels>
Description: the (0-based) number of pyramid levels used by the tracker. Smaller means faster tracking, larger means more robust for faster movements.
<features_search_iter>
Description: the maximum number of iterations used by the tracker.
<min_distance_to_add_features>
Description: the minimum (pixel) distance among features required to add a new feature to track. With small values we usually have more features to track that could result in slow performances, in practice not too many features are required as long as their 'quality' is good.
<min_number_of_longtime_features>
Description: the minimum number of 'longtime' features that are required to keep tracking. A 'longtime' feature is a feature that the tracker has been able to track since the previous initialization, if the number of such kind of features drops below the specified value we force the tracker to re-initialize the assumption is that such 'longtime' features are of higher quality with respect to recently added ones). Just set to 0 to disable this behaviour.
<max_features>
Description: the maximum number of features to track. Note that the number of tracked feature is independent of the maximum number of features used to initialize, this gives you a lot of flexibility and allows you to tune the tracker for a quick initialization and a robust tracking at the same time.
<debug_mode>
Description: will allow you to see all tracked features and/or a reference rectangle (whose vertices are specified within another parameter). If the specified value is 0 then no information will be shown, if the value is 1 then each tracked feature will be drawn onto the actual frame, finally if the value is 2 then all the features and also a reference rectangle will be drawn (you should use values 1 and 2 only for debugging purposes and either remove the tag or set the value to 0 when deploying the tracking configuration).
<reference_rectangle>
Description: a reference rectangle specified by its 3D coordinates. Each of the four corners of the rectangle are specified as X, Y and Z (in this order) one after the other in counter-clockwise order.
NOTE: the coordinates reference system is such that X positive goes to the right, Y positive goes forward and Z positive goes upward (be warned: this convention is used only to draw the reference rectangle, instead the pose is always returned as specified in the SDK documentation).
You change this coordinates depending on the object you are tracking and its real world measures (as a reference you typically use the 3D model used to create the target).
<cache_write>
Description: enables/disables the creation of a cache meant to be deployed instead of the whole keyframes set.
When deploying a 3D target you should use a cache that stores the extracted features from the keyframes set, this will make the initialization of the tracker much faster because the extraction won't be performed anymore. Also the cache usually occupies much less space if compared to the total amount of storage required by the whole set of keyframes.
Indeed the cache is made of just a couple of files:
- - cache_<hashcode>.flann
- - cache_<hashcode>.flann_index
Note that the cache is created when you init the tracker and is tightly dependent on the values of the parameters stored in the configuration file, so if you plan to modify even just one of these parameters you should re-create the cache files to take into account the modified value.
The cache should be created only when all parameters have been tuned and won't change anymore (at least when the tracker is created, on the other hand they still can change at runtime even though they won't be serialized). When you are tuning parameters always disable the creation of the cache and keep using the whole keyframes set.
When you specify the value 0 no cache will be created. If you specify 1 then cache files will be created when the tracker reads the configuration file.
<cache_read>
Description: enables/disables the reading of information from a cache.
When you specify the value 0 any available cache will be ignore and keyframes features will be extracted as usual. If you specify 1 then extracted features will be read from the cache files making tracker's initialization faster.
Note that you cannot specify the name of the the cache to read, instead the actual cache file that will be loaded is determined by the content of the configuration file, indeed there is a 1-to-1 correspondence between the values of parameters stored in the configuration file and the filenames of the cache files (so for example if you created a cache for a particular configuration file and later you modified some parameters, the previously created cache won't be read even if you specify 1).
