# VirtualTourPlugin NEW

API Documentation

Create virtual tours by linking multiple panoramas.

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

# Usage

The plugin allows to define nodes which contains a panorama and one or more links to other nodes. The links are represented with a 3D arrow (default) or using the Markers plugin.

There two different ways to define the position of the links : the manual way and the GPS way.

The nodes can be provided all at once or asynchronously as the user navigates.

# Example

# Nodes options

# id (required)

  • type: string

Unique identifier of the node

# panorama (required)

Refer to the main config page.

  • type: array

Definition of the links of this node. See bellow.

# position (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 (opens new window) is supported.

# panoData

Refer to the main config page.

# sphereCorrection

Refer to the main config page.

# name

  • type: string

Short name of this node, used in links tooltips.

# caption

  • type: string

Caption displayed in th navbar, if not defined the global caption will be used.

# markers

  • type: array

Additional markers displayed on this node, requires the Markers plugin.

# nodeId (required)

  • type: string

Identifier of the target node.

# x & y or latitude & longitude (required in manual mode)

  • type: integer or double

Position of the link in texture coordinates (pixels) or spherical coordinates (radians).

# position (required in GPS+server mode)

  • type: number[]

Overrides the GPS coordinates of the target node.

# name

  • type: string

Overrides the tooltip content (defaults to the node's name property).

# arrowStyle (3d mode only)

  • type: object

Overrides the global style of the arrow used to display the link. See global configuration for details.

# markerStyle (markers mode only)

  • type: object

Overrides the global style of the marker used to display the link. See global configuration for details.

# Configuration

# dataMode

  • type: 'client' | 'server'
  • default: 'client'

Configure how the nodes configuration is provided.

# positionMode

  • type: 'manual' | 'gps'
  • default: 'manual'

Configure how the links between nodes are positionned.

# renderMode

  • type: 'markers' | '3d'
  • default: '3d'

How the links are displayed, markers requires the Markers plugin.

# nodes (client mode only)

  • type: array

Initial list of nodes. You can also call setNodes method later.

# getNode(nodeId) (required in server mode)

  • type: function(nodeId: string) => Promise<Node>

Callback to load the configuration of a node.

  • type: function(nodeId: string) => Promise<NodeLink[]>

Callback to load the links of a node.

# startNodeId

  • type: string

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

Enable the preloading of linked nodes, can be a function that returns true or false for each link.

# markerStyle (markers mode only)

  • type: object

Style of the marker used to display links.

Default value is:

{
  html     : arrowIconSvg, // an SVG provided by the plugin
  width    : 80,
  height   : 80,
  scale    : [0.5, 2],
  anchor   : 'top center',
  className: 'psv-virtual-tour__marker',
  style : {
    color: 'rgba(0, 208, 255, 0.8)',
  },
}

# arrowStyle (3d mode only)

  • type: object

Style of the arrow used to display links.

Default value is:

{
  color     : 0x0055aa,
  hoverColor: 0xaa5500,
  opacity   : 0.8,
  scale     : [0.5, 2],
}

(The 3D model cannot be modified).

# markerLatOffset (markers+GPS mode only)

  • type: number
  • default: -0.1

Vertical offset in radians applied to the markers to compensate for the viewer position above ground.

# arrowPosition (3d mode only)

  • type: 'top' | 'bottom'
  • default: 'bottom'

Vertical position of the arrows.

# linksOnCompass

  • type: boolean
  • default: true if markers mode

If the Compass plugin is enabled, displays the links on the compass.

# Methods

# setNodes(nodes, [startNodeId]) (client mode only)

Changes the nodes and display the first one (or the one designated by startNodeId).

# setCurrentNode(nodeId)

Changes the current node.

# Events

# node-changed(nodeId)

Triggered when the current node is changed.

virtualTourPlugin.on('node-changed', (e, nodeId) => {
  console.log(`Current node is ${nodeId}`);
});