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