CV Quad Warp

Four points in, homography out. This is the node you reach for when you've identified a quadrilateral in an image and now need to either flatten it or put something inside it. It's one of the pack's showcase nodes, and it's a good example of a wrap that adds value beyond the raw cv2 calls: automatic corner ordering, aspect recovery, and a composite that doesn't leave a dark rim.

Two directions

extract - rectify the quad into a rectangle. The photo is the input, the four corners outline the thing you want straightened (a page, a whiteboard, a sign, a screen), and the output is a flat, front-on view of it. This is a manual document scanner: point at the corners, get the document.

fill - warp this image into the quad. The image is now the content, the points are the destination, and the whole thing is composited onto canvas (or a black canvas sized to the quad if you leave it unwired). That's a poster on a wall, a logo on a screen, artwork on a billboard - anything where you have flat art and a photographed surface to put it on.

What the node does that a bare homography doesn't

Three things, and each solves a real annoyance.

The four points may arrive in any order - click order from CV Annotate Points, the output of a detector, whatever - and are sorted into TL/TR/BR/BL automatically. Getting the corner ordering wrong in a hand-wired cv2.getPerspectiveTransform produces a folded, bow-tie warp, and it's a tedious bug to spot.

In extract mode it recovers the true aspect ratio from the perspective (Zhang's whiteboard method, principal point at the image centre) instead of trusting the projected edge lengths. A page shot from an angle comes back as a page, not as a squashed parallelogram - the same math CV Quad To Rectangle exposes as a standalone node.

In fill mode the composite is done as a premultiplied alpha blend rather than a straight paste, so the edge of the warped content doesn't pick up a dark halo from the black pixels outside it. Small thing, very visible when you're pasting a bright graphic onto a photograph.

Inputs and outputs

image is whatever mode implies - the source photo for extract, the content for fill. It accepts a ComfyUI IMAGE/MASK directly or an NPARRAY, and the warped output comes back in the same format you fed in. points is exactly four corners; mode picks the direction; max_size caps the extract output's width/height. canvas is fill mode's background, and the points live in its coordinates.

Three outputs. warped is the result, in the input's format. matrix is the 3x3 homography actually used - feed it to CV Homography Map when you want to fold this warp into a remap chain with other distortions, or compare it against a known transform. success is the boolean that tells you whether anything happened: anything other than exactly four points passes the image through untouched with success=false and an identity matrix. Branch on it with an if/else node, because a graph that ignores success will happily carry an unmodified image through the rest of the pipeline and look like it worked.

Installing

ComfyUI Manager → search "ComfyUI CV", or:

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

Python ≥ 3.12, a recent ComfyUI on the V3 node API, opencv-contrib-python-headless~=5.0.0.93 plus numpy and torch. Optional companions for the example workflows - Inspire Pack, Custom-Scripts, Basic Data Handling - are only needed for the shipped graphs, not for this node.

Gotchas

Extract mode's aspect recovery assumes the photo's centre is the principal point. That's a fine approximation for a phone snapshot and wrong for a heavily cropped or shifted image. If a document rectifies into a subtly wrong aspect, that assumption is where to look.

Fill mode needs the coordinates to match the canvas. The points are in the canvas's pixel space, not the source image's. Getting that backwards pastes your content into a corner.

Four points means four points. Not a bounding box's corners arranged differently, not eight points from a polygon, not three. The failure is graceful, but it's still a failure - and since the image passes through unchanged, the giveaway is success, not a broken picture.