Load Spherical Environment Map as Three.js Background

This guide explains how to load a spherical (equirectangular) texture and apply it as a 360-degree background in a Three.js scene. You will learn how to use the TextureLoader, configure the texture mapping coordinates, and assign the loaded texture to the scene background to create an immersive environment for your 3D applications.

To load and apply a spherical environment map in Three.js, follow these steps:

Step 1: Initialize the Texture Loader

Three.js uses TextureLoader to load standard image formats (like JPG or PNG) that represent a spherical map.

import * as THREE from 'three';

const textureLoader = new THREE.TextureLoader();

Step 2: Load the Spherical Texture

Load your 360-degree equirectangular image. Once loaded, you must change the texture’s mapping property to THREE.EquirectangularReflectionMapping so Three.js projects the flat image correctly onto a sphere surrounding the camera.

textureLoader.load('path/to/your/spherical-image.jpg', (texture) => {
    // Set the mapping to equirectangular
    texture.mapping = THREE.EquirectangularReflectionMapping;
    
    // Ensure correct color rendering
    texture.colorSpace = THREE.SRGBColorSpace;

    // Apply texture to the scene
    scene.background = texture;
    scene.environment = texture; // Optional: applies ambient reflections to objects
});

Step 3: Handle HDR Environment Maps (Optional)

If you are using a High Dynamic Range (HDR) spherical map for more realistic lighting, use the RGBELoader instead of the standard TextureLoader.

import { RGBELoader } from 'three/examples/jsm/loaders/RGBELoader.js';

const rgbeLoader = new RGBELoader();
rgbeLoader.load('path/to/your/environment.hdr', (texture) => {
    texture.mapping = THREE.EquirectangularReflectionMapping;
    
    scene.background = texture;
    scene.environment = texture;
});

Key Properties Explained