How to Use an HDRI Environment in Three.js

Source quality is not renderer setup

A clean 2:1 panorama can still look wrong when it is assigned without equirectangular mapping, used unfiltered on rough physical materials, or displayed with unsuitable tone mapping. Conversely, renderer settings cannot level a tilted horizon, reconstruct a broken 360 seam, or turn an LDR-derived estimate into measured capture data.

The live proof uses a deterministic Radiance RGBE derivative of a real PLAYTEX AI panorama. It contains open-domain values so HDRLoader, PMREM, and exposure can be exercised, but it is explicitly a look-development estimate rather than a calibrated bracketed light probe.

PMREM answers material roughness, not sky sharpness

PMREM prefilters the environment so rough materials can sample broader lighting and glossy materials can sample tighter reflections efficiently. The official Three.js documentation identifies 1024 by 512 as the ideal equirectangular input for its 256 by 256 cubemap output.

That target is suitable for lighting, but a large visible backdrop may need more apparent detail. Keeping the raw panorama on scene.background and the PMREM texture on scene.environment preserves that choice.

Memory checks look for growth across swaps

Texture download size is not decoded GPU cost. A compressed or RGBE file is expanded into renderer resources, and PMREM adds a render target. The most useful acceptance test is a repeated environment-swap loop whose renderer.info counts settle instead of increasing every cycle.

Three.js documents that some internal textures and geometries remain visible in renderer.info after cleanup because the renderer reuses them. Treat the count as a trend signal, remove scene references first, and confirm that source textures and PMREM render targets receive explicit dispose calls.

Three.js HDRI settings and what each one controls

Loader and projection

These choices determine how Three.js reads and wraps the source file.

• HDRLoader: Decodes a Radiance RGBE .hdr file into a half-float data texture by default in Three.js r185. Use the addon loader for Radiance HDR. Do not copy an older RGBELoader import into a current r185 project.
• EquirectangularReflectionMapping: Tells Three.js that horizontal position represents longitude and vertical position represents latitude in a 2:1 panorama. Set it immediately after loading an equirectangular source; do not use it on six separate cubemap faces.
• PMREMGenerator.fromEquirectangular: Creates the prefiltered CubeUV texture sampled by physically based materials at different roughness levels. Use it for PBR image-based lighting. Keep the raw source separately when the visible background needs more detail.

Background, lighting, and display

These controls solve different problems and should be tuned independently.

• scene.background: Draws the panorama behind the scene but does not by itself define the global environment for physical materials. Set it to the raw HDR texture for a visible sky, a Color for a studio backdrop, or null for transparency.
• scene.environment: Provides the default environment map used by physical materials unless a material overrides envMap. Assign the PMREM texture for image-based lighting and reflections; set it to null to isolate direct lights.
• environmentIntensity and backgroundIntensity: Scale environment lighting and the visible background separately without rebuilding PMREM. Use these scene controls to balance lighting against sky visibility before changing display exposure.
• toneMappingExposure: Scales the renderer input before tone mapping and affects the final displayed scene, not only the HDRI. Sweep it after color space and tone mapping are correct; do not use it to disguise a broken source or material.

Memory and lifecycle checks

File size, decoded texture memory, PMREM storage, and engine-owned caches are different measurements.

• renderer.info.memory.textures: Reports the renderer texture count and is useful for detecting a count that grows after repeated environment swaps. Record before, during, and after several swaps. Do not require the count to reach zero because Three.js keeps reusable internal resources.
• Source half-float estimate: A 1024 by 512 RGBA half-float source is about 4 MiB before counting PMREM, driver overhead, or other scene textures. Use it as a labeled planning estimate only; profile the target device for the actual total.
• dispose(): Releases GPU allocations for textures, render targets, geometries, and materials when the application declares them unused. Call it at environment replacement or viewer teardown, after removing active scene references to the resource.

Set up and verify an HDRI environment in Three.js r185

Load a 2:1 Radiance HDR file with HDRLoader, mark it as equirectangular, give a PMREM-filtered texture to scene.environment, and assign the original panorama to scene.background only when it should be visible. Then set tone mapping and exposure, test rough and reflective materials, and dispose both source and PMREM resources when the environment changes.

Step 1: Start with a reviewed 2:1 environment

Create or upload the panorama in HDRI Sphere Generator, inspect the entire 360-degree wrap, level the horizon, check the left-right seam, and bake yaw only when the file orientation itself should change. Export Radiance HDR for the HDRLoader path or a labeled Three.js cubemap pack when CubeTextureLoader is the better delivery contract.

Create and inspect the environment

Step 2: Configure display output before judging brightness

Create WebGLRenderer, keep outputColorSpace at SRGBColorSpace explicitly, select ACESFilmicToneMapping, and begin with toneMappingExposure at 1.0. Lighting calculations stay in the linear working space; tone mapping and output conversion prepare the final display image.

Step 3: Load the Radiance file with HDRLoader

In Three.js r185, import HDRLoader from three/addons/loaders/HDRLoader.js. Await loadAsync, set the texture mapping to EquirectangularReflectionMapping, and retain the source texture so the visible background can remain sharper than the filtered lighting texture.

Step 4: Prefilter lighting with PMREM

Create one PMREMGenerator for the renderer, optionally compile the equirectangular shader while the file downloads, and call fromEquirectangular. Assign the returned render-target texture to scene.environment so MeshStandardMaterial and MeshPhysicalMaterial can sample roughness-appropriate lighting.

Step 5: Separate background, lighting, and exposure checks

Assign the original equirectangular texture to scene.background only if the panorama should be visible. Toggle the background while leaving scene.environment active, then toggle environment lighting while keeping the sky visible. Sweep exposure from 0.5 to 2.0 and inspect a rough dielectric plus a glossy metal before choosing a final value.

Step 6: Dispose every resource owned by the environment

Before swapping or unmounting, set scene.background and scene.environment to null, dispose the source HDR texture, dispose the PMREM render target, and dispose PMREMGenerator when the application no longer needs it. Geometry, materials, controls, and the renderer also need their own cleanup when the whole viewer is destroyed.

Failure symptoms and the setting that usually owns them

• The background looks correct but metals are black: scene.environment is null, direct light is insufficient, or PMREM was never assigned.
• Rough materials show sharp or noisy reflections: the raw HDR was used as the material environment instead of a PMREM result.
• The sky disappears when IBL is disabled: the same toggle is clearing both scene.background and scene.environment.
• Everything is washed out: verify the source range, tone mapping, exposure, and output color space before editing material values.
• Texture counts rise on every environment swap: old scene references, the source HDR, or the PMREM render target is still retained.
• A generated .hdr is treated as measured capture: PLAYTEX AI estimated HDR output must remain labeled and validated as a creative lighting asset.

Do I need PMREM for a Three.js HDRI environment?

Use PMREM for MeshStandardMaterial and MeshPhysicalMaterial image-based lighting. It prefilters the environment for material roughness. The raw equirectangular texture can remain on scene.background for a sharper visible sky.

Should scene.background and scene.environment use the same texture?

They may originate from the same file, but use the raw equirectangular texture for scene.background and the PMREM render-target texture for scene.environment. Keeping separate references also lets you hide or dim either role independently.

What tone mapping should I use for an HDRI in Three.js?

ACESFilmicToneMapping is a practical starting point for an HDR scene, but it is a look choice rather than a universal requirement. Keep outputColorSpace at SRGBColorSpace for display, begin exposure at 1.0, and judge the full scene on the target display.

Can a PNG be used as an environment map?

Yes, an LDR equirectangular image can light and reflect in Three.js after the correct mapping and PMREM step, but it does not contain open-domain HDR values. Mark a PNG color texture as sRGB and do not describe it as measured HDR lighting.

How much memory does a 1K HDRI use?

The live proof labels a 1024 by 512 RGBA half-float source estimate at about 4 MiB. PMREM, driver storage, render targets, and other scene resources add more, so use the estimate for planning and renderer.info plus device profiling for trends.

What must be disposed when replacing a Three.js HDRI?

Clear active scene references, dispose the source HDR texture, and dispose the PMREM WebGLRenderTarget. Dispose PMREMGenerator when its lifetime ends. Viewer teardown also owns geometry, materials, controls, animation, observers, and the renderer.