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. Default build system used by this Makefile is [Ninja](https://ninja-build.org/). If you want to build only specific version use `make [version]`, where inplace of `version` use one the following:
  55
  56 |Version| Description |
  57 | --- | --- |
  58 | `opencvfft-st` | OpenCV FFT single threaded version|
  59 | `opencvfft-async` | OpenCV FFT multithreaded version using C++ async directive|
  60 | `fftw` | FFTW FFT single threaded version|
  61 | `fftw_openmp` | FFTW FFT multithreaded version using OpenMP|
  62 | `fftw_async` | FFTW FFT multithreaded version using C++ async directive|
  63 | `fftw_big` | FFTW FFT single threaded version using Big batch mode|
  64 | `fftw_big_openmp` | FFTW FFT multithreaded version using Big batch mode|
  65 | `cufftw` | CuFFTW version|
  66 | `cufftw_big` | CuFFTW version using Big batch mode|
  67 | `cufftw_big_openmp` | CuFFTW version using Big batch mode and OpenMP multithreading to get maximal response|
  68 | `cufft` | CuFFT FFT version|
  69 | `cufft_big` | CuFFT FFT version using Big batch mode|
  70 | `cufft_big_openmp` | CuFFT FFT version using Big batch mode and OpenMP multithreading to get maximal response|
  71
  72
  73 This code compiles into binary **kcf_vot**
  74
  75 ## Usage
  76 `./kcf_vot [options] <path/to/region.txt or groundtruth.txt> <path/to/images.txt> [path/to/output.txt]`
  77 - using [VOT 2014 methodology](http://www.votchallenge.net/)
  78 - to get dataset used in VOT go [here](http://www.votchallenge.net/vot2016/dataset.html)
  79  - INPUT : expecting two files, images.txt (list of sequence images with absolute path) and
  80            region.txt with initial bounding box in the first frame in format "top_left_x, top_left_y, width, height" or
  81            four corner points listed clockwise starting from bottom left corner.
  82  - OUTPUT : output.txt containing the bounding boxes in the format "top_left_x, top_left_y, width, height"
  83  -There are also multiple additional terminal `[options]`, which you can use:
  84 |Option| Description |
  85 | --- | --- |
  86 | `--visualize | -v [delay_ms]` | Visualize the output with specified delay. If the delay is set to 0 the output file will stay until the user presses any button.|
  87 | `---output | -o <outout.txt>` | Specifies output file.|
  88 | `--debug | -d` | Additional debugging output.|
  89 | `--fit | -f [dimensions]` | Specifies dimension to which the extracted patch should be scaled. It should be divisible by 4, which is the size of the HOG cell. You can either input single dimension, which will result in in the other both dimensions being the same. Or both dimensions in the form of: `[X dimension]X[Y dimension]`.|
  90
  91 ## Author
  92 * **Karafiát Vít**, **Sojka Michal**
  93
  94 ## References
  95
  96 [1] João F. Henriques, Rui Caseiro, Pedro Martins, Jorge Batista, “High-Speed Tracking with Kernelized Correlation Filters“,
  97 IEEE Transactions on Pattern Analysis and Machine Intelligence, 2015
  98 _____________________________________
  99 Copyright (c) 2014, Tomáš Vojíř
 100
 101 Permission to use, copy, modify, and distribute this software for research
 102 purposes is hereby granted, provided that the above copyright notice and
 103 this permission notice appear in all copies.
 104
 105 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 106 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 107 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 108 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 109 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 110 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 111 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.