# MapPlugin Styles
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}`);
});