Skip to content

Feature

360 Photo Metadata and File Formats Explained

360 photo metadata

Wondering why your panorama shows up flat or tilted online? 360 photo metadata, mostly XMP tags inside a JPEG, tells viewers how to wrap the image into a sphere. Keep it intact when editing.

Part of the wider topic of 360 photography, this guide covers the technical labels that travel inside image files.

Item Value
Metadata standard for photo spheres Adobe XMP
GPano namespace URI http://ns.google.com/photos/1.0/panorama/
Full panorama width-to-height ratio 2:1
PoseHeadingDegrees range 0 degrees to under 360 degrees
Default for UsePanoramaViewer True

These figures come from Google’s Photo Sphere XMP documentation and the Photo Sphere Viewer guide. Specifications can change, so check the source before you rely on them.

What metadata a 360 photo file carries

A flat photo is pixels plus a few camera notes, but a spherical image needs extra instructions. XMP, Adobe’s eXtensible Metadata Platform, is a labeling technology that lets you embed data about a file into the file itself, as Trek View’s overview of XMP namespaces explains.

For panoramas, the relevant tag set is XMP-GPano, which the same overview describes as a namespace for 360 photos written by Google Photosphere. Google’s documentation says the data lives inside the image under the namespace http://ns.google.com/photos/1.0/panorama/.

Do not confuse XMP with EXIF. According to Trek View, EXIF is a closed specification with a defined number of tags, while XMP covers a much broader spectrum of file types. The same post’s worked example lists camera, GPS and XMP-GPano tags for a single photo, so the layers sit side by side in one file.

What the GPano tags tell a viewer

The GPano properties fall into a few groups, and each answers a different question for the viewer.

  • Projection: ProjectionType names how the flat image maps onto a sphere. As of the 2024-10-09 update of Google’s Open Spherical Camera reference, Google products support equirectangular.
  • Pose: PoseHeadingDegrees is a compass heading for the image centre, from 0 degrees up to but not including 360 degrees, while pitch and roll describe tilt against the horizon, per Google’s metadata page.
  • Initial view: heading and pitch values plus a horizontal field of view, which works a bit like a zoom level for the first frame a viewer shows.
  • Size and crop: full panorama width and height, cropped area width and height, and the left and top offsets.
  • Capture notes: CaptureSoftware, StitchingSoftware, SourcePhotosCount and photo dates.

That same Open Spherical Camera reference lists the fields it treats as required, among them the projection type, the viewer flag, the pose heading and the size and crop values. The safest habit is to keep the whole block together rather than hand-picking tags.

Two of the capture fields have a clear rule. CaptureSoftware should be left blank if source images were captured manually, such as with a DSLR on a tripod, according to Google, whereas StitchingSoftware records the software used to create the final photo sphere.

An open drawer contains a row of assorted paper folders.

Why crops and resizes break a panorama

Editing is where most metadata trouble starts. Google’s documentation says that when editing a photo sphere it is essential to update the matching metadata, especially CroppedAreaImageWidthPixels and CroppedAreaImageHeightPixels.

The geometry rule is simple: the full panorama’s width-to-height ratio must always be 2:1, according to the Photo Sphere Viewer guide. The cropped area values then record the real size of your image, and the offsets define where it sits inside that full frame.

A partial panorama shows why this matters. A file might cover 360° horizontally but only 90° vertically, and when a viewer finds neither a 2:1 image nor XMP data it can only make a best effort to avoid distortion, per the same guide.

That viewer’s useXmpData option reads the real image size from XMP and must be kept true if the panorama has been cropped after the shot, according to its documentation.

Which file formats carry 360 photos?

Three families show up in the sources, and they store their labels in different places.

  • Equirectangular stills: an image plus GPano tags, and the default projection used by most 360° cameras, according to the Photo Sphere Viewer guide.
  • VR photos: Cardboard Camera’s JPEG-based stereoscopic format.
  • Spherical video: a separate tag set called XMP-GSpherical.

In Google’s Cardboard Camera VR photo format, the container image acts as the left eye image, while the right eye and an optional audio file are stored as binary blobs in the metadata. Ordinary viewers therefore show an ordinary flat panorama, and the .vr.jpg extension lets software spot these files without parsing headers. GPano tags are included so the file stays compatible with the Photo Sphere standard.

Video is different. Trek View notes that exiftool is unable to write XMP-GSpherical tags into video files, and points to Google’s Spatial Media Metadata Injector, a Python script, for that job.

How to check and repair the metadata

A quick audit takes a few minutes and needs only a command-line tool and a viewer.

  1. Dump the file’s tags with exiftool and look for the XMP-GPano block, the group shown in Trek View’s example output.
  2. Confirm ProjectionType reads equirectangular, and that for an unedited file the cropped width and height equal the actual image size, as Google’s reference describes.
  3. If tags are missing, write them: the Photo Sphere Viewer guide says you can inject XMP yourself with tools like exiftool, and Trek View adds that exiftool can write XMP into photo, image and video files.
  4. Open the result in a viewer and check that the horizon is level and the first view looks right.

If your 360 photo editing software crops or resizes an export, repeat the audit afterwards. Once the tags look right, the next step is to learn how to share 360 photos online.

Frequently asked questions

Is XMP the same thing as EXIF?

Show answer

No. An XMP namespace defines a set of properties, and many namespaces exist, whereas EXIF is a fixed list of tags with a closed specification, as Trek View explains.

Can you crop a panorama without breaking it?

Show answer

Yes, if the stored size values are rewritten to match the new pixels. Google’s reference says the cropped-area image width property needs to be updated to reflect the new size of the image after a scale or crop.

Do 360 videos use the same tags?

Show answer

Not quite. Trek View calls XMP-GSpherical the most widely adopted standard for 360 videos, and says it is written into the video track rather than at the top level like other XMP tags.

What is a VR photo in Google’s older format?

Show answer

It is a stereoscopic panorama with sound, per Google’s VR documentation. That site has been archived, with its content last updated in 2019, so treat the format as legacy.