explaingit

mpetroff/pannellum

★ 4,790JavaScriptAudience · developerComplexity · 2/5LicenseSetup · easy

TLDR

Pannellum is a lightweight browser-based 360-degree panorama viewer (21KB gzipped) that embeds into any webpage via a single iframe tag, supports hotspot linking between scenes, multi-resolution tiled loading for large images, and a JavaScript API, no plugins required.

Mindmap

mindmap
  root((Pannellum))
    Embedding
      iframe snippet
      JSON config file
      Config tool
    Display Options
      Starting position
      Field of view
      Hotspots
    Multi Resolution
      Python tiling script
      Nona tool
      Zoom levels
    JavaScript API
      Page integration
      Dynamic control
    Browser Support
      Firefox Chrome Safari
      Edge desktop
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Embed a 360-degree property or venue tour photo into a real-estate or events website

USE CASE 2

Display interactive panoramic photography in a portfolio or travel blog

USE CASE 3

Link multiple panorama scenes together with hotspots to create a virtual walkthrough

USE CASE 4

Load very large high-resolution panoramas efficiently using tiled multi-resolution mode

Tech stack

JavaScriptHTMLCSSWebGLPythonJSONiframe

Getting it running

Difficulty · easy Time to first run · 5min

Upload pannellum.htm and your panorama image to any web server, then embed with a single iframe tag. Multi-resolution tiling requires Python, Pillow, and Nona from the Hugin suite.

Open source under a permissive free license, you can use, modify, and embed it in your own projects freely.

In plain English

Pannellum is a web-based panorama viewer that lets you display 360-degree photos on any website. It runs entirely in the browser using standard web technologies, with no plugins or extra software required by the person viewing the page. The finished file is only about 21 kilobytes when compressed, so it loads quickly and can be dropped into any page by adding a single iframe tag. The most common use case is embedding a panorama into a webpage. You upload the panorama image and the viewer file to your web server, then copy a short snippet of HTML generated by the included configuration tool. For more control, the viewer accepts a JSON configuration file that lets you set the starting position, field of view, hotspots for linking between scenes, and other display options. A JavaScript API is also available for developers who want the viewer to respond to other elements on the page. For large panoramas where a single full-resolution image would be too slow to load, the project includes a Python script that slices the image into tiles at multiple zoom levels. This multi-resolution mode loads only the tiles the viewer actually needs to display, which keeps things fast even for very large images. The tiling script requires a separate tool called Nona, available as part of the Hugin panorama stitching software, along with a couple of Python image libraries. The viewer works in any modern desktop browser including Firefox, Chrome, Safari, and Edge. Mobile browsers and web application frameworks are not officially tested or supported. The project is open source under a free license, and its documentation and live examples are hosted at pannellum.org.

Copy-paste prompts

Prompt 1
I have a 360-degree equirectangular JPEG and want to embed it in my HTML page using Pannellum. Show me the minimal iframe snippet and JSON config to set initial yaw to 90 degrees and add a hotspot at pitch 0 yaw 45 linking to a second scene.
Prompt 2
Using the Pannellum JavaScript API, write code that creates a viewer on a div with id panorama, loads a config from panorama.json, and adds a button that resets the view to default pitch and yaw when clicked.
Prompt 3
I have a 200-megapixel equirectangular panorama and want to use Pannellum multi-resolution tiled mode. Walk me through running the Python tiling script with Nona from Hugin, the output folder structure expected, and the JSON config fields needed.
Prompt 4
Write a Pannellum JSON configuration for a virtual tour with three scenes, a lobby, a hallway, and a room, each linked to the others via hotspots, with custom tooltip text and autoLoad set to true.
Open on GitHub → Explain another repo

← mpetroff on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.