AMADEUS

AMADEUS detects oriented bounding boxes (OBBs), estimates head direction, and tracks individual identities. It learns from the input video using self-supervised learning, without manual training annotation.

AMADEUS 1.0.0

What AMADEUS does

No manual training annotation

Training images and labels are generated automatically from the input video after you configure foreground segmentation.

Batch processing

Configure segmentation, then specify the animal count, overlap severity, and whether animals move backward. Training and tracking then run automatically.

Graphical user interface

Use the graphical interface to configure segmentation, run processing stages, and review and correct tracking results.

Position and direction estimation

Each animal is represented by an oriented bounding box (OBB) enclosing its body, together with its head direction.

Robust to interactions

Training on synthetic interaction images supports tracking during crossings and crowding.

Works with diverse videos

AMADEUS can analyze laboratory videos of diverse species.

Workflow

Prepare the video with Cropping & Trimming, if needed.
Configure Segmentation so the animals are extracted cleanly.
Run training and tracking with Easy Tracking.
Check the result video and CSV, and correct them in Refinement if needed.

Use Advanced Tracking to configure individual stages and Multi Config Batch to run several configurations in sequence. To run training and tracking on a Google Colab GPU, save your configuration and open Colab (beta) from the Home screen.

Read the manual

Install and launch

Download and run the installer for your operating system. Git is not required. On macOS, a compatible Python installation is required as described below.

Windows10 / 11 macOSApple Silicon LinuxUbuntu / WSL2

AMADEUS has not yet been extensively tested on macOS or Linux. If you encounter an error, please contact Yusuke Notomi at jpmyrmecol [at] gmail.com and include your operating system, installation method, and the error message.

The installer downloads AMADEUS and prepares the required environment, then opens the Home screen. An internet connection is required. Windows and Linux launchers also prepare Python automatically.

How to open the downloaded file

Windows: double-click AMADEUS-Setup.bat. For subsequent launches, you can also use the AMADEUS desktop shortcut.

macOS: open AMADEUS-Setup.command. A downloaded file may not have permission to run. If needed, type chmod +x in Terminal, drag the downloaded file into the Terminal window, press Enter, and open the file again. If macOS blocks opening it, check System Settings → Privacy & Security.

Linux: allow execution as a program in the file properties, then choose to run AMADEUS-Setup.sh in a terminal. Names and actions vary by desktop environment. A graphical desktop or WSLg is required.

On macOS, install a native Apple Silicon version of Python 3.10–3.12 with Tcl/Tk 8.6 before launching AMADEUS. Tcl/Tk 9 is not supported by the current GUI dependencies. To select another installation, set AMADEUS_PYTHON to the full path of its Python executable. To use a separate environment, set AMADEUS_VENV to its directory. See the macOS setup instructions.

On macOS and Linux, run the same downloaded launcher for subsequent sessions. It uses the existing AMADEUS installation.

Install using Git (Windows, macOS, Linux)

Windows macOS Linux

Windows

With Git installed, open Command Prompt (cmd) in your preferred installation directory and run this one line (Windows 10 / 11). The directory must not already contain an AMADEUS folder.

git clone https://github.com/jpmyrmecol/AMADEUS.git && cd AMADEUS && AMADEUS.bat

The launcher automatically prepares uv, Python, and the required packages, then opens the home screen. Initial setup requires an internet connection.

For subsequent launches, open a new Command Prompt and run the following. Keep the created AMADEUS folder in place.

amadeus

macOS (Apple Silicon)

With Git installed, run the following command in a terminal in the directory where you want to install AMADEUS.

git clone https://github.com/jpmyrmecol/AMADEUS.git && cd AMADEUS && bash AMADEUS.sh

The supplied environment targets Apple Silicon. Intel Macs are not supported by the bundled PyTorch 2.7.1 configuration. Launch without Rosetta.

Open AMADEUS.command. If permission to run the file is denied, run chmod +x AMADEUS.command AMADEUS.sh in Terminal in the AMADEUS folder.

AMADEUS uses MPS when available and CPU otherwise. MPS and the full workflow on actual macOS hardware have not been validated.

To use amadeus / amade from Terminal, add ~/.local/bin to PATH. See the instructions shown at startup for setup. Read any error messages in Terminal.

Linux (Ubuntu / WSL2)

With Git installed, run the following command in a terminal in the directory where you want to install AMADEUS.

git clone https://github.com/jpmyrmecol/AMADEUS.git && cd AMADEUS && bash AMADEUS.sh

Run bash AMADEUS.sh in the AMADEUS folder. A GUI display environment, such as a desktop session or WSLg, is required.

If errors related to Tk, OpenCV, or shared libraries occur, check the missing component reported in the terminal. CUDA is used with a supported NVIDIA GPU; otherwise CPU is used.

To launch with amadeus or amade, add ~/.local/bin to PATH. Linux x86_64 CPU environment setup has been verified, but the full workflow with real video and Linux ARM hardware have not been validated.

Install from a downloaded ZIP

Download from GitHub using “Code → Download ZIP”, extract the archive, and start the launcher for your operating system.

OS	Launcher
Windows 10 / 11	Double-click `AMADEUS.bat`
macOS (Apple Silicon)	Open `AMADEUS.command`
Ubuntu / WSL2	Run `bash AMADEUS.sh`

Recommended recording conditions

AMADEUS learns directly from the input videos, so tracking performance depends on recording conditions. The following conditions are recommended.

A sufficiently elongated body shape to define a body axis, with visually distinguishable front and rear.
A fixed camera viewing the animals from above, with movement approximately confined to a two-dimensional plane.
Stable illumination, an essentially static background, and sufficient contrast between the animals and the background.
Sufficient spatial resolution, frame rate, and shutter speed for reliable visual tracking in each frame.
Sufficient periods in which animals are separated from one another. Images of isolated individuals are used to generate training data.

Training and analysis videos may be recorded separately, provided that the recording conditions are the same.

Citation

See the Publication page for the preprint DOI and recommended citation format.

Please also cite the address of this site: https://amadeus.jpmyrmecol.com/

License

AMADEUS is released under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). Third-party components keep their own licenses, listed in the third-party notices distributed with the software.