KLT_TrackingContext
typedef struct {
int mindist;
int window_width, window_height;
KLT_BOOL sequentialMode;
KLT_BOOL smoothBeforeSelecting;
KLT_BOOL writeInternalImages;
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;
int nSkippedPixels;
int borderx;
int bordery;
int nPyramidLevels;
int subsampling;
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 (see
Good Features to Track). 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
.
- 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.
- 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.
- pyramid_last, pyramid_last_gradx, pyramid_last_grady Used
to hold the most recent image. These fields must not be touched manually.
Default: NULL.