Metadata-Version: 2.5
Name: blobtrack
Version: 1.1.7
Summary: Real-time motion blob tracker with a Dear PyGui interface
Project-URL: Homepage, https://rilerialabs.onrender.com/
Project-URL: Repository, https://github.com/rileriaaa/blobtrack
Author: rileriaaa
License: MIT
Keywords: computer-vision,dearpygui,motion-tracking,opencv
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.8
Requires-Dist: dearpygui>=1.10
Requires-Dist: imageio-ffmpeg>=0.4.9
Requires-Dist: numpy>=1.20
Requires-Dist: opencv-python>=4.5
Description-Content-Type: text/markdown

# BlobTrack

A real-time motion blob tracker built with Dear PyGui and OpenCV. Load any video file (or a live camera feed), and BlobTrack detects moving objects via background subtraction, then overlays customizable bounding shapes, labels, and network-style connection lines between detected blobs.

![Python](https://img.shields.io/badge/python-3.8+-blue)
![License](https://img.shields.io/badge/license-MIT-green)

## Features

- **Live motion detection** using MOG2 background subtraction
- **Customizable overlays** — square/circle/no outline, adjustable size, thickness, and color per blob
- **Bounding box filters** — apply Invert, Blur, Pixelate, Thermal, or Edge effects inside each detected region
- **Mesh connection lines** — link each blob to its *k* nearest neighbors with distance-based fade, for a network/web visualization
- **Adjustable playback speed** (1x–2x) for file sources
- **Live Resolution scaling** (Native/75%/50%/25%) to trade preview quality for performance without affecting export quality
- **Video export/recording** — save the processed feed (with all overlays) to `.mp4`, always at full native resolution regardless of preview settings
- **Fullscreen toggle** and a responsive video panel that resizes cleanly with the window

## Installation

Install as an isolated CLI tool with [pipx](https://pypa.github.io/pipx/) (recommended):

```bash
pipx install blobtrack
```

Or with pip into your own environment:

```bash
pip install blobtrack
```

## Usage

Run with no arguments and use the **Load** button to pick a video file:

```bash
blobtrack
```

Or pass a video path or camera index directly:

```bash
blobtrack --source path/to/video.mp4
blobtrack --source 0   # webcam
```

## Controls

| Control | Description |
|---|---|
| **Minimum Area** | Filters out blobs smaller than this pixel area |
| **Max Blobs** | Caps how many blobs are tracked per frame |
| **Shape** | Bounding shape drawn around each blob (Square / Circle / None) |
| **Bounding Size / Thickness** | Size and stroke width of the bounding shape |
| **Connection Lines** | Toggles mesh-style lines between nearby blobs |
| **Nearest Neighbors** | How many neighbors each blob connects to |
| **Bounding Box Filter** | Visual effect applied inside each bounding box |
| **Font Size** | Size of the confidence-score label per blob |
| **Bounding Box / Connection Line Color** | Preset colors or a custom color picker |
| **Playback Speed** | Preview and export playback rate (locked during recording) |
| **Live Resolution** | Preview processing resolution (export always stays native) |
| **Record** | Opens a save dialog to choose where to export the processed feed, then starts/stops recording |
| **Save Preset** | Opens a save dialog to save your current settings (thresholds, shape, filter, colors, speed, resolution) as a `.json` preset file |
| **Load Preset** | Opens a file dialog to load a previously saved `.json` preset and instantly apply all its settings |


Floating buttons on the video panel: **Load** (open a file), **Pause/Play**, **Full** (fullscreen toggle).

## How it works

Each frame runs through OpenCV's `BackgroundSubtractorMOG2` to isolate moving regions, followed by thresholding, morphological opening, and dilation to clean up the mask. Contours are extracted, filtered by minimum area, and the largest N are kept as tracked blobs. Overlays are drawn directly onto the frame before it's uploaded to a Dear PyGui dynamic texture for display — and, if recording, written to disk via `cv2.VideoWriter` at full native resolution independent of what's shown in the live preview.

## Notes

- Recording locks the Playback Speed selector since the export FPS is fixed at recording start.
- Reaching the end of a file loop automatically stops any active recording and restarts playback from frame 0.

---

Built by [@rileriaaa](https://github.com/rileriaaa)