Metadata-Version: 2.5
Name: blobtrack
Version: 2.2.9
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, network-style connection lines, and a glitchy fragment scatter effect on each detected blob.

![BlobTrack UI](hello.PNG)

![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, with an adjustable detection rate and min/max blob area filters
- **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
- **Fragment Scatter effect** — copies random patches from around each blob and scatters them nearby as resized fragments, with optional borders and lines tracing back to the blob (count, spread, regenerate rate, and border style are all adjustable)
- **Optional score labels** — each blob shows its area as a fraction of the frame; toggle on/off and set the font size
- **Adjustable playback speed** (0.5x–2x) for file sources
- **Live Resolution scaling** (Native/75%/50%/25%) to trade preview quality for performance without affecting export quality
- **Broad video format support** — MP4, MOV, AVI, MKV, WEBM, M4V, WMV, FLV (case-insensitive extension matching)
- **One-click webcam access** — jump straight to a live camera feed from the video panel, no CLI needed
- **Letterboxed preview** — video always keeps its native aspect ratio inside the panel, with black bars filling any leftover space instead of stretching
- **Video export/recording with audio** — save the processed feed (with all overlays) to `.mp4`, always at full native resolution regardless of preview settings. For file sources, the original audio is automatically muxed back in and tempo-adjusted to match your chosen playback speed
- **Save/Load presets** — store and restore your whole look as a `.json` file
- **Fullscreen toggle** (hides the sidebar) 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
```

You can also switch to your webcam at any time from inside the app using the **Cam** button in the video panel — no need to relaunch with `--source`.

## Controls

### Detection
 
| Control | Description |
|---|---|
| **Minimum Area** | Filters out blobs smaller than this pixel area |
| **Max Blobs** | Caps how many blobs are tracked per frame |
| **Detection Rate** | Runs detection every N frames in the live preview (higher = faster, less responsive). Recording always detects every frame |
| **Maximum Area %** | Ignores blobs larger than this percentage of the frame (useful for filtering out camera shake or lighting changes) |
 
### Overlays
 
| Control | Description |
|---|---|
| **Shape** | Bounding shape drawn around each blob (Square / Circle / None) |
| **Bounding Size / Thickness** | Size (16–512 px presets) 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 |
| **Connection Line Thickness** | Stroke width of the connection lines |
| **Bounding Box Filter** | Visual effect applied inside each bounding box |
| **Font Size / Show Score Text** | Size of the score label per blob, and whether it's shown at all |
| **Bounding Box / Connection Line Color** | Preset colors or a custom color picker |

Floating buttons on the video panel: **Load** (open a video file), **Cam** (switch to webcam), **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. In the live preview, detection runs on a downscaled copy of the frame (max 640 px on the long side) and can skip frames based on the Detection Rate setting. Contours are extracted, filtered by minimum and maximum area, and the largest N are kept as tracked blobs. Overlays (and the optional fragment effect) 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.

When a recording of a video file finishes, the matching audio segment is extracted with ffmpeg, time-stretched with atempo if you used a non-1x speed, and muxed into the exported .mp4.

## Notes

- Starting a recording rewinds the video to frame 0, unpauses it, and records from the beginning.
- While recording, the live preview temporarily drops to 25% resolution to keep the UI smooth; your previous setting is restored when recording stops. The exported video is unaffected and stays at native resolution.
- Recording locks the Playback Speed selector since the export FPS is fixed at recording start.
- Reaching the end of a file automatically stops any active recording and restarts playback from frame 0.
- Webcam recordings are saved without audio.
- Detection Rate, Maximum Area %, and the Fragment Count / Regenerate Rate / Spread sliders are not currently included in saved presets.

---

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