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