{<img src="https://secure.travis-ci.org/guerilla-di/tracksperanto.png" />}[http://travis-ci.org/guerilla-di/tracksperanto]

Tracksperanto is a universal 2D-track translator between many apps.

== Why Tracksperanto?

Historically, every matchmoving app uses it's own UI for tracking 2D features.
Unfortunately, the UIs of these are all different and not very user-friendly. It happens
that an app cannot solve a shot that another one will, but you usually have to redo your 2D
tracks in each one of them.

Another problem with today's matchmoving apps is that they are vastly inefficient when
doing 2D tracks. Almost all of them use OpenGL and want to load the whole frame into memory
at once. When doing tracks of long shots at high resolutions (like 2K and HD), especially
on 32bit platforms, the app usually cannot even cache the whole shot and tracking is very
very slow.

Compositing apps, in contrast, are very efficient. Both Shake and Nuke offer very
fast trackers because they have tiling image engines and can load only the search area
for the tracker into memory and not a pixel more. When you use manual feature selection 
you can create many tracks quickly even without having fast IO. Flame is also very fast
since it has virtually zero IO overhead thanks to it's fast storage. Compositing apps
also allow for precise, local preprocessing of tracking features like boosting contrast,
doing expensive (especially temporal) denoise, blurs and so on, while matchmoving apps
offer only a single, global preprocessing step (like a LUT or a gamma curve adjustment)
which is not adequate for all of the features being tracked.

So it's very natural to track in a modern compositing app that has selective image
loading, and then export one single group of tracks into all of the matchmoving
applications at once. Also, you can always escape into the 2D world if no 3D app proves
to be adequate. If you need to move from one app to another, you won't have to retrack.

Another issue with tracks is adjusting to formats. Very few apps allow you to convert your
tracks in one step from format to format - like doing an unproportional scale on the
tracks, or moving them a few pixels left and right. This comes at a high cost if the
footage you are tracking came cropped or in a wrong aspect - the only way to solve the shot
will be to retrack it from scratch. Tracksperanto allows you to work around this
by applying simple transformations to the tracks.

== Usage

The main way to use Tracksperanto is with the the supplied "tracksperanto" binary, like so:

 tracksperanto -w 1920 -h 1080 /Films/Blockbuster/Shots/001/script.shk

-w and -h stand for Width and Height and define the size of your comp (different tracking
apps use different coordinate systems and we need to know the size of the comp to properly
convert these). Some formats contain clear hints on the size of the comp, but most don't -
for formats that do contain them you don't need to supply anything.
You also have additional options like -xs, -ys and --slip - consult the usage info for the tracksperanto binary.

The converted files will be saved in the same directory as the source, if resulting
converted files already exist <b>they will be overwritten without warning</b>.

== Format support

Import and export support:
* Nuke v5 script (Tracker3 nodes, also known as Tracker in the UI - this is the node that you track with, and Reconcile3D)
* Shake tracker node export (textfile with many tracks per file)
* PFTrack 2dt (version 4 and 5) anf PFMatchit/PFTrack 2011 point track exports
* Syntheyes 2D tracking data exports
* 3DE point exports (as output by the default script) - versions 3 and 4
* MatchMover Pro .rz2
* MayaLive track export (square pixel aspect only, you will need to write some extra code if your tracks are based on nonsquare pixels)
* Flame .stabilizer file
* Boujou feature track export

Import only:
* Shake scripts (Tracker, Matchmove and Stabilize nodes embedded in ANY shake script)
* MatchMover RZML files

Export only:
* AfterEffects .jsx script that creates one null object per tracker (run through the script editor)
* Ruby (will make calls to Tracksperanto to create trackers/keyframes) - useful if you want to play with trackers as data
* Maya locators (animated locators on an image plane)
* Softimage/XSI Python script (animated nulls on an image plane)

== Editing your tracks while converting

Tracksperanto has a number of features to scale, move, slip, distort and rename trackers.
Consult the --help option to see what is available.

== Development

If you are interested in reusing Tracksperanto's code or adding modules to the software consult
the {short developer introduction}[https://github.com/guerilla-di/tracksperanto/blob/master/DEVELOPER_DOCS.rdoc]

== Limitations

Information about the search area, reference area and offset is not passed along (outside
of scope for the app and different trackers handle these differently, if at all). For some
modules no residual will be passed along (3D tracking apps generally do not export residual
with backprojected 3D features).


== Licensing

Tracksperanto is made avalable under the MIT license that is included in the package.