DORIS user guide

DORIS is an easy-to-use interactive object detection and tracking software with a Graphical User Interface. DORIS is a free and open-source software available for GNU/Linux, Windows and Mac OS.

version 2022.12.19


This is an ALPHA release. Use it for testing and report bugs and suggestions.

This project was inspired by the Tracktor project:



Install DORIS

DORIS can be downloaded from the GiHub repository

All versions (Windows and Mac) are portable, they do not need to be installed on your system.

All previous versions of DORIS are available in the GitHub repository.


DORIS run with Python >= 3.8

  • Create a virtual environment (to isolate DORIS and dependencies from your system):
python3 -m venv doris_venv
  • Activate the virtual environment
source doris_venv/bin/activate

The prompt should now be prefixed by doris_venv

  • Install DORIS
pip install doris-tracker
  • Launch DORIS
python3 -m doris


Download the file, unzip it and launch start_doris.bat.

Mac OS

Download the doris-x.y.z.dmg image file, mount it and launch the DORIS program.

How to run a tracking project with DORIS step by step

In order to demonstrate the use of DORIS we will set a tracking project. This tracking project aims to track 3 ants during 1 minute trying to maintain individuality.

A video tutorial is available at (no audio).

After launching DORIS you should see the main window.

DORIS main window

Open a video

File > Open a video

The video will be loaded and the first frame will be displayed in the Original frame window (left window). Another window called Processed frame will also be displayed (right window).

video loaded

A directory of images (from time lapse experiments for example) can also be used for tracking project: File > Load directory of images

Frame processing

The Processed frame window displays the frame after conversion to binary image (b/w), application of a blur filter and eventually conversion to negative.

In this example we apply a simple threshold method to convert the grayscale image (values from 1 to 255) to binary (0 or 1). Another threshold methods are available: Adaptive thresholding (mean) and Adaptive thresholding (Gaussian). See the OpenCV documentation for details.

DORIS will detect the white objects in the Processed frame window.

In this case you will have to check the Invert checkbox to convert to negative. The dark objects will be displayed in white and the light objects in black:

Blur and Invert filters DORIS main window

The dark objects (like ants) are now displayed in white on the Processed frame window.

The Filtered objects list and the Original frame window display all the 60 filtered objects:

Filtered objects

The value of the Blur filter can be increased in order to simplify the objects.

Blur and Invert filters

Applying a value of 5 to the Blur filter decrease the number of filtered objects to 25.

Arena definition

An arena can be defined in order to limit the objects tracking to the objects detected inside the arena.

Define arena button > Circle arena (3 points)

Click on the video to define 3 points. The circular arena will pass through these 3 points.

Blur and Invert filters

The arena can be defined with a rectangle, a circle (using center - radius) or a polygon.

Objects size

The object detection can be limited to objects included in a size interval (area).

Some detected objects are very small:

Filtered objects

By setting the minimum object size to 100 px the number of detected objects decreases to 3.

Oobjects size Filtered objects

This matches with the 3 ants we want to track:

3 ants

Save project

The project can be saved on a file (.doris) in order to reopen it with al parameters already set. **File* > Save project

Selection of objects to track

If you want to track all the filtered object click the Track all filtered objects button. Otherwise if you want to track fewer objects click the Select objects to track button, then select the object number to track:

objects selection objects selection

Origin definition (not mandatory)

The origin of the referential system of coordinates can be defined.

Define origin button > Origin from a point

You will have to select the origin point on the video frame.

Origin of referential system

The X axis extends from left to right. The Y axis extends from top to bottom.

If an origin is defined the coordinates of the tracked objects will refer to this origin. Otherwise the origin is set in the upper-left corner of the frame.

Scale definition (not mandatory)

A scale can be defined in order to obtain values with a real unit (m, cm, mm …).

Define scale button

You will have to define a segment (by clicking 2 points on the video frame) matching a reference of known size.

Scale definition

In this example the block has a length of 20 mm.

If a scale is defined the coordinates will be defined applying the scale. In this example in millimeters.

Record coordinates of tracked objects

Check the Record coordinates checkbox

record coordinates

Record presence of the tracked objects in areas

Select the Objects in areas tab and check the Record presence of objects in areas checkbox

You will have to define all the areas (rectangle, circle or polygon) using the Add area button.

In this example 5 areas were defined:

area center

Run tracking

Click the Run tracking button

The tracking process will start. The tracked objects will be displayed on the Original frame window.

The coordinates of tracked objects are displayed in the Objects position list.

The presence of tracked objects in the defined areas are displayed in the Presence of objects in areas list.

The tracking can be run only on a frame interval with the Run trackin on frames interval button.

The tracking can be hidden to speed up the process: uncheck the Display analysis checkbox.



This 3rd column will contain the frame number and the following columns the x,y coordinates of the various tracked objects.

The coordinates can be saved in a TSV file with the Save objects positions button.

The coordinates can be plotted:

  • Plot path button.
  • Plot position button.
Plot path

The presence density can be plotted:

Plot path

The total distances for every tracked objects can be exported in a TSV file with the Distances button:


Presence in areas

  • The presence of objects in areas can be exported with the Save results button.
  • The time in areas for every tracked objects can be exported with the Time in areas button:
Time in areas