YORU Tracker

YORU Tracker is multi-animal tracking for YORU. YORU detects animals and behaviours in every frame; YORU Tracker gives each animal a persistent ID across frames, draws its trajectory, and exports per-animal tracks — live from a camera, from a video, or for a whole folder of videos.

It is a sister application, not a YORU plugin: it has its own window and its own command, and the normal YORU application is unchanged by it. It uses YORU’s detectors through YORU’s public API, so every model YORU can load — YOLOv5 checkpoints from YORU v1, YOLOv8 / YOLO11, RT-DETR, torchvision, ONNX, oriented boxes included — works here without conversion.

Versions

The full change list is in the CHANGELOG.

Features

• Persistent identities. Every animal keeps one ID from frame to frame, through crossings, contacts and short detector misses.
• Three workflows in one window. Realtime Tracking (camera), Video Tracking (one video, frame by frame) and Batch Tracking (a whole folder).
• Any YORU model. Detection goes through YORU’s detector registry, so the models you trained in YORU work as they are.
• Re-track in seconds. The detector’s output is saved; after changing the tracker settings, a video is tracked again without running the model or a GPU.
• Track YORU’s own recordings. YORU’s video-analysis CSV and real-time *_detect.csv can be tracked afterwards.
• Known number of animals. Tell the tracker how many animals are in view (for example, a pair of flies in a chamber) and it never invents or retires an ID.
• Reproducible. The same detections and settings always give the same IDs, and every tracks CSV comes with a JSON file that records everything needed to reproduce it.
• Light enough for closed loops. The Lite tracker runs no neural network of its own and takes about 0.1–0.5 ms per frame for a few animals.
• Command line. Everything the window does for videos and folders can be run headless.

Quick install

YORU Tracker needs a YORU checkout next to it. The Install guide has the details.

YORU-dev/
├── YORU/            # https://github.com/Kamikouchi-lab/YORU
└── YORU-Tracker/    # https://github.com/Kamikouchi-lab/YORU-Tracker

1. Install uv and Git.

   Windows (PowerShell):

    winget install --id=astral-sh.uv -e
   

2. Clone both repositories into one folder.

    mkdir YORU-dev
    cd YORU-dev
    git clone -b v2.0.0-beta.4 https://github.com/Kamikouchi-lab/YORU.git
    git clone -b v0.1.0 https://github.com/Kamikouchi-lab/YORU-Tracker.git
   

   YORU Tracker needs YORU 2.0.0 Beta 4 or later, the first YORU release with the external API YORU Tracker uses. v2.0.0-beta.4 is also the YORU version YORU Tracker’s CI tests against.

3. Build the environment. This installs YORU (editable, from ../YORU) with its CUDA build of PyTorch, then YORU Tracker on top.

    cd YORU-Tracker
    uv sync
   

4. Launch YORU Tracker.

    uv run yoru-tracker
   

Quick start

In the window. uv run yoru-tracker opens the start screen, which offers the three workflows and the tracker settings:

From the command line.

uv run yoru-tracker track movie.mp4 --model best.pt --out results/            # detect + track
uv run yoru-tracker track movie.mp4 --model best.pt --out results/ --render   # + overlay video
uv run yoru-tracker track results/movie_detections.csv --config two_flies.yaml # re-track, no GPU
uv run yoru-tracker batch videos/ --model best.pt --out results/
uv run yoru-tracker config > tracker.yaml                                      # default settings

For movie.mp4 you get movie_tracks.csv (one row per track per frame), movie_tracks.json (how to reproduce it) and movie_detections.csv (the detector’s output, for re-tracking). See Output Files.

Learn about YORU Tracker

• User Guides — every screen, setting and file, one page each

• Step-by-step Protocols — from a YORU model to an analysed tracks table

• Tracker Settings — which settings to change, and when

• Development notes — the Python tracker API, plugins and testing

• Q and A

Requirements

OS

• Windows 10 or later. YORU Tracker is developed for Windows, and its CI runs on Windows. Other platforms that YORU supports are untested.

Hardware

• The detector is YORU’s, and has YORU’s needs: an NVIDIA GPU is recommended for detection, with driver 570 or newer for the CUDA 12.8 build of PyTorch that YORU v2.0.0-beta.4 uses. See YORU’s requirements.
• Tracking itself runs on the CPU and is light. Re-tracking stored detections needs no GPU at all.

Software

• Python 3.10. uv installs it for you.
• uv and Git.
• A YORU checkout (≥ 2.0.0b4, < 3) beside the YORU Tracker folder.

Status

Implemented (v0.1.0): application, GUI and command line; YORU detector integration; tracker API; Lite tracker with motion prediction, gating, IoU and axis cost, Hungarian assignment, recovery, lifecycle and known-population mode; video, realtime and batch tracking; CSV export with reproducibility metadata; metrics and benchmark.

Next: explicit occlusion state for Lite (detecting merged boxes), then the Advanced tracker (appearance-based re-identification when identities are ambiguous), then offline refinement (gap filling, smoothing).

Reference

YORU Tracker builds on YORU. If you use it in your research, please cite YORU:

• Hayato M. Yamanouchi et al., YORU: Animal behavior detection with object-based approach for real-time closed-loop feedback. Sci. Adv. 12, eadw2109 (2026). DOI: 10.1126/sciadv.adw2109

License

AGPL-3.0-or-later, as YORU. See the LICENSE file for details.