BlobTrack
Overview
A real-time motion blob tracker built entirely on Dear PyGui and OpenCV — no browser, no server, just a native desktop window running a live computer-vision pipeline frame by frame. Load a video file or point it at a webcam, and BlobTrack isolates moving regions via background subtraction, then overlays bounding shapes, confidence labels, and network-style connection lines between detected blobs, all fully adjustable while playback is running. Every visual element in the sidebar — shape, color, thickness, filter, mesh density — maps directly onto the same frame that gets written out when you hit Record, so what you see live is exactly what gets exported, just always at full native resolution regardless of the live preview scale.
Tech Stack
Interface: Dear PyGui, an immediate-mode GUI library that renders natively rather than through a browser or web view — chosen for how directly it can push raw frame buffers to screen at high frame rates without the overhead a DOM-based UI would introduce. Vision pipeline: OpenCV's BackgroundSubtractorMOG2 for motion detection, followed by thresholding, morphological opening, and dilation to clean up noise before contour extraction — a classical (non-deep-learning) approach, which keeps the whole thing dependency-light and runs comfortably on CPU alone.
Frame buffers: NumPy arrays reused across frames rather than reallocated each tick, cutting the allocation and garbage-collection overhead that would otherwise stand between this and a steady frame rate at higher resolutions. Export: OpenCV's VideoWriter, writing processed frames straight to .mp4 at a speed-adjusted FPS, locked for the duration of a recording so the exported file's timing stays consistent regardless of what Playback Speed or Live Resolution is set to mid-session. Packaging: distributed via PyPI and installable through pipx, so the whole app runs as a single isolated CLI command with zero manual dependency management on the user's end.
Software requirements
Python 3.8 or newer, plus pipx (or a plain pip environment) to handle installation. No account, no API key, no internet connection needed after install — the entire vision pipeline runs locally against whatever video file or camera index you point it at, with nothing ever sent off the machine. Runs on Windows, macOS, and Linux, since both Dear PyGui and OpenCV ship cross-platform wheels.
Setup
With pipx installed, run pipx install blobtrack. This pulls the package from PyPI into its own isolated virtual environment and exposes a single blobtrack command on your PATH — no manual venv creation, no separate pip install of dearpygui, opencv-python, or numpy required, since those are declared as dependencies and get resolved automatically at install time.
First run
Run blobtrack from any terminal with no arguments to open an empty window and use the floating Load button to pick a video file, or pass a path or camera index directly with blobtrack --source path/to/video.mp4 or blobtrack --source 0 for a webcam feed. The window opens straight into the live preview — no separate render step, no waiting on a build, the moment a source is loaded the detection pipeline starts running against it immediately.
Usage / Controls
- Minimum Area / Max Blobs — filters out small noise and caps how many blobs get tracked per frame, keeping the overlay readable on busy footage
- Shape, Bounding Size, Bounding Thickness — controls the outline drawn around each detected blob, with Square, Circle, or None (label-only) as options
- Connection Lines — links each blob to its k nearest neighbors with a distance-based fade, producing a mesh/network look across the frame rather than isolated boxes
- Bounding Box Filter — applies Invert, Blur, Pixelate, Thermal, or Edge effects inside each detected region specifically, leaving the rest of the frame untouched
- Playback Speed / Live Resolution — adjusts preview playback rate and processing resolution independently of the export, which always renders at full native quality regardless of these two settings
- 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
Configuration options
No config file or settings menu — every option lives directly in the sidebar and takes effect immediately on the next frame, since the app reads slider and button state live inside the render loop rather than caching it at startup. There's nothing to persist between sessions by design; every run starts from the same defaults (green boxes, Square shape, Native resolution, 1x speed), keeping behavior predictable across machines and sessions rather than depending on a saved profile.
Troubleshooting
- Video won't load; confirm the file path has no unusual characters and the container/codec is supported by your OpenCV build; .mp4 and .avi are the safest bet, some .mov or .mkv files can fail silently on certain platform builds of OpenCV.
- Preview stays black after loading — check whether playback is paused, since the pause state persists across a new Load and a paused feed simply stops pulling new frames rather than indicating a failed load.
- Recording produces an empty or truncated file — this traces back to the writer being created while the video was paused, or the export starting mid-playback instead of from frame zero; both cases are handled automatically now, but if it recurs, confirm the destination path in the save dialog is writable and not on a read-only or network drive.
- Frame rate drops on high-resolution sources — lower the Live Resolution setting during preview; this only affects what's processed and shown live, the exported recording still renders every frame at full native resolution regardless of this setting.
- pipx command not found after install — make sure pipx's bin directory is on your PATH (pipx ensurepath handles this automatically and may require a terminal restart to take effect).