Matthew Petroff 1eaccef60f | 1 month ago | |
---|---|---|
.github | 4 years ago | |
doc | 3 months ago | |
examples | 3 years ago | |
paper | 5 years ago | |
src | 1 month ago | |
tests | 2 years ago | |
utils | 2 months ago | |
.gitignore | 5 years ago | |
.npmignore | 8 years ago | |
.travis.yml | 2 years ago | |
CITATION.cff | 3 years ago | |
COPYING | 8 months ago | |
VERSION | 5 years ago | |
changelog.md | 5 years ago | |
package.json | 5 years ago | |
readme.md | 1 year ago |
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.
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.htm
and 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.htm
or pannellum.js
& 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 build/pannellum.htm
, build/pannellum.js
, and build/pannellum.css
.
generate.py
to create multires panoramasTo 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
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. On a Unix-like platform, with nona
already on the system path use:
$ cd utils/multires
$ python3 generate.py pano_image.jpg
where 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 / web 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.
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. On a Unix-like platform:
$ cd utils/build
$ ./build.sh
If successful, this should create build/pannellum.htm
, build/pannellum.js
, and 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:
python3 run_tests.py
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.
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.
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