README.md

   1 # KCF tracker – parallel and PREM implementations
   2
   3 The goal of this project is modify KCF tracker for use in the
   4 [HERCULES][1] project, where it will run on NVIDIA TX2 board. To
   5 achieve the needed performance we try various ways of parallelization
   6 of the algorithm including execution on the GPU. The aim is also to
   7 modify the code according to the PRedictable Execution Model (PREM).
   8
   9 Stable version of the tracker is available from a [CTU server][2],
  10 development happens at GitHub [here][wsh] and [here][3].
  11
  12 [1]: http://hercules2020.eu/
  13 [2]: http://rtime.felk.cvut.cz/gitweb/hercules2020/kcf.git
  14 [wsh]: https://github.com/wentasah/kcf
  15 [3]: https://github.com/Shanigen/kcf
  16
  17 ## Prerequisites
  18
  19 The code depends on OpenCV 2.4 library
  20 and [CMake][13] (optionally with [Ninja][8]) is used for building.
  21 Depending on the version to be compiled you need to have development
  22 packages for [FFTW][4], [CUDA][5] or [OpenMP][6] installed.
  23
  24 On TX2, the following command should install what's needed:
  25 ``` shellsession
  26 $ apt install cmake ninja-build libopencv-dev libfftw3-dev
  27 ```
  28
  29 [4]: http://www.fftw.org/
  30 [5]: https://developer.nvidia.com/cuda-downloads
  31 [6]: http://www.openmp.org/
  32 [13]: https://cmake.org/
  33
  34 ## Compilation
  35
  36 There are multiple ways how to compile the code.
  37
  38 ### Compile all supported versions
  39
  40 ``` shellsession
  41 $ git submodule update --init
  42 $ make -k
  43 ```
  44
  45 This will create several `build-*` directories and compile different
  46 versions in them. If prerequisites of some builds are missing, the
  47 `-k` option ensures that the errors are ignored. This uses [Ninja][8]
  48 build system, which is useful when building naively on TX2, because
  49 builds with `ninja` are faster (better parallelized) than with `make`.
  50
  51 To build only a specific version run `make <version>`. For example,
  52 CUDA-based version can be compiled with:
  53
  54 ``` shellsession
  55 $ make cufft
  56 ```
  57
  58 [8]: https://ninja-build.org/
  59
  60 ### Using cmake gui
  61
  62 ```shellsession
  63 $ git submodule update --init
  64 $ mkdir build
  65 $ cmake-gui .
  66 ```
  67
  68 - Use the just created build directory as "Where to build the
  69   binaries".
  70 - Press "Configure".
  71 - Choose desired build options. Each option has a comment briefly
  72   explaining what it does.
  73 - Press "Generate" and close the window.
  74
  75 ```shellsession
  76 $ make -C build
  77 ```
  78 ### Command line
  79
  80 ```shellsession
  81 $ git submodule update --init
  82 $ mkdir build
  83 $ cd build
  84 $ cmake [options] ..  # see the tables below
  85 $ make
  86 ```
  87
  88 The `cmake` options below allow to select, which version to build.
  89
  90 The following table shows how to configure different FFT
  91 implementations.
  92
  93 |Option| Description |
  94 | --- | --- |
  95 | `-DFFT=OpenCV` | Use OpenCV to calculate FFT.|
  96 | `-DFFT=fftw` | Use fftw and its `plan_many` and "New-array execute" functions. If `std::async`, OpenMP or cuFFTW is not used the plans will use 2 threads by default.|
  97 | `-DFFT=cuFFTW` | Use cuFFTW interface to cuFFT library.|
  98 | `-DFFT=cuFFT` | Use cuFFT. This version also uses pure CUDA implementation of `ComplexMat` class and Gaussian correlation.|
  99
 100 With all of these FFT version additional options can be added:
 101
 102 |Option| Description |
 103 | --- | --- |
 104 | `-DASYNC=ON` | Use C++ `std::async` to run computations for different scales in parallel. This doesn't work with `BIG_BATCH` mode.|
 105 | `-DBIG_BATCH=ON` | Concatenate matrices of different scales to one big matrix and perform all computations on this matrix. This mode doesn't work with `OpenCV` FFT.|
 106 | `-DOPENMP=ON` | Parallelize certain operation with OpenMP. This can only be used with `OpenCV` or `fftw` FFT implementations. By default it runs computations for differenct scales in parallel. With `-DBIG_BATCH=ON` it parallelizes the feature extraction and the search for maximal response for differenct scales. With `fftw`, Ffftw's plans will execute in parallel.|
 107 | `-DCUDA_DEBUG=ON` | Adds calls cudaDeviceSynchronize after every CUDA function and kernel call.|
 108 | `-DOpenCV_DIR=/opt/opencv-3.3/share/OpenCV` | Compile against a custom OpenCV version. |
 109
 110
 111 ### Compilation for non-TX2 CUDA
 112
 113 The CuFFT version is set up to run on NVIDIA Jetson TX2. If you want
 114 to run it on different architecture, change the `--gpu-architecture
 115 sm_62` NVCC flag in **/src/CMakeLists.txt** to your architecture of
 116 NVIDIA GPU. To find what SM variation you architecture has look
 117 [here][9].
 118
 119 [9]: http://arnon.dk/matching-sm-architectures-arch-and-gencode-for-various-nvidia-cards/
 120
 121 ## Running
 122
 123 No matter which method is used to compile the code, the results will
 124 be `kcf_vot` binary.
 125
 126 It operates on an image sequence created according to [VOT 2014
 127 methodology][10]. You can find some image sequences in [vot2016
 128 datatset][11].
 129
 130 The binary can be run as follows:
 131
 132 1. `./kcf_vot [options]`
 133
 134    The program looks for `groundtruth.txt` or `region.txt` and
 135    `images.txt` files in current directory.
 136
 137    - `images.txt` contains a list of images to process, each on a
 138      separate line.
 139    - `groundtruth.txt` contains the correct location of the tracked
 140      object in each image as four corner points listed clockwise
 141      starting from bottom left corner. Only the first line from this
 142      file is used.
 143    - `region.txt` is an alternative way of specifying the location of
 144      the object to track via its bounding box (top_left_x, top_left_y,
 145      width, height) in the first frame.
 146
 147 2. `./kcf_vot [options] <directory>`
 148
 149    Looks for `groundtruth.txt` or `region.txt` and `images.txt` files
 150    in the given `directory`.
 151
 152 3. `./kcf_vot [options] <path/to/region.txt or groundtruth.txt> <path/to/images.txt> [path/to/output.txt]`
 153
 154 By default the program generates file `output.txt` containing the
 155 bounding boxes of the tracked object in the format "top_left_x,
 156 top_left_y, width, height".
 157
 158 [10]: http://www.votchallenge.net/
 159 [11]: http://www.votchallenge.net/vot2016/dataset.html
 160
 161 ### Options
 162
 163 | Options | Description |
 164 | ------- | ----------- |
 165 | --visualize, -v[delay_ms] | Visualize the output, optionally with specified delay. If the delay is 0 the program will wait for a key press. |
 166 | --output, -o <output.txt>      | Specify name of output file. |
 167 | --debug, -d                            | Generate debug output. |
 168 | --fit, -f[W[xH]] | Specifies the dimension to which the extracted patch should be scaled. It should be divisible by 4. No dimension or zero rounds the dimensions to the nearest smaller power of 2, a single dimension `W` will result in patch size of `W`×`W`. |
 169
 170
 171 ## Authors
 172 * Vít Karafiát, Michal Sojka
 173
 174 Original C++ implementation of KCF tracker was written by Tomas Vojir
 175 [here][12] and is reimplementation of algorithm presented in
 176 "High-Speed Tracking with Kernelized Correlation Filters" paper \[1].
 177
 178 [12]: https://github.com/vojirt/kcf/blob/master/README.md
 179
 180 ## References
 181
 182 \[1] João F. Henriques, Rui Caseiro, Pedro Martins, Jorge Batista,
 183 “High-Speed Tracking with Kernelized Correlation Filters“, IEEE
 184 Transactions on Pattern Analysis and Machine Intelligence, 2015
 185
 186 ## License
 187
 188 Copyright (c) 2014, Tomáš Vojíř\
 189 Copyright (c) 2018, Vít Karafiát\
 190 Copyright (c) 2018, Michal Sojka
 191
 192 Permission to use, copy, modify, and distribute this software for research
 193 purposes is hereby granted, provided that the above copyright notice and
 194 this permission notice appear in all copies.
 195
 196 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 197 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 198 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 199 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 200 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 201 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 202 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.