Photo Sphere Viewer

# VirtualTourPlugin Styles

NPM version NPM Downloads jsDelivr Hits
API Documentation

Create virtual tours by linking multiple panoramas.

This plugin is available in the @photo-sphere-viewer/virtual-tour-plugin (opens new window) package.

# 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

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.

  • type: array

Definition of the links of this node. See bellow.

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

# 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 it is automatically computed in GPS mode depending on the distance to the node, but can be overriden if necessary.

# arrowStyle / markerStyle

Overrides the global style of the arrow/marker 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: 'markers' | '3d'
  • default: '3d'
  • updatable: no

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

# 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

  • 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', fadeIn: true, 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.

# map (client mode only)

Configuration when using the Map plugin.

# 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 which contains the node name + thumbnail + caption.

# markerStyle (markers mode only)

  • type: object
  • updatable: no

Style of the marker used to display links.

Default value is:

{
  element: // a circular button with a ripple effect
  size   : { width: 80, height: 80 },
}

TIP

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


 



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

# arrowStyle (3d mode only)

  • type: object
  • updatable: no

Style of the arrow used to display links.

Default value is:

{
  color       : 0xaaaaaa,
  hoverColor  : 0xaa5500,
  outlineColor: 0x000000,
  size        : 1,
}

(The 3D model cannot be modified).

# markerPitchOffset (markers+GPS mode only)

  • type: number
  • default: -0.1
  • updatable: no

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'
  • updatable: no

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, [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}`);
    }
});

Triggered when the user puts the cursor hover or away an arrow.

In markers mode, listen to enter-markers/leave-marker on the markers plugin (link markers have an additional tourLink data).

← VisibleRangePlugin →