Warp a Display Output's UV Mapping

Last updated 11 August 2026

A display output (LED wall, monitor, panelled screen) can carry its own UV warp, so content lands correctly on a physically non-planar surface - a dome, a curved wall, or faceted panels. You author the warp as a control-point mesh, an imported warp image, or both.

Before you start

  • A display output exists and is routed to a surface in the Video Routing matrix.
  • Content playing on the display so you can see the effect of your warp.
  • If you plan to import a warp image, have the file ready. Use PFM (32-bit float). An 8-bit image can only address 255 coordinates across its width, which produces visible stepping on any large output. 16-bit PNG does not help either. PFM holds the coordinate exactly.

Steps

1. Open the warp window on your display output

Select the display output in the Outputs panel. In the Inspector, expand the Mesh Warping section and click Open Mesh Warping Window. This creates the UV warp and opens a window whose title bar reads Output Mesh Adjustment - <output name>, with your display already selected. This is the same window that the Output Warping reference page documents.

You can also select an output from the dropdown inside the warp window itself - it lists every projector and every display output. Picking a display that has no warp yet creates one automatically.

2. Choose a base shape

In the Mode dropdown, pick the parametric shape that best matches your physical display:

  • Planar - flat output, with an optional 4-corner keystone.

  • Cylindrical - curved top and bottom edges (6 base handles). Use for a curved wall.

  • Toroidal - curved on all four edges (8 base handles). Use for a dome or doubly-curved wall.

3. Adjust the base handles

If you chose Cylindrical or Toroidal, click the base-shape icon in the toolbar (cylinder or saddle icon) to enter base-edit mode. Click a handle to select it, then click again and drag to move it. Use arrow keys for fine adjustment. Click the icon again to return to grid editing.

4. Refine with the control-point grid

Set the grid resolution with the Grid X and Y fields. Then drag individual control points to fine-tune the warp. Dragging moves the image in the direction of the drag.

  • Click to select a point. Ctrl+click to add to the selection. Box-select by dragging on empty space.

  • Ctrl+A selects all points. Arrow keys nudge the selection.

  • Right-click for Reset Selected Points, + Add point, and Remove Points.

  • The toolbar's Spline toggle switches between curved and linear interpolation. Falloff H / V controls whether an edit spreads to neighbouring points horizontally or vertically.

5. Import a warp image (optional)

If a calibration tool has produced a warp image (a file whose red and green channels encode the UV coordinate to sample at each pixel), click Import Image... on the third row of the top strip and select the file. Once loaded, the row shows the decoded resolution and format, plus Reload and Remove buttons.

How image and mesh compose. The imported image does not replace the mesh. The mesh's control-point grid is what addresses the image: an unwarped grid leaves the imported mapping exactly as authored, and dragging a control point moves that mapping with it. This makes an imported calibration file a starting point you can refine by hand, rather than a final answer you must accept. There is no mode switch - it is always on.

6. Import or export the mesh

Use Import Mesh... and Export Mesh... to save or load a warp grid file. An imported mesh replaces the current grid geometry and resets the base handles to flat. Use this to transfer a hand-built warp between outputs or machines.

7. Disable the warp without losing it

To turn the warp off while keeping the project data, select the display output, open the Mesh Warping section in the Inspector, and clear the Enable UV Warp checkbox. This frees the warp's textures. Re-enabling it restores the mesh and any imported image.

Common Mistakes

  • Expecting to warp the whole surface from one output. On a split display surface, the warp grid spans only this output's display slot, not the whole surface. Each output's grid covers the image that output actually shows, and the grid's aspect follows the slot.

  • Importing an 8-bit warp image. 8-bit images produce visible stepping (~7.5 px plateaus on a 1920-wide output) because only 255 coordinate values exist across the width. Use a 32-bit float PFM.

  • Importing a mesh and expecting the base shape to survive. Import Mesh replaces the grid geometry and resets the base handles to flat (Planar). Build the base shape after importing, or export and re-import only the grid.

  • Trying to undo a Reload. Reload re-reads the same file and is not undoable. Import and Remove are undoable.

Tips

  • A missing warp-image file is a warning, not an error. The output keeps its mesh warp and retains the file path, so Reload works once the file is available again. Useful when moving a project between machines.

  • The reset button is context-sensitive: it reads Reset Keystone / Reset Cylinder / Reset Toroid while editing the base, Reset Selected with points selected, and Reset Grid otherwise.

  • Navigate the view with Ctrl+Wheel to zoom, middle-drag or scroll wheel to pan, Shift+Wheel for horizontal pan, and F to reset the view.

  • Everything persists in the project. Older projects that have no warp load unchanged - a warp-free project carries no overhead.

Configure Projector Warping (Mesh Warp) - projector warping uses the same window, base shapes, and grid interaction.

Output Warping - reference for the Output Warping window.

Warp, Blend & Black Level - parent section covering warping, blending, and black level.