tracktorlive 1.0.2

Real-time low-cost animal tracking and response delivery.

TracktorLive v1.0.2 ('Clytemnestra')

TracktorLive is a real-time video tracking and data serving framework designed for lightweight, scriptable tracking of individual animals in behavioral experiments. It provides programmatic hooks for processing and responding to tracked data on-the-fly, with no interaction needed with actual computer vision code.

The video tracking used in this project emerges from Tracktor::

Sridhar, V. H., Roche, D. G., & Gingins, S. (2019). Tracktor: Image-based automated tracking of animal movement and behaviour. Methods in Ecology and Evolution, 10(6), 815–820. DOI:10.1111/2041-210X.13166"

TracktorLive builds on that work, enabling real-time tracking and response delivery.

---

✨ Features

• Real-time tracking of 1 or more individuals from real-time camera feed or pre-recorded video sources
• Buffered data sharing via shared memory (suitable for high-speed use)
• Modular "cassette" system for on-the-fly processing
• Built-in support for:
  • Data streaming to external clients
  • Live or on-demand video and data recording
• A number of useful tutorial scripts and a growing library of cassettes, through which even novice users can quickly create and run scripts.
• Minimal external dependencies (NumPy, OpenCV, Scikit-Learn etc.)

---

🧠 Concept

TracktorLive works on a server--client model, where:

• A server processes a video stream and maintains a shared data buffer with clock and tracked locations.
• One or more clients can connect and access this data in real time.
• Small, user-defined functions ("cassettes") can be registered to run every frame or at server shutdown.
• This way, all tracking and multiprocessing happens in the background allowing users without computer vision experience to directly get involved with such experimental setups.

All interaction is via the use of cassettes. Cassettes are designed to be readily copied into scripts. New cassettes can be written easily by anyone with basic knowledge of Python. We also suggest the TracktorLive Cassette Maker GPT, an openAI customGPT. However, this is not an official part of the software and our providing this link must not be seen as an endorsement of this company. The idea for including a customGPT comes from Dr. Aiswarya Prasad.

---

📦 Installation

TracktorLive is mainly targeted towards Linux-like environments. However, it works (and has been tested) on MacOS and Windows. If you are already using a Linux system, you can run

pip install tracktorlive

For usage Windows (through Windows Subsystem for Linux, WSL) see DOCS. We do not currently support TracktorLive for real-time use on MacOS.

---

🔁 Example: Print current location of animal

import tracktorlive as trl

server, semm = trl.spawn_trserver("video.mp4", params, n_ind=1, buffer_size=1, realtime=False)
client = trl.spawn_trclient(server.feed_id)

@client
def printloc(data, clock):
    pos = data[0,:,-1]
    print(clock[-1], ":", pos)
    

run_trsession(server, semm, client)

Here is the basic structure of a TracktorLive script:

import json
import tracktorlive as trl

with open("params.json") as jsonf:
    params = json.load(jsonf)
FEED_ID = "trial-feed"

server, semm = trl.spawn_trserver(0, params, feed_id=FEED_ID)

# SERVER CASETTES WILL GO HERE
# THOSE WILL TAKE CARE OF VIDEO PROCESSING ETC

client = trl.spawn_trclient(feed_id=FEED_ID) #optional

# OPTIONALLY:
# CLIENT CASETTES WILL GO HERE
# THOSE WILL TAKE CARE OF RESPONSE DELIVERY

trl.run_trsession(server, semm, client)

🧪 Real-world Use Cases

We provide eight complete tutorials to demonstrate the capabilities of this software. See out list of tutorials to know more.

While these are the uses we have explored so far, we encourage users to try more things. We have discussed as potential future applications, e.g., 3D tracking using 3 cameras, and camera control to select recording device based on individual's location.

📬 Status

TracktorLive is a still an evolving toolkit. APIs may change slightlly. You're encouraged to adapt parts for your own research or build wrappers that suit your workflow.

For questions or bugs, feel free to open an issue or reach out directly.