Digitalizace pomocí API webové mapové aplikace

Doc. Dr. Vladimír Homola, Ph.D.

Anotace

Geoinformatické aplikace se opírají o jednoznačné určení místa na povrchu Země, obecně o jeho prostorové souřadnice. Operativní získání alespoň plošné složky typu [Lat,Lon] lze bez vynaložení enormních nákladů na software nebo digitalizační služby zajistit službami webových mapových serverů, poskytujících API pro budování odvozených aplikací.

Annotation

Geoinformatics applications are based on the unambiguous determination of the Earth's surface point, generally on its spatial coordinates. Operational getting of - at least [Lat, Lon] - coordinates can be offered by web mapping services of the map servers. The only requirement is, to provide an API for derived applications built.

1. Popis problému

Geo-informatické aplikace se opírají o prostorovou lokalizaci zpracovávaných dat. V současné době lze získat z mnoha zdrojů souřadnice předmětných míst, ovšem za dvou předpokladů:

Získat plošné souřadnice konkrétních míst lze však i prostředky, které nabízí stávající webové mapové aplikace. Tento postup sice neposkytuje komfort profesionálních digitalizačních programů, je však jednoduchý, rychlý a rozhodně poslouží v případě nenadálé potřeby shromáždění kvalitních geografických souřadnic.

Mapové aplikace nabízí k využití Application Programming Interface (API) - rozhraní pro programování vlastních odvozených aplikací využívající (některé) objektové třídy a jejich vlastnosti, metody a události mapové aplikace. Pro zamýšlený účel digitalizace je zapotřebí, aby API poskytovalo možnost získat souřadnici místa nejlépe "ukázáním" na něj v mapě (např. událostí Click), a aby odvozená aplikace byla schopna tyto souřadnice ve stabilním tvaru uchovat (nejlépe v souboru).

2. API aplikace MAPY.CZ

Citujme ze stránek api4.mapy.cz:

Službu Mapy API provozuje společnost Seznam.cz, a.s., se sídlem Radlická 608/2, 150 00 Praha 5, IČ: 26168685, zapsaná v obchodním rejstříku vedeném Městským soudem v Praze, oddíl B., vložka 6493. Použití Mapy API je zcela zdarma a je možné i pro komerční účely - pro většinu činností není jeho používání nijak omezeno. Použitím Mapy API se především potvrzuje souhlas s - na internetových stránkách (URL) http://www.mapy.cz/ uvedeným - SMLUVNÍM UJEDNÁNÍM PRO SLUŽBU MAPY API

Služba Mapy API umožňuje svým uživatelům používat některé funkce mapové aplikace, poskytované Společností na internetových stránkách (URL) http://www.mapy.cz/ (dále jen „funkce Služby“), i na vlastních webových stránkách Uživatelů a v rámci vlastních webových aplikací Uživatelů (dále jen "Odvozené aplikace") za dodržení smluvních ujednání.

Mezi nabízené funkce Služby patří např. zobrazování mapových podkladů a poskytování uživatelského rozhraní pro práci s těmito podklady (pohyb mapy, změna měřítka, apod.).

Konec citace.

Na uvedených stránkách je rovněž uvedena sice jednoduchá, ale většinou postačující dokumentace k podporovaným objektových třídám - některé detailnější informace je nutno získat nepříliš náročným experimentováním. Mnohé objasní i prostudování řady na stránkách zveřejněných příkladů.

Popisovaná aplikace pro digitalizaci využívá z uvedeného API tyto objektové třídy:

Použití uvedených objektových tříd může vytvořit prostředí pro digitalizaci podle následujícího obrázku:



Obr. 1: Cílové prostředí pro digitalizaci

3. Funkčnost odvozené aplikace

Výsledkem použití aplikace by měl být co nejjednodušší soubor zpracovatelný většinou navazujících programů. Tomu vyhovuje prostý textový soubor s údaji oddělenými nějakým oddělovačem, např. středníkem. Pro lepší orientaci při navazujícím zpracování se zdá, že uchovanými údaji by mohlo být pořadové číslo místa event. s nějakým popisujícím textem, a dvojice souřadnic.

Přijmeme-li za cíl prostředí podle obr. 1, pak

Datová čtveřice [číslo, popis, souřadnice-1, souřadnice-2] je pak do výstupního souboru zapsána v reakci na událost click, přičemž popis převezme z obsahu textového pole aktuálního v okamžiku události. Tento zápis do souboru může proběhnout pokaždé posloupností činností: otevření na pokračování - zápis - uzavření souboru. Vzhledem k pomalosti práce uživatele to nepředstavuje zdržení, naopak při náhodné havárii systému jsou k disposici v uzavřeném souboru doposud digitalizovaná data.

4. Forma a struktura odvozené aplikace

Formou odvozené aplikace pro digitalizaci je soubor ve zcela běžném formátu HTML obsahující sekce skriptů.

Struktura tohoto souboru může být následující:

       <html>
       
          <head>
             ...
             <script>
             </script>
          </head>
          
          <body>
             ...
             <div>
             </div>
             <script>
             </script>
          </body>
          
       </html>

5. Popis odvozené aplikace

5.1. Záhlaví dokumentu

Záhlaví dokumentu je klasické, kromě běžných konstrukcí obsahuje dva tagy <script> zpřístupňující knihovnu API a na globální úrovni popisy proměnných a funkcí. Může být následující:

      <head>
         <meta http-equiv="Content-Type" content="text/html; charset=windows-1250">
         <meta http-equiv="Content-Language" content="cs">
         <meta name="Author" content="Vladimír Homola + MAPY.CZ">
         <meta name="Description" content="Digitalizace pomocí API webové mapové aplikace">
         <meta name="Keywords" content="Digitalizace, Programování, API, BasicScript, JavaScript">

         <title>Digitalizace pomocí api4.mapy.cz</title>
      
         <script type="text/javascript" src="http://api4.mapy.cz/loader.js"></script>
         <script type="text/javascript">Loader.load();</script>
         
         <style> ...(*)... </style>
               
       </head>

Případně uvedené styly označené (*) mohou být použity pro formátování odstavců těla dokumentu.

5.2. Tělo dokumentu

I tělo dokumentu je klasické. V jeho úvodním tagu je volána akce pro inicializaci globálních dat stránky, první a jediný odstavec obsahuje textové pole pro vložení popisu následně digitalizovaného místa. Pro procvičení je vloženo tlačítko pro výmaz tohoto textového pole. Pak následuje oddíl, jehož id je důležitý pro odkaz na místo vložení mapy mapovou aplikací. Tělo může mít následující strukturu:

      <body id="Digitalizace">

         <p>
            Popis následně digitalizovaného místa:
            <input type="text" id="txPopis" size="50">     
            <input type="button" id="tlSmazPopis" value="Vymaž popis" onclick="SmazPopis()">
         </p>
 
      <div id="PodkladMapa"></div>
  
      <script (**)> </script>
        
   </body>

Skripty označené (**) jsou spolu s komentáři obsahem níže uvedeného samostatné kapitoly 6.

6. Použité skripty

6.1. Proměnné a objekty na globální úrovni

V úvodní části jsou deklarovány "konstanty" použité např. při zpracování výstupního souboru. Rovněž je napevno uvedena úplná cesta k němu. Pro jednoduchost není výstupní soubor zadáván dynamicky, jádro článku je jinde. Úvodní část rovněž deklaruje globální proměnné.

Identifikátory se autor snažil volit tak, aby text skriptu byl pokud možno samodokumentující.

      <script language="jscript">
   
      /* Globální "konstanty" */

      var cJmenoVystupu = "C:\HOMDGTZE.TXT";
      
      var cUvoz = "\"";
      
      var ForReading = 1;
      var ForWriting = 2;
      var ForAppending = 8;
      var OverwriteFile = true;

      var TristateUseDefault = -2
      var TristateTrue = -1;                  /* Unicode */
      var TristateFalse = 0;                  /* ASCII */
      var TristateMixed = -2;


      /* Globální proměnné */

      var StredZobrazení;
      var MapaW;
      var OvladaniMysi;
      var SynchroMapySoknem;
      var VrstvaZnacek;
      var VrstvaVolbyTypu;
      
      var PredanyText ;                       /* Globální předávání textů */
      var CisloBodu ;                         /* Globálně dostupné číslo posledního bodu */
         
         
      InitGlobalVars();                       /* Volání inicializační funkce */

Dále jsou uvedeny pomocné funkce. Z nich funkce InitGlobalVars nejdříve vytvoří prázdný výstupní textový soubor (postupně bude otevírán pro pokračování v zápisu). Déle realizuje propojení s API mapové aplikace: naplní inicializační střed mapy (lze změnit na jakýkoliv oblíbený v rámci ČR), definuje chování myši, vloží vrstvu pro značky a ovládací prvky pro volbu typu zobrazeného mapového podkladu. Vytvoří novou instanci výstupu mapové aplikace a propojí ji s oddílem definovaným v těle dokumentu (metoda Get Element knihovny JAK). Umožní používat všechny tři základní vrstvy pro zobrazení mapy, aktuální učiní základní mapové zobrazení. Na závěr přidá požadované ovládání.


      /* Inicializace globálních proměnných */
      function InitGlobalVars() 
      {
         var FSO = new ActiveXObject("Scripting.FileSystemObject");
         var TXS = FSO.CreateTextFile(cJmenoVystupu, OverwriteFile);
         TXS.Close();
         
         StredZobrazení = SMap.Coords.fromWGS84(14.400307, 50.071853);
         MapaW = new SMap(JAK.gel("PodkladMapa"), StredZobrazení, 8);

         OvladaniMysi = new SMap.Control.Mouse(SMap.MOUSE_PAN | SMap.MOUSE_WHEEL | SMap.MOUSE_ZOOM);
         SynchroMapySoknem = new SMap.Control.Sync({ bottomSpace: 15 });
         VrstvaZnacek = new SMap.Layer.Marker();
         VrstvaVolbyTypu = new SMap.Control.Layer();

         MapaW.addDefaultLayer(SMap.DEF_BASE).enable();
         MapaW.addDefaultLayer(SMap.DEF_OPHOTO);
         MapaW.addDefaultLayer(SMap.DEF_TURIST);

         MapaW.addDefaultControls();
         MapaW.addDefaultContextMenu();
         MapaW.addControl(OvladaniMysi);
         MapaW.addControl(SynchroMapySoknem);
         MapaW.addLayer(VrstvaZnacek);

         VrstvaZnacek.enable();

         VrstvaVolbyTypu.addDefaultLayer(SMap.DEF_BASE);
         VrstvaVolbyTypu.addDefaultLayer(SMap.DEF_OPHOTO);
         VrstvaVolbyTypu.addDefaultLayer(SMap.DEF_TURIST);

         MapaW.addControl(VrstvaVolbyTypu, { left: "0px", top: "0px" });
         
         PredanyText = "";
         CisloBodu = 0;
      }


      function DotazNaPopis()
         {
            PredanyText = txPopis.value;
         } 
       
   
       
      function SmazPopis()
         {
            txPopis.value = "";
         }
  


      /* Výstup do textového souboru */
      function ZapisDoSouboru(X, Y)
      {
         var FSO = new ActiveXObject("Scripting.FileSystemObject");
         var FLE = FSO.GetFile(cJmenoVystupu);
         var TXS = FLE.OpenAsTextStream(ForAppending,TristateUseDefault);
         var TXT = "";
         TXT = TXT +cUvoz + PredanyText + cUvoz + "; ";
         TXT = CisloBodu + "; " + TXT;
         TXT = TXT + Y + "; "
         TXT = TXT + X;
         TXS.WriteLine(TXT);
         TXS.Close();
      }

6.2. Skripty pracující s API

Stěžejní je funkce nazvaná ClickDoMapy volaná pro zpracování události map-click. V ní se zjistí souřadnice ve WGS84, vytvoří se nová značka a přidá do vrstvy značek, a volá se podprogram pro výstup do souboru.

     
      /* Po kliknutí do mapy ... */  
      function ClickDoMapy(Udalost, Prvek) 
         {
            var SouradniceClicku = SMap.Coords.fromEvent(Udalost.data.event, MapaW);
            var SouradniceWGS = SouradniceClicku.toWGS84();
            var VolbyObrazku = {src:SMap.CONFIG.img+"/marker/drop-blue.png"}
            var VolbyPopisku = {position:"absolute", left:"0px", top:"2px", textAlign:"center", width:"22px", color:"white"}

            var DivZnacky = JAK.mel("div")
            var VolbyZnacky = {url:DivZnacky};
            var DivPopisku = JAK.mel("div", {}, VolbyPopisku);
            var Obrazek = JAK.mel("img", VolbyObrazku);
            var Znacka = new SMap.Marker(SouradniceClicku, null, VolbyZnacky);

            DotazNaPopis();

            CisloBodu = CisloBodu + 1;
            DivPopisku.innerHTML = CisloBodu;
            DivZnacky.appendChild(Obrazek);
            DivZnacky.appendChild(DivPopisku);
            VrstvaZnacek.addMarker(Znacka);

            ZapisDoSouboru(SouradniceWGS[0], SouradniceWGS[1])
          }
      

      MapaW.getSignals().addListener(window, "map-click", ClickDoMapy);   

   
      </script>

7. Spuštění aplikace

Poznámka: následující obrazové ukázky jsou generovány aplikací Internet Explorer. Jiné prohlížeče lze použít jen tehdy, pokud podporují užití ActiveX prvků.

Po zavedení stránky je prohlížečem rozpoznáno, že obsahuje jednak skripty, jednak používá ActiveX prvky. Při běžném nastavení ochrany je proto nejprve zobrazeno upozornění typu

 


Obr. 2: Varovné hlášení při otevírání stránky

Při Volbě dalších možností je pro jistotu zobrazen ještě jednou dotaz typu

 


Obr. 3: Potvrzení spuštění ActiveX prvků

případně Windows 7 a Internet Explorer 9 kombinují oba dotazy do jediného, lehce přehlédnutelného dotazového formuláře (který se navíc po jisté době nečinnosti sám zavře)

 


Obr. 4: Potvrzení spuštění ActiveX prvků ve Windows 7 / iExplorer 9

Podle nastavení zabezpečení prohlížeče je po zavedení stránky s mapovým podkladem zobrazena poslední výstraha - např. aplikací Internet Explorer následující

 


Obr. 5: Potvrzení spuštění ActiveX prvků

Poté je inicializovaná stránka zobrazena v počátečními parametry (viz var StredMapy v odst. 6.1):

 


Obr. 6: Počáteční mapové zobrazení

Postupným klikáním do mapy s event. předvyplněním textového pole pro popis místa vzniká stránka analogická následující:

 


Obr. 7: Mapové zobrazení v průběhu digitalizace

Tím, že ve skriptu z odst. 6.1. byla přidána vrstva s ovládacími prvky pro volbu typu mapového zobrazení, je umožněn výběr podle obr. 8:

 


Obr. 8: Volba zobrazení vrstev

Tím, že ve skriptu z odst. 6.1. byly přidány implicitní ovládací prvky je umožněn pohyb resp. změna měřítka podle obr. 9:

 


Obr. 9: Ovládací prvky pro posun a změnu měřítka

8. Výsledná data

Data ve formě uspořádaných čtveřic [číslo, popis, souřadnice-1, souřadnice-2] jsou ukládána do textového souboru. Jeho příklad podle obr. 7 je následující:

     
        1;"Evropská x Kanadská"; 50,0997299216368; 14,3787898168837
       2;"Thrákurova x Technická"; 50,1038515923322; 14,3894200549719
       3;"Kulaťák střed"; 50,1006449968383; 14,3953895039288
       4;"Železniční přejezd u žst. Praha-Dejvice"; 50,0981891187213; 14,4075008952603

přičemž volba pořadí souřadnic je dána pořadím aktuálních parametrů při volání podprogramu VystupDoSouboru - viz také odst. 6.1.

Tato data lze přímo do aktivního listu importovat aplikací Excel tak, že vznikne oblast např.

 


Obr. 10: Importovaná digitalizovaná data

a to buď "ručně" pomocí nabídek prostředí aplikace Excel, nebo automatizovaně voláním podprogramu analogickému níže uvedenému ImportDigitDat:

   
Sub ImportDigitDat(qJmenoSouboru As String, qAdresaCile As String, qJmenoDotazu As String)

   ' Zavedení dat generovaných digitalizací pomocí API na MAPY.CZ

   Dim wb As Excel.Workbook
   Dim ws As Excel.Worksheet
   Dim qt As Excel.QueryTable
   Dim cn As String
   
   cn = "TEXT;" + qJmenoSouboru
   
   Set wb = ThisWorkbook
   Set ws = wb.ActiveSheet
   Set qt = ws.QueryTables.Add(cn, ws.Range(qAdresaCile))
   
   With qt
      .Name = qJmenoDotazu
      .FieldNames = True
      .RowNumbers = False
      .FillAdjacentFormulas = False
      .PreserveFormatting = True
      .RefreshOnFileOpen = False
      .RefreshStyle = xlInsertDeleteCells
      .SavePassword = False
      .SaveData = True
      .AdjustColumnWidth = True
      .RefreshPeriod = 0
      .TextFilePromptOnRefresh = False
      .TextFilePlatform = 1250
      .TextFileStartRow = 1
      .TextFileParseType = xlDelimited
      .TextFileTextQualifier = xlTextQualifierDoubleQuote
      .TextFileConsecutiveDelimiter = False
      .TextFileTabDelimiter = False
      .TextFileSemicolonDelimiter = True
      .TextFileCommaDelimiter = False
      .TextFileSpaceDelimiter = False
      .TextFileColumnDataTypes = Array(1, 2, 1, 1)
      .TextFileTrailingMinusNumbers = True
      .Refresh BackgroundQuery:=False
   End With
       
End Sub

9. Ke stažení

Shora popsanou stránku HTM spolu se sešitem obsahujícím importovaná data lze stáhnout z adresy uvedené zde. Po stažení a rozbalení lze HTM přímo použít pouze tehdy, má-li uživatel oprávnění k vytváření a rušení souborů v root adresáři disku C. Pokud ne, musí změnit v úvodu skriptu 6.1. úplné označení výsledného souboru na takové umístění, ke kterému práva má.

Sešit obsahující importovaná data - ale hlavně příslušné makro - lze použít  pouze tehdy, má-li uživatel oprávnění k vytváření a rušení souborů v root adresáři disku C. Pokud ne, musí v sešitu změnit v úvodu modulu Programy úplné označení výsledného souboru na takové umístění, ke kterému práva má.

 

 

Rev. 06 / 2016