STMap Generate

Lens distortion is the difference between footage that looks shot and footage that looks generated. Real lenses bend: the edges stretch, the center bulges, the frame is never quite straight. ComfyTV's STMap Generate stage is the tool that bakes that distortion into a reusable map - the image that tells the UV Remap stage exactly how to warp your footage - so you apply the same lens behavior to every frame without re-solving it each time. It lives under ComfyTV/VideoFX.

An STMap (spatial/temporal map) is just a displacement image: each pixel stores where to sample from. Generate's job is to compute that map from lens math once, at width×height (defaults 1920×1080, up to 8192² - and if you wire in the optional video, it snaps the map to that footage's actual dimensions). The model dropdown picks the lens model: nuke_k1k2 (default - the classic two-constant Nuke polynomial), pf_barrel, 3de_classic, 3de_radial, and more. direction says which way to go: undistort (unbend the lens back to straight) or distort (bend straight footage to look lensy).

Then the actual lens parameters: k1/k2 (the radial distortion coefficients - the heart of the polynomial model), fov (field of view, 20–180, default 140 - the wide-lens feel), center_x/center_y (where the optical center sits, in normalized offset), squeeze (anamorphic-ish horizontal squeeze), lens_scale (zoom inside the map), plus cx_curv/cy_curv and tang_u/tang_v for curvature and tangential distortion. And pt_c - the "pleat" coefficient, the extra term that makes Nuke's model match real wide lenses. The single output, stmap (COMFYTV_IMAGE), is what you wire into the UV Remap stage's uv_image input.

The workflow shape

Generate once, apply everywhere. Because the map is resolution-matched and cheap to produce, the flow is: generate your map → UV Remap it over the clip → chain the warped footage onward. The payoff vs. applying distortion as a per-frame filter is both speed and consistency - every frame gets exactly the same warp, which is what your eyes read as "this was shot with a lens."

Install

With ComfyTV:

cd ComfyUI/custom_nodes
git clone https://github.com/jtydhr88/ComfyTV

Restart ComfyUI; under ComfyTV → VideoFX. ComfyUI Manager: search "ComfyTV". Desktop/macOS: clone into the running instance's absolute custom_nodes (startup-log path), fix any ComfyTV/ComfyTV/ nesting, full backend restart. No models, no extra deps.

Troubleshooting

• Subtle or no distortion at defaults. k1/k2 start at 0 - nothing is distorted until you set them. Even ±0.05–0.1 is visible on a wide frame.
• Map doesn't match my footage. Wire the video input so the map resolves to the clip's real dimensions; a 1920×1080 map on 4K footage stretches.
• Undistort makes the edges go soft/empty. That's normal for aggressive undistortion - you're pulling edge pixels outward. Add lens_scale (zoom in) to crop the empty margin.