API¶

Additionally, the common API of a module is available.

Methods¶

loadView3d()¶

Asynchronous method that loads a specific 3d view from a venue.

Input:

• load_options (object): Object with the information of the 3d view to be loaded. Its properties are:
  • venue_id (string): venue id.
  • view_id (string): view id. It is usually a seat id or a section id, and the ids, in general, match those found in map_viewer maps.
  • reset_camera_rotation (boolean) [optional]: resets the camera rotation so the new view will be looking at the front. true by default. false is useful in some plugins, like navigation plugin.

Output:

• promise (Promise): loadView3d returns a promise that will be resolved if the 3d view is loaded successfully, or it will be rejected if there was a problem when loading the 3d view.
  • If the promise is resolved successfully, the first argument will be an object with the property instance, with the reference to the module.
  • If the promise is rejected, the first argument will be an error with a property instance with the module instance that failed to load.

Example:

1
2
3
4
5
6
7
8
9

var obj = { venue_id: "venue", view_id: "view" };
viewer3d.loadView3d(obj)
    .then(function(obj) {
        console.log("VIEW LOADED");
    })
    .catch(function(err) {
        // Something went wrong. Maybe you do not have permissions or the view does not exist
        console.error(err)
    })

loadSpace3d()¶

Asynchronous method that loads a specific 3d space from a venue.

Input:

• options (object): Object with the information of the 3d view to be loaded. Its properties are:
  • venue_id (string): venue id.
  • space_id (string): space id.
  • set_id (string) [optional]: venue set id.
  • rotation ([number, number]) [optional]: Initial camera position (phi, theta)in spherical coords.
  • reset_camera_rotation (boolean) [optional]: resets the camera rotation or keep the last camera position.

Output:

• promise (Promise): loadSpace3d returns a promise that will be resolved if the 3d space is loaded successfully, or it will be rejected if there was a problem when loading the 3d view.
  • If the promise is resolved successfully, the first argument will be an object with the property instance, with the reference to the module.
  • If the promise is rejected, the first argument will be an error with a property instance with the module instance that failed to load.

Example:

1
2
3
4
5
6
7
8
9

var obj = { venue_id: "venue", space_id: "space" };
viewer3d.loadSpace3d(obj)
    .then(function(obj) {
        console.log("VIEW LOADED");
    })
    .catch(function(err) {
        // Something went wrong. Maybe you do not have permissions or the view does not exist
        console.error(err)
    })

checkView3d()¶

Asynchronous method that checks if a specific 3d view exists.

Input:

• options (object): Object with the information of the 3d view to be checked. Its properties are:
  • venue_id (string): venue id.
  • view_id (string): view id. It is usually a seat id or a section id, and the ids, in general, match those found in map_viewer maps.

Output:

• promise (Promise): returns a promise that will be resolved with a boolean, being true if the view exists, or false if it does not. The promises will be rejected if there is another problem, for example if you do not have permissions to access this venue, regardless of whether the view exists or not.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

var obj = { venue_id: "venue", view_id: "view" };
viewer3d.checkView3d(obj)
    .then(function(exists) {
        if (exists) {
            // The view does exist
            return viewer3d.loadView3d(obj)
                .then(function(obj) {
                    console.log("VIEW LOADED");
                });
        } else {
            // The view does not exist.
            doSomething();
        }
    })
    .catch(function(err) {
        // Something went wrong. Maybe you do not have permissions
        console.error(err)
    });

getThumbnail()¶

Asynchronous method that returns an image with a preview of the 3d view.

The returned image has a size of 256x256 pixels.

Input:

• options (object): Object with the information of the preview to be downloaded. Its properties are:
  • venue_id (string): venue id.
  • view_id (string): view id. It is usually a seat id or a section id, and the ids, in general, match those found in map_viewer maps.
• url (boolean) [optional]: true if you want that the promise to be resolved in a url, false will be resolved in an image. false by default.

Output:

• promise (Promise): If the image is downloaded successfully, the Promise resolves with the image. If the flag url is false it is resolved in an url.

Example:

1
2
3
4
5
6
7
8
9

var obj = { venue_id: "venue", view_id: "view" };

viewer3d.getThumbnail(obj)
    .then(function(img) {
        document.body.appendChild(img);
    })
    .catch(function(err) {
        console.error(err);
    });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

var obj = { venue_id: "venue", view_id: "view" };

viewer3d.getThumbnail(obj, true)
    .then(function(url) {
        var img = new Image();
        img.src = url;
        document.body.appendChild(img);
    })
    .catch(function(err) {
        console.error(err);
    });

isInitialized()¶

Returns true if the module has been initialized.

Output:

• initialized (boolean): true if it has been initialized, false otherwise.

Example:

1

var initialized = viewer3d.isInitialized();

isLoaded()¶

Returns true if there is a 3d view currently loaded.

Output:

• loaded (boolean): true if a 3d view is completely loaded, false otherwise.

Example:

1

var loaded = viewer3d.isLoaded();

reset()¶

unloads the current 3d view (if any). It is necessary to call loadView3d again after this.

Example:

1

viewer3d.reset();

subscribe()¶

Allows the subscription to callbacks. This is the same as passing the callbacks when loading the module.

Input:

• callback_name (string): Any callback of the list.
• callback_func (function): Function that will be called when triggered.

Example:

1

viewer3d.subscribe("panning", function(obj) { console.log("PANNING"); });

unsubscribe()¶

Removes a callback previously added with subscribe method or loading the module.

Input:

• callback_name (string): Any callback of the list.
• callback_func (function): reference to the function to be removed.

Example:

1
2
3
4
5

viewer3d.subscribe("panning", func);
function func(obj) {
    console.log(obj.action);
    viewer3d.unsubscribe("panning", func);
}

getViewDescription()¶

Asynchronous method that resolves in a panoramic view description.

Input:

• options (object) [optional]: true Optional object with the information of the 3d view to get its description. If no input is passed, it will get the description of the current loaded view (if any). Its properties are:
  • venue_id (string)
  • view_id (string)

Output:

• description (Promise): promise that will be resolved with an object with "title" and "description".

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

var obj = { venue_id: "venue", view_id: "view" };
viewer3d.getViewDescription(obj)
    .then(function(result) {
        console.log("Title:", result.title);
        console.log("Description:", result.description);
    })
    .catch(function(err) {
        // Something went wrong. Maybe you do not have permissions or the view doesn't exist.
        console.error(err)
    });

open()¶

Appends the 3d viewer to the DOM.

Example:

1

viewer3d.open();

close()¶

Detaches the 3d viewer from the DOM.

Example:

1

viewer3d.close();

getVenueId()¶

Returns the id of the current loaded venue.

Output:

• current_venue (string|null): returns the id of the current loaded venue. If there is no venue loaded yet, it will return null.

Example:

1

var current_venue = viewer3d.getVenueId();

getViewId()¶

Returns the id of the current loaded 3d view.

Output:

• current_view (string|null): returns the id of the current loaded 3d view. If there is no view loaded yet, it will return null.

Example:

1

var current_view = viewer3d.getViewId();

getSpaceId()¶

Returns the id of the current loaded 3d space.

Output:

• current_view (string|null): returns the id of the current loaded 3d space. If there is no space loaded yet, it will return null.

Example:

1

var current_view = viewer3d.getSpaceId();

getSceneType()¶

Returns the scene configuration.

Output:

• scene_type ("pano"|"space"|null): returns if the scene is a pano or space. If there is no view loaded yet, it will return null.

Example:

1

var scene_type = viewer3d.getSceneType();

setContainer()¶

Changes the container where the 3d viewer is.

Input:

• div_element (string | HTMLDivElement): if the input is a string, it must be de unique id of an HTMLDivElement. Otherwise, it must be the HTMLDivElement itself.

Example:

1

viewer3d.setContainer("new-container-id");

1
2

var container = document.getElementById("new-container-id");
viewer3d.setContainer(container);

toggleFullscreen()¶

enables/disables full screen mode.

This method triggers the following callbacks:

• fullscreen_enabled
• fullscreen_disabled

Output:

• promise (Promise): It will be resolved once the fullscreen request has been fullfilled. If the request fails, for example if the browser blocks de request because it has been requested outside a user event, it will be rejected.

Example:

1

viewer3d.toggleFullscreen();

rotateCamera()¶

Rotates the camera a certain angle.

Input:

• spherical ([number, number]): phi and theta coords.
• inertia (boolean?): the rotation will generate inertia if this is true. false by default.

lookAt()¶

Rotate the camera to look at the vec coords.

Input:

• load_options (object): Object with the information of the map to be loaded. Its properties are:
  • target ([number, number, number] | Viewer3dNode): if target is a vector this indicate where the camera should look. If it's a node the camera will look at it.
  • time (number?) = 0: time of the interpolation animation from the current camera rotation
  • local (boolean?) = false: true if the point is in local coordinates. false by default. Ignored if target is not a node.
  • behavior ("no_rotation" | "look_at" | "normal" | "best_view" | "node_look_at_vector" | "default"?) = "default": In 3D Spaces it indicates how we should interprate the rotation and movement. In 3D Panos it's ignored.

Input:

• vec ([number, number, number]): position to look at.
• time (number): how many ms should last the transition.
• local (boolean?): Is the vec input in venue coords or relative to the pano.

Output:

• look_at_promise (Promise): returns the transition promise to detect when it end. The promise will be rejected if the venue is not loaded or if the user interrupts the animation.

Example:

1
2

// reset the view to the pano front instantly.
var look_at_promise = viewer3d.lookAt([0,0,-1], 0, true);

Properties¶

aspect_ratio¶

Changes or returns the 3d viewer aspect ratio. It only works if fixed_aspect_ratio is true.

Input/Output:

• aspect_ratio (number): aspect ratio from the 3d viewer. The value is obtained by dividing height/width. For instance, to use a 16:9 aspect ratio, the division is9/16. This is set to 9/16 by default.

Example:

1

viewer3d.aspect_ratio = 9/16;

pixel_ratio¶

Sets the canvas pixel ratio. By default, it is set to 1. For more info check this.

Input/Output:

• pixel_ratio (number): pixel ratio.

Example:

1

viewer3d.pixel_ratio = window.devicePixelRatio || 1;

fov¶

Changes or returns the 3d viewer field of view.

Input/Output:

• fov (number): field of view of the camera, in degrees.

Example:

1

viewer3d.fov = 75;

azimuth_limit¶

Changes or returns the spherical azimuth limit.

Input/Output:

• [min, max] ([number, number]): min and maximum azimuth (horizontal move), in degrees ([0, 360]).

Example:

1

viewer3d.azimuth_limit = [30, 320];

polar_limit¶

Changes or returns the spherical polar limit.

Input/Output:

• [min, max] ([number, number]): min and maximum polar (horizontal move), in degrees ([0, 180]).

Example:

1

viewer3d.polar_limit = [60, 120];

Flags¶

fixed_aspect_ratio¶

Specifies the rescaling mode of the 3d viewer.

• If true: The 3d viewer will take up the 100% of the container width, and the height will be computed multiplying the width by the aspect_ratio. For instance, if aspect_ratio = 0.5, the height will be 500px when the Viewer container has width of 1000px.
• If false: The Viewer will take up the 100% of the container width and height. It is important to ensure that the container has some height or it will be set as 0px. aspect_ratio will be ignored.

Input/Output:

• fixed_aspect_ratio (boolean): true enables the fixed_aspect_ratio mode. false disables it. This is set to true by default.

Example:

1

viewer3d.flags.fixed_aspect_ratio = true;

show_fullscreen_button¶

show/hides fullscreen button.

• If true: The 3d viewer will take up the 100% of the container width, and the height will be computed multiplying the width by the aspect_ratio. For instance, if aspect_ratio = 0.5, the height will be 500px when the Viewer container has width of 1000px.
• If false: The Viewer will take up the 100% of the container width and height. It is important to ensure that the container has some height or it will be set as 0px. aspect_ratio will be ignored.

Input/Output:

• show_fullscreen_button (boolean): true shows the button. false hides it. This is set to true by default.

Example:

1

viewer3d.flags.show_fullscreen_button = true;

show_loading_screen¶

Enables/disables the loading screen while a view is loading.

• If true: It will show a loading screen animation while loading.
• If false: no loading screen.

Input/Output:

• show_loading_screen (boolean): true enables the loading screen. false disables it. This is set to true by default.

Example:

1

viewer3d.flags.show_loading_screen = true;

show_tutorial¶

Enables/disables the tutorial animation the first time a view is loaded.

• If true: A tutorial animation with a predefined movement will be shown the first time a view is loaded.
• If false: No tutorial animation will be shown.

Input/Output:

• show_tutorial (boolean): true enables the tutorial. false disables it. This is set to true by default.

Example:

1

viewer3d.flags.show_tutorial = true;

keyboard_arrows_rotation¶

allows using the left/right keyboard arrows to rotate the camera when a view is loaded.

• If true: left and right keyboard arrows will rotate the view.
• If false: disables keyboard arrow rotation.

Input/Output:

• keyboard_arrows_rotation (boolean): true enables arrow keys rotation. false disables arrow keys rotation. This is set to true by default.

Example:

1

viewer3d.flags.keyboard_arrows_rotation = true;

zooming¶

Enables or disables zooming with mouse or touch. Not all 3D views allows to zoom, independently of the value of this flag.

• If true: allows zooming on the 3d view (if the view allows it) with mouse scroll or pinch.
• If false: disables zooming on the view with scroll or pinch. You still can zoom in and out with interface buttons or other API methods. Disabling it will allow scrolling on the page over the view.

Input/Output:

• zooming (boolean): true enables zooming. false disables it. This is set to true by default.

Example:

1

viewer.flags.zooming = true;

panning¶

Enables or disables panning with mouse or touch.

• If true: allows panning with mouse or touch.
• If false: disables panning on the view when using mouse or touch. You still can move with interface buttons or other methods.

Input/Output:

• panning (boolean): true enables panning. false disables it. This is set to true by default.

Example:

1

viewer.flags.panning = true;