repository·master·Indexed 21 days ago
https://github.com/joaofaro/kcfcppA C++ implementation of the Kernelized Correlation Filter (KCF) tracker ported to OpenCV 3.0.0. The library provides high-speed object tracking compatible with the VOT benchmark, featuring the KCFTracker class for HOG and Lab color space features, as well as a CSK Tracker implementation using raw grayscale features.
The repository provides different modes of the KCF algorithm via the KCF executable:
./KCF): KCF using HOG features../KCF lab): KCF using both HOG and Lab features (Lab features are quantized into 15 centroids via k-means).To integrate the tracker into your own C++ application without using the VOT toolkit, follow this pattern:
KCFTracker object with your desired feature and scale options.tracker.init() with the initial bounding box (Rect) and the first frame.tracker.update() to retrieve the new object position.// Create the KCFTracker object with one of the available options
KCFTracker tracker(HOG, FIXEDWINDOW, MULTISCALE, LAB);
// Give the first frame and the position of the object to the tracker
tracker.init( Rect(xMin, yMin, width, height), frame );
// Get the position of the object for the new frame
result = tracker.update(frame);The KCF Tracker requires OpenCV 3.0.0. To build the project, use CMake and make from the root directory.
cmake CMakeLists.txt
makeThe KCFTracker class implements tracking based on Kernelized Correlation Filters (KCF) and Circulant Structure with Kernels (CSK).
To use the tracker:
init() with the target's initial bounding box (cv::Rect) and the first frame (cv::Mat).update() with the new frame (cv::Mat), which returns the new target position (cv::Rect).Note: If multiscale is enabled, fixed_window must be set to false in the constructor.
// Example usage pattern
KCFTracker tracker(true, true, true, true);
// Initialize with target ROI and first frame
cv::Rect roi(100, 100, 50, 50);
cv::Mat first_frame = ...;
tracker.init(roi, first_frame);
// Update in a loop with new frames
cv::Mat next_frame = ...;
cv::Rect new_roi = tracker.update(next_frame);The following options are available when running the ./KCF executable:
gray: Use raw gray level features.hog: Use HOG features.lab: Use Lab colorspace features (this also enables HOG features by default).singlescale: Performs single-scale detection using a variable-size window.fixed_window: Keeps the window size fixed when in singlescale mode.show: Displays the tracking results in a window.The KCF executable is designed to interface with the VOT benchmark. You can pass several options to configure the tracking algorithm behavior.
./KCF [OPTION_1] [OPTION_2] [...]The KCFTracker constructor accepts four boolean parameters to define the tracking mode:
hog (default: true): If true, uses HOG features (KCF mode). If false, uses raw pixels (CSK mode).fixed_window (default: true): If true, uses a fixed window size. If false, uses the ROI size (more accurate but slower).multiscale (default: true): Enables multi-scale tracking. Note: This cannot be used if fixed_window is set to true.lab (default: true): Enables Lab color space features.KCFTracker(bool hog = true, bool fixed_window = true, bool multiscale = true, bool lab = true);The Tracker class is an abstract base class that defines the interface for all tracking algorithms in this library. To use a specific tracking algorithm, you must call init to set the initial target location and then call update in a loop to follow the target in subsequent frames.
Key methods:
init(const cv::Rect &roi, cv::Mat image): Initializes the tracker with the initial bounding box (roi) and the first frame (image).update(cv::Mat image): Processes a new frame and returns the updated bounding box (cv::Rect) of the target. If the target is not found, the behavior depends on the specific implementation (typically returning an empty rect or the last known position).// Example usage pattern for a Tracker implementation
Tracker* tracker = /* get instance of a specific tracker, e.g., KCFTracker */;
// 1. Initialize with the first frame and the target ROI
cv::Rect initial_roi(100, 100, 50, 50);
cv::Mat first_frame = cv::imread("frame0.jpg");
tracker->init(initial_roi, first_frame);
// 2. Update in a loop with subsequent frames
while (true) {
cv::Mat frame = /* get next frame from video stream or file */;
if (frame.empty()) break;
cv::Rect updated_roi = tracker->update(frame);
if (updated_roi.width > 0 && updated_roi.height > 0) {
// Draw the bounding box on the frame
cv::rectangle(frame, updated_roi, cv::Scalar(0, 255, 0), 2);
}
cv::imshow("Tracking", frame);
if (cv::waitKey(30) == 27) break;
}
delete tracker;After instantiation but before calling init(), you can fine-tune the tracker's behavior by modifying its public member variables:
| Parameter | Type | Description |
|---|---|---|
interp_factor | float | Linear interpolation factor for adaptation |
sigma | float | Gaussian kernel bandwidth |
lambda | float | Regularization |
cell_size | int | HOG cell size |
padding | float | Horizontal area surrounding the target, relative to its size |
output_sigma_factor | float | Bandwidth of gaussian target |
template_size | int | Template size in pixels (use 0 to use ROI size) |
scale_step | float | Scale step for multi-scale estimation (set to 1 to disable) |
scale_weight | float | Weight to downweight detection scores of other scales for stability |
Performance Tip: For optimal speed, ensure the ratio (template_size / cell_size) is a power of 2 or a product of small prime numbers.