IG_LoadCheckerboardImageForCalibrateCamera

Most ComfyUI nodes make images. This one does real computer vision instead: it runs an actual camera-calibration routine - the same OpenCV pipeline a robotics lab uses - so the rest of your graph can undo the way a lens bends straight lines. It's the first step in the three-node iFREEGROUP/comfyui-undistort pack, and it's the step people actually fumble, because it asks you to do homework: print a checkerboard and take some photos.

You reach for it when your source images come from a real camera whose lens curves the world - phone wide-angles, action cams, cheap webcams, the dreaded fisheye - and that curvature is fighting whatever comes next. Diffusion models quietly assume a pinhole camera, so a heavily barrel-distorted photo fed into img2img, an upscaler, or IPAdapter carries geometry errors into the output. Fix the geometry first and the rest of the workflow behaves the way you'd expect. Photorealism guides treat lens distortion as a telltale of genuine captures; this node is the reverse move, deliberately stripping that tell so the image matches what the pipeline assumes.

How the calibration actually works

Textbook stuff, and none of it needs a GPU. Print a checkerboard, photograph it from a dozen angles, and the node finds the board's interior corners in every shot, refines them to subpixel accuracy, and feeds them all to cv2.calibrateCamera. OpenCV solves for the camera matrix (focal lengths and principal point) plus the distortion coefficients that describe why straight lines come out curved. It's Zhang's method, decades old, still the right tool, and it runs in seconds on CPU. No models, no weights, no downloads.

The inputs that matter

Only three, and the last two are where everyone burns themselves.

• directory - an enum of subfolders under ComfyUI/input. Your checkerboard photos must live in a subfolder like input/checkerboard/; loose files sitting directly in input/ won't show up. Only .jpg, .jpeg, and .png are read.
• rows and cols - sliders from 3 to 20, default 3. Here's the trap: these are the number of squares along each side of the board, not the interior corners. The node subtracts one from each and hands (cols-1, rows-1) to findChessboardCorners. So the classic 8×6-corner print target needs rows = 7, cols = 9. Leave the default 3×3 and you're calibrating with a grand total of four corners, which is nothing.

What comes out

Six outputs, but you'll use two of them:

• matrix - the 3×3 intrinsics, and dist_coef - the five distortion coefficients. These are the ones that matter; wire them straight into IG_Undistort.
• rvecs / tvecs - per-photo rotation and translation vectors. The pack's own example workflow doesn't even connect them. You won't need them.
• h / w - height and width of the last image the node read. Handy for confirming it actually saw your photos.

Install

The pack installs once and provides all three nodes. ComfyUI Manager → search "comfyui-undistort", or:

cd ComfyUI/custom_nodes
git clone https://github.com/iFREEGROUP/comfyui-undistort

then restart ComfyUI. The only dependency is opencv-python in requirements.txt, and since a ComfyUI environment almost always has cv2 already, this is one of the rare packs that just works with no extra install step. It's a tiny, single-commit repo from May 2024 that nobody's updated since - fine for a utility this small, but don't expect maintenance.

When it breaks

Two failure modes are visible in the code itself, so they're worth knowing upfront. First: if no image yields a corner detection - blurry shots, boards cut off at the frame edge, harsh glare - the point lists stay empty and calibrateCamera throws, because there's no error handling. Aim for a dozen clean, sharp, varied-angle photos and you'll avoid it. Second: corner detection runs with default flags and no adaptive thresholding, so a board with uneven lighting or strong shadows can simply not be found. And since every detection goes into one shared solve, a couple of misfit frames quietly skew the whole result - retake the shot, don't trust the output.