Pannellum Documentation

Pannellum is a lightweight, interactive, web-based panorama viewer written in JavaScript. It uses WebGL for GPU-accelerated rendering to an HTML5 <canvas> element.

Key capabilities include:

• Format Support: Displays equirectangular panoramas (full sphere or partial), cube map formats, and tiled formats (multi-resolution) for efficient dynamic loading.
• Virtual Tours: Allows linking multiple panoramas together into a tour.
• Interactivity: Supports "hot spots" for navigation between panoramas and for adding annotations.
• Extensibility: Provides an API for external code to control the viewer, implement custom buttons, or integrate with other webpage elements (e.g., maps).
• Advanced Rendering: Uses a pinhole camera model implemented as a WebGL fragment shader for equirectangular panoramas, providing higher accuracy than geometric sphere approximations.

Pannellum is a lightweight, open-source panorama viewer for the web built with HTML5, CSS3, JavaScript, and WebGL.

To begin using Pannellum, you can:

• Explore hosted examples at pannellum.org to see various functionalities.
• Use the simple tutorial and configuration utility for basic single-panorama displays.
• Self-host by following the 'How to use' guide for local testing.

To create multiresolution (tiled) panoramas, use the generate.py script located in utils/multires.

Prerequisites:

• nona program (part of Hugin) must be installed and on your system path (or specified via -n).
• Python 3 with Pillow and NumPy packages.
• pyshtools (recommended).

Usage: Run the script against your equirectangular panorama. By default, tiles and a config.json are generated in the ./output folder.

Commands:

• Basic usage: python3 generate.py pano_image.jpg
• Specifying nona path: python3 generate.py -n /path/to/nona pano_image.jpg
• View help: python3 generate.py --help

cd utils/multires
python3 generate.py pano_image.jpg

For production deployment, it is recommended to use minified files. You can build them using the scripts in the utils/build directory.

On Unix-like platforms:

1. Navigate to the build directory.
2. Run ./build.sh.

This will generate build/pannellum.htm, build/pannellum.js, and build/pannellum.css in the repository root.

cd utils/build
./build.sh

A tour configuration file is organized into two top-level properties:

1. default: Contains options applied to every scene. This property must include a firstScene property containing the ID of the scene to be displayed first.
2. scenes: A dictionary where keys are scene IDs and values are the specific configuration objects for those scenes.

Note: Options defined within an individual scene will override any matching options defined in the default property.

To use advanced Pannellum features, you must provide a JSON configuration file via the config URL parameter. The configuration file must be hosted on the same origin as the pannellum.htm file.

If you are only using a basic equirectangular image without advanced features, you may be able to rely solely on URL parameters instead of a JSON file.

To use Pannellum locally or on a server, follow these steps:

1. Upload files: Upload build/pannellum.htm and your equirectangular panorama to a web server.
   • Note: Due to browser security restrictions, you must use a web server even for local testing. You can use python3 -m http.server to start a local server.
2. Configure: Create a configuration using the utils/config/configuration.htm tool, the utils/multires/generate.py script, or by writing your own JSON configuration.
3. Embed: Insert the generated <iframe> code into your page, or use the Pannellum API/JSON configuration for advanced integrations.

Best Practice: When using the standalone viewer, use a location hash instead of a query string to avoid sending parameters to the server (e.g., pannellum.htm#panorama=... instead of pannellum.htm?panorama=...).

After generating tiles, the output (including config.json and tile directories) will be in your output directory. To view the result:

1. Start a local HTTP server from the repository root:

python3 -m http.server

2. Navigate to the following URL in your browser (adjusting the path to your specific output directory if necessary):

http://localhost:8000/src/standalone/pannellum.htm#config=../../utils/multires/output/config.json

Once dependencies are installed, use the generate.py script to convert a panorama image into a multi-resolution tileset.

Local Execution:

python3 generate.py examplepano.jpg

If you prefer not to install dependencies locally, you can use the provided Dockerfile.

1. Build the container:

docker build -t generate-panorama .

2. Run the container: Bind your current working directory to /data inside the container. Ensure the --output path is within the bound directory so files are saved to your host.

docker run -it -v $PWD:/data generate-panorama --output /data/output /data/examplepano.jpg

To run the generate.py script locally, you must install nona (from Hugin), Python 3, and several Python packages.

On Ubuntu, you can install the system dependencies using:

sudo apt install python3 python3-pil python3-numpy python3-pip hugin-tools

Then, install the recommended Python packages via pip:

pip3 install --user pyshtools

Note: If pyshtools fails to install due to architecture issues, you may need to follow the pyshtools build-from-source directions.

To enable automatic rotation of the panorama, configure these parameters:

• autoRotate (number): Rotation speed in degrees per second. Positive values rotate counter-clockwise; negative values rotate clockwise.
• autoRotateInactivityDelay (number): Delay in milliseconds to start rotation after user inactivity. Requires autoRotate to be set.
• autoRotateStopDelay (number): Delay in milliseconds to stop rotation after loading. Requires autoRotate to be set.