.. _fr.inria.built-in.Tracker:

Tracker node
============

.. raw:: html

   <!-- Do not edit this file! It is generated automatically by Natron itself. -->

*This documentation is for version 1.0 of Tracker (fr.inria.built-in.Tracker).*

Description
-----------

Track one or more 2D point(s) using LibMV from the Blender open-source software.

Goal
----

Track one or more 2D point and use them to either make another object/image match-move their motion or to stabilize the input image.

Tracking
--------

-  Connect a Tracker node to the image containing the item you need to track
-  Place tracking markers with CTRL+ALT+Click on the Viewer or by clicking the **+** button below the track table in the settings panel
-  Setup the motion model to match the motion type of the item you need to track. By default the tracker will only assume the item is underoing a translation. Other motion models can be used for complex tracks but may be slower.
-  Select in the settings panel or on the Viewer the markers you want to track and then start tracking with the player buttons on the top of the Viewer.
-  If a track is getting lost or fails at some point, you may refine it by moving the marker at its correct position, this will force a new keyframe on the pattern which will be visible in the Viewer and on the timeline.

Using the tracks data
---------------------

You can either use the Tracker node itself to use the track data or you may export it to another node.

Using the Transform within the Tracker node
-------------------------------------------

Go to the Transform tab in the settings panel, and set the Transform Type to the operation you want to achieve. During tracking, the Transform Type should always been set to None if you want to correctly see the tracks on the Viewer.

You will notice that the transform parameters will be set automatically when the tracking is finished. Depending on the Transform Type, the values will be computed either to match-move the motion of the tracked points or to stabilize the image.

Exporting the tracking data
---------------------------

You may export the tracking data either to a CornerPin node or to a Transform node. The CornerPin node performs a warp that may be more stable than a Transform node when using 4 or more tracks: it retains more information than the Transform node.

Inputs
------

+--------+-------------+----------+
| Input  | Description | Optional |
+========+=============+==========+
| Source |             | No       |
+--------+-------------+----------+

Controls
--------

.. tabularcolumns:: |>{\raggedright}p{0.2\columnwidth}|>{\raggedright}p{0.06\columnwidth}|>{\raggedright}p{0.07\columnwidth}|p{0.63\columnwidth}|

.. cssclass:: longtable

 
| Parameter / script name                                   | Type    | Default        | Function                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
| Motion Type / ``motionType``                              | Choice  | None           | | The type of motion in output of this node.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
|                                                           |         |                | | **None**: No transformation applied in output to the image: this node is a pass-through. Set it to this mode when tracking to correctly see the input image on the viewer                                                                                                                                                                                                                                                                                                                                                                                |
|                                                           |         |                | | **Stabilize**: Transforms the image so that the tracked points do not move                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
|                                                           |         |                | | **Match-Move**: Transforms a different image so that it moves to match the tracked points                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
|                                                           |         |                | | **Remove Jitter**: Transforms the image so that the tracked points move smoothly with high frequencies removed                                                                                                                                                                                                                                                                                                                                                                                                                                           |
|                                                           |         |                | | **Add Jitter**: Transforms the image by the high frequencies of the animation of the tracks to increase the shake or apply it on another image                                                                                                                                                                                                                                                                                                                                                                                                           |
 
| Transform Type / ``transformType``                        | Choice  | CornerPin      | | The type of transform used to produce the results.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|                                                           |         |                | | **Transform**: The tracks motion will be used to compute the translation, scale and rotation parameter of a Transform node. At least 1 track is required to compute the translation and 2 for scale and rotation. The more tracks you use, the more stable and precise the resulting transform will be.                                                                                                                                                                                                                                                  |
|                                                           |         |                | | **CornerPin**: The tracks motion will be used to compute a CornerPin. A CornerPin is useful if you are tracking an image portion that has a perspective distortion. At least 1 track is required to compute the homography transforming the “From” points to the “To” points, and 4 required to track a perspective transformation.The more points you add, the more stable and precise the resulting CornerPin will be.                                                                                                                                 |
 
| Reference Frame / ``referenceFrame``                      | Integer | 1              | When exporting tracks to a CornerPin or Transform, this will be the frame number at which the transform will be an identity.                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
| Set to Current Frame / ``setReferenceButton``             | Button  |                | Set the reference frame to the timeline’s current frame                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 
| Jitter Period / ``jitterPeriod``                          | Integer | 10             | Number of frames to average together to remove high frequencies for the add/remove jitter transform type                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
| Smooth / ``smooth``                                       | Integer | t: 0 r: 0 s: 0 | Smooth the translation/rotation/scale by averaging this number of frames together                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 
| Smooth / ``smoothCornerPin``                              | Integer | 0              | Smooth the CornerPin by averaging this number of frames together                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 
| Compute Transform Automatically / ``autoComputeransform`` | Boolean | On             | When checked, whenever changing a parameter controlling the Transform Generation (such as Motion Type, Transform Type, Reference Frame, etc...) or changing the Enabled parameter of a track, the transform parameters will be re-computed automatically. When unchecked, you must press the Compute button to compute it.                                                                                                                                                                                                                                 |
 
| Compute / ``computeTransform``                            | Button  |                | Click to compute the parameters of the Transform Controls or CornerPin Controls (depending on the Transform Type) from the data acquired on the tracks during the tracking. This should be done after the tracking is finished and when you feel the results are satisfying. For each frame, the resulting parameter is computed from the tracks that are enabled at this frame and that have a keyframe on the center point (e.g: are valid).                                                                                                             |
 
| Robust Model / ``robustModel``                            | Boolean | On             | When checked, the solver will assume that the model generated (i.e: the Transform or the CornerPin) is possible given the motion of the video and will eliminate points that do not match the model to compute the resulting parameters. When unchecked, the solver assumes that all points that are enabled and have a keyframe are valid and fit the model: this may in some situations work better if you are trying to find a model that is just not correct for the given motion of the video.                                                        |
 
| Fitting Error (px) / ``fittingError``                     | Double  | 0              | This parameter indicates the error for each frame of the fitting of the model (i.e: Transform / CornerPin) to the tracks data. This value is in pixels and represents the rooted weighted sum of squared errors for each track. The error is essentially the difference between the point position computed from the original point onto which is applied the fitted model and the original tracked point.                                                                                                                                                 |
 
| Warn If Error Is Above / ``fittingErrorWarnAbove``        | Double  | 1              | A warning will appear if the model fitting error reaches this value (or higher). The warning indicates that the calculated model is probably poorly suited for the stabilization/match-move you want to achieve and you should either refine your tracking data or pick another model                                                                                                                                                                                                                                                                      |
 
| Disable Transform / ``disableProcess``                    | Boolean | Off            | When checked, the CornerPin/Transform applied by the parameters is disabled temporarily. This is useful if you are using a CornerPin and you need to edit the From or To points. For example, in match-move mode to replace a portion of the image by another one. To achieve such effect, you would need to place the From points of the CornerPin controls to the desired 4 corners in the image. Similarly, you may want to stabilize the image onto a moving vehicle, in which case you would want to set the CornerPin points to enclose the vehicle. |
 
| Set to Input Rod / ``setToInputRod``                      | Button  |                | Set the 4 from points to the image rectangle in input of the tracker node                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
| Export / ``export``                                       | Button  |                | Creates a node referencing the tracked data. The node type depends on the node selected by the Transform Type parameter. The type of transformation applied by the created node depends on the Motion Type parameter. To activate this button you must select set the Motion Type to something other than None                                                                                                                                                                                                                                             |
 
| Mag. Window Size / ``magWindowSize``                      | Integer | 200            | The size of the selected track magnification winow in pixels                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
