# MapPlugin Styles

NPM version NPM Downloads jsDelivr Hits
API Documentation

Adds a interactive map on the viewer, with zoom/pan and optional hotspots.

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

TIP

Looking for geographic map ? (OpenStreetMap, Google, etc) try the Plan plugin instead.

# Usage

The minimal configuration of this plugin contains imageUrl and center (the position of the panorama on the map, in pixels). The map rotation can be ajusted with rotation.

const viewer = new PhotoSphereViewer.Viewer({
    plugins: [
        [PhotoSphereViewer.MapPlugin, {
            imageUrl: 'path/to/map.jpg',
            center: { x: 785, y: 421 },
            rotation: '-12deg',
        }],
    ],
});

# Example

TIP

The north of the compass is always toward the top of the map, before rotation.

# Configuration

# imageUrl (required)

  • type: string
  • updatable: no, use setImage() method

URL of the image to use as map.

# center (required)

  • type: { x: number, y: number }
  • updatable: yes

The position of the panorama on the map, in pixels. You can also use setCenter() method.

# rotation

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

Rotation to apply to the map to make it match with the panorama.

# size

  • type: string
  • default: 200px
  • updatable: yes

The size of the widget, can be declared in px, rem, vh, etc.

# position

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

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

# static

  • type: boolean
  • default: false
  • updatable: yes

If true the map will not rotate, only the central pin will, to indicate where the panorama is oriented.

# overlayImage

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

SVG or image URL drawn on top of the map, can be null to disable.

# 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.

# coneColor

  • type: string
  • default: #1E78E6
  • updatable: yes

Color of the cone of the compass, set to null to disable.

# coneSize

  • type: number
  • default: 40
  • updatable: yes

Size of the cone of the compass.

# hotspots

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

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

# spotStyle

  • type: object
  • updatable: yes

Style of hotspots.

# defaultZoom

  • type: number
  • default: 100
  • updatable: no

Default zoom level of the map.

# maxZoom

  • type: number
  • default: 200
  • updatable: yes

Maximum zoom level of the map.

# minZoom

  • type: number
  • default: 20
  • updatable: yes

Minimum zoom level of the map.

# visibleOnLoad

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

Displays the map when loading the first panorama.

# buttons

  • type: object
  • default: { north: true, 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',
    mapNorth: 'Go to north',
    mapReset: 'Reset',
}

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.

# yaw+distance or x+y (required)

  • type: number

Configure the position of the hotspot on the map, either with a angle and a distance (in pixels on the map image) or absolute x/y coordinates (also in pixels on the map image).

# 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 map data, which must be an hotspot object (minus yaw which is know from the marker position).

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: {
            map: { distance: 120, image: 'pin.png' },
        },
    },
    {
        id: 'marker-2',
        text: 'Warning',
        position: { textureX: 4500, textureY: 2100 },
        data: {
            map: { x: 150, y: 310 },
        },
    },
],

# Methods

# setHotspots(hotspots)

Changes the hotspots.

mapPlugin.setHotspots([
    { id: '1', yaw: '0deg', distance: 120, tooltip: 'Hotspot one' },
    { id: '2', x: 150, y: 310, image: 'blue-dot.png' },
]);

# clearHotspots()

Removes all hotspots.

# setImage(url, center?, rotation?)

Changes the image of the map.

mapPlugin.setImage('map2.jpg', { x: 500, y: 500 });

# setCenter(center)

Changes the position of the panorama on the map.

mapPlugin.setCenter({ x: 500, y: 500 });

# close() | open()

Switches between closed and opened mode.

# maximize() | minimize()

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

# Events

# select-hotspot(hotspotId)

Triggered when the user clicks on a hotspot.

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