Tracker

Function
The Tracker function is used only to generate tracks. Unlike the MatchMove and Stabilize functions, it does not alter the input image. The Tracker function is used to create tracks that are referenced either in other tracking nodes or in non-tracking nodes such as Move2D, Rotate, etc. While MatchMove and Stabilize are limited to creating one, two, or four track points, the Tracker node can hold as many trackers as you want. To add a tracker, click Add at the bottom of the Parameter View. If your workflow continually uses Smoothing and Averaging of tracks for application in a Stabilize or MatchMove, you should probably generate the tracks with a Tracker node.

With the Tracker node, you can delete trackers, and save the tracks to disk. To save an individual track, right-click in the trackName field and select Save Track.

 

Parameters
Type
 Default Notes
subPixelResolution string 1/16

The resolution of your track. The smaller the number, the more precise and slower your tracking will become.

Possible values:

1 area is sampled at every pixel. Not very accurate or smooth, but very fast.
1/4 area is sampled at every .25 pixels, i.e, 16 times more than with a sampling of 1.
1/16 area is sampled at every .0625 pixels, i.e, 256 times more than with a sampling of 1.
1/32 area is sampled at every .03125 pixels, i.e, 1024 times more than with a sampling of 1.
1/64 area is sampled at every .015625 pixels, i.e, 4096 times more than with a sampling of 1.
matchSpace string luminance The pixels are matched according to the correlation between the selected color space, either luminance, hue, or saturation. If an image has roughly the same luminance, but contrasting hues, the user would switch over to hue-based tracking.
referenceTolerance float .75 A tracking correlation of 1 is a perfect score, meaning there is an exact match between the original reference frame and the sampled area. By lowering the referenceTolerance, you are accepting greater inaccuracy in your track. If tracked keys are between the referenceTolerance and the failureTolerance, they will be highlighted in the Viewer. Also, in some cases, referenceBehavior will be triggered if the tracking correlation is below the referenceTolerance.
referenceBehavior string use start frame

This behavior dictates what source sample a tracking area should reference. By default, the reference sample is the first frame at which you started the track, not necessarily the first frame of the trackRange. The last two behaviors measure the tracking correlation and match it to the referenceTolerance to decide an action.

use start frame
The reference area the new samples are compared to comes from the first frame at which you started tracking. If you stop tracking midway, and start up again at a later frame, the later frame will be used as the reference sample.

update every frame
The source sample is updated from the previous frame. This will give you an inherent drift in your track, as tiny errors will accumulate. This method is for movements that have drastic changes in perspective and scale.

update from keyframes
If you are using a failureBehavior of predict location and don't create keys or don't predict location, a keyframe will not necessarily be saved every frame. In this case, you may only want to update from the last frame that had a valid keyframe.

update if above reference tolerance
This will update the reference sample from the previous frame if the correlation is above the referenceTolerance. The intent of this is update every frame unless you know the point is obscured. If you have a predict mode and know there are obstructions, it keeps the ref area from updating if the point is completely obscured.


update if below reference tolerance
This will update the reference sample from the previous frame if the correlation is below the referenceTolerance. This is basically saying "If I can't get a good match, then resample". This is excellent for gradual perspective and scale shifts in your tracking area.
failureTolerance float .5 If the correlation of a track falls below this value, it will initiate the failureBehavior.
failureBehavior string stop

stop
The tracker stops if the correlation is less than the failureTolerance. You can also hit Esc to manually stop tracking.

predict location and create key.
If a failure is detected, then the tracker predicts the location of the key based a vector of the last two keys, and continues tracking in the new area.

predict location and don't create key.
As above, but new keys are not created, it merely predicts the new search area. This is excellent for tracked objects passing behind foreground objects.

don't predict location
In this case, the tracker merely sits in the same spot looking for new samples. New keys are not created.

use existing key to predict location
This setting allows you to manually create keys along your track path. You then go back to the beginning to track and start tracking, and the search pattern will start looking at where the pre-existing motion path is.
limitProcessing int 1 This will create a DOD of the bounding box of all active trackers. Only that portion of the image will be loaded from disk, therefore your tracking will go more quickly.
trackRange
string
 1 This is the potential frame range limit of your tracking. If you read in a clip, the range will be set to the clip range. For generated elements like RGrad, it will take a range of 1. You can set new limits using Shake's standard range description, i.e., 10-30x2. If you stop tracking and start up again, it will start from the current frame until it reaches the lower or upper limit of your trackRange, depending on if you are tracking forwards or backwards.
trackNName string trackN The name of the track. You can change this.
trackNX/Y float
width/3, height/3
2*width/3, height/3
2*width/3, 2*height/3
width/3, 2*height/3
The actual track point in X and Y. This is what you would use if you were linking a parameter to a track point.
trackNCorrelation float NA The correlation value of that key to the original sample. A score of 1 is a perfect score. 0 is a very very very very bad score.
trackNWindow Parameters float NA These multiple parameters control the windowing of the tracking box, and are not relevant to exported values.



Synopsis

 image Tracker( 
  image In,
  const char * trackRange,
  const char * subPixelRes,
  const char * matchSpace,
  float referenceTolerance,
  const char * referenceBehavior,
  float failureTolerance,
  const char * failureBehavior,
  int limitProcessing,
  float referencFrame
  ...
 );


Script

 image = Tracker( 
  In,
  "trackRange",
  "subPixelRes",
  "matchSpace",
  float referenceTolerance,
  "referenceBehavior",
  float failureTolerance,
  "failureBehavior",
  int limitProcessing,
  float referencFrame
  ...
 );

See Also
 MatchMove, Stabilize