Skip to content

Latest commit

 

History

History
333 lines (218 loc) · 7.22 KB

plugin-markers.md

File metadata and controls

333 lines (218 loc) · 7.22 KB
Raw

MarkersPlugin

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.

[[toc]]

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.

<iframe style="width: 100%; height: 500px;" src="//jsfiddle.net/mistic100/kdpqLey2/embedded/result,js/dark" allowfullscreen="allowfullscreen" allowpaymentrequest frameborder="0"></iframe>

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)

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'

polygonPx

  • type : integer[2][]

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

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

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]]

polylinePx

  • type : integer[2][]

Same as polygonPx but generates a polyline.

polylineRad

  • type : double[2][]

Same as polygonRad but generates a polyline.

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.