Blob Track | Akatz

Blob Track is Akatz's lightweight motion tracker: it finds the moving regions in a frame batch and hands you both an annotated composite image and a mask of where they were. No YOLO, no SAM, no model download - it's frame differencing plus OpenCV's SimpleBlobDetector, which makes it fast and free to run, and also means you should set expectations accordingly.

The honest use case is "I need a rough region of interest that follows movement, and I don't need pixel-perfect object identity." Think driving an effect region from something crossing the frame, generating a tracking mask for a follow effect, or detecting a dancer's motion to drive mask animation. If you need to track a specific named object or keep identity through occlusions, reach for a real tracker or segmentation instead - this is the cheap, coarse layer.

How it works

Each frame is compared against a reference built from the previous cache_frames frames (averaged). The absolute difference becomes a grayscale motion map, thresholded by diff_threshold, and that threshold image is fed to OpenCV's SimpleBlobDetector. Detected blobs get drawn as alpha-blended boxes on the composite, and as filled white rectangles on the mask output. With line_alpha above zero it also connects blob centers with lines, which read as crude "paths" across a clip.

Inputs that matter

There are a lot of knobs here, but you'll actually set a handful:

• image - your IMAGE batch (it accepts a live video stream too, hence defaultInput).
• cache_frames - how many previous frames to average as the motion reference. Default 1 = compare against the last frame.
• diff_threshold - how much a pixel must change to count as motion. This is your main sensitivity dial; too low and noise becomes blobs, too high and slow movement disappears.
• filter_by_area with min_area/max_area - throw away tiny specks and giant background fills.
• max_blobs - cap how many it tracks (default 10).
• The rest (min_threshold, max_threshold, threshold_step) are SimpleBlobDetector's binarization ladder; you can usually leave them alone.

Outputs are IMAGE (frames with colored outlines and lines) and MASK (white boxes on black). The mask is the useful one - wire it into a dilation or inpaint region.

Installing it

Part of the akatz-ai/ComfyUI-AKatz-Nodes pack. Install via Manager (search "AKatz") or:

cd ComfyUI/custom_nodes
git clone https://github.com/akatz-ai/ComfyUI-AKatz-Nodes
cd ComfyUI-AKatz-Nodes
pip install -r requirements.txt

Then restart ComfyUI. Requirements are numpy, torch, opencv-python and pydub - no models to download.

Common issues

Nothing detected is the classic failure, and it's almost always diff_threshold or min_area: lower the threshold, and if your blobs are small, drop min_area. The other trap is expecting it to work on a static camera - it's purely motion-based, so if nothing moves, nothing gets tracked. If the composite looks fine but the mask is empty, check line_alpha - lines are only drawn into the mask when it's above zero.