kubakub align to source

What it's for

Every image model that repaints a whole picture gives it back slightly moved. Qwen-Image-Edit is the famous one - the KB has a whole troubleshooting entry for "the whole picture shifts, or the face drifts across edits", with early builds arriving visibly offset. Flux 2 Klein edits come back warmer and nudged too. On a photo nobody notices two pixels. On a facade that gets projected onto a real building, two pixels at the corner of the matrix is the window frame landing on the wall next to the window.

kubakub align to source exists to undo exactly that: you hand it the edited picture and the thing it was edited from, and it puts the edit back where it belongs, at the source's size.

Worth knowing up front: this is not for the pack's own region work. The region sampler pastes inside masks, so nothing drifts and this node does nothing for you there. You want it when you ran a whole-picture edit - a Klein or Qwen pass over the entire matrix - and the result has to sit pixel-on-pixel back on the clay or the matrix.

How it works

It does not match features. Feature matching on a facade of identical windows will happily lock onto the wrong window, which is precisely why a naive "align these two images" node is dangerous here. Instead it works on edges - structure survives a restyle, colour does not - and it starts from "nothing moved", searching only for a small shift, scale and shear with OpenCV's ECC registration, coarse to fine.

Three guard rails, all from the shipped code:

• The fit runs over a 1024px long edge and refuses anything asking for more than 4% of the long edge in movement or 5% in scale. At that point it's not drift, it's a different picture.
• The fit has to actually improve the edge match (a minimum correlation gain of 0.01), and a second fit started from a different offset has to land within about a pixel of the first. If two starting points disagree, the answer isn't trusted.
• Fail either check and you get your picture back untouched, plus a line in the report saying why. Silent failure would be worse than no node at all.

Measured on a 1.5k facade: 3 to 30 px at the corners, one to two percent scale - about 3 seconds per picture.

Inputs and outputs

Three things matter:

• images - the edit, or the frames of a clip.
• source - what it was made from: the clay, the matrix, the render. One image for all frames, or one per frame. Sizes don't have to match; the output takes the source's size.
• fit - move and scale (the default; shift, scale and a bit of shear, which is what image models actually do) or move only when you know the size is right and just want the shift undone.

The optional frames is the one worth knowing about for video: each on its own corrects every frame independently, one fit for all fits the first frame and applies that same correction to every frame - which is what you want for a clip that drifted as a whole, because per-frame fitting on a moving shot is how you get a wobble. It's hidden behind the advanced-inputs toggle, so you need ComfyUI 0.37.0 or newer to even see it.

Out comes images (at the source's size) and report, a text listing how far each picture sat off or why it was left alone. Wire the images to your save/export, and if a picture comes back unmoved, read the report instead of re-queueing blindly.

Install

ComfyUI Manager → search kubakub nodes → install → restart. By hand:

cd ComfyUI/custom_nodes
git clone https://github.com/kubakubkub/ComfyUI_KubaNodes
python -m pip install -r ComfyUI_KubaNodes/requirements.txt

On the portable build, python_embeded\python.exe -m pip ... instead. The only package it adds is opencv-python-headless - and if you already have another OpenCV build, keep yours. The pack needs ComfyUI 0.37.0+ and is tested on 0.38.2 with torch 2.10; the pack prints [Kub] N nodes from M modules at startup so you can confirm it loaded.

Common issues

• Nothing moved. That's the safe answer, not a bug - the report tells you which check tripped. Usually source isn't the picture the edit was actually made from, or the edit changed the framing/edges enough that the shared structure is gone.
• It corrects the picture as a whole. Regions that moved differently from each other within the same frame won't be fixed, and it doesn't claim to.
• Size expectations. The output has the source's size, not the edit's, so don't wire an edit-sized mask downstream without resizing it.