cv2.HoughCircles

Hough circles find round things: wheels, coins, dials, lens rims, pupils. The output is not a mask and not a box - it is a list of (x, y, radius) triples, which is exactly the shape you want when "where" and "how big" are separate questions. Radius gives you a scale reference for free, which is why the classic use is not detection for its own sake but measurement: find the circle, and now you know the camera distance, the object's real size, or where to put a mask.

For the "find the object" job, a trained detector wins every time and this node is a poor substitute. Where it wins is the case with no model: something circular, on a plain background, and you do not want to download weights to find it. Cheap, deterministic, no GPU, no licence questions - a fine preprocessing step in the detector layer described in masking-detection-detailing.md.

How it works

cv2.HoughCircles(image, method, dp, minDist, param1, param2, minRadius, maxRadius). Internally it runs Canny first (param1 is the high threshold; the low one is half that), then accumulates votes in a 3-D space of centre-x, centre-y, radius. A genuine circle accumulates votes along a ridge; noise does not. Circles above the accumulator threshold (param2 for the gradient method) come back, strongest first.

dp is the accumulator's inverse resolution: dp = 1 means the accumulator matches the image resolution, dp = 2 halves it (faster, coarser). For the alternative method, OpenCV's recommendation is dp = 1.5.

And HOUGH_GRADIENT_ALT is not a variant of the same algorithm: it is more accurate on well-exposed images and recomputes radiuses properly, but its parameters change meaning, which is the trap below.

Inputs that matter

• image - 8-bit single channel. The wrapper grayscales a colour IMAGE link for you. It reads frame 0 of a batch; this function is not in the pack's per-frame list.
• method - the dropdown offers all five Hough modes, but cv2's circle detector only implements the two gradient ones, and the author's tooltip says as much: HOUGH_GRADIENT (default) or HOUGH_GRADIENT_ALT. Picking HOUGH_STANDARD will not give you a different algorithm, it will fail.
• dp - starts at 0 in the widget, which is not a usable resolution. Set 1 (or 1.5 for ALT) explicitly.
• minDist - minimum distance between circle centres. The classic failure knob: too small and one circle comes back five times with different radii; too large and you miss all but the strongest.
• param1 - Canny's high threshold, default 100. For HOUGH_GRADIENT_ALT OpenCV uses Scharr derivatives and expects something like 300 on a normal-contrast image.
• param2 - read this carefully, because its meaning flips with the method. For HOUGH_GRADIENT it is a vote count: lower finds more circles, including false ones. For HOUGH_GRADIENT_ALT it is a perfectness measure between 0 and 1, where 0.9 is the recommended starting point. Leaving it at the 100 default while using ALT is meaningless.
• minRadius, maxRadius - always constrain these if you can. maxRadius <= 0 means "the image's largest dimension", and a negative value makes the gradient method return centres without radiuses at all. Limiting the range is what kills most false positives.

Output is one nparray of (x, y, radius) triples - and CV Draw Circles takes that layout directly, with draw_centers on by default so concentric hits stay readable. Other consumers: cv2.minEnclosingCircle-adjacent geometry nodes, CV Array To Text to read radiuses out, or the same array into a crop policy if you want to crop what you found.

If nothing is found, cv2 returns nothing and the socket carries an empty value; CV Draw Circles explicitly passes the image through in that case and reports count = 0, so branching on count is the correct way to detect "no circles".

Install

Manager → search comfyui_cv (bmad4ever), or:

cd ComfyUI/custom_nodes
git clone https://github.com/bmad4ever/comfyui_cv
pip install "opencv-contrib-python-headless~=5.0.0.93"

Python ≥ 3.12 and a recent ComfyUI on the V3 node API. One dependency, no models. The pack is ~470 generated wrappers plus a few hundred curated nodes, forked from geroldmeisinger's opencv-comfyui - so older tutorials about that pack still describe the same concepts.

When it goes wrong

• The same circle, five times. minDist too small, or strong circular texture (foliage, ripples, a brick wall). Set minRadius/maxRadius to the actual size range and raise minDist above the object's diameter; the problem usually becomes trivial.
• Nothing at all, on an image full of circles. Either you are feeding a grey photo instead of an edge-strong image (run cv2.Canny first - a soft circle has no gradient to vote with), or param2 is too high.
• The radii are wrong or zero. You are on HOUGH_GRADIENT with a negative maxRadius, or on ALT where radiuses are always computed - check which method the dropdown is actually on.
• Frame 0 only. A batch of 12 frames gives you frame 0's circles; split with CV Unstack Batch and stack results yourself.
• Contrib wheel hygiene. All OpenCV distributions share one site-packages/cv2; a later non-contrib install silently removes contrib nodes. tools/repair_opencv_contrib.py --check / --apply.