CV Thin Plate Spline Warp

Non-rigid warp from point correspondences (cv2.createThinPlateSplineShapeTransformer). Where a homography can only move a plane rigidly (8 parameters, straight lines stay straight), a thin plate spline BENDS the image so that EVERY 'from' point lands exactly on its 'to' point while minimising the bending energy in between - the physical analogy is a thin metal sheet forced through the control points. Uses: face and object morphing, warping one shape onto another after 'CV Match Features', correcting non-linear distortion no lens model covers. The shape module is a class API no raw wrapper reaches. NOTE the classes must come from the create* factory - constructing them directly yields an abstract object whose every call throws.

By bmad4ever·Created 3 months ago·Updated 2 days ago· 0

image
points_from
points_to
extra_points

image
warped_points
residual

◄regularization0►

Categoryimage/CV/features

Inputs (5)

Name	Type	Default	Description
image	COMFY_MATCHTYPE_V3		Image to bend; it is warped so that 'points_from' land on 'points_to'. Accepts a ComfyUI IMAGE/MASK directly (frame 0 of a batch) or an NPARRAY. Arithmetic ops (add, multiply, etc.) process the full IMAGE batch when both inputs have the same batch size.
points_from	NPARRAY		Nx2 control points in the INPUT image (matched keypoints, landmarks, a grid...). At least 3.
points_to	NPARRAY		Nx2 target positions, row-aligned with points_from - where each control point should end up.
regularization	FLOAT	00–1000000	Smoothing of the spline. 0 interpolates the control points EXACTLY (and follows noisy correspondences faithfully); raising it trades exactness for a gentler, more rigid warp - the knob to turn when the result folds or ripples. IMAGE-SCALE DEPENDENT: cv2 adds this to the diagonal of a kernel matrix whose other entries are d^2*log(d^2) in PIXELS SQUARED, so useful values are large - on a few-hundred-pixel image 100 buys 0.1 px of give and ~1e4 is the first setting you can see. Scale it with the SQUARE of the image size.
extra_pointsopt	NPARRAY		Optional extra Nx2 points to push through the same warp (e.g. a bounding box or contour that must follow the image). Not used to fit the spline.

Outputs (3)

Name	Type	Description
image	COMFY_MATCHTYPE_V3	The warped image, same format and size as the input.
warped_points	NPARRAY	Nx2 'extra_points' mapped through the spline (empty when none were connected).
residual	NPARRAY	Nx2 where 'points_from' actually landed minus where they should have - all ~0 at regularization 0, growing as you smooth. The honest measure of how much the spline gave up.