KLT_TrackingContext
typedef struct {
int mindist;
int window_width, window_height;
KLT_BOOL sequentialMode;
KLT_BOOL smoothBeforeSelecting;
KLT_BOOL writeInternalImages;
KLT_BOOL lighting_insensitive;
int min_eigenvalue;
float min_determinant;
float min_displacement;
int max_iterations;
float max_residue;
float grad_sigma;
float smooth_sigma_fact;
float pyramid_sigma_fact;
float step_factor;
int nSkippedPixels;
int borderx;
int bordery;
int nPyramidLevels;
int subsampling;
int affine_window_width, affine_window_height;
int affineConsistencyCheck;
int affine_max_iterations;
float affine_max_residue;
float affine_min_displacement;
float affine_max_displacement_differ;
void *pyramid_last;
void *pyramid_last_gradx;
void *pyramid_last_grady;
} *KLT_TrackingContext;
A KLT_TrackingContext collects all the parameters governing the tracker,
so that calls to the tracker do not have to involve an exhorbitant
number of parameters. Each parameter may be changed manually by the
user except for the last three, which must not be touched.
In addition, a few of the parameters can be more easily changed via
the convenience functions KLTChangeTCPyramid() and
KLTUpdateTCBorder().
Below is a brief description of each parameter, along with suggested default
values (which are located in "klt.c").
The parameters preceded by an asterisk (*) are those whose effects can be
viewed by setting writeInternalImages.
- mindist The minimum distance between each feature being
selected, in pixels.
Used by KLTSelectGoodFeatures() and KLTReplaceLostFeatures().
Default: 10.
- window_width, window_height The size of the feature window,
in pixels.
It is suggested that you call the convenience function
KLTUpdateTCBorder() after changing this parameter.
Default: 7.
- sequentialMode If
TRUE, then the previous image is saved and
used later. Used by KLTTrackFeatures() and KLTReplaceLostFeatures() to speed the
computation when tracking through an image sequence.
Default: FALSE.
- * smoothBeforeSelecting If
TRUE, then the image is smoothed
before features are selected in both
KLTSelectGoodFeatures() and KLTReplaceLostFeatures().
This is to ensure that the image used for
selecting features is identical to the image used for tracking features,
in which case the feature selection is optimal by construction. If you only need to select features but not
track them, or if you are willing to sacrifice a slight decrease in
performance for a slight
improvement in speed, then set this parameter to FALSE.
After setting to TRUE, do not manually set to FALSE,
but rather call KLTStopSequentialMode().
Default: TRUE.
- writeInternalImages If
TRUE, then the internal images
used for feature selection and tracking, that is, the smoothed and
differentiated versions of the original images, are written to files
"kltimg_sgfrlf*.pgm" by KLTSelectGoodFeatures() and
KLTReplaceLostFeatures(). The smoothed and differentiated versions at each
level of the pyramid are written to files "kltimg_tf*.pgm"
by KLTTrackFeatures(). By examining these files, the user can better
determine the desired parameters for smoothing, etc.
Default: FALSE.
- lighting_insensitive Whether to normalize the image intensities for gain and bias
within the window. This is an extension beyond the standard algorithm.
Used by KLTTrackFeatures().
Default: FALSE.
- min_eigenvalue The minimum allowable eigenvalue for new features
being selected. In other words, KLTSelectGoodFeatures() and
KLTReplaceLostFeatures() add only those features whose minimum eigenvalue is
at least
min_eigenvalue, which must not be less than one. By
setting this parameter to a number larger than one and
nFeatures to a very large number, the effect is to select all
features whose minimum eigenvalue is above a threshold.
Default: 1.
- min_determinant The minimum allowable determinant before
a feature is declared lost.
Used by KLTTrackFeatures().
Default: 0.01.
- min_displacement The minimum displacement, in pixels,
necessary to stop the
iterative tracker and declare tracking successful.
Used by KLTTrackFeatures().
Default: 0.1.
- max_iterations The maximum number of iterations allowed when
tracking. If exceeded, the feature is lost.
Used by KLTTrackFeatures().
Default: 10.
- max_residue The maximum residue, averaged per pixel, allowed
when tracking. If exceeded, the feature is lost.
Used by KLTTrackFeatures().
Default: 1.0.
- * grad_sigma The standard deviation, in pixels, of the Gaussian
used for computing the image gradients.
Default: 1.0.
- * smooth_sigma_fact Multiplied by
max(window_width,window_height)
to yield the standard deviation of the Gaussian
used for smoothing the image. Because the tracker uses a Newton-Raphson method,
there must be no local minima within each window.
It is suggested that you call the convenience function
KLTUpdateTCBorder() after changing this parameter.
Default: 0.1.
- * pyramid_sigma_fact Multiplied by
subsampling to
yield the standard deviation of the Gaussian used for
smoothing the image before subsampling.
It is suggested that you call the convenience function
KLTUpdateTCBorder() after changing this parameter.
Default: 0.9.
- step_factor Determines the size of the Newton step.
The value 2.0 is theoretically correct according to the equations,
but 1.0 seems to do better at avoiding overshooting.
Default: 1.0.
- nSkippedPixels The number of pixels in between each
pair of possible features. Used to speed up the computation of
KLTSelectGoodFeatures() and KLTReplaceLostFeatures().
Default: 0.
- borderx, bordery The size of the border, in pixels,
that is not analyzed
by the computation of KLTSelectGoodFeatures() and KLTReplaceLostFeatures().
This border is necessary because convolution with the Gaussian causes
much of the image's values to become unknown. Tracking in those regions
can produce strange results.
Can be changed more easily using the convenience function
KLTUpdateTCBorder().
Default: KLTUpdateTCBorder() => 23.
- * nPyramidLevels The number of pyramid levels.
Can be changed more easily using the convenience function
KLTChangeTCPyramid().
Default: KLTChangeTCPyramid(15) => 2.
- * subsampling The amount of subsampling between adjacent
pyramid levels.
Must be either 2, 4, 8, 16, or 32.
Can be changed more easily using the convenience function
KLTChangeTCPyramid().
It is suggested that you call the convenience function
KLTUpdateTCBorder() after changing this parameter.
Default: KLTChangeTCPyramid(15) => 4.
- affine_window_width, affine_window_height The width and height
of the window used for the affine consistency check.
Default: 15.
- affineConsistencyCheck Governs whether to evaluates the consistency
of features with affine mapping:
-1 = don't evaluates the consistency
0 = evaluates the consistency of features with translation mapping
1 = evaluates the consistency of features with similarity mapping
2 = evaluates the consistency of features with affine mapping
Default: -1.
- affine_max_iterations Maximum number of iterations for affine consistency check.
Default: 10.
- affine_max_residue Maximum residue for affine consistency check.
Default: 10.0.
- affine_min_displacement Minimum displacement for terminating affine consistency check iterations.
Default: 0.02f.
- affine_max_displacement_differ Maximum difference between the displacement calculated
by the affine tracker and the frame to frame tracker in pixels.
Default: 1.5f.
- pyramid_last, pyramid_last_gradx, pyramid_last_grady Used
to hold the most recent image. These fields must not be touched manually.
Default: NULL.