## KLTTrackFeatures()

## `void KLTTrackFeatures(
KLT_TrackingContext tc,
KLT_PixelType *img1,
KLT_PixelType *img2,
int ncols,
int nrows,
KLT_FeatureList fl);
`

KLTTrackFeatures() takes two images pointed to by `img1` and `img2`. (NOTE: `KLT_PixelType` is, unless modified by the user, an `unsigned char`.) If `tc->sequentialMode` is `TRUE`, and KLTTrackFeatures() has been previously called, then `img1` is ignored and the first image is taken instead from `tc->pyramid_last`, `tc->pyramid_last_gradx`, and `tc->pyramid_last_grady`. In either case, the resulting images are smoothed by convolving with a Gaussian of sigma = `tc->smooth_sigma_fact * max(tc->window_width, tc->window_height)`. Then a multi-resolution image pyramid is created with `tc->nPyramidLevels` levels and `tc->subsampling` pixels subsampled between each level; smoothing before sampling is accomplished with sigma = `tc->subsampling * tc->pyramid_sigma_fact`. Gradients are computed at each level of the pyramid by convolving with the derivative of a Gaussian of sigma = `tc->grad_sigma`.

In the feature list, each feature that is not lost (i.e., whose value is nonnegative) is tracked beginning with the coarsest resolution and ending with the finest resolution, with each resolution providing the starting point for the subsequent resolution. At each resolution, tracking is accomplished by a Newton-Raphson iterative minimization between the intensities of the two windows, one window in each image. There are five conditions that cause the iterations to stop (only in the first case is the tracker successful):

1. the feature moves by no more than `tc->min_displacement`
2. the determinant of the 2-by-2 gradient matrix is less than `tc->min_determinant`
3. the number of iterations exceeds `tc->max_iterations`
4. the feature is out of bounds (i.e., it is within `tc->borderx` or `tc->bordery` of the border of the image)
5. the residue is too large (i.e., the average intensity difference between pixels in the two windows is greater than `tc->max_residue`)

The value of the feature in these cases becomes `KLT_TRACKED`, `KLT_SMALL_DET`, `KLT_MAX_ITERATIONS`, `KLT_OOB`, and `KLT_LARGE_RESIDUE`, respectively, which are in turn equal to 0, -2, -3, -4, and -5. (See the reference page of `KLT_Feature` to see what a value of -1 means.)

If `tc->writeInternalImages` is `TRUE`, then the smoothed image and the image derivatives at each level of the pyramid are written to `"kltimg_tf_[I][n].pgm"`, `"kltimg_tf_[I][n]_gx.pgm"`, and `"kltimg_tf_[I][n]_gy.pgm"`, where `[I] = i,j` denotes either the first image or the second image, and `[n] = 0,1,2,...` denotes the level of the pyramid.

After all the features are tracked, if `tc->sequentialMode` is `TRUE`, then the second image and its derivatives are stored in `tc->pyramid_last`, `tc->pyramid_last_gradx`, and `tc->pyramid_last_grady`.