C_Tracker

CaraVR’s 2D Tracker allows you to extract animation data from the pan, tilt, and roll of a pattern. You can then apply the data directly to transform or match-move another element. Or you can invert the data values and apply them to the original element to stabilize the image.

Note:  C_Tracker differs from vanilla Nuke's tracker in that it can track in latlong space, meaning features are tracked as they pass the edge of the frame when the image wraps around.

Inputs and Controls

Connection Type

Connection Name

Function

Input

unnamed

The sequence you want to track.

Control (UI)

Knob (Scripting)

Default Value

Function

C_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

long

N/A

Dependent on source input

Displays the longitudinal, or horizontal, position of the tracking anchor.

lat

N/A

Dependent on source input

Displays the latitudinal, or vertical, position of the tracking anchor.

fov

N/A

Dependent on source input

Displays the field of view used to convert from spherical to rectilinear and back again after tracking.

P

N/A

enabled

When enabled, pan is calculated during tracking.

T

N/A

enabled

When enabled, tilt is calculated during tracking.

R

N/A

disabled

When enabled, roll is calculated during tracking.

Note:  Tracking roll 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

Export Menu

exportMenu

C_SphericlaTransform (Stabilise)

Sets the nodes to output when you click Create:

C_SphericalTransform (Stabilise) - creates an expression linked C_SphericalTransform containing Pan, Tilt, and Roll data to stabilize the output.

C_SphericalTransform (Match-move) - creates an expression linked C_SphericalTransform containing Pan, Tilt, and Roll data to match-move content.

C_MetaDataTransform (Stabilise) - creates an expression linked C_MetaDataTransform containing Pan, Tilt, and Roll data to stabilize the output.

C_MetaDataTransform (Match-move) - creates an expression linked C_MetaDataTransform containing Pan, Tilt, and Roll data to match-move content.

Create

exportButton

N/A

Click to create the export specified in export dropdown.

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, C_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 C_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 C_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_link

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, C_Tracker re-grabs a pattern at the current position each time tracking is stopped.

when tracker is moved

regrab_when_offset

enabled

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

Transform Tab

Local GPU

gpuName

N/A

Displays the GPU used for rendering when Use GPU if available is enabled. Local GPU displays Not available when:

Use CPU is selected as the GPU device in the Preferences.

no suitable GPU was found on your system.

it was not possible to create a context for processing on the selected GPU, such as when there is not enough free memory available on the GPU.

You can select a different GPU device, if available, by navigating to the Preferences and selecting an alternative from the GPU Device dropdown.

Note:  Selecting a different GPU requires you to restart Nuke before the change takes effect.

Use GPU if available

useGPUIfAvailable

enabled

When enabled, rendering occurs on the Local GPU specified, if available, rather than the CPU.

Note:  Enabling this option with no local GPU allows the script to run on the GPU whenever the script is opened on a machine that does have a GPU available.
You should also select this if you wish to render from the command line with the --gpu option.

See Nuke 14 Release Notes for more information on the GPUs Nuke supports.

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.

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

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.

pan tilt roll pan_tilt_roll 0, 0, 0 Sets the pan, tilt, and roll in degrees.
pan-tilt position transform_pan_tilt 0, 0 Sets the latlong position of the pan-tilt transform.
roll position transform_roll 0, 0 Sets the latlong position of the roll transform.

Filter

filter

Cubic

Select the filtering algorithm to use when remapping pixels from their original positions to new positions.

As a general guideline, the filters increase in quality at the cost of processing time as you move down the list. Bilinear filtering is the fastest and Lanczos the sharpest.