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.

gotoLink(nodeId, [speed]): Promise

Moves the view to face a specific link. Default speed is 8rpm, set it to 0 for an immediate rotation.

virtualTourPlugin.gotoLink('2', '4rpm')
  .then(() => /* animation complete */);

getCurrentNode()

Returns the current node.

getLinkPosition(nodeId): Position

Returns the position of a link in the viewer.

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.