cv2.findHomography

A homography is the transform between two views of a flat thing. Poster, painting, book cover, screen, wall, floor tile - anything planar. Find four or more point correspondences between the source and the destination, and OpenCV gives you the 3×3 matrix that maps one plane onto the other. That matrix is what puts a rendering into a photograph, snaps a snapped photo back to a rectangle, or aligns two frames of a document.

In this pack, cv2_findHomography is the raw wrapper. It's also the node I'd only pick when I want its exact parameters, because the curated CV Find Homography (RANSAC) next to it adds the two things the raw version lacks: a found flag and a safe identity fallback.

Inputs

srcPoints and dstPoints are the two point sets - typically from CV Match Features for an automatic estimate, or from CV Points / CV Find Contours when you know the corners by hand. Both are NPARRAY-only data sockets (the pack says so in the tooltips; these are coordinate arrays, not pictures) and both must have the same length. cv2 wants floating-point CV_32FC2 data; integer arrays are the usual cause of weird results.

method is the robust estimator: RANSAC (default; handles almost any outlier ratio but needs a threshold), LMEDS (no threshold, but only when more than half your points are inliers), RHO (PROSAC-ish), the USAC_* variants, or least-squares (all points) for the no-outlier case where you just want the plain fit. For feature matches: RANSAC, no debate.

ransacReprojThreshold (3.0 by default) is the maximum reprojection error in pixels for a pair to count as an inlier - OpenCV's own docs suggest 1 to 10 for pixel coordinates. maxIters (2000) and confidence (0.995) are window dressing until the inlier ratio is bad.

That leaves the optional mask input, and the tooltip is unusually blunt about it: input mask values are ignored. It's the C++ output-buffer parameter. The inlier mask is an output.

Outputs

H is the 3×3 perspective transform (determined up to scale, normalized so h33 = 1 when it's non-zero). mask is the Nx1 uint8 inlier mask. Feed the mask to CV Draw Matches and you'll see instantly whether you're looking at a real planar alignment or four points that happened to be near each other.

Two consumers matter. cv2_warpPerspective warps the whole image through H (dsize is a Size - author it with CV Tuple), and cv2_perspectiveTransform pushes individual points through it, which is how you overlay vector geometry or a synthetic layer. The pack's AR examples - exercise_homography_ar.json, exercise_ar_planar_cube.json, exercise_ar_planar_video.json, exercise_multiposter_detection.json - are all built on that pair, and they're the fastest way to see what a good H buys you.

For the case where you already have four corners and don't need robust estimation, cv2_getPerspectiveTransform is the direct four-point solution: no RANSAC, no mask, no surprises. And if you need the opposite direction - "given this H, what planar motion does it mean?" - CV Decompose Homography returns the candidate rotations and translations with a disambiguation step.

The raw-wrapper trade

Here's the thing about using this node rather than the curated one. When findHomography can't find a sensible transform - three collinear points, a degenerate configuration, fewer than four pairs - cv2 can return an empty matrix or a matrix full of garbage, and the raw wrapper hands it to you without comment. Everything downstream then warps an image to nowhere. The curated CV Find Homography (RANSAC) node checks for exactly this: too few points, a non-finite result, or fewer than your minimum inlier count returns an identity homography, a zero mask and found = false, so a control-flow node can skip the compositing. That contract is worth more than parameter access, most days.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/bmad4ever/comfyui_cv
pip install "opencv-contrib-python-headless~=5.0.0.93"

ComfyUI Manager: search "ComfyUI CV", install, restart. Python ≥ 3.12 and a recent, V3-node-API ComfyUI.

Common issues

H is a mess and the warp looks like a fun-house mirror. Fewer than four non-collinear pairs, or correspondences that aren't really on one plane. If your "plane" has depth in it (a building facade seen at an angle, a person), no homography exists and you want an essential matrix instead.

cv2 error about point types. Cast to float and reshape to Nx1x2 (CV Cast Array, then CV Reshape Array) before feeding the node. Contour output in particular arrives in shapes cv2's homography won't take as-is.

Warped output is black in places. H maps source pixels outside the destination canvas. Check the warp's dsize and border mode, not the homography.

A contributing wheel fight. If nodes from this pack's contrib-dependent areas vanish, a non-contrib OpenCV wheel has likely emptied the shared site-packages/cv2. tools/repair_opencv_contrib.py --check then --apply.