If you build anything that touches 360° content (a viewer, an upload pipeline, a tour builder), almost every bug report starts with the same file format: the equirectangular image. Here is what that format actually is, how to validate it before it reaches your viewer, and the edge cases we keep running into at Prewalk, where we turn 360° photos and renders into browser-based virtual tours.
One file, the whole sphere
A 360° photo stores everything visible from one point in a single flat image: 360° horizontally and 180° vertically. Unwrapping a sphere onto a rectangle that way is the equirectangular projection, and it has three properties your code can rely on:
- The horizontal axis is longitude. x = 0 is −180°, x = width is +180°, and the left and right edges are the same meridian.
- The vertical axis is latitude. y = 0 is straight up (+90°), y = height is straight down (−90°).
- The horizon is the middle row. In a level shot it runs exactly through y = height / 2.
Because both axes are linear in degrees and they span 360° and 180°, a valid file is exactly 2:1. That single fact is your cheapest validation check.
A panorama is not a 360° image
Phone panorama mode captures a horizontal strip with no ceiling or floor, usually 3:1 or wider. Feed that into a spherical viewer and it gets stretched over the poles. Google's Photo Sphere spec makes the same distinction: a full sphere (360° × 180°) versus a partial panorama.
Validate before you render
The aspect ratio check catches most bad uploads. In the browser:
async function checkEquirect(file) { const bitmap = await createImageBitmap(file); const { width, height } = bitmap; bitmap.close(); if (width !== height * 2) { return { ok: false, reason: `Not 2:1 (${width} × ${height})` }; } if (width > 16384) { return { ok: false, reason: 'Wider than 16384 px; most GPUs cannot hold it as one texture' }; } return { ok: true, width, height }; } A few things we learned the hard way:
- Allow no tolerance on the ratio. 8000 × 4096 "looks" 2:1, but the viewer stretches it to fit the sphere and the left and right edges no longer meet cleanly.
- Do not trust metadata alone. Google's Photo Sphere XMP adds
GPano:ProjectionType = equirectangular, which is useful as a hint, but plenty of valid renders ship without it and plenty of wrong crops keep it. - Stereo files are square. A top-bottom stereo panorama stacks two 2:1 spheres, so it is 1:1 (e.g. 8192 × 8192). Decide explicitly which eye is on top; mixing that up makes near objects look far away in a headset.
- Cube maps are a different format. Six faces, not one projection. Convert them before they reach an equirectangular pipeline.
How the viewer turns it back into a room
A viewer maps the image onto the inside of a sphere and puts the camera at its center. For each screen pixel it computes a ray direction, converts that to longitude and latitude, and samples the image there. So the "warping" users complain about in the raw file is correct; it only looks wrong outside a viewer.
Resolution in practice
For phones and laptops, around 5.7K (5760 × 2880) is a reasonable floor; 8K (8192 × 4096) holds up when people zoom. Past 8K, a single texture becomes a problem on many devices, so viewers load the image in tiles. That is how we serve up to 16K panoramas without making the first frame slow.
Further reading
The full guide (how to shoot and view 360° photos, camera resolutions, viewers) is here: What is a 360° photo?. If you want to see the format end to end, this sample tour is built from 2:1 renders and opens in the browser and in a Meta Quest.
Disclosure: I work on Prewalk. This post was written with AI.



