File	Date	Author	Commit
matlab	2015-09-30	Kai Ruhl	[18901e] Added Matlab base algorithm source.
python	2015-10-15	Kai Ruhl	[e1a9bf] cuda_drv naming cleanup.
.gitignore	2015-09-30	Kai Ruhl	[85e500] Fresh repo for kinflow.
README.txt	2015-10-11	Kai Ruhl	[6c4497] Adjusted mini manual in README.

Read Me

------
README
------

kinflow is a Python/CUDA app that brings user interaction to optical flow
(per-pixel motion detection between two images).

My code and the resources can be checked out with:
git clone git://git.code.sf.net/p/kinflow/code
git clone git://git.code.sf.net/p/kinflow/res

I am reachable under http://www.kairuhl.net and the project homepage is
http://kinflow.sf.net

------

This list is intended for a programmer who wants to get started quickly
with kinflow in order to compute an optical flow between two images.

(1) Go into res/img and select a directory with images you like, e.g.
    31_symbiz_low; optionally edit 31_symbiz_low.yaml to your liking.

(2) Go into code/python/src and call ./run_testsrc.py to check that everything
    is working at the most basic level.

(3) Call ipython kinflow.py -D 31, this will search for the "res" directory
    and find 31_symbiz_low.yaml, then start the GUI application.

(4) Within the GUI, press Space for pause. Click prolonged into the upper
    left window for some object you want to fix. A circle should appear and
    grow larger the longer you hold the mouse button. Then click into the
    upper right window for a target position. Unpause with Space.

    Watch the effect of your edit. Press Shift+R to reset the estimation.
    Press h for help. Try out 7 for image warp animation.

(5) Press ESC to quit the app. Results are in the 31_symbiz_low directory.

    The files are <image_name>.exr, e.g. for "frame1.png" and "frame2.png",
    there will be "frame1.png.exr" and "frame2.png.exr" in the input directory.

    Only the former is useful at this stage, since symmetric flow has not
    been implemented yet.

(6) To find more data options, look at kincontext.py.

(7) If you want to contribute your own flow estimation algorithm,
    please refer to the design file "kinflow_<version>_design.pdf" to be
    found in "res/docs/architectural_design_document".
    
    In short, you need to extend the classes AbstractFlowData (your dataset at
    each pyramid level) and AbstractFlowSolver (your solver).

------

The next part is for researchers looking into optical flow.

My baseline algorithm is from Christopher Zach/Thomas Pock, their 2007 paper
"A duality based approach for realtime TV-L1 optical flow"
https://sites.google.com/site/christophermzach/home/papers

The Matlab source code is part of the gpu4vision project:
http://gpu4vision.icg.tugraz.at/index.php?content=downloads.php

------

For people starting out in optical flow, Deqing Sun and his 2010 paper
"Secrets of Optical Flow Estimation and Their Principles"
contain a survey of algorithms, as well as Matlab source code.
http://people.seas.harvard.edu/~dqsun/

A better but also definitively non-realtime optical flow is by Thomas Brox,
described in his 2009 paper "Large Displacement Optical Flow" (+binary).
http://lmb.informatik.uni-freiburg.de/resources/software.php

------