<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[Prewalk Engineering]]></title><description><![CDATA[Prewalk Engineering]]></description><link>https://prewalk.hashnode.dev</link><image><url>https://cdn.hashnode.com/uploads/logos/6afa28cc694857d5fe45b873/f61fb140-4e52-4e60-83dc-0b92e063c505.png</url><title>Prewalk Engineering</title><link>https://prewalk.hashnode.dev</link></image><generator>RSS for Node</generator><lastBuildDate>Wed, 18 Nov 2026 14:02:31 GMT</lastBuildDate><atom:link href="https://prewalk.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[Why 360° panoramas must be exactly 2:1, and how to validate them before upload]]></title><description><![CDATA[Why equirectangular panoramas must be exactly twice as wide as tall, the usual export mistakes, and JS code to validate files before upload.]]></description><link>https://prewalk.hashnode.dev/why-360-panoramas-must-be-exactly-2-1-and-how-to-validate-them-before-upload</link><guid isPermaLink="true">https://prewalk.hashnode.dev/why-360-panoramas-must-be-exactly-2-1-and-how-to-validate-them-before-upload</guid><category><![CDATA[JavaScript]]></category><category><![CDATA[webdev]]></category><category><![CDATA[image processing]]></category><category><![CDATA[Virtual Reality]]></category><dc:creator><![CDATA[Prewalk]]></dc:creator><pubDate>Sun, 15 Nov 2026 21:54:01 GMT</pubDate><content:encoded><![CDATA[<p>Most "my virtual tour looks broken" bug reports we get at <a href="https://prewalk.co">Prewalk</a> come down to one thing: the uploaded image isn't a real 360° panorama. The fix is cheap if you check the file before it ever reaches the server. Here's why the rule exists and a few lines of code to enforce it.</p>
<h2>Why 2:1?</h2>
<p>A 360° tour viewer takes a flat image and wraps it onto the inside of a sphere. The standard flat format for that is the <strong>equirectangular</strong> projection: longitude maps to x, latitude maps to y.</p>
<ul>
<li>Horizontally, the image covers 360°.</li>
<li>Vertically, it covers 180° (straight up to straight down).</li>
</ul>
<p>360 / 180 = 2. So a complete panorama is always exactly twice as wide as it is tall: 8192 × 4096, 5760 × 2880, 16384 × 8192. If the ratio is off, the viewer either stretches the image or leaves a hole at the top and bottom of the sphere.</p>
<h2>The usual suspects</h2>
<table>
<thead>
<tr>
<th>What the user uploads</th>
<th>What goes wrong</th>
</tr>
</thead>
<tbody><tr>
<td>A phone "panorama mode" strip</td>
<td>Not a sphere at all: no ceiling, no floor, ratio like 6:1</td>
</tr>
<tr>
<td>A 360° photo exported as "flat" or "tiny planet" from the camera app</td>
<td>Re-projected; looks fine as a picture, wrong as a sphere</td>
</tr>
<tr>
<td>A render cropped to 8192 × 3800</td>
<td>Close to 2:1, but the poles are cut off and the horizon shifts</td>
</tr>
<tr>
<td>EXR / HDR / HEIC / RAW</td>
<td>Needs converting to JPG, PNG, TIFF or WebP first</td>
</tr>
</tbody></table>
<p>The cropped one is the nastiest, because it <em>looks</em> right in a file browser.</p>
<h2>Check it in the browser before upload</h2>
<p><code>createImageBitmap</code> gives you dimensions without rendering anything:</p>
<pre><code class="language-js">async function checkPanorama(file) {
  const allowed = ['image/jpeg', 'image/png', 'image/webp', 'image/tiff'];
  if (!allowed.includes(file.type)) {
    return { ok: false, reason: 'Convert to JPG, PNG, TIFF or WebP first.' };
  }

  // TIFF usually can't be decoded by browsers; check it on the server instead.
  if (file.type === 'image/tiff') return { ok: true, checkedOnServer: true };

  const bmp = await createImageBitmap(file);
  const { width, height } = bmp;
  bmp.close();

  if (width !== height * 2) {
    return {
      ok: false,
      reason: `${width} × ${height} is not 2:1. A full 360° panorama is exactly twice as wide as it is tall.`,
    };
  }
  return { ok: true, width, height };
}
</code></pre>
<p>Use a strict equality, not a tolerance. A file that's "almost 2:1" is almost always a crop, and accepting it just moves the bug to the viewer.</p>
<h2>Check it in a pipeline</h2>
<p>For batch jobs (say, a render farm dropping files into a bucket), the same check with <code>sharp</code> in Node:</p>
<pre><code class="language-js">import sharp from 'sharp';

export async function isEquirect(path) {
  const { width, height } = await sharp(path).metadata();
  return width === height * 2;
}
</code></pre>
<p>Or from the shell with ImageMagick: <code>identify -format "%w %h" pano.jpg</code>.</p>
<h2>Size limits are a separate check</h2>
<p>Once the ratio is right, check the width against whatever your viewer supports. In Prewalk that's up to 8192 px on the free plan and up to 16384 px on paid plans, and up to 1 GB per file. Very large images are where tiled loading earns its keep: the viewer shows a low-res preview immediately and sharpens only the part you're looking at, instead of decoding one giant texture on a phone.</p>
<h2>Stereo panoramas: same rule, stacked</h2>
<p>For VR headsets, a top-bottom stereo panorama stacks the left eye above the right eye. Each half is 2:1, so the full file is 1:1 (for example 8192 × 8192). If you support stereo, check for both shapes and decide which one the user meant.</p>
<hr />
<p>The full list of export mistakes, with fixes for common cameras and render tools, is in our guide: <a href="https://prewalk.co/blog/common-360-export-mistakes">Common 360° export mistakes</a>. If you validate panoramas differently, I'd like to hear how.</p>
]]></content:encoded></item></channel></rss>