cv2.computeECC

What it's for

cv2.computeECC takes a template and an image and returns a single FLOAT: how well do these two align as they are? No transform is estimated, nothing is warped, you just get the score. The Enhanced Correlation Coefficient is a normalized similarity measure built for images whose brightness or contrast don't match - that's its whole selling point over plain SSD/correlation - so it's the right number when you're comparing a render against a photo, a grade against a reference, or a frame against the plate it was supposed to match.

Reach for it when you want to judge alignment rather than perform it. "Did the paste land?", "is this frame still registered to the plate?", "which of these candidate crops is closest to the reference?" A single scalar is much easier to branch on than an image.

It's a raw wrapper from ComfyUI CV (bmad4ever/comfyui_cv), category image/CV/low-level/cv2 C. Note that this is a score-only function; the same module also has the heavy version, which works out the warp.

How it works

ECC compares the two images through a normalized correlation that is invariant to brightness and contrast changes - that's why an exposure shift doesn't tank the score the way it would with a naive difference. Same image, aligned, scores close to 1.0; worse alignment or different content scores lower. It's a correlation coefficient, so treat it as "how similar", not as a calibrated error in pixels.

If you want the transform instead of the score, that's the curated CV Find Transform (ECC) node in this same pack - a different node, built around findTransformECC, which is what the pack's docs recommend for direct intensity registration. Use this node for scoring, and give the input mask some thought if you do use it for registration.

Inputs and outputs that matter

• inputImage - required. The image to be compared against the template. Must share type and channel count with the template. Takes an IMAGE or MASK directly (frame 0 of a batch) or an NPARRAY.
• templateImage - required. The reference. Same type, same channels.
• inputMask - optional, and this is the one knob worth understanding. The author's tooltip calls it "a single-channel mask to specify the valid region of interest in inputImage and templateImage" - it excludes pixels in both images. The pack's notes on the sibling node put it bluntly: the mask must be a coherent region, not scattered speckle. A patchy mask changes the statistics in a way that makes the score meaningless.
• float - the ECC score. Wire it into a comparison, a display, or a note node.

Optional inputs live under "show advanced inputs".

Where it fits

In a deterministic post-processing stack (post-processing.md covers that layer and why it's worth preferring to a diffusion re-pass), scoring is what turns a pipeline into something that can decide: auto-pick the best of N alignments, flag the frames where the camera moved, gate a re-render on "did the previous step actually change anything?". Pair it with the pack's CV Phase Correlate (Translation) when you want the shift and the confidence, or with CV Matrix Multiply / CV Warp Flags when you'd rather build the registration yourself and then check your work with this score.

Installing the pack

Manager → search ComfyUI CV, or:

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

Restart. Hard requirements: Python ≥ 3.12 and a ComfyUI with the V3 node API. The dependency is opencv-contrib-python-headless~=5.0.0.93 (plus numpy/torch). The pack pins that OpenCV build deliberately - behaviour "is curated against 5.0.0.93", so a much older or newer wheel can change results.

Where people get burned

• Mismatched types and channels. The tooltip is explicit that the two images "must have the same type and number of channels". A 3-channel IMAGE against a single-channel MASK is an error, not a graceful degradation. Grey both sides first.
• Expecting a pixel error. This is an ECC value, not a distance. A score of 0.92 versus 0.88 tells you one is better; it does not tell you "3 pixels off". Don't build a threshold on it as if it were measured in pixels - calibrate the threshold on your own images.
• Speckled masks. The mask is meant to be one region. A scattered mask is the difference between a meaningful score and a more confident-looking random number.
• A brand-new OpenCV function on a brand-new OpenCV major version. computeECC is part of the OpenCV 5 line this pack pins. If you're on a machine with an older OpenCV that some other node pack dragged in, expect the node to be missing or to raise - and remember that all four OpenCV wheels share one cv2 namespace, so a stray opencv-python install can quietly strip contrib functionality. The repo ships tools/repair_opencv_contrib.py (--check / --apply) for that. And as ever with this pack: README says LLM-assisted, updates not planned, verify anything you'd stake a pipeline on. There's no community corpus behind it to compare notes with.