Pannellum is built using WebGL and JavaScript, with a sprinkling of HTML5 and
CSS3. It can run standalone or can be embedded using either an <iframe> or
a JavaScript API. The standalone method, which is used for <iframe>
embedding, is the easiest and simplest to use, but the JavaScript API is more
powerful and provides tighter integration. Internally, the standalone viewer
parses URL parameters to build a JSON-based configuration and then instantiates
the viewer using the JavaScript API. The standalone viewer accepts a subset of
configuration parameters as URL parameters; the rest of the parameters can be
set using a JSON configuration file specified using the special config URL
parameter.
Since Pannellum is static content, it can be hosted on virtually any web server. A CDN is also provided for convenience. For more information on getting Pannellum, see the downloads page.
Panoramic images can be provided in either equirectangular, cube map, or
multiresolution formats. Equirectangular is the simplest to use as only a
single image is needed; Google Photo Sphere XMP metadata
is automatically read and used if provided. However, to ensure support among
all WebGL-capable devices, the maximum image size should be preferably limited
to 4096 px wide; 8192 px is also acceptable for most devices.
Cube maps require six images but support somewhat higher resolution panoramas,
as the vast majority of devices support cube faces up to 4096 px across.
Additionally, cube maps are supported by Pannellum’s fallback CSS 3D
transform-based renderer and will therefore work on older mobile devices that
don’t support WebGL. Although larger images are supported, download sizes
should be taken into consideration. The final input format is Pannellum’s
multiresolution format, which is generated from an equirectangular image using
Pannellum’s generate.py
Python script. This format is a cube map-based format, except each cube face is
a tiled image pyramid
instead of a single image. Arbitrarily large images are supported, the CSS 3D
transform-based fallback renderer is supported, and load times are quick due to
the image pyramids. The downside of this format is that extra work is required
to convert an image to it and the large number of files that must be hosted.
Additional features of Pannellum include hot spots for displaying information,
linking of multiple panoramas into virtual tours, and video support. The best
way to learn about Pannellum’s features and how to use them is to peruse the
examples and
configuration reference. Since it is not
obvious from the examples, it is prudent to note that the hotSpotDebug
parameter exists to aid in the placing of hot spots. It can be enabled while
setting up the hot spots, but it should always be disabled in production.
Pannellum is developed on GitHub by Matthew Petroff.