ankhzaya / flowiz

Converts Optical Flow files to images and optionally compiles them to a video. Flow viewer GUI is also available. Check out mockup right from Github Pages:

Converts Optical Flow .flo files to images .png and optionally compiles them to a video .mp4 via ffmpeg

• Installation
• Usage
  • Command line usage
  • Python usage
  • GUI usage
  • Help
• Acknowledgements
• FAQ
• To-Do

Installation

Grab the latest package from PyPI repo

pip install flowiz -U

or grab it straight from Github

pip install git+https://github.com/georgegach/flowiz/

or clone the repo and install using setup.py

git clone https://github.com/georgegach/flowiz.git
cd flowiz
python setup.py install --user

Make sure you have following packages installed

pip install numpy tqdm matplotlib eel
apt install ffmpeg

Usage

Package can be used both from the command line and python script.

Command line usage

The following script grabs .flo files from ./demo/flo/ directory and converts into .png saving in the same directory

python -m flowiz demo/flo/*.flo

You can pass output directory for .png images via -o or --outdir parameter

python -m flowiz demo/flo/*.flo --outdir demo/png/

You may compile converted .png images into a 24 fps .mp4 clip by passing -v or --videodir parameter with a video output directory (without a filename)

python -m flowiz demo/flo/*.flo -o demo/png --videodir demo/mp4

Pass -r or --framerate parameter to control the framerate of compiled video

python -m flowiz demo/flo/*.flo -o demo/png -v demo/mp4 --framerate 2

Python usage

Relevant python code is available in demo/test.ipynb notebook. Here's an excerpt:

import flowiz as fz

files = glob.glob('demo/flo/*.flo')
img = fz.convert_from_file(files[0])
plt.imshow(img)

In case you need to visualize U V channels separately from your numpy floArray:

uv = fz.convert_from_flow(floArray, mode='UV')
axarr[0].imshow(uv[...,0], cmap=plt.get_cmap('binary'))
axarr[1].imshow(uv[...,1], cmap=plt.get_cmap('binary'))

GUI usage

Beta version of the flowiz graphical user interface is now accessible via flowiz.gui package. It is packaged using ChrisKnott / Eel and available via default web browser. To run the GUI simply type:

python -m flowiz.gui

Upon launching the web app, drag and drop or choose .flo file(s) using the open file dialog. Files will be converted using the python backend and placed in a temporary directory flowiz/gui/web/guitemp. Upon every session temporary directory will be emptied to avoid unnecessary polution.

Mockup of the GUI is available at georgegach.github.io/flowiz

Help

$ python -m flowiz -h

usage: __main__.py [-h] [--outdir OUTDIR] [--videodir VIDEODIR]
                    [--framerate FRAMERATE]
                    input [input ...]

positional arguments:
  input                 Input file(s). (e.g.: __ ./demo/flo/*.flo)

optional arguments:
  -h, --help            show this help message and exit
  --outdir OUTDIR, -o OUTDIR
                        Output directory path. Default: same directory as
                        [.flo] files. (e.g.: __ -o ./demo/png/)
  --videodir VIDEODIR, -v VIDEODIR
                        Compiles [.mp4] video from [.png] images if parameter
                        is passed. Parameter requires video output directory
                        path without a filename. (e.g.: __ -v ./demo/mp4/)
  --framerate FRAMERATE, -r FRAMERATE
                        Frames per second of the video. (e.g.: __ -r 2)

Acknowledgements

The library is based on Midlebury's Vision Project MATLAB code: http://vision.middlebury.edu/flow/ Original credits to Daniel Scharstein (C++) and Deqing Sun (MATLAB)

FAQ

Q: But what kind of name is flowiz?
A: The kind you choose when flowkit, flowtools, flowlib, flowlab are already taken.

Q: Future work?
A: Some of the To-Do features are listed below with no determined timeline. If you'd like to contribute with the said features or something completely new, you may and issue a pull request.

To-Do

• Ported from Matlab flow_code
• Project is available on PyPI
• GUI
  • Fully argparsable CLI launch support
  • File open with support
  • Original image overlay
  • Full file explorer
  • Flow file info
    • Basics: name, width, height, filesize
    • Histogram
  • Progress bar
  • Client-side .flo format validation (using tag)
• Library
  • Arrow visualizations (using opencv or custom compact nanomodule)
  • Standalone rgb and uv:binary image creation (removes matplotlib dependency)
  • Standalone .mp4 compiler (removes ffmpeg dependency)
• CLI
  • Nothing for now
• Miscellaneous
  • Better logo