How to Load an HDRI Environment Map in Three.js

Using an HDR (High Dynamic Range) environment map is one of the most effective ways to achieve realistic, image-based lighting and reflections in Three.js. This guide provides a direct, step-by-step walkthrough on how to load a .hdr file using the RGBELoader and apply it to your scene’s background and lighting environment.

1. Import the Required Modules

To load .hdr files, you need the standard Three.js library and the RGBELoader utility, which is located in the examples folder of the Three.js package.

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

2. Set Up the Renderer

Ensure your renderer is configured to handle high dynamic range colors correctly. You should enable tone mapping to prevent the bright parts of your HDRI from clipping.

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.toneMapping = THREE.ACESFilmicToneMapping; // Enhances contrast and brightness
renderer.toneMappingExposure = 1.0; // Adjusts overall lighting intensity
document.body.appendChild(renderer.domElement);

3. Load and Apply the HDRI

Create an instance of RGBELoader to fetch the .hdr file. Once loaded, you must configure its mapping type so Three.js projects the 2D texture onto a 3D sphere surrounding the camera.

const scene = new THREE.Scene();

// Initialize the RGBELoader
const rgbeLoader = new RGBELoader();

// Load the HDRI file
rgbeLoader.load('path/to/your/environment.hdr', function (texture) {
    // Set equirectangular mapping for spherical projection
    texture.mapping = THREE.EquirectangularReflectionMapping;

    // Use the texture as the visual background of the scene
    scene.background = texture;

    // Use the texture as the light source and reflection map for materials
    scene.environment = texture;
});

4. Create Reflective Materials

For your models to benefit from the environment map’s lighting and reflections, use Physically Based Rendering (PBR) materials like MeshStandardMaterial or MeshPhysicalMaterial.

const geometry = new THREE.SphereGeometry(1, 64, 64);
const material = new THREE.MeshStandardMaterial({
    metalness: 1.0,  // High metalness makes reflections highly visible
    roughness: 0.1   // Low roughness makes the surface shiny
});

const sphere = new THREE.Mesh(geometry, material);
scene.add(sphere);

Summary of Key Properties