Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 39 ยท Textures and Loading Models

Textures and UV Mapping in Three.js

Learn how Three.js textures work: TextureLoader, CanvasTexture, UV coordinates, wrapping, repeat, filtering, color spaces and scrolling textures, with live examples.

A plain colored material only gets you so far. Real surfaces have wood grain, bricks, labels and scratches, and in Three.js you add that detail with textures: images that are stretched over a mesh. A texture is just pixel data that the GPU can sample, and a material decides what to do with each sample (use it as the color, as a bump, as roughness, and so on).

To place an image on a 3D shape, every vertex needs to know which point of the image it corresponds to. Those per-vertex image coordinates are called UV coordinates. In this lesson you will create textures from code and from files, understand UVs, control how images repeat and filter, and avoid the color-space mistake that makes textures look washed out.

Textures and UV coordinates

A UV coordinate is a pair (u, v) where both numbers run from 0 to 1. (0, 0) is the bottom-left corner of the image, (1, 1) is the top-right corner. Every built-in geometry already ships with a uv attribute, so BoxGeometry, SphereGeometry, PlaneGeometry and the rest are ready for texturing.

How a texture reaches the screen

Image Pixels from a file or canvas
UV Each vertex stores a (u, v) point
Material Samples the image per fragment

The GPU interpolates UVs across each triangle, then looks up the matching pixel.

1 / 2

Creating a texture with CanvasTexture

You do not need an image file to get a texture. Draw on a 2D canvas and hand it to THREE.CanvasTexture. This is handy for generated patterns, labels and HUD panels, and it works anywhere because no network request is involved.

A texture drawn on a canvas

MeshBasicMaterial ignores lights, which keeps this first example simple. The same map property works on MeshStandardMaterial and every other lit material.

Loading an image with TextureLoader

For real files use THREE.TextureLoader. It returns a texture immediately (empty at first) and fills it when the image arrives, so you can assign it to a material right away. For a callback or a promise, use load(url, onLoad) or loadAsync(url).

Two rules apply to images from a server. First, the server must send CORS headers if the image is on another origin, otherwise WebGL refuses the upload. Second, loaded images are decoded asynchronously, so measure their size inside the callback. The example below uses a data: URL, which has no CORS restrictions, so it runs in the sandboxed preview.

TextureLoader with repeat and wrapping

If you forget wrapS and wrapT, the default ClampToEdgeWrapping smears the last row of pixels instead of repeating, so repeat alone shows a stretched edge.

Wrapping, offset, rotation and center

Every texture has a small 2D transform applied to its UVs:

Property Meaning
wrapS, wrapT Horizontal and vertical behavior outside 0 to 1: ClampToEdgeWrapping, RepeatWrapping, MirroredRepeatWrapping
repeat How many times the image fits across the surface (Vector2)
offset Shifts the image; animating it gives a scrolling texture
rotation Rotation in radians around center
center Pivot for rotation, default (0, 0) (a corner); use (0.5, 0.5) to spin around the middle

Repeat and offset are cheap to change at runtime because only a small matrix is updated, which makes scrolling water, conveyor belts and sliding UI panels easy.

Filtering and mipmaps

When a texture is magnified (you are close to it) the GPU uses magFilter; when it is minified (it is far away) it uses minFilter.

  • THREE.LinearFilter blends neighbouring pixels: smooth. This is the default for magFilter.
  • THREE.NearestFilter picks one pixel: crisp, blocky, perfect for pixel art.
  • minFilter defaults to LinearMipmapLinearFilter, which uses mipmaps: pre-shrunk copies of the image that avoid shimmering at a distance.
  • Mipmaps need power-of-two sizes only in old WebGL 1; WebGL 2 (what Three.js uses) handles any size.
  • texture.anisotropy (up to renderer.capabilities.getMaxAnisotropy()) keeps textures sharp on surfaces seen at a steep angle, such as floors stretching to the horizon.
Scrolling texture and pixel-art filtering

Color space: the washed-out texture bug

Three.js does lighting math in linear space and converts to sRGB for the screen. An image that stores colors (a photo, a painted logo) is already sRGB-encoded, so you must tell Three.js:

JavaScript
texture.colorSpace = THREE.SRGBColorSpace;

Textures that store data (normal maps, roughness, metalness, ambient occlusion, height) are not colors and must stay in the default NoColorSpace. Rule of thumb: only the color map (map), emissive map and similar color inputs get SRGBColorSpace. Forgetting it makes images look pale; setting it on a normal map produces odd lighting.

Editing UV coordinates

Because UVs are an ordinary BufferAttribute, you can read and change them. This lets you crop an atlas cell, flip a face, or generate a planar projection yourself.

JavaScript
const uv = geometry.attributes.uv;     // itemSize 2
for (let i = 0; i < uv.count; i++) {
  uv.setXY(i, uv.getX(i) * 0.5, uv.getY(i) * 0.5);   // use the lower-left quarter
}
uv.needsUpdate = true;

A texture atlas packs many small images into one big one. One texture means one draw call for many sprites, which is why game engines love atlases. You pick a cell by scaling and offsetting the UVs, as above.

Common mistakes

  • Texture loaded from another origin without CORS headers: a security error, or a black material.
  • Forgetting needsUpdate = true after changing a canvas that backs a CanvasTexture (the first upload is automatic, later redraws are not).
  • Using the same Texture with two different repeat settings: they share one object, so clone the texture (texture.clone() then set needsUpdate = true) if two meshes need different values.
  • Huge images. A 4096x4096 RGBA texture takes about 64 MB of GPU memory with mipmaps. Resize images to what the screen actually needs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What do UV coordinates describe?

    UVs are per-vertex 2D coordinates (0 to 1) into the texture image; the GPU interpolates them across each triangle.
  2. 2. You set texture.repeat.set(4, 4) but the edge pixels look smeared instead of tiling. What is missing?

    The default wrapping is ClampToEdgeWrapping, which stretches the border pixels. RepeatWrapping makes the texture tile.
  3. 3. Which texture should get colorSpace = THREE.SRGBColorSpace?

    Color images are sRGB encoded. Data textures such as normal, roughness and AO maps are not colors and keep the default.
  4. 4. Which magFilter keeps a low resolution pixel-art texture crisp when you get close?

    NearestFilter picks a single texel, so pixels stay hard-edged. LinearFilter blends them and blurs the art.

Summary

  • A texture is image data; UV coordinates tell each vertex which part of it to show.
  • TextureLoader loads files, CanvasTexture wraps a 2D canvas you draw yourself.
  • wrapS/wrapT, repeat, offset, rotation and center transform how the image covers a surface.
  • magFilter, minFilter, mipmaps and anisotropy control sharpness.
  • Color images need SRGBColorSpace; data maps do not.
  • UVs are editable attributes, and atlases pack many images into one texture.

Next: Environment Maps and PBR Texture Maps