Align to Reference (AKAZE)

You ask Qwen-Image-Edit to redraw something and the output comes back... close, but a couple pixels off. Scaled up a hair, shifted sideways. It's not you and it's not the seed - it's the model's own internals. TextEncodeQwenImageEditPlus resizes every input to a 1024×1024-area grid with 8-pixel alignment, and that round(.../8)*8 step introduces a small uniform scale-plus-shift distortion every single run. The community has been complaining about it since September 2025, and 2511's release notes claimed a fix that users found... partial, at best.

Align to Reference (AKAZE) is the corrective approach: instead of preventing the drift, it measures it after the fact and warps the output back onto your source. It's the node you reach for when the Qwen output and the original need to overlay pixel-perfectly - classic use case being line art: generate clean line work with Qwen, align it to your color original, stack the layers in Photoshop.

How it works

Standard computer-vision registration, done properly. It detects AKAZE feature points in both images, matches them with a brute-force matcher plus Lowe's ratio test (to keep only unambiguous matches), then fits a transform with RANSAC so a few bad matches can't wreck the fit. By default it estimates a similarity transform - translation + uniform scale + rotation - which is exactly the kind of distortion Qwen's resize produces. It then warps the moving image onto the reference's grid and hands it back.

On the console it prints the detected transform (tx, ty, scale, rot, match count) so you can sanity-check the alignment rather than trust it blind.

The inputs that matter

• reference - the fixed image (your color original).
• moving - the image to align (the Qwen output or line art).
• transform_mode - similarity is the recommended default. translation for shift-only, affine if you need it, but "most flexible, least stable" is accurate - stick with similarity unless you know better.
• edge_preprocess - none default, but canny or sobel is the trick that makes this node shine. When your moving image is black line art and the reference is full color, their intensities have nothing in common; pre-filtering both to edges gives the matcher something to actually match.
• max_features / ratio_threshold / ransac_threshold - the detection and matching dials. Defaults are sensible; lower ratio_threshold for stricter matches, lower ransac_threshold for a tighter fit.
• output_debug - turn on to also get a side-by-side match visualization out of the second debug output.

Gotchas

The big one: this node needs OpenCV, and it's the only node in the pack that does. Manager usually handles it via requirements, but if you get an import error you'll need pip install opencv-python into your ComfyUI environment.

Second: if it can't find enough matches (under 4 good ones after the ratio test), it silently returns the moving image unchanged - no error, just a no-op. If your alignment looks like nothing happened, check the console line and reach for edge_preprocess: canny.

And set expectations: this is a global transform. It fixes uniform scale+shift drift beautifully, but it cannot correct pose changes or local non-rigid warp. If Qwen re-posed the subject, no similarity fit is going to glue it back.

Installing it

ComfyUI Manager → search comfyui_qwen_edit_pixel_perfect → install, restart. Or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/oron1208/comfyui_qwen_edit_pixel_perfect

Restart ComfyUI. The pack targets the newer comfy_api.latest / io.Schema node API, so a stale ComfyUI won't register these nodes - update ComfyUI if they're missing. The bundled "Auto Align" and standalone "LineArt Align" workflows wire this node with two LoadImages and an rgthree Image Comparer, which is the fastest way to see what it buys you.