Maps in LaTeX Documents - an Introduction of the getmap Package

Zpravodaj Československého sdružení uživatelů TeXu Aleš Kozubík Mapy v LaTeXových dokumentoch – predstavenie balíčka getmap Zpravodaj Československého sdružení uživatelů TeXu, Vol. 27 (2017), No. 1-2, 101–109 Persistent URL: http://dml.cz/dmlcz/150274 Terms of use: © Československé sdružení uživatelů TeXu, 2017 Institute of Mathematics of the Czech Academy of Sciences provides access to digitized documents strictly for personal use. Each copy of any part of this document must contain these Terms of use. This document has been digitized, optimized for electronic delivery and stamped with digital signature within the project DML-CZ: The Czech Digital Mathematics Library http://dml.cz Mapy v LATEXových dokumentoch – predstavenie balíčka getmap Aleš Kozubík Cieľom príspevku je predstavenie balíčka getmap. Tento balíček umožňuje do LATEXových dokumentov zaradiť mapové materiály získané z externých zdrojov, ako sú OpenStreetMap alebo Google Maps a to aj s podporou Google Street View. V najjednoduchšom prípade pritom postačí aj špecifikácia požadovanej adresy. Balíček pre sťahovanie máp používa externý Lua skript, ktorý si vyžaduje aktiváciu funkcie \write18. Tento skript môže byť použitý aj samostatne z príkazového riadku. Kľúčové slová: Mapy, LATEX, getmap, Lua Úvod Poznáme to všetci – občas treba do dokumentu zaradiť obrázky, ktorých obsahom je mapa určitej oblasti alebo lokality, prípadne aj s vyznačením trasy. Niekto sa s týmto problémom stretáva častejšie (ak sa napríklad venuje geografii alebo pripravuje materiály pre cestovateľov), iný zriedkavejšie, napríklad pri príprave pozvánok a pokynov pre konferencie. Ale určite sa s touto úlohou stretol každý. My si v tomto príspevku predstavíme užitočný balíček getmap, ktorý umožňuje priamo do LATEXového dokumentu zakomponovať obrázky z takých zdrojov, ako sú OpenStreetMap alebo Google Maps včítane vkladania obrázkov z Google Street View. Podstata činnosti balíčka getmap, ktorého autorom je Josef Kleber, je pomerne jednoduchá. Balíček vlastne obsahuje jeden jediný príkaz \getmap, ktorý prostredníctvom jednoduchého Lua skriptu zabezpečí stiahnutie požadovaného obrázku, teda mapy alebo fotografie z Google Street View, do špecifikovaného grafického súboru. Takto získaný súbor potom vložíme do LATEXového dokumentu pomocou \includegraphics. Zložitejšie ako samotný príkaz sú teda jeho voliteľné argumenty, ktoré špecifikujú požadovaný obrázok. V článku sa teda budeme venovať týmto voliteľným položkám. Na správnu činnosť príkazu \getmap je potrebné aktivovať funkciu \write18, čo pri použití TEXLive znamená kompilovanie s prepínačom --shell-escape resp. pri použití MiKTeXu --enable-write18. Nakoľko mapy vkladáme do textu ako obrázky, je taktiež potrebné načítať balíček graphicx. doi: 10.5300/2017-1-2/101 101 Obrázok 1: Ukážka výstupu získaného pomocou \getmap. Zobrazená je náhodne vybraná adresa v centre mesta Žilina Príkaz \getmap Ako sme už spomenuli, balíček getmap obsahuje de facto jediný príkaz, ktorého plná syntax má tvar: \getmap[voľby]{adresa} V najjednoduchšom prípade stačí poznať len adresu, POI alebo geografické GPS súradnice zvoleného miesta. Položka adresa musí byť plne rozvinutá a nesmie obsahovať žiadne makrá. Získaný obrázok sa implicitne ukladá do súboru s názvom getmap.png, ktorý sa je uložený v aktuálnom pracovnom adresári. V prípade, že do nášho dokumentu vkladáme len jednu mapu je tento mechanizmus plne postačujúci. Príslušný zdrojový kód by teda mohol vyzerať napríklad takto: \getmap{Národná 25, 01001 Žilina, Slovakia} \includegraphics[width=.5\linewidth]{getmap} s výsledkom zobrazeným na obrázku 1. Pri opätovnej kompilácii súboru je potrebné si uvedomiť, že nedochádza ku prepisovaniu získaného obrázku getmap.png. To síce urýchľuje kompiláciu, na druhú stranu, ak dôjde ku zmene v zobrazovanej adrese, to má za následok, že obrázok v dokumente sa vlastne nezmení. To je možné riešiť buď odstránením súboru getmap.png z pracovného adresára pred novou kompiláciou, alebo vhodnou voľbou pre prepisovanie súborov, o ktorej budeme hovoriť neskôr. Voľby príkazu \getmap Činnosť príkazu \getmap podstatným spôsobom ovplyvňujú voliteľné argumenty. Dokonca je možné povedať, že sú dôležitejšie než samotný príkaz. My si predsta102 Obrázok 2: Ukážka výstupu na obrázku 1 získaného z Google Maps pomocou voľby mode=gm. Zobrazená je rovnaká adresa v centre mesta Žilina víme iba tie najdôležitejšie, resp. najpoužívanejšie z nich, úplný zoznam je možné nájsť v manuáli [3]. Voľba mode Voliteľný argument mode môže nadobúdať jednu z troch hodnôt osm|gm|gsv a určuje, ktorý mapový zdroj bude použitý. Z hodnoty argumentu je intuitívne zrejmé, ktorý zodpovedá OpenStreetMap, Google Maps alebo Google Street View. Ako implicitný zdroj je preddefinovaný OpenStreetMap. Ak by sme teda chceli výsledok na obrázku 1 získať pomocou Google Maps, je potrebné príkaz upraviť takto: \getmap[mode=gm]{Národná 25, 01001 Žilina, Slovakia} Výsledok si môžeme pozrieť na obrázku 2 . Voľby file a imagetype Voľba file=subor umožňuje pomenovať výstupný súbor, ktorý bude vytvorený príkazom \getmap. Názov súboru sa uvádza bez prípony. Na stanovenie grafického formátu získaného výstupu sa potom používa voľba imagetype, ktorá môže nadobúdať niektorú z hodnôt png|jpeg|jpg|gif, pričom ako implicitný typ je súbor vo formáte png. Táto voľba už je ale viazaná na použitý mód, pričom uvedené hodnoty sú dostupné pre mode=osm. Pri použití módu gm sú dostupné ešte ďalšie grafické formáty, ako napríklad png8|png32. Ak si teda uvedomíme, že pri spracovaní obrázku 1 bol použitý implicitný názov súboru getmap, je zrejmé, že súbor vložený do obrázku 2 je potrebné aj premenovať. Úplný zdrojový kód pre výstup na obrázku 2 teda vyzerá takto: \getmap[mode=gm,file=myobr]{Národná 25, 01001 Žilina, Slovakia} 103 Obrázok 3: Ukážka výstupu rovnakej oblasti ako na obrázku 1, získaného z Google Maps pomocou voľby type=satellite. Zobrazená je rovnaká adresa v centre mesta Žilina Voľba type Voľba type môže v móde osm nadobúdať niektorú z troch hodnôt map|sat|hyb pre zobrazenie mapy, satelitnej snímky alebo hybridné zobrazenie mapy a satelitnej snímky. Pri nastavení módu na hodnotu gm sa možné hodnoty voliteľného argumentu type menia na roadmap|satellite|hybrid|terrain. Na obrázku 3 ilustrujeme satelitný záber rovnakého výrezu centra mesta ako na mapách na obrázkoch 1 a 2. Voľba overwrite Ide o dôležitý voliteľný argument, ktorý určuje, či sa pri jednotlivých kompiláciách budú získané obrázky prepisovať alebo nie. Nastavuje sa na logické hodnoty true|false. Tento argument je užitočný, ak meníme definovaný výrez z mapy, aby sme nemuseli manuálne odstraňovať obrázky z predchádzajúcich kompilácií. Naopak, jeho nastavenie na hodnotu false urýchľuje preklad, ak máme obrázkov veľa a sú už z predchádzajúcich behov LATEXu vytvorené. Voľba xsize a ysize Tieto voliteľné hodnoty určujú rozmery získaného obrázku v pixeloch, pričom hodnota xsize určuje jeho šírku a hodnota ysize určuje jeho výšku. Implicitné rozmery sú nastavené na hodnoty 600 × 400, pričom hodnotu je možné meniť. V režime osm sú pre oba rozmery horné hranice 3 840, kým slobodná verzia Google maps je obmedzená na rozmery 640 × 640. Vyznačovanie objektov na mapách Na vyznačenie významných objektov či orientačných bodov na mape slúžia tzv. markery. Tieto sa definujú pomocou voliteľného argumentu markers a ako hodnota 104 Obrázok 4: Ukážka mapy okolia FRI ŽU (marker F) s vyznačením stravovacích zariadení „Miláno“ (marker M) a „Kazačok“ (marker K) je mu priradený zoznam všetkých značiek, ktoré majú byť vyznačené na mape. Zoznam markerov sa uzatvára do zložených zátvoriek, pričom každý z nich je definovaný sekvenciou: &markers=size:mid|color:blue|label:S|loc1|loc2|...|locn Jednotlivé položky potom definujú vlastnosti markerov. Hodnota parametra size môže nadobúdať hodnoty tiny,mid,small, pričom ako implicitná hodnota sa berie mid. Parameter color definuje farbu markera, ktorá môže byť zadaná buď pomenovaním alebo hexadecimálnym kódom. Parameter label určuje značku vo vnútri markera (len pri veľkosti mid). Prípustné sú numerické znaky alebo kapitálky. Hodnoty loc potom definujú lokalizáciu markera na mape. Ukážku mapy s vyznačenými objektmi vidíme na obrázku 4, kde je zobrazené okolie Fakulty riadenia a informatiky a v jej blízkosti dve reštaurácie. Príslušný kód príkazu \getmap vyzerá takto: \getmap[file=fricka,overwrite=true,mode=gm, markers={&markers=size:mid|label:F|color:red| Fakulta riadenia a informatiky, 01008 Žilina, Slovakia% &markers=size:mid|label:M|color:blue| Obchodná 3269, 01008 Žilina, Slovakia,% &markers=size:mid|label:K|color:blue| Slovanská 3278, 01008 Žilina, Slovakia},% visible={{49.16, 18.65}|{49.21, 18.45}} ]{} V zdrojovom kóde si môžeme všimnúť tiež argument visible. Jeho úlohou je zabezpečenie zobrazenia takého výrezu mapy, aby všetky lokality uvedené v zozname a oddelené zvislou čiarou boli na obrázku viditeľné. Je ich možné zadať ako objekty alebo pomocou GPS súradníc. 105 Obrázok 5: Ukážka mapy okolia FRI ŽU (marker F) s vyznačením stravovacích zariadení „Miláno“ (marker M) a „Kazačok“ (marker K) a trasy ku nim Vyznačenie trasy Často je potrebné v mape vyznačiť aj cestu, ako je možné prejsť od jedného objektu ku druhému, prípadne viacero trás. Na tieto účely má príkaz \getmap voliteľný parameter path, ktorý podobne ako markers očakáva zoznam URL parametrov oddelených zvislou čiarou v tvare: &path=weight:5|color:orange|loc1|loc2|...|locn Hodnota weight udáva hrúbku čiary vyznačujúcej trasu, color farbu tejto čiary a ostatné hodnoty predstavujú lokalizačné údaje. Lokalizačné údaje je pri tom možné zadávať buď ako adresy alebo dvojicu GPS súradníc. Vyznačenie dvoch trás je ilustrované na obrázku 5. Príslušný zdrojový kód upravíme takto: \getmap[file=fricka3,overwrite=true,mode=gm, markers={&markers=size:mid|label:F|color:red| Fakulta riadenia a informatiky, 01008 Žilina, Slovakia% &markers=size:mid|label:M|color:blue| Obchodná 3269, 01008 Žilina, Slovakia,% &markers=size:mid|label:K|color:blue| Slovanská 3278, 01008 Žilina, Slovakia},% path={&path=weight:5|color:orange|Fakulta riadenia a informatiky, 01008 Žilina, Slovakia|49.203912,18.763293| 49.208426,18.761190|Obchodná 3269, 01008 Žilina, Slovakia% &path=weight:5|color:purple|Slovanská 3278, 01008 Žilina, Slovakia|49.207304,18.768442|49.206660,18.766833| 49.205117,18.768314|49.203267,18.762885}]{} 106 Obrázok 6: Snímka FRI ŽU zo služby Google Street View Obrázok 7: Satelitný záber okolia FRI ŽU Obrázky Google Street View Balíček getmap umožňuje vkladať do dokumentu aj fotografie, získané prostredníctvom služby Google Street View. Na tieto účely je potrebné pomocou voliteľných argumentov nastaviť službu mode=gsv. Pre špecifikáciu záberu sú dôležité voľby heading, ktorá udáva smer záberu zo stanoveného miesta v rozpätí 0–360 (pre sever použijeme hodnotu 0, pre východ 90 atď.), pitch, ktorá definuje uhol sklonu kamery od vodorovnej roviny a udáva sa v rozpätí od −90 po 90, a voľba fov udávajúca veľkosť rozsahu horizontálneho záberu v stupňoch, a to v rozsahu 0–120. Všetky uvedené parametre sú merané v stupňoch. Ilustrujeme si to na obrázku fakulty. Príslušnú snímku získame napríklad takýmto príkazom: \getmap[file=pfricka,mode=gsv,heading=120,fov=120,pitch=20, xsize=600,ysize=450,scale=2,zoom=20,overwrite=true] {49.202217,18.761407} Výsledok potom vidíme na obrázku 6. Na susednom obrázku 7 vidíme satelitný záber okolia fakulty s vyznačeným bodom snímania. Script getmapdl Ako sme sa už zmienili v úvode tohto príspevku, balíček getmap vlastne využíva jeden Lua skript, ktorý môže byť použitý aj z príkazového riadku. Úplnú nápovedu ku skriptu získame z príkazového riadku obvyklým postupom, teda: $ getmapdl -h 107 Z dostupných prepínačov si uvedieme len niekoľko najdôležitejších: -m určuje mód, obvykle osm|gm|gsv, -l určuje lokalitu, -i určuje formát grafického súboru, -o určuje pomenovanie výstupného súboru (bez prípony). Ak to zhrnieme, potom pomocou príkazu getmapdl -m gm -l ’Národná 25,01001 Žilina, Slovakia’ -i jpg -o zilina získame rovnaký obrázok, ako je na obrázku 2 a výsledok bude uložený v súbore zilina.jpg. Záver V príspevku sme predstavili balíček getmap. Na ukážkach bolo demonštrované, ako je do textu možné zaradiť nielen mapy získané zo služieb Open Street Map alebo Google Maps, ale aj fotografie objektov získané pomocou Google Street View. Poďakovanie Tento príspevok vznikol s láskavým prispením grantu KEGA–011ŽU–4/2014 „Experimentálna matematika – zviditeľnenie neviditeľného“ podporeného Slovenskou kultúrno-edukačnou grantovou agentúrou. Reference [1] BLAŠKO, R.: LATEX nie je farba na maľovanie, Otvorený softvér vo vzdelávaní, výskume a IT riešeniach, zborník medzinárodnej konferencie OSSConf 2010, Žilina, 1.–4. júla 2010, str. 43–52, ISBN 978-80-970457-0-8, http: //ossconf.soit.sk/images/zborniky/zbornik2010.pdf. [2] BLAŠKO, R.: LATEX nie je farba na maľovanie, ale na písanie, Otvorený softvér vo vzdelávaní, výskume a IT riešeniach, zborník medzinárodnej konferencie OSSConf 2011, Žilina, 1.–4. júla 2011, str. 249–258, ISBN 978-80-970457-1-5, http://ossconf.soit.sk/images/zborniky/ zbornik2012.pdf. [3] KLEBER, J.: Downloading maps from OpenStreetMap, Google Maps or Google Street View. [4] KOPKA, H. – DALY, P. W.: LATEX – Podrobný průvodce, Brno, Computer Press, 2004, ISBN 80-722-6973-9. 108 [5] KOZUBÍK, A.: Prezentačné materiály v triede Beamer, Zborník príspevkov z medzinárodnej konferencie OSSConf 2011, Žilina, 1.–4. júla 2011, str. 223–235, ISBN 978-80-970457-1-5. [6] RYBIČKA, J.: LATEX pro začátečníky, Brno, KONVOJ 2003, ISBN 80-7302-049-1. [7] RYBIČKA, J., ČAČKOVÁ, P., PŘICHYSTAL J.: Průvodce tvorbou dokumentů, Bučovice, Nakladatelství Martin Stříž 2011, ISBN 978-80-87106-43-3. [8] STŘÍŽ, P.: Sazba v TEXu a kresba v METAPOSTu, Bučovice, Nakladatelství Martin Stříž 2011, ISBN 978-80-87106-51-8. Summary: Maps in LATEX Documents – an Introduction of the getmap Package The aim of this article is to introduce the getmap package. This package allows to include into the LATEX documents the map materials obtained from the external resources such as OpenStreetMap and Google Maps and even with the support of Google Street View. In the simplest case, the specification of an address is sufficient. The package loads the map using the \write18 feature, which must be activated to use this package. The image will be downloaded by an external Lua script that can be used also from the command line. Keywords: Maps, LATEX, getmap, Lua Katedra matematických metód a operačnej analýzy, Fakulta riadenia a informatiky, Žilinská univerzita, Univerzitná 8215/1, 010 26 Žilina, Slovenská republika 109