main

:book: Docs | :tv: YouTube | :scroll: License AGPL v3+ (free).

:office: Company use requires a paid commercial license — contact us at [email protected]

Hey there

Welcome to the git repository of TRex (https://trex.run) -- a software designed to track and identify individuals and other moving entities using computer vision and machine learning.

TRaditionally, using background-subtraction, TRex can track 256 fish faster than the video plays back, and for up to 100 individuals allows you to visually recognize individuals and automatically correct potential tracking errors using machine-learning based automatic classification.

Since version 2.0, TRex also supports machine-learning based detection models. Out of the box we support models compatible with the ultralytics (https://github.com/ultralytics) package, like YOLO. All common tasks, such as bounding-boxes, oriented bounding-boxes, keypoints, and segmentation as well as offering simple SAHI-like features (https://github.com/obss/sahi). This replaces background subtraction in situations where it is not sufficient - you can bring your own .pt model, of course!

It allows you, from the same interface, to load up existing videos or record directly from your webcam. Camera support (and other things) can be extended for other APIs with a bit of C++ or Python knowledge, of course.

Installation

TRex supports all major platforms. Miniforge is the main package repository used for installing/building TRex. Simply follow the instructions here for installing miniforge: https://github.com/conda-forge/miniforge#download. You can then create a new virtual environment (named tracking here) by running:

Windows, Linux (NVIDIA graphics card recommended), macOS (Intel / ARM64)

conda create -n tracking -c trexing trex

Usage

Within the conda environment, simply run:

trex

To convert a video to our custom pv format from the command-line:

trex -i /full/path/to/video.mp4 -o funny_name

This will output to /full/path/to/video.pv. If you want to change the output destination root, add -d /output/path.

Opening a video directly and adjusting parameters:

trex -i /full/path/to/video.mp4 -track_threshold 25 -track_max_individuals 10

If you don't want a graphical user interface and save/quit when tracking finishes, add -nowindow and -auto_quit:

trex -i /full/path/to/video.mp4 -nowindow -auto_quit

Read more about parameters for TRex here.

Contributors, Issues, etc.

This project has been developed, is still being updated, by Tristan Walter. If you want to contribute, please submit a pull request on GitHub and I will be happy to credit you here, for any substantial contributions!

If you have any issues running the software please consult the documentation first (especially the FAQ section) and if this does not solve your problem, please file an issue using the issue tracker here on github. If you experience problems with PyTorch, such as installing CUDA or cuDNN dependencies, then please direct issues to those development teams.

Significant contributions by: Angela Albi

License

Released under the GNU Affero General Public License v3.0 or later (see LICENSE and LICENSING.md). The Application/src/commons subtree continues to ship under the GNU General Public License v3.0 (see Application/src/commons/LICENSE for details).

Reference

If you use this software in your work, please cite our open-access paper:

@article {walter2020trex,
  article_type = {journal},
  title = {TRex, a fast multi-animal tracking system with markerless identification, and 2D estimation of posture and visual fields},
  author = {Walter, Tristan and Couzin, Iain D},
  editor = {Lentink, David},
  volume = 10,
  year = 2021,
  month = {feb},
  pub_date = {2021-02-26},
  pages = {e64000},
  citation = {eLife 2021;10:e64000},
  doi = {10.7554/eLife.64000},
  url = {https://doi.org/10.7554/eLife.64000},
  journal = {eLife},
  issn = {2050-084X},
  publisher = {eLife Sciences Publications, Ltd},
}