Pannellum - Documentation

Getting Started

Installation

Pannellum can be installed via npm or by including the script directly in your HTML.

npm:

If you’re using a Node.js environment, install Pannellum using npm:

npm install pannellum

Then, you can import it into your project:

import Pannellum from 'pannellum';

Direct inclusion (HTML):

For simpler projects, you can include the Pannellum script directly in your HTML file. Download the latest release from the Pannellum GitHub repository (https://github.com/mpetroff/pannellum/releases) and include it like so:

<script src="path/to/pannellum.js"></script>

Replace "path/to/pannellum.js" with the actual path to the downloaded pannellum.js file. Make sure this script is included after the <body> tag or within a DOMContentLoaded event listener to ensure the DOM is ready.

Basic Usage

After installation, creating a panorama viewer is straightforward. The core function is pannellum.viewer. This function takes a single argument: a configuration object. At minimum, this object needs an id property specifying the ID of the HTML element to contain the viewer, and a panorama property specifying the path to your panorama image.

Here’s a basic example:

pannellum.viewer('panorama1', {
  "panorama": "path/to/your/panorama.jpg"
});

Replace "path/to/your/panorama.jpg" with the actual path to your panorama image. This will create a basic panorama viewer within the element with the ID “panorama1”.

Creating your first panorama.

First, you will need a panoramic image. You can create these using a dedicated panoramic camera, or by stitching together multiple images using photo editing software such as Hugin, PTGui, or others. Ensure your image is properly formatted and high-resolution for the best viewing experience.

Next, create an HTML file (e.g., index.html) and include the Pannellum script as described in the Installation section. Within the <body> of your HTML, add a div element with an ID to serve as a container for your panorama:

<!DOCTYPE html>
<html>
<head>
  <title>My First Pannellum Panorama</title>
</head>
<body>
  <div id="panorama1"></div>
  <script src="path/to/pannellum.js"></script>
  <script>
    pannellum.viewer('panorama1', {
      "panorama": "path/to/your/panorama.jpg"
    });
  </script>
</body>
</html>

Replace "path/to/your/panorama.jpg" with the actual path to your panorama image. Open index.html in your web browser. You should now see your first panorama displayed! Remember to adjust the path to your pannellum.js file accordingly.

Core Features

Panorama Loading

Pannellum supports loading various panorama formats. The primary method is specifying the path to a spherical or equirectangular image in the configuration’s panorama property. The library automatically detects the image type and handles the appropriate projection.

Supported formats generally include JPEG, PNG, and other common image formats. For optimal performance, it is recommended to use optimized images (e.g., progressive JPEGs). Very large images might impact performance; consider using image optimization techniques to reduce file size while maintaining acceptable quality.

You can also load panoramas from different sources by utilizing the panorama option with specific parameters or using other configuration options for video or cubemap panoramas. Refer to the Configuration Options section for details on advanced loading techniques.

Hotspots

Hotspots allow you to add interactive elements to your panoramas. These are defined within the configuration’s hotSpots array. Each hotspot object requires at least a pitch, yaw, and type property. The type property determines the hotspot’s behavior (e.g., info, scene, link). Additional properties can customize appearance and behavior, such as text content, URL links, and associated scenes.

Example:

{
  "hotSpots": [
    {
      "pitch": 10,
      "yaw": 20,
      "type": "info",
      "text": "This is a hotspot!",
      "cssClass": "custom-hotspot"
    },
    {
      "pitch": -5,
      "yaw": -30,
      "type": "scene",
      "sceneId": "scene2"
    }
  ]
}

This example defines two hotspots: one displaying information and another transitioning to a different scene. Note that sceneId requires a corresponding scene definition in the configuration.

Pannellum provides intuitive navigation controls by default. Users can drag to rotate the view, zoom in and out using the mouse wheel or touch gestures. The default navigation can be customized or disabled through configuration options. For example, you can disable mouse controls, enable keyboard controls, or specify custom controls. The library also supports automatic transitions between scenes.

Configuration Options

A comprehensive set of configuration options allows for extensive customization of the panorama viewer. These options control aspects such as:

Consult the full configuration reference for a complete list and detailed descriptions of each option. Many options allow fine-grained customization of visual elements and behavior.

API Reference

The Pannellum API provides methods to interact with the viewer programmatically after initialization. Key methods include:

The full API reference provides detailed descriptions of each method, including arguments and return values. This allows developers to dynamically control the panorama viewer and integrate it seamlessly within their applications. For more advanced usage, explore event listeners available to monitor viewer interactions and state changes.

Advanced Features

Customizing the UI

Pannellum offers several ways to customize the user interface (UI). You can modify the appearance of the default controls, add custom controls, or even replace the entire UI with a completely custom design. This is achieved primarily through CSS styling and potentially by creating custom HTML elements to replace or augment the existing ones.

CSS Styling: Pannellum’s CSS classes are well-documented, providing targets for styling various elements, including the navigation controls, hotspots, and loading indicators. By adding custom CSS rules, you can change colors, fonts, sizes, and other visual aspects to match your application’s design.

Custom Controls: You can extend the viewer’s functionality by creating custom HTML elements and attaching event listeners to trigger actions within the Pannellum viewer, such as changing scenes or views.

Complete UI Replacement: For highly customized UIs, you might choose to create a separate UI entirely and interact with the Pannellum viewer using its API methods. This provides the maximum flexibility but requires more development effort.

Using External Libraries

Pannellum can be integrated with other JavaScript libraries to enhance its functionality. For example, you could use a library like Three.js to add 3D models to your panoramas or a mapping library to overlay geographical information. The integration typically involves adding the external library to your project and then using its API alongside the Pannellum API. Be mindful of potential conflicts between libraries; ensuring compatibility might require careful consideration of variable naming and execution order.

Creating Interactive Elements

Beyond the built-in hotspot functionality, you can enhance interactivity by creating custom interactive elements within the panorama using techniques similar to customizing the UI. This involves adding your own HTML elements overlaid on the panorama canvas and using JavaScript event listeners to detect user interactions (clicks, mouseovers, etc.). Careful positioning is crucial to ensure your elements align correctly with the panorama’s perspective. Consider using the Pannellum API to determine the current viewer position and adjust element placement accordingly.

Handling User Input

Pannellum provides events that enable handling user input. These events can be used to trigger actions based on user interactions, such as changes in view, hotspot clicks, or zoom events. Registering event listeners allows your application to respond dynamically to user actions within the viewer. This is particularly useful for creating custom controls and interactive experiences. For example, you can use the viewchange event to track user navigation, or the hotspotclick event to trigger actions related to hotspot interactions.

Performance Optimization

For optimal performance, particularly with high-resolution panoramas or complex scenes, several optimization strategies are recommended:

Hotspot Configuration

Creating Hotspots

Hotspots are defined within the hotSpots array in the Pannellum configuration object. Each hotspot is an object with properties specifying its position, type, and behavior. The pitch and yaw properties determine the hotspot’s position on the panorama (in degrees, where pitch is the vertical angle and yaw is the horizontal angle). The type property specifies the hotspot’s behavior (see Hotspot Types section below).

A basic hotspot definition looks like this:

{
  "hotSpots": [
    {
      "pitch": 10,
      "yaw": 20,
      "type": "info",
      "text": "This is a hotspot!"
    }
  ]
}

This creates a simple info hotspot at pitch 10 and yaw 20 degrees.

Hotspot Types

Pannellum supports several hotspot types:

Hotspot Properties

Besides pitch, yaw, and type, hotspots can have several other properties to customize their appearance and behavior:

Hotspot Events

Pannellum triggers events related to hotspot interactions. You can listen for these events using the on method of the Pannellum viewer instance. The primary event is hotspotclick, which fires when a hotspot is clicked.

Example:

var viewer = pannellum.viewer('panorama1', config);
viewer.on('hotspotclick', function(hotspot) {
  console.log('Hotspot clicked:', hotspot);
  if (hotspot.type === 'link') {
      window.open(hotspot.url);
  }
});

This code logs information about the clicked hotspot and opens the URL if it’s a link type hotspot. Other events might include hotspotenter and hotspotleave. Consult the API documentation for a comprehensive list of events.

Hotspot Animation

While Pannellum doesn’t natively support animation of hotspot properties (like movement or scaling), you can achieve animation effects by manipulating hotspot properties programmatically using JavaScript’s animation capabilities (like requestAnimationFrame or animation libraries such as GreenSock (GSAP)). This involves modifying hotspot properties over time using the Pannellum API to update the hotspot’s position, appearance, or other attributes. Note that this requires custom code and potentially frequent updates to the viewer to maintain smooth animation. The update method of the viewer can be used to re-render the scene with the changed hotspot properties.

Working with Images

Supported Image Formats

Pannellum primarily supports equirectangular and spherical panoramic images. While the library attempts to handle various formats, the best results are obtained using common image formats like JPEG and PNG. The library’s ability to handle other formats may vary depending on browser compatibility and image characteristics. Equirectangular images are generally preferred for their simplicity and wide browser support. Spherical images, while sometimes offering advantages in terms of projection accuracy, may require specific handling or conversion for optimal display in Pannellum.

Image Optimization

Optimizing your panoramic images is crucial for performance and a smooth user experience. Large image files can lead to slow loading times and potential performance issues, especially on mobile devices. Here are some key optimization techniques:

Image Stitching

Creating panoramic images often involves stitching multiple photos together using specialized software. Several popular options exist, including:

The choice of software depends on your technical expertise and the complexity of your stitching needs. The result of the stitching process should be a single, seamless equirectangular or spherical image suitable for use with Pannellum.

Handling High-Resolution Images

High-resolution panoramic images offer exceptional detail but can severely impact performance. To mitigate performance issues:

By combining these techniques, you can successfully utilize high-resolution images in your Pannellum panoramas without significant performance penalties.

Troubleshooting

Common Errors

Several common errors can occur when working with Pannellum. Here are some frequently encountered issues and their potential solutions:

Debugging Tips

Effective debugging techniques can greatly assist in resolving Pannellum-related problems:

Browser Compatibility

Pannellum is designed to be compatible with modern web browsers. While it aims for wide compatibility, optimal performance and all features might not be available in older or less common browsers. It’s generally recommended to test your application with major browsers (Chrome, Firefox, Safari, Edge) to ensure a consistent experience. Very old browsers might lack support for WebGL, which is essential for optimal Pannellum performance.

Performance Issues

Performance issues might arise with large images or complex scenes. Address these issues using the following strategies:

If performance problems persist after trying these optimizations, consider profiling your application to pinpoint specific performance bottlenecks. Your browser’s developer tools usually offer profiling tools to help identify areas for improvement.

Examples and Demos

These examples demonstrate various aspects of Pannellum’s functionality. Remember to replace placeholder image paths with your actual image files. These examples assume you have Pannellum correctly installed and included in your HTML.

Basic Panorama Example

This example demonstrates the simplest way to create a Pannellum viewer. It displays a single panorama image with default navigation controls.

<!DOCTYPE html>
<html>
<head>
  <title>Basic Pannellum Example</title>
  <script src="path/to/pannellum.js"></script> </head>
<body>
  <div id="panorama"></div>
  <script>
    pannellum.viewer('panorama', {
      "panorama": "path/to/your/panorama.jpg"
    });
  </script>
</body>
</html>

Replace "path/to/your/panorama.jpg" with the actual path to your panorama image.

Advanced Panorama Example

This example showcases a more complex panorama with hotspots, multiple scenes, and custom styling.

<!DOCTYPE html>
<html>
<head>
  <title>Advanced Pannellum Example</title>
  <script src="path/to/pannellum.js"></script>
  <style>
    .custom-hotspot {
      background-color: blue;
      color: white;
    }
  </style>
</head>
<body>
  <div id="panorama"></div>
  <script>
    pannellum.viewer('panorama', {
      "panorama": "path/to/your/panorama.jpg",
      "hotSpots": [
        {
          "pitch": 10,
          "yaw": 20,
          "type": "info",
          "text": "This is a hotspot!",
          "cssClass": "custom-hotspot"
        }
      ],
      "scenes": [
        {
          "id": "scene2",
          "panorama": "path/to/your/scene2.jpg"
        }
      ]
    });
  </script>
</body>
</html>

This example includes a hotspot with custom styling and defines a second scene. Remember to replace "path/to/your/panorama.jpg" and "path/to/your/scene2.jpg" with your image paths.

Example with Custom UI

This example outlines the approach for a custom UI. This is a conceptual example and requires significant custom HTML and CSS. It demonstrates the integration principle; you’ll need to adapt and expand upon it based on your UI design.

<!DOCTYPE html>
<html>
<head>
  <title>Custom UI Example</title>
  <script src="path/to/pannellum.js"></script>
  <style>
    /* Custom CSS for your UI elements */
    #my-custom-controls { /* ... */ }
  </style>
</head>
<body>
  <div id="panorama"></div>
  <div id="my-custom-controls">
    <button onclick="viewer.setHfov(100)">Zoom Out</button> </div>
  <script>
    var viewer = pannellum.viewer('panorama', { /* ... configuration ... */ });
  </script>
</body>
</html>

You would replace the placeholder comment with your custom UI HTML and include JavaScript code to interact with the Pannellum viewer’s API (e.g. viewer.setHfov()) to control the viewer through the custom controls.

Example with External Libraries

This example shows how to integrate Three.js (a 3D library). This is a high-level example and requires familiarity with Three.js. You would need to include Three.js in your project and handle the integration. This example only shows the basic setup; detailed Three.js integration would require significant additional code.

<!DOCTYPE html>
<html>
<head>
  <title>Example with Three.js</title>
  <script src="path/to/pannellum.js"></script>
  <script src="path/to/three.js"></script>
</head>
<body>
  <div id="panorama"></div>
  <script>
    pannellum.viewer('panorama', {
      "panorama": "path/to/your/panorama.jpg",
      // ... other configuration ...
      // Add Three.js integration code here... (Requires significant additional code)
    });
  </script>
</body>
</html>

This is a skeletal example. The actual integration with Three.js would involve creating a Three.js scene, adding 3D objects, and rendering them within the Pannellum viewer’s context. This requires advanced knowledge of both Pannellum and Three.js. Consult the documentation of both libraries for details. Remember to replace the placeholder image paths.

Contributing to Pannellum

We welcome contributions to Pannellum! Whether you’re fixing bugs, adding features, or improving the documentation, your help is valuable. Here’s how to get started:

Setting up the development environment

  1. Fork the Repository: Fork the Pannellum repository on GitHub to your own account.

  2. Clone your Fork: Clone your forked repository to your local machine:

    git clone <your_fork_url>

  3. Install Dependencies: Navigate to the project directory and install the necessary dependencies using npm:

    cd pannellum
npm install

  4. Set up the Development Server: Pannellum uses a development server to facilitate development and testing. Start the server using:

    npm start

    This will launch a development server, usually accessible at http://localhost:8080.

  5. Explore the Code: Familiarize yourself with the project structure and codebase. The src directory contains the core Pannellum code.

Code style guidelines

Pannellum follows consistent coding style guidelines to ensure readability and maintainability. Adherence to these guidelines is crucial for any contributions. The project uses a combination of linters and code formatters to enforce these guidelines. It is recommended to familiarize yourself with these guidelines before starting development.

Before submitting a pull request, make sure your code adheres to the defined style guidelines by running the appropriate linting and formatting tools.

Testing your changes

Thorough testing is crucial to ensure the quality and stability of Pannellum. Before submitting a pull request, test your changes extensively to verify they work correctly and don’t introduce regressions.

Address any test failures before proceeding. Well-tested changes are more likely to be accepted.

Submitting pull requests

  1. Create a Branch: Create a new branch for your changes:

    git checkout -b <your_branch_name>

  2. Make your Changes: Implement your changes, ensuring they adhere to the code style guidelines and pass all tests.

  3. Commit your Changes: Commit your changes with descriptive commit messages:

    git add .
git commit -m "Your descriptive commit message"

  4. Push your Branch: Push your branch to your forked repository:

    git push origin <your_branch_name>

  5. Create a Pull Request: On GitHub, create a pull request from your branch to the main branch of the original Pannellum repository. Provide a clear description of your changes and address any comments or suggestions from the maintainers. The pull request should clearly outline the purpose of the changes, the problem being solved, and any relevant considerations.

Remember to follow the project’s contribution guidelines for details on specific procedures and expectations. Be patient and responsive to feedback from the project maintainers. Your contributions will help improve Pannellum for everyone!