🔬 Circle Detection (Hough)

This node finds circles in an image the old-fashioned way: Hough's circle transform, a classic computer-vision algorithm instead of a neural net. That means no model weights, no VRAM, no model download, and - this is the part people underrate - the exact same result every single run. Feed it an image and you get back a marked-up copy plus clean masks you can drive an inpaint pass with.

Why you'd reach for it

The README's example is the whole pitch. Picture an "office under the sea" where every porthole is a circle, and you want to relocate it to outer space. You need a mask covering exactly those portholes so you can inpaint new content inside them while every pixel outside stays untouched. That's a fiddly thing to paint by hand, and Hough finds every circle in one shot. Same trick applies to wheels, dials, lenses, buttons, coins on a table, security cameras in a scene. Once you've got the mask you're in standard ComfyUI inpainting territory: set the mask, composite, regenerate just that region.

How it works

The node converts your image to grayscale, smooths it with a 3×3 blur, then runs cv2.HoughCircles with the gradient method. Each edge point votes for every circle it could belong to in (x, y, radius) space, and the accumulator peaks win. Two thresholds gate how many votes a candidate needs:

• threshold_canny_edge - the Canny edge sensitivity (param1).
• threshold_circle_center - the circle-center accumulator threshold (param2). This is your "how many circles do I get" knob: lower it and you get more candidates, and more false positives.

The author's built-in help text recommends a value around 100 for "accurate recognition" - the default is 30, which is permissive.

The inputs that actually matter

A beginner can ignore most of the widget and tune these four:

• minR / maxR - your first stop. The default minR is 1, which means it will happily report specks of noise as circles. Set minR near your real radius and detection quality jumps instantly.
• minDist - the minimum separation between detected centers. The help string suggests max(width, height) / 8.
• dp - the accumulator resolution. Tip from the help text: dp > 1.0 is the trick when you're chasing slightly deformed circles.
• exclude_circles (optional input) - because results are deterministic, you can run once, look at the numbered output, then feed in a comma list like 2,5,7 to drop those circles on the next run.

Outputs and where they go

• image_output - your image with the detected circles drawn on in color_tuple_circle, numbered if numbering is on.
• image_mask - a colored image: background filled with color_tuple_bg, circles with color_tuple_fg. It's a preview of the mask, not something you should feed an inpaint sampler directly.
• standard_mask / inverted_mask - these are the real deal: actual MASK tensors, white circles on black and its inverse. Wire one into a Set Mask node to inpaint inside the circles, or the inverted one to inpaint everything except them.
• show_terminal_data - a STRING with one line per circle (number, x, y, radius). Drop it into any text display node.
• circle_detection_help - a STRING of usage tips. Handy to wire into the pack's 📄 Show Data node so you don't have to re-read the docs.

Installation

No model files, no extra Python dependencies - there's no requirements.txt, it only needs cv2, PIL, numpy and torch, all of which ComfyUI ships. Either way, restart after install:

Via ComfyUI Manager, search "Circle Detection" and install, or:

cd ComfyUI/custom_nodes
git clone https://github.com/zentrocdot/ComfyUI_Circle_Detection

You'll find the nodes under Add Node > 🧬 Circle Detection Nodes.

Where people get burned

The author is upfront that error handling is still on the to-do list, so a bad setting can throw instead of printing a helpful message. The three failure modes you'll actually hit:

• Nothing detected - lower threshold_circle_center, and make sure maxR isn't smaller than your circles.
• Noise everywhere - your minR is too small; bump it.
• Deformed circles missed entirely - Hough wants near-perfect circles. That's not a bug in your settings; it's exactly why this same pack ships the 🔬 Ellipse Detection (Simple) node as a companion.