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