T TRACE Docs

Temporal action detection for animal behavior

TRACE

Pair untrimmed lab videos with annotation files, train temporal behavior detectors, and use them to draft annotations for new videos.

Start Here View Source

Quick Start

Install TRACE and launch the annotator.

Create a Python 3.9+ environment with conda, mamba, or uv before installing TRACE from PyPI. Training, evaluation, and prediction require a CUDA-capable PyTorch environment; the annotator app can run without local model jobs. 

# conda
conda create -n trace-tad python=3.11 pip
conda activate trace-tad

# mamba
mamba create -n trace-tad python=3.11 pip
mamba activate trace-tad

# uv
uv venv --python 3.11 --seed .venv
source .venv/bin/activate

python -m pip install trace-tad
trace prepare --weights all
trace app

Workflow

From labeled video to predictions.

01

Annotate

Open the TRACE app, choose a video directory, and save annotation CSVs beside each source video. One video can have multiple CSVs.

02

Train

Choose the video/annotation pairs for the run. TRACE prepares PTS-aligned clips and writes a timestamped model artifact directory.

03

Evaluate

Reuse the training dataset or pass a new set of video/annotation pairs to score a trained model on held-out recordings.

04

Predict

Run a trained model against new videos and write prediction CSVs that reviewers can use as draft annotation files.

Training Data

Use explicit video and annotation pairs.

The annotation CSV format is time-based. Each row maps a behavior label to start and end times in seconds. A single source video can have multiple CSVs, and each training pair chooses which annotation file to use. 

labelId,timestamp,endTimestamp
grooming,12.430,18.970
rearing,42.100,45.650

UI + CLI

Generate reproducible commands from the app.

You can annotate in the browser, select video/annotation pairs in the UI, and copy the matching CLI command for training, evaluation, prediction, or a full pipeline run. 

trace train --model large \
  --work-dir /data \
  --pairs video01.mp4=video01_final.csv

CLI Reference

Core commands.

Command Purpose Example
trace prepare Download local model weights. trace prepare --weights all
trace update Check PyPI for a newer TRACE package. trace update
trace app Start the production annotation server. trace app --host 0.0.0.0 --port 8000
trace train Prepare selected video/annotation pairs and train a small or large model. trace train --model large --work-dir /data --pairs video01.mp4=video01_final.csv
trace eval Evaluate a trained model, optionally on new paired data. trace eval --model-dir /data/model_YYYYMMDD_HHMMSS
trace predict Predict new videos and write draft annotation CSVs. trace predict --model-dir /data/model_YYYYMMDD_HHMMSS --input /data/video03.mp4
trace pipeline Run configured train, predict, and export workflows. trace pipeline configs/small.py --export csv

Artifacts

Model runs are self-contained.

Training creates model_YYYYMMDD_HHMMSS/ under --work-dir. TRACE records the generated dataset.json, classmap.txt, selected config, and checkpoint files so later eval and predict commands can resolve the same model bundle.

best.pth classmap.txt config.txt dataset.json eval_YYYYMMDD_HHMMSS/

Public Notes

What this page publishes.

The public site intentionally keeps the surface small: installation, workflow, CLI usage, artifact layout, and deployment status. Internal engineering notes can stay local until they are ready to publish.

Install

Package installation and model-weight preparation commands.

Annotate

How saved CSV annotations pair behavior labels with timestamps.

Train

Explicit video/annotation pair examples for reproducible model runs.

Evaluate

Model artifact directories and evaluation entry points.

Predict

Prediction commands that create draft annotation files for new recordings.

Deploy

GitHub Pages deployment from the curated public docs artifact.

GitHub Pages

Ready to publish from docs/.

This repository now includes a Pages workflow that deploys this static documentation site. After the workflow runs on main, the project docs are expected at kunmings.github.io/TRACE.

Open Actions