UV Remap

Distorts an image by displacing or replacing UV coordinates using a second image as a UV map.

Category: Effects Menu path: Effects > UVRemap

Ports

Port	Type	Direction	Description
in	imageRgba16f	input	Input image to distort
uv_map	imageRgba16f	input	UV map image (R = X displacement/coordinate, G = Y displacement/coordinate). Also accepts any field output (scalarField / vectorField / colorField) — the engine auto-rasterizes before use.
out	imageRgba16f	output	Distorted result

Parameters

Param	Type	Default	Description
mode	enum	Displacement	How the UV map is interpreted. Options: Displacement, Absolute.
strength	vec2	(100, 100)	Displacement magnitude in pixels (Displacement mode) or scale factor (Absolute mode). X and Y independent. Keyframeable.
wrapMode	enum	Clamp	How to handle samples outside the image bounds. Options: Clamp, Repeat, Mirror.

Expose Channels

When enabled (E button on node header), adds input ports that override params via edge connections:

Port	Type	Overrides
strength_in	vec2	strength

How It Works

The shader reads each pixel of the UV map and uses its red and green channels to modify where the input image is sampled.

Displacement mode: The UV map's R and G values (centered at 0.5 = no displacement) are converted to signed offsets and multiplied by the strength parameter. The input image is sampled at the displaced position. A neutral gray UV map (0.5, 0.5) produces no distortion.

Absolute mode: The UV map's R and G values directly specify the UV coordinates to sample from the input image, scaled by the strength parameter. This gives you complete control over the sampling position.

When the uv_map input is disconnected, UVRemap acts as a passthrough with zero processing cost.

Usage Examples

Basic: Noise distortion

1. Add a Noise node and connect its out to the uv_map input of UVRemap
2. Connect your source image to in
3. Set strength to (20, 20) for a gentle organic distortion
4. Animate the Noise evolution for flowing distortion over time

Creative: Heat haze / underwater effect

1. Use a Noise node with high scale (low frequency) and animate evolution
2. Set UVRemap strength to (5, 8) -- slightly more vertical than horizontal
3. The result simulates heat shimmer or underwater refraction

Creative: Radial caustics from Voronoi

1. Connect Voronoi.direction (vectorField) directly into UVRemap uv_map
2. Set mode to Displacement, strength around (15, 15)
3. Animate Voronoi evolution slowly for shimmering water-caustic movement — pixels warp toward each Voronoi feature point

Advanced: Custom lens distortion

1. Generate a radial gradient UV map (externally or via Gradient node)
2. Use Absolute mode to remap pixel positions based on distance from center
3. Adjust strength to control the barrel/pincushion distortion amount

Tips

• In Displacement mode, a pixel value of (0.5, 0.5) means "no displacement." Values above 0.5 push in one direction, below 0.5 in the other.
• Repeat wrap mode tiles the input, Mirror reflects it, and Clamp extends edge pixels. Choose based on whether your content should tile or fade.
• When UVRemap's uv_map is disconnected, it contributes zero overscan and has no performance cost.
• Strength is in pixels (Displacement mode), so the same strength value produces a consistent visual effect regardless of composition resolution.

Related Nodes

• Noise -- procedural noise as a displacement source
• Tile -- content-aware tiling (simpler than UVRemap for grid repetition)
• Transform2D -- affine spatial transforms (position, scale, rotation)
• Blur -- soften a UV map before using it to create smoother distortions