DDC Predict Points

Automatic dewarping is a single forward pass and it usually works. When it doesn't, the failure is specific and infuriating: a line of text bends through the middle of the page, or the right margin runs off the canvas entirely. There's no dial to turn. DocRes just decided the page was shaped like that.

That's the gap the DDC trio fills, and DDC Predict Points is step one. It runs a control-point network that lays a 31x31 grid over the page and reports where each crossing should be - then hands you a coarse, draggable subset of it. The whole point is that those points are just numbers, so a human can move them.

What it actually produces

The network is trained on a 992x992 prediction canvas and emits a 31x31 grid - 961 points. The node then resizes your image onto the 960x1024 canvas the original project marks up, maps the points into those coordinates, and subsamples the grid down to 9x9 = 81 handles. That's the whole trick: the full 31x31 grid rides along untouched for the warp to be fitted against later, while you only ever have to drag a manageable square of dots.

It has three outputs and beginners wire the wrong one about half the time:

• points (DDC_RAW_POINTS) - the payload. It carries the full fine grid, the coarse handles, the network's segment head, the canvas dimensions, and a JSON encoding of the handles. This type only connects to DDC Edit Points, so there's no ambiguity about where it goes.
• preview (IMAGE) - the canvas with the dots drawn on it. This is what the editor displays, and it's the one you look at.
• image (IMAGE) - the same 960x1024 canvas with no markings, because it's destined for warping. Power it into DDC Rectify and nothing gets drawn into your page.

Inputs

image - the distorted scan. Full stop, no pre-processing needed.

device - auto, cuda, mps, cpu. Unlike the DocRes pair, there's no loader node here; each DDC node resolves its own device, and the 51 MB weights are fetched and cached behind the scenes. On a GPU the whole prediction is quick enough that you won't think about it.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/zjkhurry/comfyui-docres.git
pip install -r comfyui-docres/requirements.txt

Restart, and everything shows up under image/DocRes - or install through Manager by searching for DocRes. Four dependencies (einops, opencv-python, scikit-image, safetensors), of which only scikit-image is likely to be missing from your environment.

One weight file matters here: ddc_fiducial1024_v1.safetensors, 51 MB, downloaded automatically on first run into comfyui-docres/weights/. Drop it in ComfyUI/models/ instead if you'd rather it never download at all.

Where it goes wrong

Nothing appears to happen. This node isn't an output node, so it only executes when something downstream needs it - typically DDC Edit Points, which is an output node and will publish the picture through its own preview. If you've got Predict Points sitting on the canvas with nothing after it, the preview image never renders.

The grid looks wrong before you've touched anything. That's the model, not a bug. It's a fiducial/control-point network: it's at its best on pages with visible structure and reasonable contrast against the background. A page with no distinguishable edges, a huge amount of background clutter, or a photo taken at an angle so steep the page is half out of frame will get a coarse grid that needs real dragging rather than mild nudging.

You're using the sledgehammer on a problem DocRes already solved. If the page is mildly curved, run the automatic dewarping task first - it's one pass and no interaction. Come here when the automatic result bends the text or pushes the margin off the canvas, which is exactly the case the control-point path was ported for.

Points without an editor. points only wires into DDC Edit Points. That node is mandatory: there's no path from prediction straight to a warp, because the editing stage is what converts the raw grid into the DDC_EDITED_POINTS type that DDC Rectify accepts.