Developers

Three.js 360° panorama viewer: equirectangular vs cubemap

Three.js can show a 360° panorama with one texture or six. The right choice depends on the source, the device and whether you need the same asset for an engine skybox. Both paths are short; the details are color space and face order.

WorkflowUpdated Nov 9, 20268 min read3 tools linked
Key takeaways
  • Equirectangular is one texture and the simplest path; cube maps are six textures and often friendlier to older mobile GPUs.
  • Set SRGBColorSpace on color textures; an RGBE environment stays linear.
  • CubeTextureLoader expects px, nx, py, ny, pz, nz — the same order PanoCraft exports.

Path 1 — one equirectangular texture

Load the 2:1 image, set its mapping to EquirectangularReflectionMapping, and assign it to the scene background. This is the fewest moving parts and the easiest path for a CMS-driven tour.

jsexample
import * as THREE from "three";

const renderer = new THREE.WebGLRenderer({ antialias: true });
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, innerWidth / innerHeight, 0.1, 1000);

const texture = await new THREE.TextureLoader().loadAsync("/panorama.jpg");
texture.mapping = THREE.EquirectangularReflectionMapping;
texture.colorSpace = THREE.SRGBColorSpace;
scene.background = texture;

renderer.setAnimationLoop(() => renderer.render(scene, camera));
The 2:1 image is sampled as a sphere around the camera.

If the texture is also used for lighting, assign it to scene.environment. For a physically plausible result, prefer an RGBE .hdr for the environment and keep the LDR image for the visible background.

Path 2 — six cube-map faces

A cube map costs six requests but gives the renderer a native cube texture. It is also the same asset you can drop into Unity or Unreal, which makes it a good archive format for a scene library.

jsexample
const loader = new THREE.CubeTextureLoader();
const cube = await loader.loadAsync([
  "/px.png", "/nx.png", "/py.png",
  "/ny.png", "/pz.png", "/nz.png",
]);
cube.colorSpace = THREE.SRGBColorSpace;
scene.background = cube;
The six URLs are ordered px, nx, py, ny, pz, nz.

Use the Panorama to Cubemap tool to produce the six faces from a 2:1 source. Keep the same size for all six; a mismatched face is immediately visible at the seam.

Looking around

OrbitControls can drive a panorama viewer if the camera stays at the sphere's center and the target is the center too. Disable panning and set a sensible zoom range; for a real viewer, map pointer drag to yaw and pitch and clamp the pitch to ±90°.

jsexample
let yaw = 0;
let pitch = 0;

renderer.domElement.addEventListener("pointermove", (event) => {
  if (event.buttons !== 1) return;
  yaw -= event.movementX * 0.0025;
  pitch -= event.movementY * 0.0025;
  pitch = Math.max(-Math.PI / 2, Math.min(Math.PI / 2, pitch));
  camera.rotation.set(pitch, yaw, 0, "YXZ");
});
A minimal drag-to-look setup; clamp pitch so the camera never flips over the pole.

Mobile performance

  • Serve 4K equirectangular images to desktop and 2K to phones when possible.
  • Cube maps can be friendlier to older GPUs, but six textures still cost memory; keep faces at 1024 px for mobile.
  • Set texture.anisotropy to the renderer's capability, not an arbitrary high number.
  • Pause rendering when the tab is hidden; a static panorama does not need a continuous 60 fps loop.

Common mistakes

  • Forgetting EquirectangularReflectionMapping, so the texture looks like a flat poster.
  • Using SRGBColorSpace on an RGBE environment; it should stay linear.
  • Passing the six faces in the wrong order, which mirrors the world.
  • Allowing pitch beyond ±90°, which flips the view over the pole.

Before you publish

Test the viewer at phone width, drag across the seam and look straight up and down. If the seam is visible, fix the source before adding UI. The Panorama Checker reports the seam and resolution class without uploading the file.

FAQ

Questions this guide answers

Which is faster in Three.js: equirectangular or cubemap?

It depends on the device and the texture size. Equirectangular is one texture and one request; cube maps are six textures but can be friendlier to older GPUs. Measure on the target phone, not only on desktop.

Why is my Three.js panorama upside down?

Check the texture mapping and the camera rotation order. EquirectangularReflectionMapping expects the standard 2:1 orientation; a flipped source or a wrong rotation order will invert the view.

How do I reduce memory on mobile?

Use 2K textures on phones, keep cube faces at 1024 px, enable mipmaps, and release textures when the scene changes. Do not keep both the equirectangular and the cube map loaded if you only need one.

Can I use an HDR environment in Three.js?

Yes. Load a Radiance .hdr with RGBELoader, set EquirectangularReflectionMapping and assign it to scene.environment. Use the Image to HDRI tool to create an LDR-derived .hdr from a panorama.

Tools used in this guide

All free tools

Related guides

Need the source?

Generate a 2:1 panorama, then run the workflow.

PanoCraft turns a prompt or a photo into a 360° panorama. The free tools take it the last mile into your engine, viewer or lighting setup.