VirtualTourPlugin Styles
Create virtual tours by linking multiple panoramas.
This plugin is available in the @photo-sphere-viewer/virtual-tour-plugin package.
Usage
import { VirtualTourPlugin } from '@photo-sphere-viewer/virtual-tour-plugin';
const viewer = new Viewer({
plugins: [
[VirtualTourPlugin, {
nodes: [...],
// or
getNode: async (id) => { ... },
startNodeId: ...,
}],
],
});
The plugin uses a list of nodes which contains a panorama
with one or more links
to other nodes and additional options.
The nodes can be provided all at once or asynchronously as the user navigates.
There are two different ways to define the position of the links : the manual mode and the GPS mode.
TIP
The Gallery plugin, Map plugin, Plan plugin and Compass plugin plugins can be easily integrated with the virtual tour.
Example
Nodes
Definition
id
(required)
- type:
string
Unique identifier of the node
panorama
(required)
Refer to the main config page.
caption
/ description
/ panoData
/ sphereCorrection
Refer to the main config page.
links
(required in client mode)
- type:
array
Definition of the links of this node. See below.
gps
(required in GPS mode)
- type:
number[]
GPS coordinates of this node as an array of two or three values ([longitude, latitude, altitude?]
).
Projection system
Only the ESPG:4326 projection is supported.
name
- type:
string
Short name of this node, used in links tooltips and the GalleryPlugin.
thumbnail
- type:
string
Thumbnail for the nodes list in the GalleryPlugin.
markers
- type:
MarkerConfig[]
Additional markers displayed on this node, requires the Markers plugin.
The markers can be positioned with the classic position
option (yaw + pitch) or, if positionMode=gps
, with the gps
option (longitude + latitude + altitude).
map
(client mode only)
Configuration of the hotspot when using the Map plugin. See global configuration for details.
plan
(client+GPS mode only)
Configuration of the hotspot when using the Plan plugin. The node will be automatically placed on the map but you can customize the style of the hotspot.
data
- type:
any
Any custom data you want to attach to the node.
Links
nodeId
(required)
- type:
string
Identifier of the target node.
position
(required in manual mode)
- type:
{ yaw, pitch } | { textureX, textureY }
Position of the link in spherical coordinates (radians/degrees) or texture coordinates (pixels).
gps
(required in GPS+server mode)
- type:
number[]
Define the GPS coordinates of the target node. It must be provided in order to position the link without having to load the target node.
linkOffset
- type:
{ yaw?, pitch?, depth? }
Offset added to the final link position, to move the marker/arrow without affecting where the viewer is rotated before going to the next node.
depth
is only used in 3D render mode to manage overlapping arrows. Note that overlapping arrows are automatically made transparent (depending on arrowsPosition.linkOverlapAngle
).
arrowStyle
Overrides the global style of the arrow used to display the link. See global configuration for details.
data
- type:
any
Any custom data you want to attach to the link.
Configuration
dataMode
- type:
'client' | 'server'
- default:
'client'
- updatable: no
Configure how the nodes configuration is provided.
positionMode
- type:
'manual' | 'gps'
- default:
'manual'
- updatable: no
Configure how the links between nodes are positionned.
renderMode
- type:
'2d' | '3d'
- default:
'3d'
- updatable: no
How the links are displayed.
nodes
(client mode only)
- type:
array
- updatable: no
Initial list of nodes. You can also call setNodes
method later.
getNode(nodeId)
(required in server mode)
- type:
function(nodeId: string) => Promise<Node>
- updatable: no
Callback to load the configuration of a node.
startNodeId
(required in server mode)
- type:
string
- updatable: no
Id of the initially loaded node. If empty the first node will be displayed. You can also call setCurrentNode
method later.
preload
- type:
boolean | function(node: Node, link: NodeLink) => boolean
- default:
false
- updatable: no
Enable the preloading of linked nodes, can be a function that returns true or false for each link.
transitionOptions
- type:
object | function
- default:
{ showLoader: true, speed: '20rpm', effect: 'fade', rotation: true }
- updatable: no
Configuration of the transition between nodes. Can be a callback.
linksOnCompass
- type:
boolean
- default:
true
- updatable: no
If the Compass plugin is enabled, displays the links on the compass.
showLinkTooltip
- type:
boolean
- default:
true
- updatable: no
Should a tooltip be displayed on each link. The default tooltip contains name
+ thumbnail
+ caption
, it is customizable with the getLinkTooltip option.
getLinkTooltip(content, link, node)
- type:
function(string, link, node) => string
- default:
null
- updatable: no
Callback used to replace/modify the tooltip for a link. The first parameter is the default tooltip content.
map
(client mode only)
Configuration when using the Map plugin.
arrowStyle
- type:
object
- updatable: no
Style of the arrow used to display links.
Default value is:
{
element: // a circular button with a ripple effect
size : { width: 80, height: 80 },
}
You can also use image
(path to an image file) and add custom CSS with style
and className
.
arrowsPosition
(3d mode only)
- type:
object
- updatable: no
Default value is:
{
/* (3D mode) Minimal vertical view angle */
minPitch: 0.3,
/* (3D mode) Maximal vertical view angle */
maxPitch: Math.PI / 2,
/* (3D mode) Make transparent links that are close to each other */
linkOverlapAngle: Math.PI / 4,
/* (2D+GPS mode) vertical offset applied to link markers, to compensate for viewer height */
linkPitchOffset: -0.1,
}
Methods
setNodes(nodes, [startNodeId])
(client mode only)
Changes the nodes and display the first one (or the one designated by startNodeId
).
updateNode(node)
(client mode only)
Updates a single node. If it is the current node, the viewer will be updated accordingly. All attributes or optionnal but id
.
virtualTourPlugin.updateNode({
id: 'node-1',
caption: 'New caption',
links: [...newLinks],
});
setCurrentNode(nodeId, [options])
Changes the current node. options
allows to override the default transitionOptions
.
getCurrentNode()
Returns the current node.
Events
node-changed(node, data)
Triggered when the current node is changed.
virtualTourPlugin.addEventListener('node-changed', ({ node, data }) => {
console.log(`Current node is ${node.id}`);
if (data.fromNode) {
// other data are available
console.log(`Previous node was ${data.fromNode.id}`);
}
});
enter-arrow(link, node)
| leave-arrow(link, node)
Triggered when the user puts the cursor hover or away an arrow.