CV Generalized Hough (Shape Template)

Hough circles find circles. Hough lines find lines. This finds the shape you hand it - a specific logo, a bracket, a bolt head, a logo'd badge, a stencil outline - by giving it a template image of that shape. Show it a clean crop of the thing, then search the scene.

The reason this exists rather than a template match: cv2_matchTemplate correlates raw pixel intensities, so change the lighting, the colour or the surrounding texture and your score collapses. The generalized Hough transform works from edges. It builds an R-table of the template's edge points - for each gradient direction, a list of offsets to the shape's reference point - and then every edge in the scene votes for where that reference point would have to sit. Edges survive shading, colour and background changes, and partial occlusion just means fewer votes. This is genuine classical CV, in bmad4ever's ComfyUI CV pack (bmad4ever/comfyui_cv, a fork of Gerold Meisinger's opencv-comfyui), wrapping the createGeneralizedHough* classes the auto-generated raw wrappers can't reach.

The two methods, and the one you want first

method is where the time goes.

Ballard (position only, fast) - translation. One accumulator. This is the default and it's what you should get working before anything else.

Guil (position + scale + rotation, slow) - also searches scale and rotation, and the accumulator multiplies by every scale step × every angle step. With the defaults (min_scale 0.8, max_scale 1.2, scale_step 0.1, min_angle 0 to max_angle 360 at angle_step 10) that's roughly a hundred passes over the scene. Widen it and you're into minutes. Keep the ranges tight - you usually know your part rotates within ±15° and appears at roughly one size.

The inputs that decide whether it works

template - the shape itself. Its edges become the R-table, so a clean, tightly cropped outline beats a busy crop every time. Crop to the object's silhouette; don't hand it a screenshot with a desk in it.

image - the scene to search. Converted to grayscale internally, edges computed inside with canny_low (50) and canny_high (100), which apply to both template and scene. Faint outline in either one? Lower the thresholds.

min_distance (10 px) - the minimum spacing between reported detections. Without this you get one shape reported as a cluster of near-identical hits, which is the single most common "why are there 40 detections" complaint with this family.

votes_threshold (30, Ballard only) - how many edge points must agree. It scales with the template's edge-pixel count, so a small tidy template needs a lower threshold than a big messy one. Nothing found → lower it. Everything found → raise it.

The advanced block is mostly Guil's: position_votes, scale_votes, angle_votes (100 / 100 / 10000), dp (accumulator resolution divisor - 2.0 halves it, coarser and faster and more tolerant), and levels (gradient-direction bins, 360).

Outputs

found - branch on it with an if/else node; zero detections is a valid result, not an error. positions - Nx2 centres, feed CV Draw Points. scales and angles - per-detection scale and rotation in degrees (all 1.0 and 0 for Ballard, which doesn't search them). votes - Nx3 accumulator votes for position, scale and angle; sort or threshold on column 0 to keep only the strong hits. bboxes - one {x, y, width, height, score, label} dict per detection, sized from the template scaled by scales, so it goes straight into a Draw BBoxes node. count - how many.

Install

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

Or search ComfyUI CV in ComfyUI Manager. Python ≥ 3.12 and a recent ComfyUI on the V3 node API. workflows/32_shape_match_warp.json puts it next to matchShapes so you can compare the two approaches on the same input.

Common issues

Guil hangs. It's not hanging, it's multiplying. Shrink max_angle/min_angle first (that's the biggest term), then angle_step up, then the scale range. dp 2.0 is the next lever.

Nothing found. Raise the Canny thresholds' tolerance (lower canny_low), lower votes_threshold, and make sure the template's scale in the scene is inside the searched range for Guil. Also check the template really is an outline-shaped crop - a soft, low-contrast, busy crop gives the R-table nothing coherent.

Hundreds of hits on a textured background. Raise votes_threshold and raise min_distance. Textured surfaces produce edges in every direction, and every one of them votes.

Detections wobble by a pixel or two between runs. That's the accumulator's resolution; dp below 1.0 refines it at the cost of time.