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