OpenCV findTransformECC_0

This is the node for a problem that doesn't get enough love in ComfyUI: registering two images that are slightly misaligned. cv2.findTransformECC uses Enhanced Correlation Coefficient (ECC) optimization to find the warp that best aligns a template image to an input image, and it returns how well it did - a correlation score in [-1, 1] - alongside the transform itself. OpenCV findTransformECC_0 wraps the full signature.

Where does that come up? Stabilizing video frames, aligning a reference render to a new one, registering a mask or segmentation to a slightly-shifted frame, or checking "did this frame actually move?" The score output is the sleeper feature: it gives you a number you can branch on. If alignment fails, the score collapses, and you can route that into a decision.

Inputs

• templateImage - the reference image you want everything to line up against (single-channel, more below).
• inputImage - the image to be aligned to the template.
• warpMatrix - the initial guess. A 2x3 affine identity for translation/euclidean/affine motion, or a 3x3 identity for homography. ECC refines this; a good guess is half the battle.
• motionType - what kind of motion to solve for: 0 = translation, 1 = euclidean (translation + rotation), 2 = affine, 3 = homography. Start at 0 or 1; don't jump to 3 unless the views are really related by perspective.
• criteria - a TermCriteria as a string literal. Type it as (3, 50, 0.001) - type 3 means "max iterations OR epsilon," 50 iterations, epsilon 0.001. The pack parses composite types with literal_eval, so it must be valid Python syntax.
• inputMask - optional mask telling ECC which pixels to care about. Ignore it at first.
• gaussFiltSize - Gaussian smoothing on the images before matching. Must be a positive odd integer; 0 means no smoothing. Start with 5.

Outputs: float - the ECC score (closer to 1 is better alignment), and nparray - the refined warp matrix. Feed that matrix plus your input image into this pack's warpPerspective to produce the actual aligned image.

The gotchas

Grayscale only. ECC wants single-channel images; the pack's cvtColor with code = 6 (BGR→GRAY) is your friend. Feed it RGB and OpenCV will assert.

Initialization matters. ECC is a local optimizer - a bad initial warpMatrix means it converges to nonsense, and it's not subtle about it. Always start from identity for the motion type you chose, and don't skip the criteria literal: the invalid syntax error is the #1 way people meet this node.

The outputs are numbers, not frames. The score is a float and the matrix is an NPARRAY of geometry. Previewing the matrix like an image throws the pack's 'NoneType' object has no attribute 'shape' error. Wire the matrix into warpPerspective to see actual pixels.

Install

ComfyUI Manager → search opencv-comfyui → install → restart, or:

cd ComfyUI/custom_nodes
git clone https://github.com/geroldmeisinger/opencv-comfyui

requirements.txt installs opencv-contrib-python, numpy, torch. The pack imports cv2 at startup - a missing or conflicting OpenCV install (the guidedFilter error is the tell) means none of its nodes register.

Verdict

findTransformECC_0 is the full version, with inputMask and gaussFiltSize as required inputs. If you'd rather those be optional, use _2/_3. The _1 twin is byte-identical to _0. For frame alignment with a built-in quality score, this is the one node in the pack that does something nothing in core ComfyUI does.