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.

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
• 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 — 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 (recommended):

pipx install blobtrack

Or with pip into your own environment:

pip install blobtrack

Usage

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

blobtrack

Or pass a video path or camera index directly:

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

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. 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