Sinapsis Trackers

Mono repo with modular packages for multi-object tracking using advanced algorithms.

🐍 Installation • 📦 Packages • 🌐 Webapps • 📙 Documentation • 🔍 License

🐍 Installation

This mono repo consists of modular packages for implementing and visualizing multi-object tracking using various tracking algorithms and models:

• sinapsis-cotracker
• sinapsis-supervision

Install using your package manager of choice. We encourage the use of uv

sinapsis-cotracker

Warning

cotracker dependency is required to install sinapsis-cotracker

UV instructions

Install cotracker in your working environment as follows:

uv pip install git+https://github.com/facebookresearch/co-tracker.git

then install sinapsis-cotracker

uv pip install sinapsis-cotracker --extra-index-url https://pypi.sinapsis.tech

Raw pip instructions

Install cotracker in your working environment as follows:

pip install git+https://github.com/facebookresearch/co-tracker.git

then install sinapsis-cotracker

pip install sinapsis-cotracker --extra-index-url https://pypi.sinapsis.tech

sinapsis-supervision

UV instructions

Install sinapsis-supervision

uv pip install sinapsis-supervision --extra-index-url https://pypi.sinapsis.tech

Raw pip instructions

Install sinapsis-supervision

pip install sinapsis-supervision --extra-index-url https://pypi.sinapsis.tech

(Optional) Install packages with all additional dependencies

Important

Templates in each package may require extra dependencies. For development, we recommend installing the package with all the optional dependencies:

  uv pip install sinapsis-cotracker[all] --extra-index-url https://pypi.sinapsis.tech

  uv pip install sinapsis-supervision[all] --extra-index-url https://pypi.sinapsis.tech

or with raw pip:

  pip install sinapsis-cotracker[all] --extra-index-url https://pypi.sinapsis.tech

  pip install sinapsis-supervision[all] --extra-index-url https://pypi.sinapsis.tech

Tip

You can also install all the packages within this project:

  uv pip install sinapsis-tracker[all] --extra-index-url https://pypi.sinapsis.tech

📦 Packages

This repository is organized into modular packages, each designed for specific integration with different tracking models, including CoTracker and ByteTrack. These packages provide ready-to-use templates for applications like object tracking, multi-object tracking, and result visualization in real-time or offline.

Below is an overview of the available packages:

Sinapsis Cotrackers

This sinapsis package provides a robust implementation for multi-object tracking with the Facebook Research's Co-Tracker model. It includes:

• Templates for multi-object tracking using Co-Tracker, offering flexible offline, online, and visualization modes.
• Efficient processing and visualization of tracking results directly on video frames for clear output.
• Tools for handling dynamic tracking across frames, including padding, line width, and trace settings.

For specific instructions and further details, see the README.md.

Sinapsis Supervision

This Sinapsis package provides a comprehensive solution for object tracking with the ByteTrack algorithm. It includes:

• A template for object tracking using ByteTrack, designed to handle real-time multi-object tracking in videos.
• Detection processing and updates with configurable parameters for track activation, matching, and occlusion handling, improving accuracy and stability.

For more details, see the README.md.

For more details, see the official documentation

🌐 Webapps

The webapps included in this project showcase the modularity of the templates, in this case for multi-object tracking and visualization tasks.

Important

To run the app, you first need to clone this repo:

git clone git@github.com:Sinapsis-ai/sinapsis-trackers.git
cd sinapsis-trackers

Note

If you'd like to enable external app sharing in Gradio, export GRADIO_SHARE_APP=True

Note

Agent configuration can be updated through the AGENT_CONFIG_PATH environment var. You can check the available configurations in each package configs folder.

🐳 Docker

IMPORTANT: This Docker image depends on the sinapsis-nvidia:base image. For detailed instructions, please refer to the Sinapsis README.

1. Build the sinapsis-trackers image:

docker compose -f docker/compose.yaml build

2. Start the container:

For sinapsis-cotracker

docker compose -f docker/compose_tracker.yaml up sinapsis-cotracker-gradio -d

For sinapsis-supervision with default bytetrack-ultralytics demo

docker compose -f docker/compose_tracker.yaml up sinapsis-supervision-gradio -d

For sinapsis-supervision with bytetrack-dfine demo

export DFINE_CONFIG_DOWNLOAD=True
export AGENT_CONFIG_PATH=/app/sinapsis_supervision/configs/bytetrack_dfine_demo.yml
docker compose -f docker/compose_tracker.yaml up sinapsis-supervision-gradio -d

3. Check the status:

For sinapsis-cotracker

docker logs -f sinapsis-cotracker-gradio

For sinapsis-supervision

docker logs -f sinapsis-supervision-gradio

4. The logs will display the URL to access the webapp, e.g.,:

Running on local URL:  http://127.0.0.1:7860

NOTE: The local URL can be different, please check the logs

5. To stop the app:

docker compose -f docker/compose_tracker.yaml down

📦 UV

To run the webapp using the uv package manager, please:

1. Create the virtual environment and sync the dependencies:

uv sync --frozen --extra cotracker

2. Install the sinapsis-trackers package:

uv pip install sinapsis-trackers[all] --extra-index-url https://pypi.sinapsis.tech

3. Run the webapp:

For demo running default cotracker-online agent config.

uv run webapps/tracking_demo.py

For demo running bytrack-ultralytics agent config.

export AGENT_CONFIG_PATH="packages/sinapsis_supervision/src/sinapsis_supervision/configs/bytetrack_ultralytics_demo.yml"
uv run webapps/tracking_demo.py

For demo running bytrack-dfine agent config.

export DFINE_CONFIG_DOWNLOAD=True
export AGENT_CONFIG_PATH="packages/sinapsis_supervision/src/sinapsis_supervision/configs/bytetrack_dfine_demo.yml"
uv run webapps/tracking_demo.py

4. The terminal will display the URL to access the webapp, e.g.:

Running on local URL:  http://127.0.0.1:7860

NOTE: The local URL can be different, please check the output of the terminal.

📙 Documentation

Documentation is available on the sinapsis website

Tutorials for different projects within sinapsis are available at sinapsis tutorials page

🔍 License

This project is licensed under the AGPLv3 license, which encourages open collaboration and sharing. For more details, please refer to the LICENSE file.

For commercial use, please refer to our official Sinapsis website for information on obtaining a commercial license.