Pannellum

About

Pannellum is a lightweight, free, and open source panorama viewer for the web. Built using HTML5, CSS3, JavaScript, and WebGL, it is plug-in free. It can be deployed easily as a single file, just 21kB gzipped, and then embedded into pages as an <iframe>. A configuration utility is included to generate the required code for embedding. An API is included for more advanced integrations.

How to use

1. Upload build/pannellum.htm and a full equirectangular panorama to a web server.
   • Due to browser security restrictions, a web server must be used locally as well. With Python 3, one can use python3 -m http.server, but any other web server will work as well.
2. Use the included multi-resolution generator (utils/multires/generate.py) or configuration tool (utils/config/configuration.htm).
3. Insert the generated <iframe> code into a page.

Configuration parameters are documented in the doc/json-config-parameters.md file, which is also available at pannellum.org/documentation/reference/. API methods are documented inline with JSDoc comments, and generated documentation is available at pannellum.org/documentation/api/.

Using generate.py to create multires panoramas

To be able to create multiresolution panoramas, you need to have the nona program installed, which is available as part of Hugin, as well as Python with the Pillow package. Then, run

python generate.py pano_image.jpg

in the utils/multires directory. This will generate all the image tiles and the config.json file in the ./output folder by default. For this to work, nona needs to be on the system path; otherwise, the location of nona can be specified using the -n flag, e.g. python generate.py -n /path/to/nona pano_image.jpg.

Examples

Examples using both the minified version and the version in the src directory are included in the examples directory. These can be viewed by starting a local web server in the root of the repository:

python3 -m http.server

in the directory containing this readme file, and then navigating to the hosted HTML files using a web browser; note that the examples use files from the src directory, so the web server must be started from the repository root, not the examples directory.

Additional examples are available at pannellum.org.

Browser Compatibility

Since Pannellum is built with web standards, it requires a modern browser to function.

Full support (with appropriate graphics drivers):

• Firefox 23+
• Chrome 24+
• Safari 8+
• Internet Explorer 11+
• Edge

The support list is based on feature support. As only recent browsers are tested, there may be regressions in older browsers.

Not officially supported:

Mobile / app frameworks are not officially supported. They may work, but they’re not tested and are not the targeted platform.

Translations

All user-facing strings can be changed using the strings configuration parameter. There exists a third-party respository of user-contributed translations that can be used with this configuration option.

Building

The utils folder contains the required build tools, with the exception of Python 3.2+ and Java installations. To build a minified version of Pannellum, run either build.sh or build.bat depending on your platform.

Tests

A minimal Selenium-based test suite is located in the tests directory. The tests can be executed by running:

python3 run_tests.py

We create a selenium web browser (with a Chrome driver) and compare generated screenshots against previously generated ones in tests. For example, to regenerate the screen shots you can do:

$ python tests/run_tests.py --create-ref

And to simply run the tests to compare to, eliminate that argument. By default, a random port is selected, along with other arguments. You can see usage via:

$ python tests/run_tests.py --help

We run tests using CircleCI. Running the tests locally requires Python 3, the Selenium Python bindings, Firefox, geckodriver, Pillow, and NumPy.

Seeking support

If you wish to ask a question or report a bug, please open an issue at github.com/mpetroff/pannellum. See the Contributing section below for more details.

Contributing

Development takes place at github.com/mpetroff/pannellum. Issues should be opened to report bugs or suggest improvements (or ask questions), and pull requests are welcome. When reporting a bug, please try to include a minimum reproducible example (or at least some sort of example). When proposing changes, please try to match the existing code style, e.g., four space indentation and JSHint validation. If your pull request adds an additional configuration parameter, please document it in doc/json-config-parameters.md.

License

Pannellum is distributed under the MIT License. For more information, read the file COPYING or peruse the license online.

In the past, parts of Pannellum were based on three.js r40, which is licensed under the MIT License.

The panoramic image provided with the examples is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.

Credits

• Matthew Petroff, Original Author
• three.js r40, Former Underlying Framework