CV Phase Correlate (Translation)
Sub-pixel GLOBAL translation between two images, measured in the Fourier domain (cv2.phaseCorrelate) - the fast standard for video stabilisation, burst alignment and scan-line registration. It is neither feature-based nor iterative: one FFT pair, no keypoints to fail on, no convergence to babysit, and it is insensitive to uniform brightness changes. Use it where 'Find Transform (ECC)' is too slow and 'Detect Features' has nothing to lock onto (sky, water, blur, plain scans); use those instead when the motion is more than a shift. A Hann window is applied internally (rectangular edges alone produce a strong false peak). Failure-tolerant: mismatched or degenerate inputs give dx=dy=0 with found=false, so branch on 'found' with a control-flow node (core 'If/Else Switch').
- image
- shifted
- dx
- dy
- response
- translation
- found
Inputs (4)
| Name | Type | Default | Description |
|---|---|---|---|
| image | NPARRAY,IMAGE | Reference image. Converted to grayscale float32 internally. Accepts a ComfyUI IMAGE/MASK directly (frame 0 of a batch) or an NPARRAY. Arithmetic ops (add, multiply, etc.) process the full IMAGE batch when both inputs have the same batch size. | |
| shifted | NPARRAY,IMAGE | The moved image. Must be the SAME size as 'image' - phase correlation compares spectra, so it cannot align frames of different sizes. Accepts a ComfyUI IMAGE/MASK directly (frame 0 of a batch) or an NPARRAY. Arithmetic ops (add, multiply, etc.) process the full IMAGE batch when both inputs have the same batch size. | |
| min_response | FLOAT | 0.000–1 | Minimum peak response for 'found' to be true. The response falls off as the overlap shrinks and as the motion stops being a pure shift, so this is the reject-the-nonsense knob. 0.0 accepts anything. |
| hann_windowopt | BOOLEAN | true | Apply the Hann window before correlating. Leave it on: without it the image borders act like a huge edge and can dominate the real peak. Turn it off only for already-windowed or periodic data. |
Outputs (5)
| Name | Type | Description |
|---|---|---|
| dx | FLOAT | Horizontal shift in pixels, sub-pixel accurate: how far 'shifted' moved RIGHT relative to 'image'. Warp it back with a translation matrix (2x3) into cv2.warpAffine. |
| dy | FLOAT | Vertical shift in pixels (positive = downward). |
| response | FLOAT | Peak sharpness in [0,1] - how confident the estimate is. 0.0 when not found. |
| translation | NPARRAY | The same shift as a 2x3 float32 affine matrix [[1,0,dx],[0,1,dy]], ready for cv2.warpAffine (identity when not found, so warping is a no-op). |
| found | BOOLEAN | — |