ORBITVU VIEWER API

API JavaScript ORBITVU VIEWER: metody, zdarzenia i sterowanie VIEWER-em z poziomu własnych kontrolek.

W wersjach Infinity360 i FREE ORBITVU VIEWER można sterować programowo, za pomocą JavaScript.

Aby uzyskać dostęp do obiektu API ORBITVU VIEWER, wykonaj następujące kroki:

zdefiniuj globalną funkcję zwrotną (JavaScript)
ustaw 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żna też użyć parametru external_access_init, ale jest on przestarzały od wersji VIEWER 2.3.33 na rzecz viewer_api_init. Przykładowy kod dla 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) {
                 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 widoku (w pikselach, względem maksymalnej rozdzielczości prezentacji)
centery – aktualna współrzędna Y środka widoku (w pikselach, względem maksymalnej rozdzielczości prezentacji)
centerX – to samo co centerx
centerY – to samo co centery
hangle – numer aktualnie wyświetlanej klatki poziomej
vangle – numer aktualnie wyświetlanej klatki pionowej

setScene

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

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

Parametry

autorotate

Uruchamia/zatrzymuje automatyczny obrót Wartości: yes | no Domyślnie: no

autorotate_dir

Kierunek automatycznego obrotu Wartości: left | right

fullscreen

Umożliwia przełączenie VIEWER-a w tryb fullscreen i definiuje metody pomocnicze do obsługi tego przełączania

Wersja: 3.6.7+

Wartości:

toggle Przełącza VIEWER do/z trybu fullscreen
pre Nakazuje VIEWER-owi zapamiętać bieżące wymiary, np. gdy VIEWER ma wymuszone width i height. Tę metodę należy wywołać np. wtedy, gdy element nadrzędny VIEWER-a ma zostać przełączony w tryb fullscreen — przed tym przełączeniem. Po włączeniu fullscreen dla elementu nadrzędnego należy wywołać metodę enter, aby zaktualizować wymiary VIEWER-a. Przy anulowaniu fullscreen trzeba wywołać metodę cancel.
enter Aktualizuje wymiary VIEWER-a, usuwając wszelkie wymuszone rozmiary, np. width i height — VIEWER dopasuje rozmiar do elementu kontenera (o ile ma on zdefiniowane jakieś wymiary). Można wywołać np. gdy element nadrzędny VIEWER-a jest przełączany w tryb fullscreen, a VIEWER również powinien zmienić rozmiar.
cancel Przywraca wymiary VIEWER-a zapamiętane metodą pre. Można wywołać np. po wyjściu z trybu fullscreen dla elementu nadrzędnego VIEWER-a.

hangle

Obrót do klatki poziomej Wartości: 0 – <liczba klatek> Przykład: viewer_api_obj.setScene({hangle: 10});

hangleInc

Zmienia kąt poziomy o podaną liczbę klatek, np. 2 lub -2

mode

Tryb, w którym pracuje ORBITVU VIEWER Wartości: rotate | drag | onerotation | onerotationslow Domyślnie: rotate

panX

Przesuwa bieżący widok wzdłuż osi poziomej, np.: 100 (przesunięcie o 100px w prawo), -10% (przesunięcie o 10% bieżącego widoku w lewo), -30px (przesunięcie o 30px w lewo).

panY

Przesuwa bieżący widok wzdłuż osi pionowej, np.: 100 (przesunięcie o 100px w dół), -10% (przesunięcie o 10% bieżącego widoku w górę), -30px (przesunięcie o 30px w górę).

reset_position

Natychmiast przywraca pozycję początkową prezentacji (z użyciem wartości początkowych first_frame, first_row i scale).

Wersja: 3.9.0+

Wartości: yes|no

Dodatkowe parametry: vangle, hangle, scale — wymuszają konkretną wartość parametru: vangle – wiersz, hangle – klatka pozioma, scale – poziom zoomu

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

vangleInc

Zmienia kąt pionowy o podaną liczbę wierszy, np. 1 lub -1

zoomMul

Zmienia zoom o podany współczynnik

Nie należy łączyć różnych parametrów w jednym wywołaniu

addCallback

Dodaje callback obsługujący zdarzenia ORBITVU VIEWER:

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

W embed code pierwszym argumentem jest nazwa globalnie dostępnej funkcji. Wywołując API z własnego kodu JavaScript, możesz zamiast tego przekazać samą funkcję — czego potrzebujesz wewnątrz modułu, gdzie nazwa globalna do niej nie sięgnie. Zobacz Używanie ORBITVU VIEWER jako ES module.

Zdarzenia

activity_start

Wersja: 3.3.0+ Wyzwalane, gdy wystąpi jakakolwiek aktywność, np. gdy użytkownik wchodzi w interakcję z VIEWER-em lub gdy wywołania API powodują jakieś działania

activity_end

Wersja: 3.3.0+ Wyzwalane, gdy w VIEWER-ze nie dzieje się nic, np. gdy automatyczny obrót został zatrzymany

autorotate_start

Wyzwalane po uruchomieniu automatycznego obrotu

autorotate_stop

Wyzwalane po zatrzymaniu automatycznego obrotu, np. gdy użytkownik kliknie prezentację

center_change

Wyzwalane przy zmianie środka widoku

fullscreen_off

Wyzwalane przy wyjściu z trybu fullscreen

fullscreen_on

Wyzwalane, gdy VIEWER wchodzi w tryb fullscreen

interaction_start

Wersja: 2.3.27 Wyzwalane przy każdej interakcji użytkownika z VIEWER-em, np. kliknięcie myszą, kliknięcie przycisku, zoom kółkiem myszy

loading

Wersja: 2.3.33 Wyzwalane, gdy ORBITVU VIEWER ładuje klatki. Do callbacku przekazywana jest wartość liczbowa oznaczająca procent już załadowanych klatek. Gdy partial_load jest ustawiony na yes, może Cię również zainteresować zdarzenie partial_loading opisane poniżej — w tym przypadku zdarzenie loading dotyczy bowiem tylko 4 pierwszych załadowanych klatek.

mode_changed

Wersja: 2.3.33 Wyzwalane przy zmianie trybu VIEWER-a, np. z rotate na drag Wartości: rotate | drag | onerotation | onerotationslow

partial_loading

Wersja: 3.0.26 Wyzwalane, gdy VIEWER ładuje klatki w tle (gdy partial_load jest ustawiony na yes). Do callbacku przekazywana jest wartość liczbowa oznaczająca procent już załadowanych klatek.

partially_initialized

Wyzwalane, gdy partial_load jest ustawiony na yes i gdy pierwszy zestaw 4 klatek został załadowany (VIEWER może już reagować na użytkownika).

rotate

Wyzwalane podczas obracania

set_scene

Wyzwalane w momencie rozpoczęcia 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żna sterować VIEWER-em oraz wchodzić z nim w interakcję. Callback otrzyma obiekt API VIEWER-a jako parametr.

zoom_in

zoom_out

calculate_position

Dostępne od wersji 2.3.15

Przelicza współrzędne x, y podane względem max_width i max_height prezentacji na bieżące współrzędne widoku (przeskalowane).

Na przykład, jeśli max_width/max_height prezentacji wynosi 4422px x 3073px, a jest ona wyświetlana w widoku o rozmiarze 368px x 400px, to współrzędne x: 1000 y: 500 zostaną przeliczone na współrzędne względem widoku, zależnie od bieżącej skali i pozycji środka:

scale: 0,175, centerX: 2623, centerY: 1930

po przeliczeniu:

x: -99, y: -50

Przydaje się, gdy chcesz wyświetlić coś w określonym miejscu nad prezentacją.

Przykład użycia:

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

gdzie viewer to obiekt zwrócony przez callback viewer_api_init (lub external_access_init).

Parametry:

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

get_presentation_info

Dostępne od wersji 2.3.15

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

width – bieżąca szerokość widoku
height – bieżąca wysokość widoku
max_width – maksymalna szerokość prezentacji
max_height – maksymalna wysokość prezentacji
hangles_no – liczba klatek poziomych
vangles_no – liczba klatek pionowych
min_scale – minimalna wartość skali zoomu
max_scale – maksymalna wartość skali zoomu
dimensions_changed – wartość true oznacza, że VIEWER zmienia swoje wymiary, np. przy wchodzeniu w tryb fullscreen

handle_resize

Ręcznie informuje ORBITVU VIEWER, że rozmiar jego kontenera się zmienił:

viewer_api_obj.handle_resize();

Metoda jest wywoływana automatycznie przy zmianie rozmiaru okna, ale jeśli zamierzasz np. interaktywnie zmieniać wymiary elementu kontenera VIEWER-a, możesz wywołać handle_resize, aby mieć pewność, że ORBITVU VIEWER wyświetla się prawidłowo.

Wartości: drag | rotate

Na tej stronie