Logo

Getting Started

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites
This algorithm is intended for processing videos recorded during experiments with head-restrained rodents, focused on their whiskers.

Using it on videos where the head of the rodent is moving freely will not provide accurate results and may even cause the program to crash. In addition, the background of the video should be stable for the whole duration of whisker-tracking, meaning that only whiskers should ideally be moving, while no lighting conditions are altered or external objects are moving.

Pre-Installation
Install: CUDA - OpenCV with CUDA support - OpenBLAS (or LAPACK) - Qt5

The project has only been tested on Ubuntu, CUDA-capable, systems thus far. This means that, in order to run WhiskEras 2.0 you will need a linux system and a CUDA-capable GPU, if you are going to use a GPU at all.

  1. Install CUDA. WhiskEras 2.0 has been tested to work with CUDA 11.2. CUDA 10.2 was tested to work too, but then the CUB library will have to be downloaded and linked manually where appropriate.
  2. Install OpenCV with CUDA support. An example guide can be found here. WhiskEras 2.0 has been tested to work with OpenCV 4.2.2 and 4.5.2.
  3. Install OpenBLAS (or LAPACK). From an Ubuntu terminal

    sudo apt-get install libopenblas-dev # option 1 # or sudo apt-get install libblas-dev liblapack-dev # option 2

  4. Intall Qt5.

    sudo apt-get install qt5-default

The rest of the packages have been provided in libs directory.


Installation
There are two ways to run WhiskEras 2.0

Either you can directly run the pre-built binary executable, or build it yourself. You can try to directly run the executable, but if some required package is missing from your system, it will probably not run. In that case, it is better to try and build it, see the errors and address them correspondingly.

Run the binary only:

  1. Download just the file WhiskEras_GUI in the bin directory of the repository.
  2. Go to the directory of the file and open a terminal in that directory (right-click on the directory, Open From Terminal).
  3. Change permissions of the binary to make it executable

    chmod +x WhiskEras_GUI

  4. Run the executable

    ./WhiskEras_GUI

Build and run:

  1. Open a terminal. Clone the repo

    git clone https://gitlab.com/neurocomputing-lab/whisker/whiskeras-2.0

  2. In case you are going to use a CUDA-capable GPU, the default CUDA directory is /usr/local/cuda. If this is not the case for your system, modify the line below in WhiskEras_GUI.pro file:

    CUDA_DIR = /usr/local/cuda

  3. Build the project using QMake and Make

    cd whiskeras-2.0 # go to the project's directory
    mkdir build && cd build
    qmake ..
    make -j <N> # replace <N> with a number of threads that your CPU supports

  4. Run the executable

    ./WhiskEras_GUI