CoachBate H3 Subject Count

A counter that drives a loop

CoachBate H3 Subject Count answers one question - how many subjects does this clip show? - and the answer is meant to be wired into Pixaroma's Loop Start total, so that a full H3 subject-refine pass runs once per subject. One subject, one render. That's the "Refine xN" blueprint in the README, and this node is its head.

It runs your YOLO detector over sampled frames (images in, detector + confidence + sample_every out of the way) and returns subjects (INT) plus a report string.

Why it's not just "max detections"

Naively, the count is the busiest frame's detection count. That's a trap, because a single-frame false positive then buys you an entire extra H3 render of the whole clip. So the node asks for the largest per-frame count that holds on at least min_fraction of the sampled frames - default 0.05, i.e. 5%. A blob that appears in one frame out of a hundred doesn't count. max_subjects (default 20) is the hard cap, and since each subject is a full render of the clip, max_subjects = 1 is a legitimate way to force a single pass on a video you know has one subject and a noisy detector.

sample_every (default 1) detects on every nth frame. For a long clip where you just want the subject count, 4 or 8 is plenty and it's the cheapest way to make this node disappear from your runtime. detector should be the same detector the tracker uses - same weights, same idea of what a subject is - otherwise you can count three and fail to track the third.

Inputs and outputs

• images - the clip.
• detector - a YOLO model registered from models/ultralytics/segm (or bbox). This is the same dropdown the tracker offers, fed by Impact-Subpack's folder registration, or by the pack's own direct folder lookup if the Subpack isn't installed.
• confidence (default 0.3), sample_every, min_fraction, max_subjects as above.

Outputs: subjects (INT) and report. The report is where you find the per-frame counts, which is how you tell "the detector sees two people" from "the detector occasionally thinks a lamp is a person".

Install

cd ComfyUI/custom_nodes
git clone https://github.com/CoachBate/ComfyUI-CoachBate.git

Or ComfyUI Manager → "CoachBate" → restart. It appears under CoachBate / H3. Requires ultralytics to be installed; weights go in models/ultralytics/segm/.

Where people get burned

• An extra render pass you didn't want. min_fraction is doing its job badly - raise it to 0.15 or so, or cap with max_subjects.
• The count is lower than you expected. Two subjects standing close together may be merged into one detection, or confidence is high enough to drop the smaller one. Check the report rather than guessing.
• Counts change between runs of the same clip. sample_every is skipping the frames where the second subject appears. Set it to 1 for the final count.