kinflow

kinflow is a Python/CUDA app that brings user interaction to optical flow estimation (per-pixel motion detection between two images). You input two images of the same size, and the output is a "flow field" with dx/dy (2D motion) for each pixel. My GUI visualizes the estimation process; as soon as you notice an error, you can correct it by long-clicking the erroneous region in both images. Press h for help on more possibilities.

Requirements

You need an Nvidia graphics card with about 2GB of GPU memory; the absolute minimum is 512MB for running the smaller image pairs (150x100). Also, you need a lot of Python libs, notably OpenEXR, OpenGL, PyCUDA, YAML, and a host of others. I have an article on how to install PyCUDA.

I wrote kinflow for my ACM Multimedia 2012 publication "Improving Dense Image Correspondence Estimation with Interactive User Guidance" (video). If you use it for research purposes leading to a publication, please cite the following paper:

@inproceedings{ruhl2012acmmm,
    author = {Ruhl, Kai and Hell, Benjamin and Klose, Felix and Lipski, Christian and Petersen, Soren and Magnor, Marcus},
    title = {Improving Dense Image Correspondence Estimation with Interactive User Guidance},
    booktitle = {Proceedings of {ACM} Multimedia 2012},
    publisher = {{ACM}},
    pages = {1129--1132},
    month = oct,
    year = {2012}
}

Installation

There is no packaged download available. I assume you are a researcher or developer with knowledge of git and Python. If this is a problem, please let me know under megid at sourceforge.net. If not create a kinflow directory of your choice and checkout source and resources:

git clone git://git.code.sf.net/p/kinflow/code
git clone git://git.code.sf.net/p/kinflow/res

There is a README.txt in code, and the gist is to cd code/python/src and ./kinflow.py -D 31 (or another number) to start the GUI app. To see which numbers are available, cd res/img and look around. Each number has exactly one directory with a YAML config file and the images. Please refer to the README.txt for more details.

Research background

kinflow uses the near real-time optical flow from Christopher Zach and Thomas Pock, published in their 2007 paper "A duality based approach for realtime TV-L1 optical flow". I am indebted to them for publishing the source code, thanks!

My contribution is visualizing the estimation process, and then adding different kinds of user interactions in order to fix (unavoidable) shortcomings in the optical flow modeling.

License

kinflow is GPL'd open source software, which means it is and will always remain free, and also means that if you build upon it, you have to open source your result too. Since I know that in research keeping your bleeding edge is essential, I give you one year after the publication date of your paper to open source your derived software. By this time, you should be onto your next paper and any time advantage of competing groups should have vanished.

For rare cases when it makes sense to use LGPL instead of GPL, write me at megid at sourceforge.net and I might give you a different license.

Also, it has to be said that here are absolutely no guarantees on this. In the unlikely event that the software crashes your phone, your life and your bank account, it is still your own fault.

Status

While I started writing the original code sometime in 2011, I only got around to clean it up and open source it after I finished my PhD programme in July 2015. Status is time-tested research code. I would call it a good alpha.

And next?

Checkout, run, tell me how it went at megid at sourceforge.net. If you use it for research purposes, please let me know. I like knowing that someone actually uses my stuff :)

EOF (Oct:2015)