Controlling the panorama display

When a panorama is displayed in the panorama player, standard UI controls are automatically added to it. They allow users to change the viewing angle on the panorama and enable full-screen mode. These controls are added both to Yandex panoramas and to custom panoramas. The developer can explicitly define which controls to add to the panorama.

Note

The API does not allow you to change the appearance of the panorama controls.

In addition, the API has a set of functions that you can use to control the panorama image at the code level. The panorama player generates various events that you can set or remove callback functions for.

Controls

By default, the following controls are added to the panorama:

Note

The «Open in Yandex Maps» link is only displayed on Yandex panoramas. This control can't be hidden.

To define the set of controls that will be added to the panorama, use the 'controls' option when creating an instance of the player (panorama.Player):

var player = new ymaps.panorama.Player('div_id', panorama, {
        // Only the panorama name and the «Open in Yandex Maps» link will be shown on the panorama.
        controls: ['panoramaName']
    });

For a list of available keys, see the reference guide.

Note that the API does not allow you to change the appearance of the panorama controls.

Controlling the panorama image programmatically

The panorama player provides various functions for controlling the panorama image. For example, you can change the viewing direction, connect to another panorama, and so on. Methods for working with the panorama are listed below.

setDirection

Sets a new viewing direction on the panorama. Set in the format [bearing, pitch], where bearing is the azimuth of the direction in degrees, and pitch is the angle of elevation above the horizon in degrees. For more information, see the Reference.

player.setDirection([10, 10]);
setSpan

Sets the size of the field of view on the panorama. For more information, see the Reference.

player.setSpan([10, 10]);
lookAt

Sets the viewing direction so that the passed point is in the center of the field of view.

player.lookAt([69.92620155262, 31.3111500947]);
moveTo

Searches for a panorama with the specified parameters and switches to it.

player.moveTo([59.9262015526, 30.3111500948], {
    // We need to switch to an aerial panorama.
    layer: 'yandex#airPanorama'
});

Note

To go to the aerial panorama, specify the layer option with the value 'yandex#airPanorama' (you need to specify this option even if the current panorama that you are leaving is also an aerial panorama).

To get information about the status of displaying the panorama, you can use the following methods:

getPanorama

Returns the panorama that is currently open in the panorama player. For more information, see the Reference.

var panorama = player.getPanorama();

// Now we can get some information about the panorama itself, such as its name.
// For more information, see <xref href="#panorama-manage/getPanoramaInfo"/>.
console.log("Panorama name: " + panorama.getName());
getDirection

Returns the current viewing direction in the format [bearing, pitch], where bearing is the azimuth of the direction in degrees, and pitch is the angle of elevation above the horizon in degrees. For more information, see the Reference.

console.log(player.getDirection()); // for example: 347.40000000000003,-14.590624999999983
getSpan

Returns the current angle of the field of view. For more information, see the Reference.

console.log(player.getSpan()); // for example: 119.99999999999999,80

Getting information about a panorama

The API provides a set of methods for getting information about a panorama (such as its name or type). The main methods are listed below:

getName

Returns the panorama name.

console.log("Panorama name: " + panorama.getName());
getLayer

Returns the type of the current panorama.

console.log("Type of panorama: " + panorama.getLayer()); 
// 'yandex#panorama' - land,
// 'yandex#airPanorama' - aerial.

Player events

The list of possible events geneated by the panorama player are shown below:

Event

Description

'directionchange'

The view direction changed.

'fullscreenenter'

The panorama player switched to full-screen mode.

'fullscreenexit'

The panorama player exited full-screen mode.

'panoramachange'

The panorama changed.

'spanchange'

The angle of the field of view changed.

'destroy'

The player was closed or destroyed using the panorama.Player.destroy method.

'error'

An error occurred in the player.

Use the add() function to subscribe to an event. The example below shows subscribing to the 'directionchange' event for Yandex.Panoramas:

// Searching for a panorama at the specified point.
ymaps.panorama.locate([55.733685, 37.588264]).done(
  function (panoramas) {
    // Checking if at least one panorama was found.
    if (panoramas.length > 0) {
      var player = new ymaps.panorama.Player('player', panoramas[0], {
            direction: [256, 16]
          });
      // Subscribing to an event.
      player.events.add('directionchange', function () {
        console.log('Viewing direction changed');
      });
    }
  });

Use the remove() function to cancel a subscription to an event. Pass the event type as the first argument of the function, and a reference to the callback function to delete (but not the callback itself) as the second argument. For example:

function onError () {
  console.log("An error occurred in the panorama player.");
}

// Subscribing to the 'error' event.
player.events.add('error', onError);
// Deleting the event handler.
player.events.remove('error', onError);

For a list of all the functions available for working with events, see the reference guide.