Displacement Map
displace
The displace parameter moves each pixel of the image according to a second image — a displacement map — that you supply. It is how you make a flat design follow the folds of a t-shirt, the ripples of a flag or the curve of a cushion, rather than merely sitting on top of them.
displace on its own does nothing. Pair it with displace-x and displace-y, which set how far pixels may move.
How a Map Works
The map’s red channel moves pixels horizontally and its green channel moves them vertically.
127 is the neutral value, not 128. A pixel in the map at exactly 127 leaves the matching image pixel where it is. Values below 127 pull the pixel one way and values above push it the other, scaled by displace-x and displace-y. A map that is a flat 7f7f7f therefore does nothing at all, which is the right starting point when authoring one.
The map is stretched over the whole image, so it does not need to match the image’s dimensions. For a product mockup this is the useful property: one map authored from a product photo works for every design placed on that photo.
Choosing a Map
A map that reads as a surface rather than as noise has four properties:
| Property | Why it matters |
|---|---|
| Grayscale | Red and green move the pixel horizontally and vertically. Equal channels move it diagonally by the same amount, which is what following a fold looks like. |
Centered on 127 | A map whose average sits well above or below 127 shifts the whole design in one direction instead of rippling it. |
| Smooth, low-frequency | Sharp edges in the map tear the image. Blurring the map is what turns a shift into a bend. |
| Low amplitude | Keep most of the map within roughly ±40 of 127 and set the distance with displace-x and displace-y. |
The surface you want the design to follow is usually the best source for its own map: desaturate the product photo, blur it so only the large shading remains, and flatten the contrast until the mid-tone sits near 127. The highlights and shadows of the real folds become the displacement field.
Any image can be used as a map, including an untreated photograph — its red and green channels simply become a chaotic displacement field, which tears rather than bends.
A Worked Example
The map below is derived from the tissue-paper photo itself with sat=-100, blur=20, con=-60 and bri=-16 — grayscale, smooth, and averaging 126. It is then passed to blend-displace so the logo, not the photo, is what bends:
https://assets.imgix.net/docs/ai-image-edit/wrinkle-fabric.jpg
?w=600
&blend=https%3A%2F%2Fassets.imgix.net%2Fimgix-logo.png%3Fw%3D300
&blend-mode=multiply
&blend-align=middle,center
&blend-displace=https%3A%2F%2Fassets.imgix.net%2Fdocs%2Fai-image-edit%2Fwrinkle-fabric.jpg%3Fw%3D600%26sat%3D-100%26blur%3D20%26con%3D-60%26bri%3D-16%26fm%3Dpng
&blend-displace-x=30&blend-displace-y=30A map passed as a URL rather than a path must be fully percent-encoded, including its own query string.
In production the map is authored once and stored alongside the product photo, so the URL carries a short path such as blend-displace=/maps/shirt-folds.png instead of a derived one.
Supplying the Map
The map is given as a path or a URL, resolved the same way a mark is.
A map that cannot be fetched fails the whole request with the origin’s own status, so a missing map returns 404. A file that is not an image returns 422.
Some maps are skipped silently, and the image renders unwarped: maps larger than 8192 px on a side, maps with 10-bit or floating-point channels, and PDFs.
Layer Forms
mark-displace and blend-displace, with their own -x and -y, displace a layer rather than the base image. Both accept indexed spellings such as blend-displace[1].
For a layer, the map is aligned to the base image rather than to the layer, which is what lets one map per product photo serve every design.
mark-tile ignores mark-displace.
Order
Displacement runs after the image is resized, unlike distort, skew and arc, which run before. Masks, borders and layers are applied afterwards.