Tracker

This is a 2D tracker that allows you to extract animation data from the position, rotation, and size of an image. Using expressions, you can apply the data directly to transform and match-move another element. Or you can invert the values of the data and apply them to the original element - again through expressions - to stabilize the image.

This is the general process for tracking an image:

1.   Connect a Tracker node to the image you want to track.
2.   Use auto-tracking for simple tracks or place tracking anchors on features at keyframes in the image.
3.   Calculate the tracking data.
4.   Choose the tracking operation you want to perform: stabilize, match-move, etc.

See also the Tracking tab in Roto and RotoPaint.

Inputs and Controls

Connection Type

Connection Name

Function

Input

unnamed

The sequence you want to track.

Control (UI)

Knob (Scripting)

Default Value

Function

Tracker Tab

Tracks

e

N/A

enabled

When enabled, the associated track anchor in the Viewer is used to track a feature from the input.

name

N/A

track 1

Sets the track name.

track_x

N/A

Dependent on source input

Adjusts the x coordinates of the associated track anchor’s center.

track_y

N/A

Dependent on source input

Adjusts the y coordinates of the associated track anchor’s center.

offset_x

N/A

0

Sets the offset amount, in pixels, between the tracking anchor and the feature position on the x and y axes.

This is especially useful when the feature you want to track is obscured or otherwise unavailable, enabling you to track another pattern to produce the required tracking data.

offset_y

N/A

0

T

N/A

enabled

When enabled, translation is calculated during tracking.

R

N/A

disabled

When enabled, rotation is calculated during tracking.

Note:  Tracking rotation requires at least two tracks.

S

N/A

disabled

When enabled, scale is calculated during tracking.

Note:  Tracking scale requires at least two tracks.

error

N/A

0

Displays the overall track error rating.

add track

add_track

N/A

Click to add a new track and anchor to the Viewer.

delete track

del_tracks

N/A

Click to delete all selected tracks.

select all

select_all

N/A

Click to select all tracks in the Tracks list.

average tracks

average_tracks

N/A

Click to average all selected tracks together into a single new track. This can be especially useful for stabilization tracking.

Export CornerPin2D

CornerPin Options

cornerPinOptions

CornerPin2D (use current frame)

Sets the node to output when you click create. The baked options do not use expression links between Tracker and the exported node:

CornerPin2D (use current frame) - creates an expression linked CornerPin2D node that warps the image according to the relative transform, using the current frame as a reference.

CornerPin2D (use transform ref frame) - creates an expression linked CornerPin2D node that warps the image according to the relative transform, using the frame specified in the Transform tab as a reference.

Transform (stabilize) - creates an expression linked Transform node with control presets to stabilize the clip.

Transform (match-move) - creates an expression linked Transform node with control presets to match-move the clip.

create

createCornerPin

N/A

Click to create the CornerPin2D or Transform node specified in Export dropdown.

Note:  There must be 4 tracks selected in the Tracks list to create a CornerPin2D node.

Settings Tab

General

track channels

channels

rgb

Tracking only occurs in these channels.

If you set this to something other than all or none, you can use the checkboxes on the right to select individual channels.

pre-track filter

pretrack_filter

median

Sets the filter applied before image patches are compared:

none - no filter is applied.

adjust contrast - the default filter, stretches the image contrast to better suit the tracking algorithm. This is the recommended setting and shouldn’t need changing in most circumstances.

median - attempts to remove image noise.

adjust for luminance changes

adjust_for_luminance_changes

disabled

When enabled, Tracker does some extra pre-filtering to compensate for changes in brightness.

This option slows the tracking process and can reduce the accuracy of tracks, so only enable this control if there are known changes in brightness.

Note:  Enabling adjust for luminance changes can occasionally produce better tracks on shots with no differences in luminance, particularly on jittery shots where sub-pixel accuracy is vitally important.

max iterations

max_iter

100

Sets the maximum number of iterations before the tracking algorithm stops searching for features.

Note:  This setting does not normally need adjusting.

epsilon / resolution

epsilon

0.01

Sets the error level at which Tracker is assumed to have found the feature - no further search for a better match is performed. Higher values may result in a faster but less accurate track.

Note:  This setting does not normally need adjusting.

max_error

max_error

0.2

Sets the error level at which Tracker stops searching for features.

clamp super-white, sub-zero footage

clamp_footage

enabled

When enabled, tracked patches are clamped to values between 0-1.

Note:  If you want to track using the full dynamic range available in your footage, disable this control and adjust the max-error value accordingly. For example, images with pixel intensity 40 may require a max-error value of 40.

show error on track paths

show_error_on_track_links

disabled

When enabled, keyframes on the track are colored according to their relative error:

green - a good match for the grabbed pattern.

amber - a reasonable match for the grabbed pattern.

red - a poor match for the grabbed pattern.

High track error values aren’t necessarily bad keyframes. Rather, they indicate that the pattern has changed considerably since the previous pattern grab.

hide progress bar

hide_progress_bar

disabled

When enabled, the track progress dialog doesn’t display during tracking.

snap to markers

snap_to_markers

disabled

When enabled, adding tracks places a guide on suitable marker patterns, such as dots or blobs, in the Viewer. Move the tracking anchor to a guide and release the mouse to snap the anchor to the guide’s position.

show zoom window

zoom_window_behavior

always

Sets when the zoom window is visible in the Viewer:

always - the zoom window is always visible.

on track change - only display the zoom window when a track changes.

when tracking - only display the zoom window during tracking.

when tracking or track change - only display the zoom window during tracking or when a track changes.

never - the zoom window is never displayed.

zoom window size / magnification

zoom_window_size

200px

Sets the size of the zoom window.

zoom_magnification_size

x1

Sets the magnification in the zoom window.

zoom window filter

zoom_window_filter_behaviour

on playback

Sets when filtering is applied to the zoom window:

always

on playback

never

Note:  The filter applied is the same as that selected on the Transform tab, and can produce a more visually stable track. It can make track positioning more difficult, however.

Auto-Tracking

predict track

predict_track

disabled

When enabled, use the current tracker animation path to determine where to look in the next frame.

Note:  If Tracker fails to find the feature in the next frame, click the clearfwd button above the Viewer before continuing, or the same error is repeated.

warp type

warp

Translate

Selects the transformations that are tried on the pattern to match it to the image. Translate is fastest, but may lose the track if the pattern rotates, scales, or shears over the course of the track:

Translate - only expect pattern translation.

Translate/Rotate - expect pattern translation and rotation.

Translate/Scale - expect pattern translation and scaling.

Translate/Rotate/Scale - expect pattern translation, rotation, and scaling.

Affine - expect straight lines and the distance between the points on them to remain equal.

Note:  This control does not relate to how the image is transformed as an output, but what transforms the pattern matching algorithm utilizes to find the best pattern match.

pattern grab behavior

grab_behavior

if error above

Sets when the tracker attempts to grab a new pattern:

on first frame - grab a pattern on the first frame only.

every frame - grab a new pattern on every frame.

every n frames - use the every n frames control to specify the frame interval.

if error above - use the when error > control to specify the grab behavior.

if error below - use the when error < control to specify the grab behavior.

custom - use the every n frames and when error <> controls to specify grab behavior.

every n frames

grab_interval

0

When pattern grab behavior is set to update every n frames or custom, sets the interval at which Tracker automatically re-grabs a pattern.

when error >

grab_error_above

0.05

When pattern grab behavior is set to update if above tolerance or custom, sets the error level above which Tracker automatically re-grabs a pattern.

when error <

grab_error_below

0

When pattern grab behavior is set to update if below tolerance or custom, sets the error level below which Tracker automatically re-grabs a pattern.

when tracking is stopped

auto_regrab_pattern

disabled

When enabled, Tracker re-grabs a pattern at the current position each time tracking is stopped.

when tracker is moved

regrab_when_offset

enabled

When enabled, Tracker re-grabs a pattern when a track is manually adjusted.

Keyframe Tracking

retrack when keyframe is moved / created

retrack_on_move

enabled

When enabled, re-track a pattern when a track is manually adjusted or a new keyframe is created.

create new key when track is moved

create_key_on_move

enabled

When enabled, create a new keyframe when the track is manually adjusted.

auto-tracks delete keyframes

auto-tracks_delete_keyframes

enabled

When enabled, auto-tracking deletes manual keyframes.

When disabled, auto-tracking adjusts the position of manual keyframes.

keyframe display

keyframe_display

scroll, single line only

Sets how keyframe snapshots are displayed in the Viewer:

all - show all keyframe snapshots in the available Viewer space.

nearest, single line only - show the nearest keyframe snapshot to the playhead, and the surrounding whole snapshots, on a single line only.

scroll, single line only - show all keyframe snapshots in a scrolling, single line only.

none - don’t show any keyframe snapshots.

keyframe size

keyframe_size

100px

Sets the size of keyframe snapshots in the Viewer.

on_screen key-track limit

max_number_of_keyframe_tracks_to_display

3

Sets the maximum number of tracks with keyframes that can be displayed in the Viewer.

Set this control to 0 to always display selected tracks with keyframes.

Transform Tab

transform

transform

none

Sets the type of transform to apply.

Note:  The transform control must be set to none when calculating tracks.

none - no transformation is applied to the input image.

stabilize - transforms the image so that the tracked points do not move.

stabilize 1pt - similar to stabilize, but designed for use with a single track.

match-move - transforms another image so that it moves to match the tracked points.

match-move 1pt - similar to match-move, but designed for use with a single track.

remove jitter - transforms the image so that the tracked points move smoothly, with high-frequencies removed.

add jitter - transform the input image by the high-frequency components of the track to increase the shake or add it to another image.

reference frame

reference_frame

1

When transform is set to stabilize or match-move, sets the frame in the input sequence to use as the reference or identity frame.

set to current frame

N/A

N/A

Click to set the current frame as the reference or identity frame.

jitter period

jitter_period

10

When transform is set to add/removejitter, sets the number of frames to average together to get a stable position.

smooth

smoothT

0

Smooths the translation by averaging this many frames together.

smoothR

0

Smooths the rotation by averaging this many frames together.

smoothS

0

Smooths the scale by averaging this many frames together.

live-link transform

livelink_transform

disabled

When enabled, changes to tracks instantly update the transform. Dynamic updating may be useful if a track position is controlled by an expression.

translate xy

translate

0, 0

Displays the translation applied to the Transform widget for the current track. Once tracking is complete, you can drag-and-drop the translate information to link other nodes, such as the Stabilize node.

rotate

rotate

0

Displays the rotation applied to the Transform widget for the current track. Once tracking is complete, you can drag-and-drop the rotate information to link other nodes, such as the Stabilize node.

scale

scale

1

Displays the scale applied to the Transform widget for the current track. Once tracking is complete, you can drag-and-drop the scale information to link other nodes, such as the Stabilize node.

skew X

skewX

0

Displays the skew applied to the Transform widget on the x axis for the current track. Once tracking is complete, you can drag-and-drop the skew information to link other nodes, such as the Stabilize node.

skew Y

skewY

0

Displays the skew applied to the Transform widget on the y axis for the current track. Once tracking is complete, you can drag-and-drop the skew information to link other nodes, such as the Stabilize node.

skew order

skew_order

 

Sets the order in which skew transforms are applied:

XY

YX

center xy

center

Dependant on input

Sets the center of rotation and scaling. You can also cmd + drag the Transform widget in the Viewer.

filter

filter

Cubic

Select the filtering algorithm to use when remapping pixels from their original positions to new positions. This allows you to avoid problems with image quality, particularly in high contrast areas of the frame (where highly aliased, or jaggy, edges may appear if pixels are not filtered and retain their original values).

Impulse - remapped pixels carry their original values.

Cubic - remapped pixels receive some smoothing.

Keys - remapped pixels receive some smoothing, plus minor sharpening (as shown by the negative -y portions of the curve).

Simon - remapped pixels receive some smoothing, plus medium sharpening (as shown by the negative -y portions of the curve).

Rifman - remapped pixels receive some smoothing, plus significant sharpening (as shown by the negative -y portions of the curve).

Mitchell - remapped pixels receive some smoothing, plus blurring to hide pixelation.

Parzen - remapped pixels receive the greatest smoothing of all filters.

Notch - remapped pixels receive flat smoothing (which tends to hide moire patterns).

Lanczos4, Lanczos6, and Sinc4 - remapped pixels receive sharpening which can be useful for scaling down. Lanczos4 provides the least sharpening and Sinc4 the most.

clamp

clamp

disabled

When using filters that employ sharpening, such as Rifman and Lanczos, you may see a haloing effect. If necessary, check clamp to correct this problem.

black outside

black_outside

enabled

This renders as black pixels outside the image boundary, making it easier to layer the element over another. If you uncheck this control, the outside area is filled with the outermost pixels of the image sequence.

In most cases, you should keep black outside checked. However, you may want to turn this off for camera shake, or if you want to texture-map or intersect the output with a similar shape.

Note:  Enabling black outside also adds a solid alpha covering the input image area if no alpha is present.

motionblur

motionblur

0

Sets the number of motion blur samples. A value of 1 should produce reasonable results for most sequences.

Increase the value to produce more samples for higher quality, or decrease it to shorten the processing time. The higher the value, the smoother the result.

shutter

shutter

0.5

Enter the number of frames the shutter stays open when motion blurring. For example, a value of 0.5 corresponds to half a frame. Increasing the value produces more blur, and decreasing the value less.

shutter offset

shutteroffset

start

Controls how the shutter behaves with respect to the current frame value:

centred - center the shutter around the current frame. For example, if you set the shutter value to 1 and your current frame is 30, the shutter stays open from frame 29,5 to 30,5.

start - open the shutter at the current frame. For example, if you set the shutter value to 1 and your current frame is 30, the shutter stays open from frame 30 to 31.

end - close the shutter at the current frame. For example, if you set the shutter value to 1 and your current frame is 30, the shutter stays open from frame 29 to 30.

custom - open the shutter at the time you specify. In the field next to the dropdown menu, enter a value (in frames) you want to add to the current frame. To open the shutter before the current frame, enter a negative value. For example, a value of - 0.5 would open the shutter half a frame before the current frame.

shuttercustomoffset

0

If the shutter offset control is set to custom, this field is used to set the time that the shutter opens by adding it to the current frame. Values are in frames, so -0.5 would open the shutter half a frame before the current frame.

Step-by-Step Guides

Tracking and Stabilizing

Tutorial 2: 2D Point Tracking

Video Tutorials

Related Topics Link IconRelated Topics