README.md

   1 # KCF tracker-FFT versions
   2 This project aims to test multiple implementation of calculating Fast Fourier Transform(FFT) and Inverse Fourier Transform(IFFT) in KFC tracker and to see how the performance changes depending on the implementation.
   3
   4 C++ implementation of KCF tracker was written by Tomas Vojir [here](https://github.com/vojirt/kcf/blob/master/README.md) and is reimplementation of algorithm presented in "High-Speed Tracking with Kernelized Correlation Filters" paper[1].
   5
   6 ### Prerequisites
   7 The code depends on OpenCV 2.4+ library and build via cmake toolchain. Depending on the version selected you have to have installed [FFTW](http://www.fftw.org/), [CUDA](https://developer.nvidia.com/cuda-downloads) or [OpenMP](http://www.openmp.org/).
   8
   9 SSE instructions were used in the original code and these are only supported on x86 architecture. Thanks to the [SSE2NEON](https://github.com/jratcliff63367/sse2neon) code, we now support both ARM and x86 architecture.
  10
  11 ## Getting Started
  12 Open terminal in the directory with the code:
  13 Using cmake gui:
  14 ________________
  15 ```
  16 $ mkdir build
  17 $ cmake-gui //Select the directory path and build directory. After which you can choose desired build option.
  18             //Each option has comment explaining briefly what it does.
  19 $ make
  20 ```
  21 Without cmake gui:
  22 ___________________
  23 ```
  24 $ mkdir build
  25 $ cd build
  26 $ cmake {OPTIONS} ..
  27 ```
  28
  29 The following table shows multiple options how to run cmake to get different version of the tracker. Following table shows FFT options available.
  30
  31 |Option| Description |
  32 | --- | --- |
  33 | `-DFFT=OpenCV` | OpenCV version of FFT.|
  34 | `-DFFT=fftw` | Fftw version of FFT using plan many and new execute functions.|
  35 | `-DFFT=cuFFTW` | cuFFT version using FFTW interface.|
  36 | `-DFFT=cuFFT` | cuFFT version of FFT. This version also uses pure CUDA for ComplexMat class and Gaussian correlation.|
  37
  38 With all of these FFT version aditional options can be added:
  39
  40 |Option| Description |
  41 | --- | --- |
  42 | `-DASYNC=ON` | Adds C++ async directive. It is used to compute response maps for all scales in parallel. Doesn't work with big batch mode.|
  43 | `-DOPENMP=ON` | Fftw version of FFT using plan many and new execute functions. If not selected with big batch mode, it also is used to compute all reposne maps for all scales in parallel. If used with big batch mode it parallelize extraction of feaures for all scales and selection of scale with highest reponse.|
  44 | `-DBIG_BATCH=ON` | Enables big batch mode, which creates one big matrix from all scales and computes them together. This mode doesn't work for OpenCV FFT.|
  45 | `-DCUDA_DEBUG=ON` | This mode adds CUDA error checking for all kernels and CUDA runtime libraries. Only works with cuFFT version.|
  46
  47 Finally call make:
  48 ```
  49 $ make
  50 ```
  51
  52 There is also Makefile located in main directory. It will build all possible versions, with all possible combination of additional options (except for CUDA_DEBUG). Each version will have build directory named after it. Build system used is [Ninja](https://ninja-build.org/).
  53
  54 This code compiles into binary **kcf_vot**
  55
  56 ./kcf_vot [-v[delay\_ms]]
  57 - using [VOT 2014 methodology](http://www.votchallenge.net/)
  58 - to get dataset used in VOT go [here](http://www.votchallenge.net/vot2016/dataset.html)
  59  - INPUT : expecting two files, images.txt (list of sequence images with absolute path) and
  60            region.txt with initial bounding box in the first frame in format "top_left_x, top_left_y, width, height" or
  61            four corner points listed clockwise starting from bottom left corner.
  62  - OUTPUT : output.txt containing the bounding boxes in the format "top_left_x, top_left_y, width, height"
  63
  64
  65
  66 ## Author
  67 * **Karafiát Vít**, **Sojka Michal**
  68
  69 ## References
  70
  71 [1] João F. Henriques, Rui Caseiro, Pedro Martins, Jorge Batista, “High-Speed Tracking with Kernelized Correlation Filters“,
  72 IEEE Transactions on Pattern Analysis and Machine Intelligence, 2015
  73 _____________________________________
  74 Copyright (c) 2014, Tomáš Vojíř
  75
  76 Permission to use, copy, modify, and distribute this software for research
  77 purposes is hereby granted, provided that the above copyright notice and
  78 this permission notice appear in all copies.
  79
  80 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  81 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  82 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  83 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  84 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  85 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  86 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.