# MarkersPlugin

API Documentation

Displays various markers/hotspots on the viewer.

This plugin is available in the core photo-sphere-viewer package in dist/plugins/markers.js and dist/plugins/markers.css.

# Usage

The plugin provides a powerful markers system allowing to define points of interest on the panorama with optional tooltip and description. Markers can be dynamically added/removed and you can react to user click/tap.

There are four types of markers :

  • HTML defined with the html attribute
  • Images defined with the image attribute
  • SVGs defined with the rect, circle, ellipse or path attribute
  • Dynamic polygons & polylines defined with the polygonPx/polygonRad/polylinePx/polylineRad attribute

Markers can be added at startup with the markers option or after load with the various methods.

const viewer = new PhotoSphereViewer.Viewer({
  plugins: [
    [PhotoSphereViewer.MarkersPlugin, {
      markers: [ 
        {
          id: 'new-marker',
          longitude: '45deg',
          latitude: '0deg',
          image: 'assets/pin-red.png',
        },
      ],
    }], 
  ],
});

const markersPlugin = viewer.getPlugin(PhotoSphereViewer.MarkersPlugin);

markersPlugin.on('select-marker', (e, marker) => {
  markersPlugin.updateMarker({
    id: marker.id,
    image: 'assets/pin-blue.png'
  });
});

# Example

The following example contains all types of markers. Click anywhere on the panorama to add a red marker, right-click to change it's color and double-click to remove it.

# Markers options

# id (required)

  • type : string

Unique identifier of the marker.

# x & y or latitude & longitude (required)

  • type : integer or double

Position of the marker in texture coordinates (pixels) or spherical coordinates (radians). (This option is ignored for polygons and polylines)

WARNING

Texture coordinates are not applicable to cubemaps.

# width & height

  • type : integer

Size of the marker. (This option is ignored for polygons and polylines)

# scale

  • type : double | double[]

Scale factor multiplied by the zoom level. Provide an array of two values for min and max. By default the scale is constant.

scale: 1 // the marker is scalling with the zoom level (from 0 to 100%)

scale: [0.5, 1] // at minimum zoom level the marker is half its size at maximum zoom level

# className

  • type : string

CSS class(es) added to the marker element.

# style

  • type : object

CSS properties to set on the marker (background, border, etc.).

style: {
  backgroundColor: 'rgba(0, 0, 0, 0.5)',
  cursor         : 'help'
}

# svgStyle

  • type : object

SVG properties to set on the marker (fill, stroke, etc.). Only for SVG and polygons/polylines markers.

svgStyle: {
  fill       : 'rgba(0, 0, 0, 0.5)',
  stroke     : '#ff0000',
  strokeWidth: '2px'
}

# anchor

  • type : string
  • default : 'center center'

Defines where the marker is placed toward its defined position. Any CSS position is valid like bottom center or 20% 80%. (This option is ignored for polygons and polylines)

# visible

  • type : boolean
  • default : true

Initial visibility of the marker.

# tooltip

  • type : string | {content: string, position: string}
  • default : {content: null, position: 'top center'}

Tooltip content and position. Accepted positions are combinations of top, center, bottom and left, center, right with the exception of center center.

tooltip: 'This is a marker' // tooltip with default position

tooltip: { // tooltip with custom position
  content : 'This is marker',
  position: 'bottom left'
}

# content

  • type : string

HTML content that will be displayed on the side panel when the marker is clicked.

# data

  • type : any

Any custom data you want to attach to the marker.

# Markers definition

One of these options is required.

# image

  • type : string

Path to the image representing the marker. Requires width and height to be defined.

# html

  • type : string

HTML content of the marker. It is recommended to define width and height.

# rect

  • type : integer[2] | {width: integer, height: integer}

Size of the rectangle.

rect: [10, 5]

rect: {width: 10, height: 5}

# circle

  • type: integer

Radius of the circle.

# ellipse

  • type : integer[2] | {cx: integer, cy: integer}

Radiuses of the ellipse.

ellipse: [10, 5]

ellipse: {cx: 10, cy: 5}

# path

  • type : string

Definition of the path (0,0 will be placed at the defined x/y or longitude/latitude).

path: 'M 0 0 L 60 60 L 60 0 L 0 60 L 0 0'

# polygonRad

  • type : double[2][]

Same as above but coordinates are in longitude and latitude.

polygonRad: [[0.2, 0.4], [0.9, 1.1], [1.5, 0.7]]

# polygonPx

  • type : integer[2][]

Array of points defining the polygon in pixel coordinates on the panorama image.

polygonPx: [[100, 200], [150, 300], [300, 200]]

WARNING

Texture coordinates are not applicable to cubemaps.

# polylineRad

  • type : double[2][]

Same as polygonRad but generates a polyline.

# polylinePx

  • type : integer[2][]

Same as polygonPx but generates a polyline.

WARNING

Texture coordinates are not applicable to cubemaps.

# Configuration

# lang

  • type: object
  • default:
lang: {
  markers : 'Markers',
  markersList : 'Markers list',
}

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

# clickEventOnMarker

  • type: boolean
  • default: false

If a click event is triggered on the viewer additionally to the select-marker event.

# Methods

# addMarker(properties)

Adds a new marker to the viewer.

markersPlugin.addMarker({
  id: 'new-marker',
  longitude: '45deg',
  latitude: '0deg',
  image: 'assets/pin-red.png',
});

# clearMarkers()

Removes all markers.

# getCurrentMarker(): Marker

Returns the last marker clicked by the user.

# gotoMarker(id, speed): Animation

Moves the view to center a specific marker, with optional animation.

markersPlugin.gotoMarker('marker-1', 1500)
  .then(() => /* animation complete */);

# hideMarker(id) | showMarker(id) | toggleMarker(id)

Changes the visiblity of a marker.

# removeMarker(id)

Removes a marker.

# setMarkers(properties[])

Replaces all markers by new ones.

# updateMarker(properties)

Updates a marker with new properties. The type of marker cannot be changed.

markersPlugin.updateMarker({
  id: 'existing-marker',
  image: 'assets/pin-blue.png'
});

# Events

# over-marker(marker) | leave-marker(marker)

Triggered when the user puts the cursor hover or away a marker.

markersPlugin.on('over-marker', (e, marker) => {
  console.log(`Cursor is over marker ${marker.id}`);
});

# select-marker(marker, data)

Triggered when the user clicks on a marker. The data object indicates if the marker was selected with a double a click on a right click.

# unselect-marker(marker)

Triggered when a marker was selected and the user clicks elsewhere.