DOCSEARCHbyAlgolia
Submit Docs

Photo Sphere Viewer Documentation

repository·main·Indexed 25 days ago

https://github.com/mistic100/photo-sphere-viewer

A JavaScript library for displaying 360° panoramas, supporting equirectangular images, cubemaps, and 360° videos. It features an extensible plugin architecture, a core Viewer API for camera control and animation, and support for custom WebComponents in the navbar.

Tokens
77.2K
Snippets
143
Records
385
Agent score
80%

What's inside Photo Sphere Viewer

  1. Overview of Photo Sphere Viewer features

    main

    Photo Sphere Viewer is a JavaScript library designed to display 360° panoramas. Key capabilities include:

    • Spheres and cubemaps: Supports standard equirectangular panoramas as well as cubemaps.
    • Fully configurable: Provides extensive options, methods, and events for deep integration into web applications.
    • Plugin system: Allows adding new features (like autorotate or compass) without increasing the core library size.
    • Interactive support: Optimized for touchscreen, gyroscope, and various user interactions across devices.
    • Markers system: Enables displaying text, images, and videos on top of the panorama.
    • Video support: Supports 360° videos in both equirectangular and cubemap formats.

  2. Development environment requirements and stack

    main

    Photo Sphere Viewer is a monorepo managed with Turborepo. To develop with this repository, ensure you have the following environment and tools installed:

    • Node.js: Version 22 is required.
    • Language/Styling: TypeScript and SASS.
    • Build Tool: tsup (based on esbuild).
    • Documentation: VitePress and TypeDoc.
    • Linting: ESLint and Stylelint.
    • Testing: Mocha (unit tests) and Cypress (E2E tests).

  3. What are Adapters in Photo Sphere Viewer

    main

    Adapters are specialized code modules responsible for loading panorama texture(s) into the Three.js scene. They allow the viewer to support different projection types and loading methods beyond the default equirectangular format.

    Supported adapters include:

    • equirectangular: The default adapter for full or partial equirectangular panoramas.
    • equirectangular tiles: For loading tiled equirectangular panoramas.
    • equirectangular video: For loading equirectangular videos.
    • cubemap: For loading cubemap projections (six textures).
    • cubemap tiles: For loading tiled cubemap panoramas.
    • cubemap video: For loading cubemap videos.
    • dual fisheye: For displaying raw files from 360 cameras (e.g., Ricoh Theta, Insta360) for both stills and videos.

  4. How plugins work in Photo Sphere Viewer

    main

    Plugins are used to extend the functionality of Photo Sphere Viewer. They have access to the viewer's internal APIs and the underlying Three.js renderer.

    To use a plugin, you must provide its class to the plugins array in the Viewer configuration. Some plugins require a configuration object, which can be passed using the withConfig static method during initialization.

    const viewer = new Viewer({
    plugins: [
        PluginA,
        PluginB.withConfig({
            option1: 'foo',
            option2: 'bar',
        }),
    ],
});

  7. Use HTML and DOM elements as markers

    main

    You can render markers using HTML content or existing DOM elements.

    • html: Accepts a string of HTML content. It is recommended to define a size. Warning: Content is rendered as raw HTML; sanitize untrusted input.
    • element: Accepts an existing HTMLElement. These are rendered flat above the viewer.
    • elementLayer: Accepts an existing HTMLElement. These are rendered 'inside' the scene with natural movement and scaling. Unlike element, elementLayer can only be positioned using position + rotation.

    Custom Web Components: If you use a Web Component as an element or elementLayer, the plugin will call its updateMarker() method on every render, passing an object containing: marker, position (2D viewport), viewerPosition, zoomLevel, and viewerSize.

    // HTML marker
{
    id: 'marker-1',
    html: '<strong>Click here</strong>',
    position: { yaw: 0, pitch: 0 },
    size: { width: 100, height: 30 },
}

// DOM element marker
{
    id: 'marker-1',
    element: document.querySelector('#my-marker'),
    position: { yaw: 0, pitch: 0 },
}

// DOM element layer (3D)
{
    id: 'marker-1',
    elementLayer: getYoutubeIframe(videoId),
    position: { yaw: 0, pitch: 0 },
    rotation: { yaw: '10deg' },
}

  8. How events work in Photo Sphere Viewer

    main

    Both the Viewer and its plugins implement the EventTarget API, allowing you to attach event listeners. Photo Sphere Viewer uses a custom TypeScript interface to provide strongly typed events.

    When an event is dispatched, the listener receives an Event subclass containing:

    • type: The name of the event.
    • target: A reference to the object that dispatched the event (the Viewer or the plugin).
    • Additional properties specific to the event type (e.g., position for position-updated).

    You can listen for events using string literals (magic values) or, preferably, the exported events constants from @photo-sphere-viewer/core for better type safety and maintainability.

    import { events } from '@photo-sphere-viewer/core';

// Preferred: use constants for type safety
viewer.addEventListener(events.PositionUpdateEvent.type, (e) => {
    // e.type === 'position-updated'
    // e.target === viewer
    // e.position
});

// Alternative: use magic string values
viewer.addEventListener('position-updated', ({ position }) => ());

  9. How to use cropped panorama data for visible ranges

    main

    If you are using a cropped panorama, you can automatically limit the visible range to the actual size of the panorama data.

    You can do this in two ways:

    1. Set usePanoData: true in the VisibleRangePlugin configuration.
    2. Call visibleRangePlugin.setRangesFromPanoData() on the plugin instance after the panorama has loaded.

  10. Use image and video layers for 3D rendering

    main

    To render images or videos 'inside' the panorama (allowing for natural movement and scaling), use imageLayer or videoLayer instead of the standard image option.

    Positioning Layers: Layers can be positioned in two ways:

    1. Using a single position (spherical coordinates) + size + optional anchor and rotation.
    2. Using an array of four position values defining the corners of the image/video (clockwise from top-left).

    Video Layers: videoLayer supports the autoplay option and can be used with chromaKey to make specific colors transparent.

    // Single position layer
{
    id: 'marker-1',
    imageLayer: 'pin-red.png',
    position: { yaw: 0, pitch: 0 },
    size: { width: 32, height: 32 },
}

// Four-corner position layer
{
    id: 'marker-2',
    imageLayer: 'pin-red.png',
    position: [
        { yaw: -0.2, pitch: 0.2 },
        { yaw: 0.2, pitch: 0.2 },
        { yaw: 0.2, pitch: -0.2 },
        { yaw: -0.2, pitch: -0.2 },
    ],
}

// Video layer
{
    id: 'marker-1',
    videoLayer: 'intro.mp4',
    position: { yaw: 0, pitch: 0 },
    size: { width: 600, height: 400 },
}

  12. Use the Panel component to display HTML content

    main

    The Panel component displays HTML content in a sidebar on the right side of the Photo Sphere Viewer.

    Security Warning: The content is rendered as raw HTML. Always sanitize untrusted input before passing it to the show method to prevent XSS attacks.

    Accessibility Note: Once the panel is opened, the first focusable element (such as an <a>, <button>, or any element with a tabindex) will automatically receive focus. This allows users to navigate the panel using the Tab key and trigger the clickHandler using the Enter key.