OpenCV  3.0.0
Open Source Computer Vision
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Classes | Macros | Typedefs | Functions
Tracking API


class  cv::BaseClassifier
class  cv::ClassifierThreshold
class  cv::ClfMilBoost
class  cv::ClfOnlineStump
class  cv::CvFeatureEvaluator
class  cv::CvFeatureParams
class  cv::CvHaarEvaluator
class  cv::CvHaarFeatureParams
class  cv::CvHOGEvaluator
struct  cv::CvHOGFeatureParams
class  cv::CvLBPEvaluator
struct  cv::CvLBPFeatureParams
class  cv::CvParams
class  cv::Detector
class  cv::EstimatedGaussDistribution
class  cv::StrongClassifierDirectSelection
class  cv::Tracker
 Base abstract class for the long-term tracker: More...
class  cv::TrackerBoosting
 This is a real-time object tracking based on a novel on-line version of the AdaBoost algorithm. More...
class  cv::TrackerFeature
 Abstract base class for TrackerFeature that represents the feature. More...
class  cv::TrackerFeatureFeature2d
 TrackerFeature based on Feature2D. More...
class  cv::TrackerFeatureHAAR
 TrackerFeature based on HAAR features, used by TrackerMIL and many others algorithms. More...
class  cv::TrackerFeatureHOG
 TrackerFeature based on HOG. More...
class  cv::TrackerFeatureLBP
 TrackerFeature based on LBP. More...
class  cv::TrackerFeatureSet
 Class that manages the extraction and selection of features. More...
class  cv::TrackerMedianFlow
 Median Flow tracker implementation. More...
class  cv::TrackerMIL
 The MIL algorithm trains a classifier in an online manner to separate the object from the background. More...
class  cv::TrackerModel
 Abstract class that represents the model of the target. It must be instantiated by specialized tracker. More...
class  cv::TrackerSampler
 Class that manages the sampler in order to select regions for the update the model of the tracker [AAM] Sampling e Labeling. See table I and section III B. More...
class  cv::TrackerSamplerAlgorithm
 Abstract base class for TrackerSamplerAlgorithm that represents the algorithm for the specific sampler. More...
class  cv::TrackerSamplerCS
 TrackerSampler based on CS (current state), used by algorithm TrackerBoosting. More...
class  cv::TrackerSamplerCSC
 TrackerSampler based on CSC (current state centered), used by MIL algorithm TrackerMIL. More...
class  cv::TrackerSamplerPF
 This sampler is based on particle filtering. More...
class  cv::TrackerStateEstimator
 Abstract base class for TrackerStateEstimator that estimates the most likely target state. More...
class  cv::TrackerStateEstimatorAdaBoosting
 TrackerStateEstimatorAdaBoosting based on ADA-Boosting. More...
class  cv::TrackerStateEstimatorMILBoosting
 TrackerStateEstimator based on Boosting. More...
class  cv::TrackerStateEstimatorSVM
 TrackerStateEstimator based on SVM. More...
class  cv::TrackerTargetState
 Abstract base class for TrackerTargetState that represents a possible state of the target. More...
class  cv::TrackerTLD
 TLD is a novel tracking framework that explicitly decomposes the long-term tracking task into tracking, learning and detection. More...
class  cv::WeakClassifierHaarFeature


#define CC_FEATURE_PARAMS   "featureParams"
#define CC_FEATURE_SIZE   "featSize"
#define CC_ISINTEGRAL   "isIntegral"
#define CC_MAX_CAT_COUNT   "maxCatCount"
#define CC_NUM_FEATURES   "numFeat"
#define CC_RECT   "rect"
#define CC_RECTS   "rects"
#define CC_TILTED   "tilted"
#define CV_SUM_OFFSETS(p0, p1, p2, p3, rect, step)
#define CV_TILTED_OFFSETS(p0, p1, p2, p3, rect, step)
#define FEATURES   "features"
#define HFP_NAME   "haarFeatureParams"
#define HOGF_NAME   "HOGFeatureParams"
#define LBPF_NAME   "lbpFeatureParams"
#define N_BINS   9
#define N_CELLS   4
#define sign(s)   ((s > 0 ) ? 1 : ((s<0) ? -1 : 0))


typedef std::vector< std::pair
< Ptr< TrackerTargetState >
, float > > 
 Represents the model of the target at frame \(k\) (all states and scores) More...
typedef std::vector< Ptr
< TrackerTargetState > > 
 Represents the estimate states for all frames. More...


template<class Feature >
void cv::_writeFeatures (const std::vector< Feature > features, FileStorage &fs, const Mat &featureMap)
float cv::CvHOGEvaluator::Feature::calc (const std::vector< Mat > &_hists, const Mat &_normSum, size_t y, int featComponent) const
uchar cv::CvLBPEvaluator::Feature::calc (const Mat &_sum, size_t y) const
float cv::calcNormFactor (const Mat &sum, const Mat &sqSum)
virtual float cv::CvHOGEvaluator::operator() (int varIdx, int sampleIdx)

Detailed Description

Long-term optical tracking API

Long-term optical tracking is one of most important issue for many computer vision applications in real world scenario. The development in this area is very fragmented and this API is an unique interface useful for plug several algorithms and compare them. This work is partially based on [107] and [74] .

This algorithms start from a bounding box of the target and with their internal representation they avoid the drift during the tracking. These long-term trackers are able to evaluate online the quality of the location of the target in the new frame, without ground truth.

There are three main components: the TrackerSampler, the TrackerFeatureSet and the TrackerModel. The first component is the object that computes the patches over the frame based on the last target location. The TrackerFeatureSet is the class that manages the Features, is possible plug many kind of these (HAAR, HOG, LBP, Feature2D, etc). The last component is the internal representation of the target, it is the appearence model. It stores all state candidates and compute the trajectory (the most likely target states). The class TrackerTargetState represents a possible state of the target. The TrackerSampler and the TrackerFeatureSet are the visual representation of the target, instead the TrackerModel is the statistical model.

A recent benchmark between these algorithms can be found in [135]

UML design: see Tracking diagrams

To see how API works, try tracker demo:

This Tracking API has been designed with PlantUML. If you modify this API please change UML in modules/tracking/doc/tracking_diagrams.markdown. The following reference was used in the API

Creating Own Tracker

If you want create a new tracker, here's what you have to do. First, decide on the name of the class for the tracker (to meet the existing style, we suggest something with prefix "tracker", e.g. trackerMIL, trackerBoosting) – we shall refer to this choice as to "classname" in subsequent. Also, you should decide upon the name of the tracker, is it will be known to user (the current style suggests using all capitals, say MIL or BOOSTING) –we'll call it a "name".

Every tracker has three component TrackerSampler, TrackerFeatureSet and TrackerModel. The first two are instantiated from Tracker base class, instead the last component is abstract, so you must implement your TrackerModel.


TrackerSampler is already instantiated, but you should define the sampling algorithm and add the classes (or single class) to TrackerSampler. You can choose one of the ready implementation as TrackerSamplerCSC or you can implement your sampling method, in this case the class must inherit TrackerSamplerAlgorithm. Fill the samplingImpl method that writes the result in "sample" output argument.

Example of creating specialized TrackerSamplerAlgorithm TrackerSamplerCSC : :

class CV_EXPORTS_W TrackerSamplerCSC : public TrackerSamplerAlgorithm
TrackerSamplerCSC( const TrackerSamplerCSC::Params &parameters = TrackerSamplerCSC::Params() );
bool samplingImpl( const Mat& image, Rect boundingBox, std::vector<Mat>& sample );

Example of adding TrackerSamplerAlgorithm to TrackerSampler : :

//sampler is the TrackerSampler
Ptr<TrackerSamplerAlgorithm> CSCSampler = new TrackerSamplerCSC( CSCparameters );
if( !sampler->addTrackerSamplerAlgorithm( CSCSampler ) )
return false;
//or add CSC sampler with default parameters
//sampler->addTrackerSamplerAlgorithm( "CSC" );
See also
TrackerSamplerCSC, TrackerSamplerAlgorithm


TrackerFeatureSet is already instantiated (as first) , but you should define what kinds of features you'll use in your tracker. You can use multiple feature types, so you can add a ready implementation as TrackerFeatureHAAR in your TrackerFeatureSet or develop your own implementation. In this case, in the computeImpl method put the code that extract the features and in the selection method optionally put the code for the refinement and selection of the features.

Example of creating specialized TrackerFeature TrackerFeatureHAAR : :

class CV_EXPORTS_W TrackerFeatureHAAR : public TrackerFeature
TrackerFeatureHAAR( const TrackerFeatureHAAR::Params &parameters = TrackerFeatureHAAR::Params() );
void selection( Mat& response, int npoints );
bool computeImpl( const std::vector<Mat>& images, Mat& response );

Example of adding TrackerFeature to TrackerFeatureSet : :

//featureSet is the TrackerFeatureSet
Ptr<TrackerFeature> trackerFeature = new TrackerFeatureHAAR( HAARparameters );
featureSet->addTrackerFeature( trackerFeature );
See also
TrackerFeatureHAAR, TrackerFeatureSet


TrackerModel is abstract, so in your implementation you must develop your TrackerModel that inherit from TrackerModel. Fill the method for the estimation of the state "modelEstimationImpl", that estimates the most likely target location, see [107] table I (ME) for further information. Fill "modelUpdateImpl" in order to update the model, see [107] table I (MU). In this class you can use the :cConfidenceMap and :cTrajectory to storing the model. The first represents the model on the all possible candidate states and the second represents the list of all estimated states.

Example of creating specialized TrackerModel TrackerMILModel : :

class TrackerMILModel : public TrackerModel
TrackerMILModel( const Rect& boundingBox );
void modelEstimationImpl( const std::vector<Mat>& responses );
void modelUpdateImpl();

And add it in your Tracker : :

bool TrackerMIL::initImpl( const Mat& image, const Rect2d& boundingBox )
//model is the general TrackerModel field od the general Tracker
model = new TrackerMILModel( boundingBox );

In the last step you should define the TrackerStateEstimator based on your implementation or you can use one of ready class as TrackerStateEstimatorMILBoosting. It represent the statistical part of the model that estimates the most likely target state.

Example of creating specialized TrackerStateEstimator TrackerStateEstimatorMILBoosting : :

class CV_EXPORTS_W TrackerStateEstimatorMILBoosting : public TrackerStateEstimator
class TrackerMILTargetState : public TrackerTargetState
TrackerStateEstimatorMILBoosting( int nFeatures = 250 );
Ptr<TrackerTargetState> estimateImpl( const std::vector<ConfidenceMap>& confidenceMaps );
void updateImpl( std::vector<ConfidenceMap>& confidenceMaps );

And add it in your TrackerModel : :

//model is the TrackerModel of your Tracker
Ptr<TrackerStateEstimatorMILBoosting> stateEstimator = new TrackerStateEstimatorMILBoosting( params.featureSetNumFeatures );
model->setTrackerStateEstimator( stateEstimator );
See also
TrackerModel, TrackerStateEstimatorMILBoosting, TrackerTargetState

During this step, you should define your TrackerTargetState based on your implementation. TrackerTargetState base class has only the bounding box (upper-left position, width and height), you can enrich it adding scale factor, target rotation, etc.

Example of creating specialized TrackerTargetState TrackerMILTargetState : :

class TrackerMILTargetState : public TrackerTargetState
TrackerMILTargetState( const Point2f& position, int targetWidth, int targetHeight, bool foreground, const Mat& features );
bool isTarget;
Mat targetFeatures;

Try it

To try your tracker you can use the demo at

The first argument is the name of the tracker and the second is a video source.

Macro Definition Documentation

#define CC_FEATURE_PARAMS   "featureParams"
#define CC_FEATURE_SIZE   "featSize"
#define CC_ISINTEGRAL   "isIntegral"
#define CC_MAX_CAT_COUNT   "maxCatCount"
#define CC_NUM_FEATURES   "numFeat"
#define CC_RECT   "rect"
#define CC_RECTS   "rects"
#define CC_TILTED   "tilted"
#define CV_SUM_OFFSETS (   p0,
/* (x, y) */ \
(p0) = (rect).x + (step) * (rect).y; \
/* (x + w, y) */ \
(p1) = (rect).x + (rect).width + (step) * (rect).y; \
/* (x + w, y) */ \
(p2) = (rect).x + (step) * ((rect).y + (rect).height); \
/* (x + w, y + h) */ \
(p3) = (rect).x + (rect).width + (step) * ((rect).y + (rect).height);
#define CV_TILTED_OFFSETS (   p0,
/* (x, y) */ \
(p0) = (rect).x + (step) * (rect).y; \
/* (x - h, y + h) */ \
(p1) = (rect).x - (rect).height + (step) * ((rect).y + (rect).height);\
/* (x + w, y + w) */ \
(p2) = (rect).x + (rect).width + (step) * ((rect).y + (rect).width); \
/* (x + w - h, y + w + h) */ \
(p3) = (rect).x + (rect).width - (rect).height \
+ (step) * ((rect).y + (rect).width + (rect).height);
#define FEATURES   "features"
#define HFP_NAME   "haarFeatureParams"
#define HOGF_NAME   "HOGFeatureParams"
#define LBPF_NAME   "lbpFeatureParams"
#define N_BINS   9
#define N_CELLS   4
#define sign (   s)    ((s > 0 ) ? 1 : ((s<0) ? -1 : 0))

Typedef Documentation

typedef std::vector<std::pair<Ptr<TrackerTargetState>, float> > cv::ConfidenceMap

Represents the model of the target at frame \(k\) (all states and scores)

See [107] The set of the pair \(\langle \hat{x}^{i}_{k}, C^{i}_{k} \rangle\)

See also
typedef std::vector<Ptr<TrackerTargetState> > cv::Trajectory

Represents the estimate states for all frames.

[107] \(x_{k}\) is the trajectory of the target up to time \(k\)

See also

Function Documentation

template<class Feature >
void cv::_writeFeatures ( const std::vector< Feature >  features,
FileStorage &  fs,
const Mat &  featureMap 
float cv::CvHOGEvaluator::Feature::calc ( const std::vector< Mat > &  _hists,
const Mat _normSum,
size_t  y,
int  featComponent 
) const
uchar cv::CvLBPEvaluator::Feature::calc ( const Mat _sum,
size_t  y 
) const
float cv::calcNormFactor ( const Mat &  sum,
const Mat &  sqSum 
float cv::CvHOGEvaluator::operator() ( int  varIdx,
int  sampleIdx