cv2.ft.FT02D_iteration

cv2.ft.FT02D_iteration is one step of the fuzzy-transform repair loop: a forward F-transform, an inverse transform, and a mask update - with a status code so the caller knows how it went. OpenCV's own docs say it plainly: this function is what ft::inpaint uses internally.

That's the honest framing. If you want fuzzy-transform inpainting, use cv2.ft.inpaint, which does the iterating for you. This node is here for the case where you want to run the iterations yourself - inspect the mask between steps, stop when the status says things have settled, or feed it a mask from somewhere else entirely.

The mechanism

The F-transform works in two halves. The forward pass slides a window (whose shape and radius come from a kernel built by cv2.ft.createKernel) across the image and reduces each window to a weighted average; the inverse pass rebuilds pixels from the overlapping window values. Iterating means doing that round trip repeatedly, letting each pass's result seed the next, while keeping track of which pixels were trustworthy to begin with and which were reconstructed.

The mask is that bookkeeping. Non-zero means the pixel is known, zero means it's missing - the same convention as cv2.xphoto.inpaint and the opposite of cv2.inpaint. Since a mask you paint in ComfyUI has the hole set to 1, this node needs a cv2.bitwise_not in front of it. That reversal is the single most common mistake made with this entire family.

Inputs and outputs

• matrix - IMAGE, MASK or NPARRAY. An IMAGE arrives as uint8 BGR, frame 0 of a batch only.
• kernel - from cv2.ft.createKernel, channel count matching the image.
• mask - required here, unlike its optional sibling FT02D_process. Non-zero = known.
• firstStop - a boolean that decides how failures are reported: true means bail out and return -1 the moment a problem appears, false means push through and return the sum of all problems. It only affects the status value, not the pixels.
• maskOutput - optional, and it's an input on purpose: hand it a mask to start from.

Then three outputs, and the second and third are the loop:

• int - the status. 0 is a clean pass, -1 is "stopped at the first problem", anything else is an accumulated problem count. Read it. This is the rare node in ComfyUI that tells you it went badly instead of returning a plausible-looking array.
• nparray_1 - the 32-bit float image after this iteration.
• nparray_2 - the mask after this iteration, which is the mask you feed into the next copy of this node.

Running the loop

ComfyUI has no built-in loop construct, so "iterate" here means chaining a few copies of this node - mask output into the next node's maskOutput, image output into its matrix - or using a loop node from another node pack. Three to five copies is a perfectly reasonable thing to sketch out by hand for a one-off repair. For anything you'd run twice, use cv2.ft.inpaint, which packages exactly this loop and lets you pick the strategy.

nparray_1 and nparray_2 are NPARRAYs, so they don't preview as images. Watch the image with Preview CV Array and read the mask and the status with Inspect CV Data.

Install

Manager → search ComfyUI CV, or:

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

Restart ComfyUI. ft is contrib-only, so a non-contrib opencv-python sneaking into the shared site-packages/cv2 deletes this node along with the rest of the family. Needs Python ≥ 3.12 and a recent ComfyUI on the V3 node API; no models to download.

Where people get burned

• Mask convention. Non-zero = known. Invert your hole mask first.
• Radius 0 kernels. The kernel is (2r+1) square, so radius 0 gives a 1×1 kernel and the "iteration" does nothing at all - quietly.
• Ignoring the int output. If it's -1 every pass, you're iterating on a mask and image that cv2 considers a problem, and no amount of chaining will fix it.
• Feeding it a whole clip. Frame 0 only. This is not a video node.