<iframe>. A configuration utility is included to generate the required code for embedding. An API is included for more advanced integrations.
A set of examples that demonstrate the viewer's various functionality is hosted on pannellum.org. This is the best place to start if you want an overview of Pannellum's functionality. They also provide helpful starting points for creating custom configurations.
If you are just looking to display a single panorama without any advanced functionality, the steps for doing so are covered on the simple tutorial page. Said page also includes a utility for easily creating the necessary Pannellum configuration.
If you would like to locally test or self-host Pannellum, continue to the How to use section below.
build/pannellum.htmand a full equirectangular panorama to a web server or run a development web server locally.
python3 -m http.server, but any other web server should also work.
utils/multires/generate.py), the configuration tool (
utils/config/configuration.htm), or create a configuration from scratch or based on an example.
<iframe>code into a page, or create a more advanced configuration with JSON or the API.
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/. For the standalone viewer, configuration parameters are preferably specified using a location hash instead of a location search query, e.g.,
pannellum.htm#panorama=... instead of
pannellum.htm?panorama=..., since this does not unnecessarily send the query parameters to the server.
For final deployment, it is recommended that one use a minified copy of Pannellum instead of using the source files in
src directly. The easiest method is to download the most recent release and use the pre-built copy of either
pannellum.css. If you wish to make changes to Pannellum or use the latest development copy of the code, follow the instructions in the Building section below to create
generate.pyto 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 3 with the Pillow and NumPy packages. The pyshtools Python package is also recommended. Then, run
python3 generate.py pano_image.jpg
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. On a Unix-like platform, with
nona already on the system path use:
$ cd utils/multires $ python3 generate.py pano_image.jpg
pano_image.jpg is the filename of your equirectangular panorama. If
nona is not on the system path, use:
$ cd utils/multires $ python3 generate.py -n /path/to/nona pano_image.jpg
For a complete list of options, run:
$ python3 generate.py --help
To view the generated configuration, run:
$ cd ../.. $ python3 -m http.server
This goes back to the root directory of the repository and starts a local development web server. Then open http://localhost:8000/src/standalone/pannellum.htm#config=../../utils/multires/output/config.json in your web browser of choice.
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, e.g., by running:
$ 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. For the
example-minified.htm example to work, a minified copy of Pannellum must first be built; see the Building section below for details.
Additional examples are available at pannellum.org.
Since Pannellum is built with web standards, it requires a modern browser to function.
The support list is based on feature support. As only recent browsers are tested, there may be regressions in older browsers.
Mobile / app frameworks are not officially supported. They may work, but they're not tested and are not the targeted platform.
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.
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.bat depending on your platform. On a Unix-like platform:
$ cd utils/build $ ./build.sh
If successful, this should create
build/pannellum.css, relative to the root directory of the repository.
A minimal Selenium-based test suite is located in the
tests directory. The tests can be executed by running:
A Selenium-driven web browser (with a Chrome driver, by default) is created, and screenshots are generated and compared against previously generated ones in tests. For example, to regenerate the screenshots one can run:
$ python3 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. One can see usage via:
$ python tests/run_tests.py --help
Continuous integration tests are run via Travis CI. Running the tests locally requires Python 3, the Selenium Python bindings, Pillow, NumPy, and either Firefox & geckodriver or Chrome & ChromeDriver.
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.
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. Please make an attempt to write in grammatically-correct English on the issue tracker; using the results of machine translation is acceptable if one in not fluent in the language, and attempts to work past language barriers will be made. 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. Pull requests should preferably be created from feature branches.
Pannellum is distributed under the MIT License. For more information, read the file
COPYING or peruse the license online.
The panoramic image provided with the examples is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.
If used as part of academic research, please cite:
Petroff, Matthew A. "Pannellum: a lightweight web-based panorama viewer." Journal of Open Source Software 4, no. 40 (2019): 1628. doi:10.21105/joss.01628