OverlaysPlugin

Display additional images on top of the panorama.

This plugin is available in the @photo-sphere-viewer/overlays-plugin package.

Usage

Overlays are images "glued" to the panorama. Contrary to markers they are part of the 3D scene and not drawn on top of the viewer. Both equirectangular (full or cropped) and cubemaps are supported.

import { OverlaysPlugin } from '@photo-sphere-viewer/overlays-plugin';

const viewer = new Viewer({
    plugins: [
        OverlaysPlugin.withConfig({
            overlays: [
                {
                    id: 'overlay',
                    path: 'path/to/overlay.png',
                },
            ],
        }),
    ],
});

Example

Configuration

overlays

• type: OverlayConfig[]
• updatable: no

The list of overlays, see below. Can be updated with various methods.

autoclear

• type: boolean
• default: true
• updatable: yes

Automatically remove all overlays when the panorama changes.

inheritSphereCorrection

• type: boolean
• default: true
• updatable: no

Applies the global sphereCorrection to each overlay.

Overlays

Overlays can be a single image/video for a spherical gerometry or six images for a cube geometry (no videos).

id (recommended)

• type: string
• default: random value

Used to remove the overlay with removeOverlay() method.

opacity

• type: number
• default: 1

zIndex

• type: number
• default: 0

Spherical overlays

path (required)

• type: string

Path to the image.

panoData

• type: PanoData

This option acts the same as the core panoData and allows to display partial panoramas.

overlays.addOverlay({
    id: 'my-overlay',
    path: 'my-overlay.png',
    opacity: 0.8,
    panoData: {
        fullWidth: 3000,
        croppedX: 1250,
        croppedY: 500,
    },
});

Note: The fullWidth provided here is not necessarily the same of the base panorama, croppedX/croppedY will be scaled accordingly.

Cube overlays

path (required)

• type: CubemapPanorama

Check the cubemap adapter page for the possible syntaxes. All six faces are required but some can be null.

Methods

addOverlay(config)

Adds a new overlay.

removeOverlay(id)

Removes an overlay.

clearOverlays()

Removes all overlays.

Events

overlay-click(overlayId)

Triggered when an overlay is clicked.

overlaysPlugin.addEventListener('overlay-click', ({ overlayId }) => {
    console.log(`Clicked on overlay ${overlayId}`);
});