Skip to content

DREEM Relates Every Entity's Motion

CI codecov code Release PyPI

Welcome to the documentation for DREEM – an open-source tool for multiple object tracking. It enables you to track identities of objects in video data. You can run tracking using our pretrained models for animals and microscopy, or train a new model on your own data. In either case, DREEM takes in detection outputs in the form of pose keypoints or segmentation masks, and outputs identities of objects in the video. For an interactive demo, visit our Hugging Face demo page.

$ uv venv && source .venv/bin/activate
$ uv pip install dreem-track
$ dreem track ./data --checkpoint ./models/pretrained.ckpt --output ./results --crop-size 128
Running tracking...
---> 100%
Tracking complete! Results saved to results/

Key Features

  • ✅ Command-Line & API Access: Use DREEM via a simple CLI or integrate into your own Python scripts.
  • ✅ Pretrained Models: Get started quickly with models trained for microscopy and animal domains. Available on Hugging Face.
  • ✅ Configurable Workflows: Easily customize training and inference using YAML configuration files.
  • ✅ Visualization: Visualize tracking results in your browser without any data leaving your machine, or use the SLEAP GUI for a more detailed view.
  • ✅ Examples: Step-by-step notebooks and guides for common workflows.

Installation

Head over to the Installation Guide to get started.

Quickstart

Ready to try DREEM? Follow the Quickstart Guide to:

  1. Download example datasets and pretrained models
  2. Run tracking on sample videos
  3. Visualize your results

Example Workflows

Explore the Examples section for notebooks that walk you through the DREEM pipeline. We have an end-to-end demo that includes model training, as well as a microscopy example that shows how to use DREEM with an off-the-shelf detection model.

Documentation Structure

Get Help

  • Questions? Open an issue on GitHub.