Motion Tracking *MK-I* Plugin for AviUtl (Tracking by Feature Points/Dense OpticalFlow)
by Maverick Tse
(rev. Jun 29 2014)
======================================

Changes in rev. Jul 31 2014
==============================
Check for opened video before running the plugin.
Added a slider for giving an ID for generated EXO file.
The ID default to 0 and increase by 1 after every analysis.

Changes in rev. Jun 29 2014
==============================
SSE2 Dynamic Build only
Minor acceleration using OpenMP
Memory leak fix

Changes in v0.6
===================
-Dropped AVX version, SSE2-Static build only
-Switched to OpenCV 2.4.9
-Switched to Visual Studio 2013
-Tuned compiling optimization
-Bugfix: mouse coordinate out-of-range might cause crashing

Changes in v0.51
===================
Added option "ImgStabilization" for keeping a desired object fixed on the screen.
If you first selected a background object that is not supposed to move on its own,
then the outputed "stabilized.exo" can act as a camera-shake stabilization object.
Load the exo, change the object type to "Video" and set the starting frame.

This is just object-tracking in disguise, so you can try any one of the 4 modes of tracking,
and you can use dY, dX

Limitation: On scene change, or once the tracked object is lost, subsequent frames will not have desired result.
Please run a new analysis on scene change.

Changes in v0.5
===================
Integrated the old plugin's color tracking algorithm into this plugin.
To use the old algorithm, check "Use CamShift".
Its parameter is now reduced to a single one: "z/100".
The "z" is actually the z-value of a normal distribution curve, but multiplied by 100 here.
In practice, increasing this parameter make tracking more prone to interference,
while decreasing too much may lead to a complete lost of object.
A value between 50-90 will suite most situation
This mode gives a rather unstable trajectory but sometimes able to track
objects that can not be handled by the OpticalFlow algorithms.


Intro
---------
This plugin achieve motion tracking by feature recognition and optical flow(Lucas-Kanade Pyramidal method, with optional Farneback and SimpleFlow).
Generated trajectory is more stable than the original plugin and works pretty well with default setting.
However, there are cases when the original plugin works better than this one.

System Requirement
-----------------------
-CPU with SSE2 support
-VC2013 Redistributable
-Win7 and later
-AviUtl v1.0 with Advanced Editing(拡張編集)　0.92

Installation
----------------
Extract all files in the archieve and put into AviUtl's ROOT folder.


Usage
-------
1> Mark the ending frame (e.g. with the "]" key)
2> Go to the first frame you want start tracking
3> Activate this filter (tick the top-right checkbox)
4> "Feature points" will be shown in red by default.
4A> Select your region of interest by dragging a box on the main window.
When you release the mouse button, a larger "Center point"(blue by default) will be displayed if your selected region contains "Feature points".
You may drag again to define another area.
Note that analysis will only proceed when the Center point appeared.
5> Inactivate the plugin (uncheck the top-right checkbox)
6> Click on [Analyze!], wait till "EXO Saved" appear on title bar or... the program crash :P
The title bar may appear "Not responding", but usually it is not a crash, just be patient and wait...
7> Load "tracking.exo".

Tuning/ Parameters
------------------------
-The color of Center Point and Feature Points can be changed by "dotColor" slider
- Color of selection box can be changed by "boxColor" slider
- The "Center Point" is the arthrimatic average of the selected "Feature Points".
This will be the starting coordinate of your new object. Adjust dY, dX with reference to this.
- If there are very few Feature Points in your region of interest,
try increasing "MaxPt" slider.(may have no effect depending on image content)
The MaxPt slider set the top best N feature points to be displayed.

- Major tuning parameters for the internal Lucas-Kanade engine are "WinSize" and "mEig*E-5" sliders.
- Increasing mEig*E-5 will reject more points but increase processing speed.
(Warning: if this parameter is set too high, there may be no data in the final EXO!)
- a very Small WinSize tends to make unstable trajectory. an overly large WinSize will reduce
sensitivity (may seems to lag behind actual object)

- Selecting more (approriate)feature points tends to improve result

- Channel: The L-K engine actuall works on grey scale image and this slider set how to get the greyscale data:
0: Overall greyscale using all RGB data
1: use only the red channel as grey scale data
2: use only the green channel as grey scale data
3: use only the blue channel as grey scale data
(Use this silder if certain channel gives better contrast)

DF_Mode:
0= Fastest. Speed correspond to number of points selected;
(Lucas-Kanade method with reverse tracking check)
1= Medium speed. Speed correspond to size of image and independent of the points selected;
(Farneback Dense Optical Flow method)
2= Extremely slow (5-10sec per frame). Most accurate in most situation, but may be too slow to be practical.
Speed correspond to size of image and independent of the points selected;

Hints
----------
- Here are some know case that can cause tracking to fail:
> An object is crossing a boundary of two different backgrounds
(e.g. when an object appear moving from the sky to the ground)

> fast & complex/ pendulum motion

> The tracking object is approaching image's edge

> Occulution

> Interference from heavy shadow
- This plugin can follow certain degree of panning, zooming and limited rotation.
Works particularly well for feature-rich objects, e.g. text, people(body and face).

- The original plugin/CamShift Option works better when:
>The object to be tracked is a block of uniform color against a uniform background of very different color.
>Complex/irregular motion

- I'd suggest AGAINST loading your source video in to exedit's NLE panel.
Your video may be moved while dragging selection box! (or Lock the video's layer)

- You can actually click on the Analyze! button while the plugin is Active.
However, the result may be a bit different and takes longer to complete.

Please report bug/suggestion to (accepts Japanese, English and Chinese):
http://mavericktse.mooo.com/wordpress/

History
---------
6 Feb, 2014: Initial release, alpha 0.01
7 Feb, 2014: Added reverse tracking check and neigbouring points search, 
Fixed SimpleFlow method, Added Farneback method, beta 0.2
(The tracking algorithm is now set using the DF_mode slider.)
9 Feb, 2014: Beta 0.5. Integrated two plugins into one. Simplified CamShift tuning.
18 May, 2014: Beta 0.6. Bugfix, library and compiler upgrade, modified manual instruction, dropped AVX and DLL builds
29 Jun, 2014: rev. Jun 29 2014: Performance boost, memory leak fix.
31 Jul, 2014: minor bug fix.

*Free to distrbute and modifiy. The author, Maverick Tse, however, will not be responsible for any lost
arise from the use of this software.