A tool for easy extraction of motion vectors stored in video files
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
examples Update vis_mpeg_flow.sh Mar 24, 2017
LICENSE Initial commit Jul 20, 2015
Makefile Update Makefile Dec 11, 2017
README.md Update README.md Nov 1, 2017
mpegflow.cpp Update mpegflow.cpp Apr 11, 2018
vis.cpp Vis now works Mar 21, 2017


Information & Contact

We release mpegflow for easy extraction of MPEG-flow (motion vectors) from video files along with a visualization tool vis, both under the MIT license. We provide Makefiles for Linux / Windows and distribute binary releases.

Please submit bugs on GitHub directly. For any other question, please contact Vadim Kantorov at vadim.kantorov@inria.fr or vadim.kantorov@gmail.com.

If you use this code, please cite our work:

      author = {Kantorov, V. and Laptev, I.},
      title = {Efficient feature extraction, encoding and classification for action recognition},
      booktitle = {Proc. Computer Vision and Pattern Recognition (CVPR), IEEE, 2014},
      year = {2014} }

Below is a visualization of some flow maps of MPI Sintel's alley_1 sequence:

Source 3 15 50
Ground truth


The tool accepts a video file path as command-line argument and writes MPEG-flow (motion vectors) to standard output. By default, the tool outputs the motion vectors arranged in two matrices - dx and dy.

Command-line options:
Option Description
--help or -h will output the usage info
--raw will prevent motion vectors from being arranged in matrices
--grid8x8 will force fine 8x8 grid
--occupancy will append occupancy matrix after motion vector matrices
--quiet will suppress debug output


The tool accepts a video file path and a dump directory as command-line arguments, output of mpegflow on standard input and saveson disk the visualization of motion vectors overlayed on video frames.

Command-line options:
Option Description
--help or -h will output the usage info
--occupancy will expect occupancy information from mpegflow and will visualize it as well


  • To extract motion vectors:

    ./mpegflow examples/mpi_sintel_final_alley_1.avi > examples/alley_1.txt

  • To visualize motion vectors:

    mkdir -p examples/vis_dump && ./mpegflow examples/mpi_sintel_final_alley_1.avi | ./vis examples/mpi_sintel_final_alley_1.avi examples/vis_dump

Feel free to copy-paste and run the examples above. More runnable examples are in examples/extract_motion_vectors.sh and examples/vis_motion_vectors.sh. Feel free to use vis.cpp and examples/vis_hue.m as examples of parsing mpegflow output. examples/vis_hue can also be used to produce hue flow visualizations like above.

Building from source

mpegflow depends only on a recent FFmpeg, vis depends on FFmpeg, OpenCV and libpng. The tools are known to work with FFmpeg 3.1 and OpenCV 3.1.

Once the dependencies are visible to g++, run:

make     # to build mpegflow
make vis # to build vis

You will probably end up with a shared build, for static build, please feel free to play with Makefile.

You may use wigwam to install them to a local directory (no root required):

wigwam init
wigwam install opencv ffmpeg
wigwam in

To build the tools on Windows:

  1. Create directory dependencies
  2. Extract FFmpeg dev and shared builds to the dependencies directory (for mpegflow and vis)
  3. Extract an OpenCV 3.x build to the dependencies directory (for vis)
  4. Open VS2015 x64 Native Tools Command Prompt (VS2015 Community Edition will work) and run:
# fix the paths and versions before running

nmake mpegflow.exe FFMPEG_DIR=dependencies\ffmpeg-3.0.1-win64-dev\ffmpeg-3.0.1-win64-dev
# nmake vis.exe OPENCV_DIR=dependencies\opencv-3.1.0\opencv\build\x64\vc14
  1. The Windows build is not fully static. You need to keep avutil-54.dll, avformat-56.dll, avcodec-56.dll, swresample-2.dll (for mpegflow) and opencv_world310.dll (for vis) in the same directory as the binary. Note that the instructions and the Makefile assume x64 machine architecture.