Three.js UV Layout Previewer & Distortion Heatmap

Inspect a mesh's UV layout in Three.js with a live 2D UV panel, a labelled checker texture, a per-triangle stretch heatmap and planar, cylindrical and spherical projections, plus hover highlighting linked between mesh and UV space.

Key topics: three.js uv, uv mapping, uv unwrap, texture distortion, checker texture, uv layout

What this code does

- UV Panel: triangles from the `uv` attribute are drawn into a canvas, flipped vertically because UV v points up.
- Checker: a labelled checker shows seams, flips and stretching directly on the mesh.
- Stretch Heatmap: each triangle's share of 3D area divided by its share of UV area; green is uniform, red stretched, blue squashed.
- Projections: planar, cylindrical and spherical mappings recompute UVs from position, the starting point of most unwraps.
- Linked Hover: raycasting the mesh highlights the triangle in UV space, and hovering the UV panel highlights it in 3D.
- Controls: model, UV projection, checker or heatmap and UV wireframe.

Continue Learning

JavaScript Implementation

ES6+
// Draw a mesh's UV layout into a 2D canvas
const geometry = new THREE.TorusKnotGeometry(0.8, 0.28, 128, 16).toNonIndexed()
const uv = geometry.attributes.uv
const ctx = uvCanvas.getContext('2d')
const S = uvCanvas.width
ctx.strokeStyle = '#38bdf8'
for (let i = 0; i < uv.count; i += 3) {
  ctx.beginPath()
  for (let k = 0; k < 3; k++) ctx.lineTo(uv.getX(i + k) * S, (1 - uv.getY(i + k)) * S) // v points up in UV space
  ctx.closePath()
  ctx.stroke()
}
// texel stretch per triangle = (3D area / total 3D) ÷ (UV area / total UV): 1 means uniform density