Orbitvu Public Support Site / VIEWER, ORBITTOUR, and 360° Presentations PL / Lista parametrów

ORBITVU VIEWER API

Updated on Aug 17, 2021

W wersjach Infinity360 oraz FREE możliwe jest sterowanie ORBITVU VIEWER przy użyciu JavaScript.

Aby uzyskać dostęp do API ORBITVU VIEWER należy wykonać następujące czynności:

zdefiniować funkcję callback (JavaScript)
ustawić parametr viewer_api_init na nazwę tej funkcji

Przykładowy kod:

<!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>

Możliwe jest użycie parametru external_access_init, ale on jest przestarzały od wersji VIEWER 2.3.33 na korzyść viewer_api_init. Przykładowy kod 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

Zwraca informacje o aktualnie wyświetlanej scenie.

viewer_api_obj.getScene();

Zwraca obiekt słownika z następującymi informacjami:

scale - aktualna skala
centerx - aktualna współrzędna X środka okna podglądu (w pikselach - w stosunku do maksymalnej rozdzielczości prezentacji)
centery - aktualna współrzędna Y środka okna podglądu (w pikselach - w stosunku do maksymalnej rozdzielczości prezentacji)
centerX - taki sam jak centerx
centerY - taki sam jak centery
hangle - numer aktualnie wyświetlanej klatki (w poziomie)
vangle - numer aktualnie wyświetlanej klatki (w pionie)

setScene

Główna funkcja służąca do manipulowania prezentacją:

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

Parametry

autorotate

Włącz/wyłącz autoobracanie
Wartości: yes | no
Domyślnie: no

autorotate_dir

Kierunek autoobrotu
Wartości: left | right

fullscreen

Umożliwia przełączenie przeglądarki do trybu pełnoekranowego i definiuje pomocnicze metody przełączania przeglądarki do trybu pełnoekranowego

Wersja: 3.6.7+

Wartość:

toggle
Przełączanie przeglądarki do trybu pełnoekranowego
pre
Instruuje VIEWER do przechowywania bieżących wymiarów, np. jeśli VIEWER ma wymuszoną wysokość i szerokość. Ta metoda powinna być wywołana np. jeśli element nadrzędny VIEWER-a zostanie przełączony w tryb pełnoekranowy-przed tym przełączeniem. Po wyłączeniu trybu pełnoekranowego dla elementu nadrzędnego, należy wywołać metodę enter VIEWER-a w celu aktualizacji wymiarów VIEWER-a. W trybie pełnoekranowym należy wywołać metodę cancel.
enter
Aktualizuje wymiary VIEWER-a poprzez usunięcie wymuszonych rozmiarów, np. szerokości i wysokości. VIEWER automatycznie dostosowuje się do elementu kontenera (jeśli tylko ma on zdefiniowane wymiary). Można wywołać tę metodę np. gdy element nadrzędny VIEWER-a jest przełączony na tryb pełnoekranowy i VIEWER powinien również zmienić swój rozmiar.
cancel
Przywraca wymiary VIEWER do tych zapisanych metodą pre. Można wywołać np. po opuszczeniu trybu pełnoekranowego przez element nadrzędny VIEWER-a.

hangle

Obrót do danej klatki - w poziomie
Wartości: 0 - <liczba ramek>
Przykład: viewer_api_obj.setScene({hangle: 10});

hangleInc

Zmiana kąta w poziomie o określoną liczbę klatek, np. 2 lub -2.

mode

Tryb w którym działa ORBITVU VIEWER
Wartości: rotate | drag | onerotation | onerotationslow
Domyślnie: rotate

panX

Przesunięcie widoku wzdłuż osi poziomej, np.: 100 (przesuń 100px w prawo), -10% (przesuń 10% bieżącego widoku w lewo), -30px (przesuń 30px w lewo).

panY

Przesunięcie widoku wzdłuż osi pionowej, np.: 100 (przesuń 100px w dół), -10% (przesuń 10% aktualnego widoku do góry), -30px (przesuń 30px do góry).

reset_position

Natychmiastowe zresetowanie pozycji prezentacji do wyjściowej pozycji (używając początkowych wartości first_frame, first_row i scale).

Wersja: 3.9.0+

Wartości: yes|no

Dodatkowe parametry: vangle, hangle, scale - wymuszenie określonej wartości dla parametrów vangle - wiersz, hangle - klatka w poziomie i scale - skala.

Przykłady: setScene({reset_position: 'yes'}), setScene({reset_position: 'yes', hangle: 4})

scaleUp

Przybliżenie

scaleDown

Oddalenie

vangle

Ustawienie kąta w pionie dla prezentacji 3D, np. vangle: 1, vangle: 2

vangleInc

Zmiana kąta w pionie o określoną liczbę wierszy, np. 1 lub -1

zoomMul

Powiększenie o określony współczynnik

Nie należy mieszać różnych parametrów w jednym wywołaniu.

addCallback

Dodanie wywołania zwrotnego (callback) do obsługi zdarzeń ORBITVU VIEWER.

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

Musisz podać nazwę globalnie dostępnej funkcji callback a nie sam obiekt funkcji.

Zdarzenia

activity_start

Wersja: 3.3.0+
Wyzwalane, gdy wystąpi jakakolwiek aktywność, np. gdy VIEWER jest w interakcji lub gdy wywołania API powodują pewne działania

activity_end

Wersja: 3.3.0+
Wyzwalane gdy nie jest wykonywana żadna czynność, np. gdy automatyczna rotacja jest zatrzymana

autorotate_start

Wyzwalane po rozpoczęciu autoobrotu

autorotate_stop

Wyzwalane, gdy automatyczna rotacja jest zatrzymana, np. użytkownik klika w prezentację

center_change

Wyzwalane przy zmianie centrum widoku

fullscreen_off

Wyzwalane, gdy tryb pełnoekranowy jest wyłączany

fullscreen_on

Wyzwalane, gdy przeglądarka wchodzi w tryb pełnoekranowy

interaction_start

Wersja: 2.3.27
Wyzwalane przy rozpoczęciu dowolnej interakcji użytkownika z VIEWER-em, np. kliknięcie myszy, kliknięcie przycisku, powiększenie/pomniejszenie za pomocą kółka myszy

loading

Wersja: 2.3.33
Wyzwalane, gdy ORBITVU VIEWER ładuje kolejne klatki. Przekazuje do funkcji callback wartość liczbową reprezentującą procent już załadowanych ramek.
Jeśli opcja partial_load jest ustawiona na yes, to możesz być również zainteresowany zdarzeniem partial_loading zdefiniowanym poniżej, ponieważ w tym przypadku zdarzenie ładowania będzie dotyczyło tylko 4 pierwszych załadowanych ramek

mode_changed

Wersja: 2.3.33
Wyzwalane, gdy tryb VIEWER jest zmieniany, np. z trybu obracania na tryb przeciągania
Wartości: rotate | drag | onerotation | onerotationslow

partial_loading

Wersja: 3.0.26
Wyzwalane gdy VIEWER ładuje ramki w tle (gdy partial_load jest ustawiony na tak). Przekazuje do funkcji callback wartość liczbową reprezentującą procent już załadowanych ramek

partially_initialized

Wyzwalane, gdy partial_load jest ustawione na tak i gdy pierwszy zestaw ramek został załadowany (VIEWER może być już używany przez użytkowników)

rotate

Wyzwalane podczas obrotu

set_scene

Wyzwalane po rozpoczęciu ustawiania sceny

set_scene_complete

Wyzwalane po zakończeniu ustawiania sceny

viewer_initialized

Wersja: 2.3.33
Wyzwalane, gdy wszystkie wymagane klatki są załadowane i możliwe jest manipulowanie/interakcja z VIEWER-em. Funkcja callback otrzyma obiekt API przeglądarki jako parametr.

zoom_in

zoom_out

calculate_position

Dostępne od 2.3.15

Konwertuje współrzędne x, y względem max_width (maksymalnej szerokości) i max_height (maksymalnej wysokości) prezentacji na bieżące współrzędne viewportu (skalowane).

Na przykład, jeśli max_width/max_height prezentacji to 4422px x 3073px i jest ona wyświetlana w oknie podglądu o wielkości 368px x 400px to współrzędne x: 1000 y: 500 zostaną zmienione na współrzędne względem okna podglądu w zależności od aktualnej skali i pozycji środkowej:

scale: 0.175, centerX: 2623, centerY: 1930

przekształcone:

x: -99, y: -50

Jest to przydatne, jeśli chcesz wyświetlić coś w określonej pozycji nad prezentacją.

Przykład zastosowania:

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

gdzie viewer jest obiektem zwróconym przez callback dla viewer_api_init (albo external_access_init).

Parammetry:

coords
słownik z wartościami x, y, np.: {x: 1000, y: 500}

get_presentation_info

Dostępne od 2.3.15

Zwraca słownik zawierający następujące informacje:

width - bieżąca szerokość okna podglądu
height - bieżąca wysokość okna podglądu
max_width - maksymalna szerokość prezentacji
max_height - maksymalna wysokosć prezentacji
hangles_no - liczba klatek w poziomie
vangles_no - liczba klatek w pionie
min_scale - minimalna wartość skali powiększenia
max_scale - maksymalna wartość skali powiększenia
dimensions_changed - jeśli ma wartość true, oznacza to że w danej chwili Viewer zmienia rozmiar (np. przy wejściu w tryb fullscreen). Dostępne od wersji 3.9.7

handle_resize

Ręczne powiadomienie ORBITVU VIEWER o zmianie wielkości kontenera:

viewer_api_obj.handle_resize();

Jest to wywoływane automatycznie przy zmianie rozmiaru okna, ale jeśli zamierzasz np. interaktywnie zmienić wymiary elementu kontenera VIEWER, możesz wywołać handle_resize, aby upewnić się, że ORBITVU VIEWER jest wyświetlany poprawnie.

enable_mousewheel

Włącza zoom na kółku myszy. Metoda ta przełącza parametr mousewheel na "yes"

viewer_api_obj.enable_mousewheel();

disable_mousewheel

Wyłącza zoom na kółku myszy. Metoda ta przełącza parametr mousewheel na "no"

viewer_api_obj.disable_mousewheel()

set_forced_mode

Dostępne od 2.3.33

Przełączanie na tryb drag lub rotate ORBITVU VIEWER

Wartości: drag | rotate

Previous Article Dostosowywanie kodu osadzającego ORBITTOUR - lista parametrów

Next Article ORBITTOUR API

VIEWER, ORBITTOUR, and 360° Presentations PL

Other Resources