Animapp documentation

Installation

Installation can be done using conda or pip. However, conda is strongly recommended. Some familiarity with the commandline could come in handy - this is the Terminal in MacOS and Linux, and the Anaconda Prompt in Windows.

Requirements

  • Operating system - Animapp has been tested on Windows 10, MacOS High Sierra, and Ubuntu Linux 19.10
  • Miniconda3 - A python 3 environment is required, which can be set up using Miniconda (see below)
  • Hardware - The OpenCV library is large and takes up a lot of space after installation. The entire Animapp environment needs ~1.5 GB, which should not be difficult in most systems. Other than this, any reasonably modern laptop or home PC should be able to run Animapp.

Install conda

You can skip this section if you already have conda (Anaconda or Miniconda) installed on your system. To install conda, go to the Miniconda website and install Miniconda3 (python 3) by following the instructions specific to your operating system. Conda can also be installed with Anaconda but this is not required to run Animapp.

Conda channels

Add the conda-forge channel using conda config:

conda config --add channels conda-forge

Virtual environment

It is highly recommended that you install Animapp within a virtual environment to ensure that all the dependencies are satisfied, and also to keep your python setup organised. For example, to create an environment named animapp_env, type the following at the commandline:

conda create -n animapp_env

Install Animapp

First activate the newly created channel:

conda activate animapp_env

Then install the Animapp package:

conda install -c sraorao animapp

That’s it! Check that the installation is working by trying these at the commandline. You should see a short message on usage:

threshold -h
animapp -h

Operating systems

Animapp has been tested on

  • Ubuntu Linux 18.04
  • MacOS High Sierra
  • Windows 10

Settings

The threshold program needs to be run first to create the settings.yaml file in the current working directory. The animapp program quits with an error if it cannot find this file. If for some reason you cannot run threshold first, you can manually create the settings.yaml file in the current directory with the following text (e.g. copy-pasting into Notepad), but change the values after the colon (:) as needed, depending on your video:

leftcorner: (0, 0)
rightcorner: (640, 480)
angle: 0
hue: (0, 179)
sat: (0, 254)
val: (0, 35)
ratio: 0.3333333333333333
startframe: 0

Support

If this documentation does not answer your question, please open an issue on the GitHub page. This makes it easier for me to keep track of questions/requests/bugs.

Citation

If you use this software, please cite our paper:

Rao, S.R., Olechnowicz, S.W.Z., Krätschmer, P. et al. Small Animal Video Tracking for Activity and Path Analysis Using a Novel Open-Source Multi-Platform Application (AnimApp). Sci Rep 9, 12343 (2019). https://doi.org/10.1038/s41598-019-48841-7

Changelog

Version 0.1.5.6

  • Installation moved to conda which is similar across all common platforms
  • Added graphical interface, so there is no commandline interaction now (except when starting the app)
  • Analysis unchanged, EXCEPT that all videos are now resized to 640 width (aspect ratio preserved)
  • Added docs
  • Added a diagnostic plot to post-processing

What is Animapp?

Animapp is a cross-platform package to analyse the movement of an object in a video. It leverages the powerful OpenCV framework to analyse videos and extract position information in each frame. This an be used in the field of biological research to track the movement of small animals and measure parameters such as distance and velocity.

Quick-start

Installation

This is described in detail on the Installation page:

conda config --add channels conda-forge
conda create -n animapp_env
conda activate animapp_env
conda install -c sraorao animapp

threshold
animapp

Videos

Animapp recognises files of the most common video formats (.mp4, .mkv, .avi) at a resolution of 640x480 or higher. In the current version, the videos are downsampled to 640x480. This may not be good if the object to be tracked in the video is too small relative to the field of view. If you are unsure, it may just be easier to give it a try.

Thresholding

_images/threshold.png

The threshold program must be used first to record the following settings in a file named settings.yaml in the working directory. This file may be manually created, but has to exist before proceeding to the next step of analysis.

  • hue, saturation, value - set using the double sliders at the top of the threshold window
  • starting frame - set using the slider (useful when initial setup in the video interferes with object detection)
  • rotation - clockwise or anti-clockwise, set using numberbox at the bottom of the window
  • crop - left click and drag on the colour image to draw green rectangle denoting crop area

If you have a number of videos to analyse, running threshold on any one exemplar video is sufficient, as long as the camera setup does not change between videos. If the camera type, orientation, illumination in the room, etc. change between videos, the threshold values are no longer valid (and it may also mean that the videos are not comparable, obviously!). Hence it is essential to keep all the video variables consistent among all the videos that are being analysed.

Analysis

_images/animapp.png

Finally, run the animapp program to analyse the video(s) of interest. Click on the Load video button to select the video (use ctrl+click to select multiple videos) and on the Run video to start the analysis. Wait for the video(s) to stop running in the window, this may take a while if you have a large number of videos but you can leave it unattended. Once that is finished (you should see .csv files corresponding to each video in the same folder as the videos), click on the Process results button to post-process the results. This will give you another file with the suffix _processed.csv, and a pdf file.

Results

Three files are created in the same folder as the video, at the end of the analysis and post-processing.

_images/diagnostic_plot.png

.csv file

The raw .csv (Comma Separated Values) file contains the following columns (in that order):

  1. x coordinate
  2. y coordinate
  3. Frame number
  4. Bounding box coordinate
  5. Bounding box coordinate
  6. Bounding box coordinate
  7. Bounding box coordinate
  8. Bounding box angle

Only columns 1-3 are used for post-processing, but the bounding box parameters are there to be analysed if they are of interest.

_processed.csv file

Some frames may be missing in the raw csv (e.g. the frame number may jump from 5 to 10) due to aggressive thresholding or because the object is not in the field of the camera. These frames are then not recorded at all and the rows corresponding to those frames are missing. In these cases, the missing frames are filled in with the last recorded frame (in order to keep the distance accurate). This may seem like the object remained stationary for a long time, and then moved a long distance within a short time. If the number of missing frames is small, the estimated distance and velocity may not be far from the truth, but keep an eye out for the object being ‘lost’ in a large number of frames. The processed csv has the following columns in that order:

  1. x coordinate
  2. y coordinate
  3. Frame number
  4. Distance from the previous location (summing this column will give you total distance travelled in the entire video)
  5. Rolling velocity - Rolling velocity is the distance travelled per 10 frames (NA for the first and last 10 frames)

.pdf file

This is a trace of the object’s movement. This is only a diagnostic plot to quickly identify problems with thresholding. Better plots can be generated using several packages in software such as Python and R.