JS Panorama

Panorama na Mapy.cz je funkce podobná Street View, která vám umožní procházet většinu ulic v ČR a rozhlížet se do všech směrů.

Pro vývojáře jsou k dispozici aktuálně dva způsoby, jak Panoramu využít:

JS Panorama – (té se věnuje tato kapitola) JavaScriptová komponenta, která poskytne vašim uživatelům podobný zážitek jako na Mapy.cz. Umožňuje volné rozhlížení a pohyb v panoramatickém zobrazení přímo ve vaší aplikaci.
Statická panorama – REST API, které vrací statický obrázek pohledu na zvolené místo. Stačí jej vložit například pomocí <img src="...">, přičemž v parametrech určíte polohu a směr pohledu. Obrázek je pevný a nelze s ním dále otáčet. Více se dočtete v kapitole API pro Statickou panoramu.

Komponenta JS Panorama

JavaScriptová komponenta pro zobrazení panoramatických snímků z celé České republiky.

Tato „panorama prohlížečka“ zařídí zobrazení sférických snímků ve vašich webových stránkách a umožní uživatelům se rozhlížet kolem dokola či se přesouvat na vedlejší snímky.

Komponenta se sama stará o načítání potřebných dat prostřednictvím REST API.

Pro konkrétní ukázky se podívejte na Panorama tutoriály.

Poslední snímkování Panoramy na Mapy.cz probíhalo v letech 2021–2023, kdy byla postupně aktualizována celá Česká republika. Každý rok byla snímkována přibližně třetina území, a současně probíhalo každoročně opakované snímkování 21 vybraných měst, včetně Prahy, Brna a Ostravy.

Ovládání panoramy

Uživatel se může v panoramě rozhlížet pomocí myši, případně na klávesnice (šipky vlevo vpravo či „a“ „d“).

V případě povolení přesunu mezi snímky (showNavigation:true) může přechod probíhat opět pomocí myši (klikáním na navigační šipky či místa dalších snímků) či na klávesnici (šipky dopředu dozadu či „w“ „s“)

Spotřeba panoramy

Panorama (jedna sféra) se nestahuje jako jedna velká fotka, ale skládá se z jednotlivých panorama dlaždic. Obvyklý rozměr celé panoramy je 16×8 dlaždic.

JS prohlížečka se sama stará o stažení potřebných dlaždice. Nestahuje celou sféru, ale jen ty dlaždice, které padnou do zobrazeného pohledu.

Spotřeba panoramy (v dlaždicích) se pak účtuje dle ceníku REST API.

Použití knihovny

Pro využití panoramy je potřeba přidat do hlavičky tento skript.

<script type="text/javascript" src='https://api.mapy.cz/js/panorama/v1/panorama.js'></script>

Díky němu máte k dispozici třídu Panorama, která zpřístupňuje jedinou funkci panoramaFromPosition().

funkce panoramaFromPosition()

Funkce pro zobrazení panoramy na určitých souřadnicích. Hledá nejbližší panoramu k zadaným souřadnicím v daném poloměru.

Vstupní parametry

parent	rodičovský html element pro připnutí panoramy
lon, lat	souřadnice, v jejich okolí se vyhledává nejbližší panorama, až do určeného poloměru (viz parametr radius)
apiKey	API klíč pro REST API
Nepovinné parametry
radius	Maximální poloměr pro hledání panoramy. V metrech. výchozí hodnota: 50 m
yaw	Natočení vzhledem k severu možné hodnoty: „auto“ – výchozí hodnota, natočení po směru focení „point“ – natočení směrem na vstupní souřadnice číslo- 0 – 2 * Math.PI (0 – sever)
pitch	sklopení ( – nahoru, + dolů) možné hodnoty: +-Math.PI výchozí hodnota 0
fov	horizontální šířka zorného pole (vlatně přiblížení) možné hodnoty: Math.PI / 2 – Math.PI/20 výchozí hodnota 1.2
showNavigation	true/false – zapne nebo vypne možnost přesunu na vedlejší snímky výchozí hodnota: false
lang	jazyk (používá se pro tooltipy, chybové hlášeky atd…) možné hodnoty: cs, de, el, en, es, fr, it, nl, pl, pt, ru, sk, tr, uk výchozí hodnota: cs

Návratové hodnoty

Funkce vrací objekt IOutput, který obsahuje tyto klíče

Informace o panoramě
info.lon, info.lat	Informace o skutečné poloze foceného místa
info.date	Datum pořízení snímku ve formátu YYYY-MM-DD hh:mm:ss
Informace o stavu
errorCode	„NONE“ \| „PANORAMA_NOT_FOUND“ \| „MISSING_API_KEY“
error	popis chyby
Funkce
funkce destroy	funkce, která panoramu odstraní
funkce addListener, removeListerner	sledování událostí pro otočení „pano-view“ a posun „pano-place“ panoramy (viz ukázka)
funkce setCamera, getCamera	funkce umožňují nastavit/přečíst aktuální pohled panoramy

Ukázka rozhraní panoramaFromPosition()


    interface ICreatePanoFromPositionOpts {
        /** Parent element */
        parent: HTMLElement;
        /** Wgs84 longitude coordinate */
        lon: number;
        /** Wgs84 latitude coordinate  */
        lat: number;
        /** API key */
        apiKey: string;
        /** Default pano view - yaw - "auto", "point" - direction to point, number - custom value <0;2 * Math.PI> [rad] */
        yaw?: "auto" | "point" | number;
        /** Default pano view - pitch */
        pitch?: number;
        /** Horizontal field of view */
        fov?: number;
        /** Search area radius [m] */
        radius?: number;
        /** Supported langs: cs, de, el, en, es, fr, it, nl, pl, pt, ru, sk, tr, uk */
        lang?: TLANGS;
        /** Show navigations - neighbors, click mask */
        showNavigation?: boolean;
        /** Hide errors output */
        hideErrors?: boolean;
        /** Resize timeout - 0 to disable, default 100 [ms] */
        resizeTimeout: 100,
    }
     
    interface ICreatePanoFromPositionOutput {
        /** Panorama meta information */
        info?: {
            /** Pano wgs84 longitude coordinate */
            lon: number;
            /** Pano wgs84 latitude coordinate */
            lat: number;
            /** Create date YYYY-MM-DD hh:mm:ss*/
            date: string;
        };
        /** Error message */
        error: string;
        /** Error code */
        errorCode: "NONE" | "PANORAMA_NOT_FOUND" | "MISSING_API_KEY" | "WRONG_API_KEY";
        /** Add listener */
        addListener: (name: T, callback: (data: IEvent[T]) => void) => void;
        /** Remove listener */
        removeListener: (name: T, callback: (data: IEvent[T]) => void) => void;
        /** Get panorama camera */
        getCamera: () => ICamera;
        /** Set panorama camera */
        setCamera: (camera: ICamera) => void;
        /** Destroy panorama */
        destroy: () => void;
    }
    interface ICamera {
        yaw: number;
        pitch: number;
        fov: number;
    }

Možnost sledování otáčení a posunů

Je možné napojit se na události, které se volají při změně natočení či při posunu na vedlejší panoramu.

Ukázka napojení událostí panoramaFromPosition()

// add listener - pano view change panoData.addListener("pano-view", viewData => console.log(["view data", viewData])); // add listener - pano change place panoData.addListener("pano-place", placeData => console.log(["place data", placeData]));

Funkce panoramaExists()

Funkce ověří, že je na daném místě panorama vůbec k dispozici. Vstupní parametry i návratové hodnoty má podobné, jako funkce panoramaFromPosition() .

Ukázka rozhraní panoramaExists()


  interface IPanoramaExistsOpts {
        /** Wgs84 longitude coordinate */
        lon: number;
        /** Wgs84 latitude coordinate  */
        lat: number;
        /** API key */
        apiKey: string;
        /** Search area radius [m] */
        radius?: number;
    }

    interface IPanoramaExistsOutput {
        /** Panorama meta information */
        info?: {
            /** Pano wgs84 longitude coordinate */
            lon: number;
            /** Pano wgs84 latitude coordinate */
            lat: number;
            /** Create date YYYY-MM-DD hh:mm:ss*/
            date: string;
        };
        /** Panorama exists? */
        exists: boolean;
    }