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][iig].
  11
  12 [1]: http://hercules2020.eu/
  13 [2]: http://rtime.felk.cvut.cz/gitweb/hercules2020/kcf.git
  14 [iig]: https://github.com/CTU-IIG/kcf
  15 [3]: https://github.com/Shanigen/kcf
  16
  17 <!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
  18 **Table of Contents**
  19
  20 - [Prerequisites](#prerequisites)
  21 - [Compilation](#compilation)
  22     - [Compile all supported versions](#compile-all-supported-versions)
  23     - [Using cmake gui](#using-cmake-gui)
  24     - [Command line](#command-line)
  25 - [Running](#running)
  26     - [Options](#options)
  27 - [Automated testing](#automated-testing)
  28 - [Authors](#authors)
  29 - [References](#references)
  30 - [License](#license)
  31
  32 <!-- markdown-toc end -->
  33
  34
  35 ## Prerequisites
  36
  37 The code depends on OpenCV (version 2.4 or 3.x) library. [CMake][13]
  38 (optionally with [Ninja][8]) is used for building. Depending on the
  39 version to be compiled you need to have development packages for
  40 [FFTW][4], [CUDA][5] or [OpenMP][6] installed.
  41
  42 On TX2, the following command should install what's needed:
  43 ``` shellsession
  44 $ apt install cmake ninja-build libopencv-dev libfftw3-dev
  45 ```
  46
  47 [4]: http://www.fftw.org/
  48 [5]: https://developer.nvidia.com/cuda-downloads
  49 [6]: http://www.openmp.org/
  50 [13]: https://cmake.org/
  51
  52 ## Compilation
  53
  54 There are multiple ways how to compile the code.
  55
  56 ### Compile all supported versions
  57
  58 ``` shellsession
  59 $ git submodule update --init
  60 $ make -k
  61 ```
  62
  63 This will create several `build-*` directories and compile different
  64 versions in them. If prerequisites of some builds are missing, the
  65 `-k` option ensures that the errors are ignored. This uses [Ninja][8]
  66 build system, which is useful when building naively on TX2, because
  67 builds with `ninja` are faster (better parallelized) than with `make`.
  68
  69 To build only a specific version run `make <version>`. For example,
  70 CUDA-based version can be compiled with:
  71
  72 ``` shellsession
  73 $ make cufft
  74 ```
  75
  76 [8]: https://ninja-build.org/
  77
  78 ### Using cmake gui
  79
  80 ```shellsession
  81 $ git submodule update --init
  82 $ mkdir build
  83 $ cmake-gui .
  84 ```
  85
  86 - Use the just created build directory as "Where to build the
  87   binaries".
  88 - Press "Configure".
  89 - Choose desired build options. Each option has a comment briefly
  90   explaining what it does.
  91 - Press "Generate" and close the window.
  92
  93 ```shellsession
  94 $ make -C build
  95 ```
  96 ### Command line
  97
  98 ```shellsession
  99 $ git submodule update --init
 100 $ mkdir build
 101 $ cd build
 102 $ cmake [options] ..  # see the tables below
 103 $ make
 104 ```
 105
 106 The `cmake` options below allow to select, which version to build.
 107
 108 The following table shows how to configure different FFT
 109 implementations.
 110
 111 |Option| Description |
 112 | --- | --- |
 113 | `-DFFT=OpenCV` | Use OpenCV to calculate FFT.|
 114 | `-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.|
 115 | `-DFFT=cuFFTW` | Use cuFFTW interface to cuFFT library.|
 116 | `-DFFT=cuFFT` | Use cuFFT. This version also uses pure CUDA implementation of `ComplexMat` class and Gaussian correlation.|
 117
 118 With all of these FFT version additional options can be added:
 119
 120 |Option| Description |
 121 | --- | --- |
 122 | `-DBIG_BATCH=ON` | Concatenate matrices of different scales to one big matrix and perform all computations on this matrix. This improves performance of GPU FFT offloading. |
 123 | `-DOPENMP=ON` | Parallelize certain operation with OpenMP. With `-DBIG_BATCH=OFF` it runs computations for differenct scales in parallel, with `-DBIG_BATCH=ON` it parallelizes the feature extraction, which runs on the CPU. With `fftw`, Ffftw's plans will execute in parallel.|
 124 | `-DCUDA_DEBUG=ON` | Adds calls cudaDeviceSynchronize after every CUDA function and kernel call.|
 125 | `-DOpenCV_DIR=/opt/opencv-3.3/share/OpenCV` | Compile against a custom OpenCV version. |
 126 | `-DASYNC=ON` | Use C++ `std::async` to run computations for different scales in parallel. This mode of parallelization was present in the original implementation. Here, it is superseeded with -DOPENMP. This doesn't work with `BIG_BATCH` mode.|
 127
 128 See also the top-level `Makefile` for other useful cmake parameters
 129 such as extra compiler flags etc.
 130
 131 ## Running
 132
 133 No matter which method is used to compile the code, the result will be
 134 a `kcf_vot` binary.
 135
 136 It operates on an image sequence created according to [VOT 2014
 137 methodology][10]. You can find some image sequences in [vot2016
 138 datatset][11].
 139
 140 The binary can be run as follows:
 141
 142 1. `./kcf_vot [options]`
 143
 144    The program looks for `groundtruth.txt` or `region.txt` and
 145    `images.txt` files in current directory.
 146
 147    - `images.txt` contains a list of images to process, each on a
 148      separate line.
 149    - `groundtruth.txt` contains the correct location of the tracked
 150      object in each image as four corner points listed clockwise
 151      starting from bottom left corner. Only the first line from this
 152      file is used.
 153    - `region.txt` is an alternative way of specifying the location of
 154      the object to track via its bounding box (top_left_x, top_left_y,
 155      width, height) in the first frame.
 156
 157 2. `./kcf_vot [options] <directory>`
 158
 159    Looks for `groundtruth.txt` or `region.txt` and `images.txt` files
 160    in the given `directory`.
 161
 162 3. `./kcf_vot [options] <path/to/region.txt or groundtruth.txt> <path/to/images.txt> [path/to/output.txt]`
 163
 164 By default the program generates file `output.txt` containing the
 165 bounding boxes of the tracked object in the format "top_left_x,
 166 top_left_y, width, height".
 167
 168 [10]: http://www.votchallenge.net/
 169 [11]: http://www.votchallenge.net/vot2016/dataset.html
 170
 171 ### Options
 172
 173 | Options | Description |
 174 | ------- | ----------- |
 175 | --fit, -f[W[xH]] | Specifies the dimension to which the extracted patches should be scaled. Best performance is achieved for powers of two; the smaller number the higher performance but worse accuracy. 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`. The numbers should be divisible by 4. |
 176 | --visualize, -v[delay_ms] | Visualize the output, optionally with specified delay. If the delay is 0 the program will wait for a key press. |
 177 | --output, -o <output.txt>      | Specify name of output file. |
 178 | --debug, -d                            | Generate debug output. |
 179 | --visual_debug, -p[p|r] | Show graphical window with debugging information (either **p**atch or filter **r**esponse). |
 180
 181 ## Automated testing
 182
 183 The tracker comes with a test suite based on [vot2016 datatset][11].
 184 You can run the test suite as follows:
 185
 186     make vot2016  # This download the datased (about 1GB of data)
 187         make test
 188
 189 The above command run all tests in parallel and displays the results
 190 in a table. If you want to measure performance, do not run multiple
 191 tests together. This can be achieved by:
 192
 193         make build.ninja
 194         ninja -j1 test
 195
 196 You can test only a subset of builds or image sequences by setting
 197 BUILDS, TESTSEQ or TESTFLAGS make variables. For instance:
 198
 199         make build.ninja BUILDS="cufft cufft-big fftw" TESTSEQ="bmx ball1"
 200         ninja test
 201
 202
 203
 204
 205 ## Authors
 206 * Vít Karafiát, Michal Sojka
 207
 208 [Original C++ implementation of the KCF tracker][12] was written by
 209 Tomas Vojir and is reimplementation of the algorithm presented in
 210 "High-Speed Tracking with Kernelized Correlation Filters" paper \[1].
 211
 212 [12]: https://github.com/vojirt/kcf/blob/master/README.md
 213
 214 ## References
 215
 216 \[1] João F. Henriques, Rui Caseiro, Pedro Martins, Jorge Batista,
 217 “High-Speed Tracking with Kernelized Correlation Filters“, IEEE
 218 Transactions on Pattern Analysis and Machine Intelligence, 2015
 219
 220 ## License
 221
 222 Copyright (c) 2014, Tomáš Vojíř\
 223 Copyright (c) 2018, Vít Karafiát\
 224 Copyright (c) 2018, Michal Sojka
 225
 226 Permission to use, copy, modify, and distribute this software for research
 227 purposes is hereby granted, provided that the above copyright notice and
 228 this permission notice appear in all copies.
 229
 230 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 231 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 232 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 233 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 234 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 235 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 236 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 237
 238 <!-- Local Variables: -->
 239 <!-- markdown-toc-user-toc-structure-manipulation-fn: cdr -->
 240 <!-- End: -->