CV Match Image Moments

Contour matching has a blind spot, and it's a big one. Give it two identical outlines and it reports distance 0.000000 - because it doesn't see inside them. Two discs lit from opposite sides are the same object to matchShapes on a contour, and completely different objects to a human. If the thing distinguishing your two candidates is internal shading - a lit face versus a shadowed one, a chip versus a blank, a printed label versus a plain surface - contour matching will confidently tell you they're identical.

This node scores frames by Hu moments of the image intensity instead, using the same scale/rotation/mirror invariance policy as the pack's contour matcher (CV Filter Contours By Shape). cv2.moments on a raster defaults to binaryImage=False, meaning a pixel's mass is its value - Hu's original formulation. That's the whole idea: shading is geometry.

How it works, and where it gets slippery

reference is your template (frame 0 if you hand it a batch); images is the batch to score. Size doesn't have to match - moments are scale invariant.

Three things you actually tune:

• weighting. intensity, peak-normalized is the default and the right starting point, and the reason is concrete: Hu moments are not invariant to a brightness change, so a half-exposure copy of the same object scores differently. Dividing by the frame's own maximum more than halved that error in the author's own testing (I1 0.0394 raw → 0.0146). It doesn't fully remove it - dimming also shrinks the effective support of a soft-edged region and no normalization fixes that. intensity is the raw formulation. binary throws away values and uses the silhouette, which is basically what the contour nodes do - with a nasty edge: every non-zero pixel counts as shape, so any background haze swallows the entire frame.
• max_distance (default 0.3). "0 = identical". Intensity distances do not share a scale with contour distances, so calibrate: crank it to 1e6, read the distances output on real data, then set a threshold that means something.
• method - CONTOURS_MATCH_I1, I2, I3. I1 is the usual choice.

Then the invariance policy: scale_mode / scale_tolerance (note that on this path "size" is sqrt(total intensity), so a brighter copy reads as bigger - unless weighting is binary), rotation_mode (the "or 180 flipped" option exists for 2-fold symmetric shapes whose orientation flips arbitrarily), rotation_tolerance_deg, mirror_mode, and min_chirality.

That last one is worth understanding rather than skipping. Handedness is decided by the sign of the 7th Hu invariant - the one OpenCV's own docs note is only proved invariant "with the assumption of infinite image resolution." Rasterize a symmetric shape and you get a small non-zero h7 whose sign is noise. min_chirality (default 1e-6) is the magnitude below which mirroring is reported as undecidable instead of guessed. Hard-edged silhouettes measure ~0.005 of noise; a smooth intensity field measures ~1e-5, which is why this default is far lower than the contour matcher's.

Inputs and outputs

reference, images (both accept IMAGE/MASK or NPARRAY directly), method, max_distance, weighting, plus the four invariance knobs.

Outputs: distances (N, float32, in batch order - deliberately not sorted, because batch order is what CV Index Batch needs), matched (N, float32 keep-mask: 1 where the frame passed both the threshold and the policy), best_index (closest accepted frame, or −1), found (boolean - wire it into an if/else rather than testing best_index by hand), scale_ratios, rotations, mirrored, and transforms - an (N,2,3) similarity matrix per frame mapping reference coordinates onto that frame, which you can hand straight to cv2_warpAffine to overlay your template on its match.

The keep-mask shape is deliberate, not lazy: it means a zero-match result stays a valid batch, so downstream batch math doesn't get a ragged input.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/bmad4ever/comfyui_cv

Or Manager → ComfyUI CV. Restart and reload. Pure cv2, no models, one dependency (opencv-contrib-python-headless~=5.0.0.93), Python ≥ 3.12, V3-API-era ComfyUI.

Common issues

Distances that look tiny and frames that still don't match. You're probably comparing an intensity distance against a contour-shaped expectation. Read distances and calibrate max_distance.

A background haze matching everything. You set weighting to binary on an image that isn't a clean silhouette. That mode treats any non-zero pixel as part of the shape.

Rotation output that looks like noise on a square. It is noise - a square has no well-defined orientation, and the node's own tooltip says so. Check pose_confidence on CV Image Moments before trusting orientation-based filtering.