trace-tad 0.2.0

TRACE: Temporal action detection for animal behavior analysis

TRACE — Temporal Recognition of Animal Behaviors Captured from Video

TRACE is a temporal action detection system for animal behavior analysis in untrimmed video.

Documentation

Project docs are set up for GitHub Pages at kunmings.github.io/TRACE. The public site source lives in site/, separate from local engineering notes in docs/.

Install

python -m pip install trace-tad

For a local checkout:

pip install -e .

Training, evaluation, and prediction require a CUDA-capable PyTorch environment. The annotation app can still be used for labeling workflows without running model jobs locally.

Usage

# Prepare local model weights used by the packaged configs
trace prepare --weights all

# Check whether PyPI has a newer TRACE release
trace update

# Start the bundled annotation app
trace app

# Train from selected video/annotation pairs
trace train --model large --work-dir /my/dataset --pairs video01.mp4=video01_final.csv video02.mp4=video02.csv

# Evaluate the training artifact, or evaluate on held-out video/annotation pairs
trace eval --model-dir /my/dataset/model_YYYYMMDD_HHMMSS
trace eval --model-dir /my/dataset/model_YYYYMMDD_HHMMSS --work-dir /my/testset --pairs video03.mp4=video03.csv

# Predict on new videos and write annotation drafts
trace predict --model-dir /my/dataset/model_YYYYMMDD_HHMMSS --input /path/to/video.mp4 --annotated-video --threshold 0.25

# Run a configured end-to-end workflow
trace pipeline configs/small.py --export csv

You can stay in the UI for annotation and still keep training or inference reproducible from the command line. The app lets you choose video/annotation pairs, configure model runs, and generate the matching CLI command, so a lab operator can annotate in the browser while a server or batch job runs the generated trace train, trace eval, trace predict, or trace pipeline command.

--pairs is explicit: each item is VIDEO_PATH=CSV_PATH. A source video can have multiple annotation CSVs beside it, such as video01_draft.csv, video01_final.csv, or a model-generated video01_predictions.csv; each training or evaluation pair chooses the annotation file to use for that video. Relative paths are resolved against --work-dir, so video01.mp4=video01_final.csv means both files are inside the work directory. Training creates a self-contained model_YYYYMMDD_HHMMSS/ folder under --work-dir.

TRACE annotation CSVs are time-based:

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

Prediction creates a predict_YYYYMMDD_HHMMSS/ folder beside the selected input video or input video directory, unless --output is provided. The CSV output uses the annotation format, so a reviewer can treat model predictions as draft annotation files. Use --annotated-video to render MP4 overlays with the same confidence threshold as the JSON/CSV outputs.

Development

# Start backend and Vite dev servers
trace dev serve

# Build the frontend and bundle it into the Python package
trace dev build-frontend

The committed public website in site/ is intentionally small and publishable; deeper engineering notes stay under docs/.

License

Apache 2.0. See LICENSE.