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 The CuFFT version is set up to run on NVIDIA Jetson TX2. If you want to run it on different architecture, change the `--gpu-architecture sm_62` NVCC flag in **/src/CMakeLists.txt** to your architecture of NVIDIA GPU. To find what SM variation you architecure has please visit http://arnon.dk/matching-sm-architectures-arch-and-gencode-for-various-nvidia-cards/.
  12
  13 ## Getting Started
  14 Open terminal in the directory with the code:
  15 Using cmake gui:
  16 ________________
  17 ```
  18 $ mkdir build
  19 $ cmake-gui //Select the directory path and build directory. After which you can choose desired build option.
  20             //Each option has comment explaining briefly what it does.
  21 $ make
  22 ```
  23 Without cmake gui:
  24 ___________________
  25 ```
  26 $ mkdir build
  27 $ cd build
  28 $ cmake {OPTIONS} ..
  29 ```
  30
  31 The following table shows multiple options how to run cmake to get different version of the tracker. Following table shows FFT options available.
  32
  33 |Option| Description |
  34 | --- | --- |
  35 | `-DFFT=OpenCV` | OpenCV version of FFT.|
  36 | `-DFFT=fftw` | Fftw version of FFT using plan many and new execute functions.|
  37 | `-DFFT=cuFFTW` | cuFFT version using FFTW interface.|
  38 | `-DFFT=cuFFT` | cuFFT version of FFT. This version also uses pure CUDA for ComplexMat class and Gaussian correlation.|
  39
  40 With all of these FFT version aditional options can be added:
  41
  42 |Option| Description |
  43 | --- | --- |
  44 | `-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.|
  45 | `-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.|
  46 | `-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.|
  47 | `-DCUDA_DEBUG=ON` | This mode adds CUDA error checking for all kernels and CUDA runtime libraries. Only works with cuFFT version.|
  48
  49 Finally call make:
  50 ```
  51 $ make
  52 ```
  53
  54 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/).
  55
  56 This code compiles into binary **kcf_vot**
  57
  58 ./kcf_vot [-v[delay\_ms]]
  59 - using [VOT 2014 methodology](http://www.votchallenge.net/)
  60 - to get dataset used in VOT go [here](http://www.votchallenge.net/vot2016/dataset.html)
  61  - INPUT : expecting two files, images.txt (list of sequence images with absolute path) and
  62            region.txt with initial bounding box in the first frame in format "top_left_x, top_left_y, width, height" or
  63            four corner points listed clockwise starting from bottom left corner.
  64  - OUTPUT : output.txt containing the bounding boxes in the format "top_left_x, top_left_y, width, height"
  65
  66
  67
  68 ## Author
  69 * **Karafiát Vít**, **Sojka Michal**
  70
  71 ## References
  72
  73 [1] João F. Henriques, Rui Caseiro, Pedro Martins, Jorge Batista, “High-Speed Tracking with Kernelized Correlation Filters“,
  74 IEEE Transactions on Pattern Analysis and Machine Intelligence, 2015
  75 _____________________________________
  76 Copyright (c) 2014, Tomáš Vojíř
  77
  78 Permission to use, copy, modify, and distribute this software for research
  79 purposes is hereby granted, provided that the above copyright notice and
  80 this permission notice appear in all copies.
  81
  82 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  83 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  84 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  85 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  86 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  87 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  88 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.