Photo Sphere Viewer 4

# VirtualTourPlugin

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 are two different ways to define the position of the links : the manual mode and the GPS mode.

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

TIP

If the Gallery plugin is loaded, it will be configured with the list of nodes (client mode only).

# 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.

# name

  • type: string

Short name of this node, used in links tooltips and the gallery.

# caption

Replace the global caption. Refer to the main config page.

# description

Replace the global description. Refer to the main config page.

# thumbnail

  • type: string

Thumbnail for the nodes list in the gallery.

# markers

  • type: array

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

# panoData

Refer to the main config page.

# sphereCorrection

Refer to the main config page.

# 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.

# 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.

# rotateSpeed

  • type: boolean | string | number
  • default: 20rpm

When a link is clicked, adds a panorama rotation to face it before actually changing the node. If false the viewer won't rotate at all and keep the current orientation.

# transition

  • type: boolean | number
  • default: 1500

Duration of the transition between nodes.

# linksOnCompass

  • type: boolean
  • default: true if markers render mode

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

# 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)',
  },
}

TIP

If you want to use another marker type like image you must define html: null to remove the default value.

markerStyle: {
  html : null,
  image: 'path/to/image.png',
}

# arrowStyle (3d mode only)

  • type: object

Style of the arrow used to display links.

Default value is:

{
  color       : 0xaaaaaa,
  hoverColor  : 0xaa5500,
  outlineColor: 0x000000,
  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.

# 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, data)

Triggered when the current node is changed.

virtualTourPlugin.on('node-changed', (e, nodeId, data) => {
  console.log(`Current node is ${nodeId}`);
  if (data.fromNode) { // other data are available
    console.log(`Previous node was ${data.fromNode.id}`);
  }
});

← VisibleRangePlugin →