The Overlays plugin lets you place images (and videos) directly onto the panorama sphere. Unlike markers, overlays are part of the 3D scene and move naturally with the panorama. Both equirectangular (full or cropped) and cubemap geometries are supported.
Installation
npm install @photo-sphere-viewer/overlays-plugin
Usage
import { Viewer } from '@photo-sphere-viewer/core';
import { OverlaysPlugin } from '@photo-sphere-viewer/overlays-plugin';
const viewer = new Viewer({
panorama: 'path/to/panorama.jpg',
plugins: [
OverlaysPlugin.withConfig({
overlays: [
{
id: 'overlay',
path: 'path/to/overlay.png',
},
],
}),
],
});
const overlaysPlugin = viewer.getPlugin(OverlaysPlugin);
overlaysPlugin.addEventListener('overlay-click', ({ overlayId }) => {
console.log(`Clicked on overlay ${overlayId}`);
});
Plugin configuration
Initial list of overlays. Not updatable — use the methods below to add or remove overlays at runtime.
Automatically remove all overlays when the panorama changes. Updatable.
Apply the global sphereCorrection viewer option to each overlay. Not updatable after init.
Overlay configuration
Each overlay is either a spherical overlay (one image/video) or a cube overlay (six images). All overlays share the following base properties.
Unique identifier used to remove the overlay with removeOverlay(). Defaults to a random value.
Stacking order when multiple overlays overlap.
Spherical overlays
Path to the overlay image or video file.
Crop data for partial panoramas. Works the same as the core panoData option. The fullWidth here does not have to match the base panorama — croppedX/croppedY are scaled accordingly.
Cube overlays
Six face images in the cubemap format. All six faces are required but individual faces can be null. See the cubemap adapter page for accepted syntax. Methods
addOverlay(config)
Adds a new overlay at runtime.
removeOverlay(id)
Removes the overlay with the given ID.
clearOverlays()
Removes all overlays.
Events
overlay-click
Triggered when the user clicks an overlay.
overlaysPlugin.addEventListener('overlay-click', ({ overlayId }) => {
console.log(`Clicked on overlay ${overlayId}`);
});
