Photo Sphere Viewer

# PlanPlugin Styles

NPM version NPM Downloads jsDelivr Hits
API Documentation

Adds a Leaflet (opens new window) map on the viewer, showing the location of the panorama and optional hotspots. It uses OpenStreetMap by default.

This plugin is available in the @photo-sphere-viewer/plan-plugin (opens new window) package.

# Usage

The minimal configuration of this plugin contains coordinates (the GPS position of the panorama).

const viewer = new PhotoSphereViewer.Viewer({
    plugins: [
        [PhotoSphereViewer.PlanPlugin, {
            coordinates: [6.79077, 44.58041],
        }],
    ],
});

WARNING

Do not forget to import Leaflet JS and CSS files.

# Example

# Configuration

# coordinates (required)

  • type: [number, number]
  • updatable: yes

GPS position of the panorama (longitude, latitude). You can also use setCoordinates() method.

# bearing

  • type: number | string
  • default: 0
  • updatable: yes

Rotation offset to apply to the central pin to make it match with the panorama orientation.

# layers

  • type: array
  • default: OpenStreetMap
  • updatable: no

List of available base layers, if more than one is defined, a button will allow to switch between layers.

Each element is an object containing urlTemplate (for standard raster tiles) OR layer (for any custom Leaflet layers), as well as name and attribution.

layers: [
    {
        name: 'OpenStreetMap',
        urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
        attribution: '© OpenStreetMap',
    },
    {
        name: 'OpenTopoMap',
        layer: new L.TileLayer('https://{s}.tile.opentopomap.org/{z}/{x}/{y}.png', {
            subdomains: ['a', 'b', 'c'],
            maxZoom: 17,
        }),
        attribution: '© OpenTopoMap',
    },
]

Note: this option is ignored if configureLeaflet is used.

# configureLeaflet

  • type: function<map>
  • updatable: no

Allows to configure Leaftlet yourself. This will disable the default layer.

configureLeaflet(map) {
    // https://leafletjs.com/reference.html
},

# size

  • type: { width: string, height: string }
  • default: { width: '300px', height: '200px' }
  • updatable: yes

The size of the widget.

# position

  • type: string
  • default: bottom left
  • updatable: yes

Position of the widget, accepted positions are combinations of top, bottom and left, right.

# pinImage

  • type: string
  • default: default SVG
  • updatable: yes

SVG or image URL used for the central pin.

# pinSize

  • type: number
  • default: 35
  • updatable: yes

Size of the central pin.

# hotspots

  • type: PlanHotspot[]
  • default: null
  • updatable: yes

Markers visible on the map. See bellow. You can also use setHotspots() method.

# spotStyle

  • type: object
  • updatable: yes

Style of hotspots.

# defaultZoom

  • type: number
  • default: 15
  • updatable: no

Default zoom level of the map.

# visibleOnLoad

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

Displays the map when loading the first panorama.

# buttons

  • type: object
  • default: { maximize: true, close: true, reset: true }
  • updatable: no

Configure which buttons are visible around the map.

# lang

  • type: object
  • default:
lang: {
    map: 'Map',
    mapMaximize: 'Maximize',
    mapMinimize: 'Minimize',
    mapReset: 'Reset',
    mapLayers: 'Base layer',
}

Note: this option is not part of the plugin but is merged with the main lang object.

# Hotspots

# id

  • type: string
  • default: generated

Useful to react to clicks with the select-hotspot event.

# coordinates (required)

  • type: [number, number]

Configure the position of the hotspot on the map.

# style

Allow to override the default spotStyle.

# tooltip

  • type: string | { content: string, className: string }
  • default: null

TIP

Markers can be displayed on the map by defining their plan data, which must be an hotspot object.

The marker tooltip is reused if defined. The viewer will be moved to face the marker if clicked on the map.







 




markers: [
    {
        id: 'marker-1',
        image: 'pin.png',
        position: { yaw: '15deg', pitch: 0 },
        data: {
            plan: { coordinates: [6.79077, 44.58041], image: 'pin.png' },
        },
    },
],

# Methods

# setHotspots(hotspots)

Changes the hotspots.

mapPlugin.setHotspots([
    { id: '1', coordinates: [6.79077, 44.58041], tooltip: 'Hotspot one' },
    { id: '2', coordinates: [6.79077, 44.58041], image: 'blue-dot.png' },
]);

# clearHotspots()

Removes all hotspots.

# setCoordinates(coordinates)

Changes the position of the panorama on the map.

mapPlugin.setCoordinates([6.79077, 44.58041]);

# close() | open()

Switches between closed and opened mode.

# maximize() | minimize()

Switches between maximized and minimized views. (Has no effect if the map is closed).

# getLeaflet()

Returns the Leaflet instance.

# Events

# select-hotspot(hotspotId)

Triggered when the user clicks on a hotspot.

planPlugin.addEventListener('select-hotspot', ({ hotspotId }) => {
    console.log(`Clicked on hotspot ${hotspotId}`);
});

← ResolutionPlugin →