Orbitvu Public Support Site

ORBITVU VIEWER API

Updated on

In Infinity360 and FREE versions of ORBITVU VIEWER it is possible to control ORBITVU VIEWER programmatically, using JavaScript.

To get access to ORBITVU VIEWER API object you have to do the following:

  • define a global callback function (JavaScript)
  • set viewer_api_init parameter to the name of this function

Sample code:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />

        <script type="text/javascript">
            // Global variable to store VIEWER API object reference
            var viewer_api_obj = null;

            // Callback called while VIEWER is loading
            window['my_loading_callback'] = function(progress){
                console.log('progress: ' + progress);
            }

            // Callback called when viewer is initialized (all required frames are loaded)
            // From this point it is possible to manipulate it, eg. rotate/zoom
            window['my_viewer_initialized_callback'] = function(){
                // as soon as viewer is initialized rotate to 10-th frame
                viewer_api_obj.setScene({hangle: 10});
            }

            // callback called on API initialization used to set another callbacks and store API object reference
            window['my_api_callback_name'] = function(api_obj) {
                viewer_api_obj = api_obj;
                api_obj.addCallback('my_viewer_initialized_callback', 'viewer_initialized');
                api_obj.addCallback('my_loading_callback', 'loading');
            };
        </script>
    </head>
    <body>
        // YOUR SITE CODE HERE
        <div class="orbitvu-viewer" style="background: url(//static.orbitvu.co/001/CmWVYLsjZz3nh3FvjzepBQ/300/350/img01.png) no-repeat center center #ffffff; width: 350px; height: 300px">
            <script type="text/javascript" src="//orbitvu.co/001/CmWVYLsjZz3nh3FvjzepBQ/ov3601/3/script?
                &width=350&content2=yes&height=300
                &viewer_api_init=my_api_callback_name"
            ></script>

        </div>
        // YOUR SITE CODE HERE
    </body>
</html>

It is also possible to use external_access_init parameter but it is deprecated since VIEWER 2.3.33 in favour of viewer_api_init. Sample code for external_access_init:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />

        <script src="http://code.jquery.com/jquery-1.10.1.min.js"></script>
        <script type="text/javascript">
            var viewer_api_obj = null;
            window['my_api_callback_name'] = function(local_viewer) {
                 /* STARTING from ORBITVU VIEWER 2.3.3 it is not required to use code below */
                 /* start: viewer <= 2.3.2*/
                     if (!local_viewer) {
                         // specify id of VIEWER Flash object
                         local_viewer = document.getElementById('ovContent-dSz54kMJ7rHKtC6E2YBHpf-obj');
                     }
                 /* end: viewer <= 2.3.2*/

                 viewer_api_obj = local_viewer;
                 local_viewer.setScene({hangle: 10});
            };
        </script>
    </head>
    <body>
        // YOUR SITE CODE HERE
        <div class="orbitvu-viewer" style="background: url(//static.orbitvu.co/001/CmWVYLsjZz3nh3FvjzepBQ/300/350/img01.png) no-repeat center center #ffffff; width: 350px; height: 300px">
            <script type="text/javascript" src="//orbitvu.co/001/CmWVYLsjZz3nh3FvjzepBQ/ov3601/3/script?
                &width=350&content2=yes&height=300
                &external_access_init=my_api_callback_name"
            ></script>

        </div>
        // YOUR SITE CODE HERE
    </body>
</html>

getScene

Returns information about currently displayed scene

viewer_api_obj.getScene();

Returns the dictionary object with the following information:

  • scale - current scale
  • centerx - current X coordinate of viewport centre (in pixels - relative to presentation’s maximum resolution)
  • centery - current Y coordinate of viewport centre (in pixels - relative to presentation’s maximum resolution)
  • centerX - same as centerx
  • centerY - same as centery
  • hangle - the number of currently shown horizontal frame
  • vangle - the number of currently shown vertical frame

setScene

Main function used to manipulate presentation:

viewer_api_obj.setScene({<param_name>: <param_value>});

Parameters

autorotate

Start/stop autorotation
Values: yes | no
Default: no

autorotate_dir

Autorotation direction
Values: left | right

fullscreen

Makes it possible to switch Viewer to fullscreen mode and defines helper methods to handle switching Viewer to Fullscreen mode

Version: 3.6.7+

Values:

  • toggle
    Toggle Viewer to/from Fullscreen mode
  • pre
    Instructs Viewer to store current dimensions, eg. if Viewer has forced width and height. This method should be called eg. if the parent element of the Viewer will be switched to Fullscreen mode - before this switch. After fullscreen is enabled for the parent element, enter method of the Viewer should be called to update viewer dimensions. On Fullscreen cancel the cancel method has to be called.
  • enter
    Updates Viewer dimensions by removing any forced sizes, eg. width and height - Viewer will autosize to the container element (if only it has any dimensions defined). Can be called eg. when parent element of the Viewer is switched to fullscreen and the Viewer should also change its size.
  • cancel
    Resets Viewer dimensions to ones stored with pre method. Can be called eg. after leaving the fullscreen mode for the parent element of the Viewer.

hangle

Rotate to horizontal frame
Values: 0 - <number of frames>
Example: viewer_api_obj.setScene({hangle: 10});

hangleInc

Change horizontal angle by specified number of frames, eg. 2 or -2

mode

Mode in which ORBITVU VIEWER operates
Values: rotate | drag | onerotation | onerotationslow
Default: rotate

panX

Move current view along horizontal axis, eg.: 100 (move 100px to the right), -10% (move 10% of the current view to the left), -30px (move 30px to the left).

panY

Move current view along vertical axis, eg.: 100 (move 100px to the bottom), -10% (move 10% of the current view to the top), -30px (move 30px to the top).

reset_position

Immediately reset presentation's position to the starting one (using initial values for first_frame, first_row and scale).

Version: 3.9.0+

Values: yes|no

Extra parameters: vangle, hangle, scale - force specific value for the parameter vangle - row, hangle - horizontal frame, scale - zoom level

Examples: setScene({reset_position: 'yes'}), setScene({reset_position: 'yes', hangle: 4})

scaleUp

Zoom in

scaleDown

Zoom out

vangle

Set vertical angle for 3D presentations

vangleInc

Change vertical angle by specified number of lines, eg. 1 or -1

zoomMul

Zoom by specified factor

You should not mix different parameters together in a single call

addCallback

Adds a callback to handle ORBITVU VIEWER events:

viewer_api_obj.addCallback('<callback_function_name>', '<event_name>');

You have to pass name of the globally accessible callback function, not the function object itself

Events

activity_start

Version: 3.3.0+
Triggered when any activity occurs, eg. when VIEWER is interacted with or when API calls cause some actions to happen

activity_end

Version: 3.3.0+
Triggered when no activity is happening in VIEWER, eg. when autorotation is stopped

autorotate_start

Triggered when autorotation is started

autorotate_stop

Triggered when autorotation is stopped, e.g. user clicks the presentation

center_change

Triggered when view centre is changed

fullscreen_off

Triggered when fullscreen mode is cancelled

fullscreen_on

Triggered when Viewer enters fullscreen mode

interaction_start

Version: 2.3.27
Triggered on any user interaction with VIEWER, e.g. mouse click, button click, zoom in/out with mouse wheel

loading

Version: 2.3.33
Triggered when ORBITVU VIEWER is loading frames. The callback is passed numeric value representing a percentage of already loaded frames.
When partial_load is set to yes then you might be also interested in partial_loading event defined below as in this case loading event will only apply to 4 first frames loaded.

mode_changed

Version: 2.3.33
Triggered when VIEWER mode is changed eg. from rotate to drag
Values: rotate | drag | onerotation | onerotationslow

partial_loading

Version: 3.0.26
Triggered when VIEWER is loading frames in the background (when partial_load is set to yes). The callback is passed numeric value representing a percentage of already loaded frames.

partially_initialized

Triggered when partial_load is set to yes and when the first set of 4 frames has been loaded (VIEWER is able to interact with a user).

rotate

Triggered while rotating

set_scene

Triggered when setting the scene starts.

set_scene_complete

Triggered when setting the scene is completed

viewer_initialized

Version: 2.3.33
Triggered when all required frames are loaded and it is possible to manipulate/interact with VIEWER.
Callback will receive viewer api object as a parameter.

zoom_in

zoom_out

calculate_position

Available since 2.3.15

Converts x, y coordinates relative to presentation’s max_width and max_height to current viewport coordinates (scaled). 

For example, if presentation's max_width/max_height is 4422px x 3073px and it is displayed in a viewport of size 368px x 400px then coordinates of x: 1000 y: 500 will be converted to coordinates relative to viewport depending on current scale and center position:

scale: 0.175, centerX: 2623, centerY: 1930

converted:

x: -99, y: -50

This is useful if you want to display something in the specific position over the presentation.

Example usage:

viewer.calculate_position({x: 1000, y: 500})

where a viewer is an object returned by the viewer_api_init (or external_access_init) callback.

Parameters:

  • coords
    dictionary with x, y values, eg.: {x: 1000, y: 500}

get_presentation_info

Available since 2.3.15

Returns the dictionary containing the following information:

  • width - current viewport width
  • height - current viewport height
  • max_width - max presentation width
  • max_height - max presentation height
  • hangles_no - number of horizontal frames
  • vangles_no - number of vertical frames
  • min_scale - minimum zoom scale value
  • max_scale - maximum zoom scale value
  • dimensions_changed - if true indicates that Viewer is changing its dimensions, eg. while entering fullscreen

handle_resize

Manually inform ORBITVU VIEWER that its container size has changed:

viewer_api_obj.handle_resize();

This is called automatically on window resize but if you intend to e.g. interactively change dimensions of the VIEWER’s container element, then you can call handle_resize to make sure ORBITVU VIEWER is shown correctly.

enable_mousewheel

Enable zoom on the mouse wheel. This method switches mousewheel parameter to ‘yes’:

viewer_api_obj.enable_mousewheel();

disable_mousewheel

Disable zoom on the mouse wheel. This method switches mousewheel parameter to ‘no’:

viewer_api_obj.disable_mousewheel()

set_forced_mode

Available since 2.3.33

Switch to drag or rotate mode of the ORBITVU VIEWER

Values: drag | rotate

Previous Article Customizing ORBITTOUR embed code - parameters reference
Next Article ORBITTOUR API

VIEWER, ORBITTOUR, and 360° Presentations EN

Introduction 5
Integration with websites 4
Offline usage on mobile devices 2
Integration examples 2
Parameters reference 6

Other Resources

Print Article
Still Need Help? Contact Us