% !TeX root = mercatormap.tex % !TeX encoding=UTF-8 % !TeX spellcheck=en_US % include file of mercatormap.tex (manual of the LaTeX package mercatormap) \clearpage \section{Automated Map Definition and Map Tiles}\label{sec:automated_map}% \begin{center} \begin{tikzpicture}[every node/.style={minimum width=3cm,minimum height=2cm, align=center,fill=red!5,draw=red!50!gray}] \node (A) {Map Supply}; \node[at=(A.east),right=8mm] (B) {Python Script}; \node[at=(B.east),right=8mm] (C) {Map Apply}; \node[at=(C.east),right=8mm] (D) {Map Drawing}; \begin{scope}[->,very thick,Blue_Gray] \draw (A)--(B); \draw (B)--(C); \draw (C)--(D); \end{scope} \end{tikzpicture} \end{center} As illustrated above, the script aided map definition is a process with several stages. \begin{itemize} \item Map Supply: \refCom{mrcsupplymap} is the replacement of the manual setup by \refCom{mrcdefinemap}. Actually, it is quite similar to \refCom{mrcdefinemap}. With \refCom{mrcsupplymap} directions for the following Python script are formulated. \item Python Script: The script is executed by \refCom{mrcsupplymap} during compilation. It does some coordinate system computations and downloads map tiles from a Web server. Finally, it writes a map definition into a file \meta{id}|.def|. \item Map Apply: \refCom{mrcapplymap} reads and applies the map definition from \meta{id}|.def|. \item Map Drawing: Afterwards, the map can be drawn by \refCom{mrcdrawmap} and other commands. \end{itemize} A map can be applied more than once, e.g. reused later in the document. If this is not needed, map supply and map apply can be combined by \refCom{mrcmap}. %------------------------------------------------------------------------------- \subsection{Script Activation} Remember to install Python beforehand, see \Fullref{sec:python}. \begin{docCommand}{mrcactivatescript}{} Use this inside the preamble of your document to activate the accompanying Python script. Without this command, the script is not executed! If the document is final (or the maps are final), this line could be removed and the document should be compilable without script. \end{docCommand} \begin{docMrcKey}{python}{=\meta{python}}{no default, initially |python|} Names the Python~3 interpreter as \meta{python}. If your Python~3 interpreter is not called |python|, but e.g. |python3|, then use \begin{dispListing} \mermapset{python=python3} \end{dispListing} \end{docMrcKey} \clearpage %------------------------------------------------------------------------------- \subsection{Map Types} Currently, there are three methods provided how a map is computed by the accompanying Python script. The technical background is documented in \cite[Section~5]{Sturm:2020}. \begin{enumerate} \item \refKey{mermap/supply/type}|=|\docValue{reference}: \tcbsidebyside[sidebyside adapt=left,blankest,grow to left by=1cm] { \tikzexternaldisable \begin{tikzpicture} \useasboundingbox (0,0) rectangle (3,2); \path[draw,fill=yellow!10] (0,0) rectangle (3,2); \path[fill=red] (1.5,1) circle [radius=1mm]; \end{tikzpicture} }{ The default method determines the map dimensions from a reference position and given document map dimensions. Also, a zoom level \refKey{mermap/supply/zoom} is required which relates to the Web Mercator map tile covering of the Earth. A higher zoom level gives a growing number of smaller map tiles. Alternative to the zoom level, a \meta{scale denominator} can be provided by \refKey{mermap/supply/flex area scale}, \refKey{mermap/flex scale} or \refKey{mermap/supply/flex reference scale} which determines the zoom level implicitly. As default, the reference position is the center of the map, but can be aligned at the map borders. This method is quite safe to use and could be the preferred one for many applications like showing the neighborhood of a route target. Finding the best reference point for depicting a certain area could be more tricky. } \item \refKey{mermap/supply/type}|=|\docValue{areafit}: \tcbsidebyside[sidebyside adapt=left,blankest,grow to left by=1cm] { \tikzexternaldisable \begin{tikzpicture} \useasboundingbox (0,0) rectangle (3,2); \path[draw,fill=yellow!10] (0,0) rectangle (3,2); \path[draw=red,line width=0.5mm] (0.2,0.5) rectangle (2.8,1.5); \end{tikzpicture} } { The map dimensions are determined by an area with latitude and longitude boundaries which is fitted into given document map dimensions. The zoom level is computed accordingly for a fixed document tile size or by \refKey{mermap/supply/flex area fit}. In any case, the map contains the target area plus some protrusion. This method is also quite safe to use and may be the preferred one for many applications like showing a map which contains a bunch of markers (e.g. for locations of universities). If the map borders are required to exactly meet the boundaries, the third method can be regarded. } \item \refKey{mermap/supply/type}|=|\docValue{boundaries}: \tcbsidebyside[sidebyside adapt=left,blankest,grow to left by=1cm] { \tikzexternaldisable \begin{tikzpicture} \useasboundingbox (0,0) rectangle (3,2); \path[draw=red,line width=0.5mm,fill=yellow!10] (0.2,0.5) rectangle (2.8,1.5); \end{tikzpicture} }{ The most obvious method determines the map dimensions from latitude and longitude boundaries. For this, a corresponding zoom level \refKey{mermap/supply/zoom} is required which relates to the Web Mercator map tile covering of the Earth. Alternative to the zoom level, a \meta{scale denominator} can be provided by \refKey{mermap/supply/flex area scale} or \refKey{mermap/supply/flex reference scale} which determines the zoom level implicitly. Note that a too high zoom level imposes the risk of downloading an unwanted high quantity of map tiles resulting in a much too large document map. Therefore, this most obvious method is \emph{not recommended} for the beginner and may be explored after some experience. } \end{enumerate} \clearpage %------------------------------------------------------------------------------- \subsection{Map Supply} \begin{docCommand}{mrcsupplymap}{\oarg{options}\marg{definition}} The \meta{options} provide parameters for the Python~3 script to supply all materials for a map. All options share the common prefix |mermap/supply/|.\par The map is identified by\\ \meta{id}=\refKey{mermap/definition prefix}+\meta{definition}\\ for later drawing. This identifier \meta{id} has to be unique for the document. It corresponds to generated files \meta{id}|.def|, \meta{id}|.md5|, and possibly \meta{id}|.png|. Do not use spaces or special characters like umlauts for \meta{definition}. \par If \refCom{mrcactivatescript} is used inside the preamble, \refCom{mrcsupplymap} executes the Python~3 script, otherwise nothing happens. \end{docCommand} \begin{docCommand}{mermapsetsupply}{\marg{options}} Sets \meta{options} for all following maps inside the current \TeX\ group. All options share the common prefix |mermap/supply/|, e.g. for setting \refKey{mermap/supply/type} use \begin{dispListing} \mermapsetsupply{type=reference} \end{dispListing} Also see \refCom{mermapset} and \refCom{mermapsetmarker}. \end{docCommand} \begin{docMrcKey}{definition prefix}{=\meta{definition prefix}}{no default, initially |maps/|} Prefix for map identifiers and generated map files, see \refCom{mrcsupplymap} and \refCom{mrcapplymap}. Note that \refKey{mermap/definition prefix} is not to be used inside the option list for \refCom{mrcsupplymap}. \end{docMrcKey} \begin{docMrcKey}[supply]{type}{=\meta{type}}{no default, initially |reference|} The \meta{type} defines the basic computation for the map. Feasible values are \begin{itemize} \item\docValue{reference}: \flqq map with reference position\frqq\\ The map is constructed from a given reference position \refKey{mermap/supply/latitude},\\ \refKey{mermap/supply/longitude},\\ a zoom level \refKey{mermap/supply/zoom},\\ map dimensions\\ \refKey{mermap/supply/width},\\ \refKey{mermap/supply/height},\\ and alignment \refKey{mermap/supply/align}. \item\docValue{areafit}: \flqq map fitting an area\frqq\\ The map is constructed from a given area boundaries\\ \refKey{mermap/supply/west},\\ \refKey{mermap/supply/east},\\ \refKey{mermap/supply/north},\\ \refKey{mermap/supply/south},\\ map dimensions\\ \refKey{mermap/supply/width},\\ \refKey{mermap/supply/height},\\ and alignment \refKey{mermap/supply/align}. \item\docValue{boundaries}: \flqq map with boundaries\frqq\\ The map is constructed from given boundaries\\ \refKey{mermap/supply/west},\\ \refKey{mermap/supply/east},\\ \refKey{mermap/supply/north},\\ \refKey{mermap/supply/south},\\ and zoom level \refKey{mermap/supply/zoom}. \end{itemize} \end{docMrcKey} \pagebreak \begin{docMrcKey}[supply]{zoom}{=\meta{setup zoom}}{no default, initially |9|} Map tile zoom factor alias $z$ coordinate of the map tiles. Used for map types \docValue{boundaries} and \docValue{reference}. \end{docMrcKey} \begin{docMrcKey}[supply]{north}{=\meta{setup north latitude}}{no default, initially |50|} Northern latitude degree, possibly negative for the southern hemisphere, lower than $90$ but always larger than \refKey{mermap/supply/south}. Used for map types \docValue{boundaries} and \docValue{areafit}. \end{docMrcKey} \begin{docMrcKey}[supply]{south}{=\meta{setup south latitude}}{no default, initially |48|} Southern latitude degree, possibly negative for the southern hemisphere, larger than $-90$ but always lower than \refKey{mermap/supply/north}. Used for map types \docValue{boundaries} and \docValue{areafit}. \end{docMrcKey} \begin{docMrcKey}[supply]{west}{=\meta{setup west longitude}}{no default, initially |11|} Western longitude degree, possibly negative for the western hemisphere, possibly shifted periodically, but always lower than \refKey{mermap/supply/east}. Used for map types \docValue{boundaries} and \docValue{areafit}. \end{docMrcKey} \begin{docMrcKey}[supply]{east}{=\meta{setup east longitude}}{no default, initially |13|} Eastern longitude degree, possibly negative for the western hemisphere, possibly shifted periodically, but always larger than \refKey{mermap/supply/west}. Used for map types \docValue{boundaries} and \docValue{areafit}. \end{docMrcKey} \begin{docMrcKeys}[ doc keypath = supply, doc parameter = {=\marg{comma separated list of named positions}}, doc description = {no default}, %doc new = 2020-05-04, ]{ { doc name = area }, { doc name = add area }, } Sets \refKey{mermap/supply/north}, \refKey{mermap/supply/south}, \refKey{mermap/supply/west}, \refKey{mermap/supply/east} according to the given \meta{comma separated list of named positions}, i.e. the described area contains all these positions.\\ \refKey{mermap/supply/area} resets the current area which requires at least two points inside the list.\\ \refKey{mermap/supply/add area} does not reset the current area, i.e. the positions are added to the current area which possibly grows to fit all positions.\\ Also note to take special care, if the international dateline is on your resulting map, see \Fullref{sec:dateline}. Used for map types \docValue{boundaries} and \docValue{areafit} or in combination with \refKey{mermap/supply/area to reference} also for for map type \docValue{reference}. \end{docMrcKeys} \begin{docMrcKeys}[ doc keypath = supply, doc parameter = {=\marg{file name}}, doc description = {no default}, doc new = 2020-05-08, ]{ { doc name = area from marker input }, { doc name = add area from marker input }, } Sets \refKey{mermap/supply/north}, \refKey{mermap/supply/south}, \refKey{mermap/supply/west}, \refKey{mermap/supply/east} according to the given \refCom{mrcmarker} positions contained in a file with the given \meta{file name}.\\ \refKey{mermap/supply/area from marker input} resets the current area which requires at least two marker positions inside the file.\\ \refKey{mermap/supply/add area from marker input} does not reset the current area, i.e. the positions are added to the current area which possibly grows to fit all positions.\\ Also note to take special care, if the international dateline is on your resulting map, see \Fullref{sec:dateline}. Used for map types \docValue{boundaries} and \docValue{areafit} or in combination with \refKey{mermap/supply/area to reference} also for for map type \docValue{reference}. \end{docMrcKeys} \begin{docMrcKey}[supply]{area to reference}{}{no value, initially unset} The map settings \refKey{mermap/supply/north}, \refKey{mermap/supply/south}, \refKey{mermap/supply/west}, \refKey{mermap/supply/east} are taken to compute the map center. This center position is saved to \refKey{mermap/supply/latitude} and \refKey{mermap/supply/longitude}. Used for map type \docValue{reference}. \end{docMrcKey} \clearpage \begin{docMrcKey}[supply]{latitude}{=\meta{setup latitude}}{no default, initially |49|} Latitude degree of a reference point, possibly negative for the southern hemisphere. Used for map type \docValue{reference}. \end{docMrcKey} \begin{docMrcKey}[supply]{longitude}{=\meta{setup longitude}}{no default, initially |12|} Longitude degree of a reference point, possibly negative for the western hemisphere. Used for map type \docValue{reference}. \end{docMrcKey} \begin{docMrcKey}[supply]{position}{=\meta{setup latitude}:\meta{setup longitude}}{no default, initially |49:12|} Latitude degree and longitude of a reference point. Used for map type \docValue{reference}. \end{docMrcKey} \begin{docMrcKey}[supply]{named position}{=\meta{name}}{style, no default} The \emph{named position} given by \meta{name} describes a reference point, see \Fullref{sec:names_positions}. Used for map type \docValue{reference}. \end{docMrcKey} \begin{docMrcKey}[supply]{width}{=\meta{setup width in tiles}}{no default, initially |4|} Width of the map as multiplicity of map tiles. Used for map types \docValue{reference} and \docValue{areafit}. \end{docMrcKey} \begin{docMrcKey}[supply]{tex width}{=\meta{width}}{style, no default} Width of the map as \TeX\ dimension. This is a style to compute \refKey{mermap/supply/width} according to the current \refKey{mermap/tile size}. \end{docMrcKey} \begin{docMrcKey}[supply]{height}{=\meta{setup height in tiles}}{no default, initially |4|} Height of the map as multiplicity of map tiles. Used for map types \docValue{reference} and \docValue{areafit}. \end{docMrcKey} \begin{docMrcKey}[supply]{tex height}{=\meta{width}}{style, no default} Height of the map as \TeX\ dimension. This is a style to compute \refKey{mermap/supply/height} according to the current \refKey{mermap/tile size}. \end{docMrcKey} \begin{docMrcKey}[supply]{align}{=\meta{setup alignment}}{no default, initially |center|} Alignment of reference point or area for map types \docValue{reference} and \docValue{areafit}. Feasible values are \docValue{northwest}, \docValue{north}, \docValue{northeast}, \docValue{west}, \docValue{center}, \docValue{east}, \docValue{southwest},\docValue{south}, \docValue{southeast}. \end{docMrcKey} \begin{docMrcKey}[supply]{target}{=\meta{setup target}}{no default, initially |tiles|} Defines the type of output for the Python~3 script. Feasible values are: \begin{itemize} \item\docValue{none}: No tiles are downloaded and no merged map is generated, just map computation. This is the fastest method and needs no tile supplier. \item\docValue{tiles}: Download map tiles from a tile map service (TMS) \refKey{mermap/supply/url}. Compilation of a document with map tile takes longer than compilation with a merged map and transparency should not be used with tiles, but the resulting document is smaller than a document with merged maps. \item\docValue{mergedmap}: Download map tiles from a tile map service (TMS) \refKey{mermap/supply/url} and merge them into a single map picture. This speeds compilation and allows transparency effects, but the resulting document is possibly larger than a document with map tiles, because map tiles often are optimized 8-bit image files while the merged image is a 24-bit PNG file. Additionally, synergy effects of using the same map tiles for different maps are lost. Also, since the pixel map is clipped to full pixels, the resulting map may differ (shift/size) from the more accurate tile representation by one pixel. \item\docValue{wmsmap}: Download a single map from a web map service (WMS) \refKey{mermap/supply/url}. Internally, the package treats a WMS like a tile map service including all tile calculations. Actually, a single file is downloaded. \end{itemize} \end{docMrcKey} \enlargethispage*{1cm} \begin{docMrcKey}[][doc new=2020-08-06]{fail on missing resource}{\colOpt{=true\textbar false}}{default |true|, initially |true|} If set to |true|, compilation stops with an error, if \refKey{mermap/supply/target} and \refKey{mermap/mapdef/resource} are different. Typically, this means that something went wrong while trying to download map tiles. Set this option temporarily to |false|, if the map tile service or the internet connection is expected to be unavailable only temporarily. \end{docMrcKey} \clearpage \begin{docMrcKey}[supply]{url}{=\meta{setup URL}}{no default, initially empty} Here, the url format with placeholder |{z}{x}{y}| for map tile download is defined. \textbf{Be sure that you have the permission to download, save, and use the map tiles from that URL. Illegal downloads are not endorsed in any way.} \begin{dispListing} url={https://abc.efg.hij/{z}/{x}/{y}.png?apikey=12345678}, \end{dispListing} See \Fullref{sec:maptileserver} for predefined URLs. \end{docMrcKey} \begin{docMrcKey}[supply]{url with api key}{=\marg{prefix}\marg{name}\marg{postfix}}{no default} This is an alternative version of \refKey{mermap/supply/url}. The URL is constructed from some fixed \meta{prefix} and \meta{postfix} with an API key in between. The API key is retrieved by \meta{name} from a repository filled by \refCom{mrcsetapikey}. \begin{dispListing} url={https://abc.efg.hij/{z}/{x}/{y}.png?apikey=}{myservice}{}, \end{dispListing} See \Fullref{sec:maptileserver} for predefined URLs. \end{docMrcKey} \begin{docCommand}{mrcsetapikey}{\marg{name}\marg{value}} Stores an API key \meta{value} for access with the given \meta{name}. Typically, \meta{value} is a received ID from a map tile service provider after personal registration. \meta{name} is a placeholder which is used inside \refKey{mermap/supply/url with api key} to mark the insertion point for the API key. \begin{dispListing} \mrcsetapikey{myservice}{....K942XY....} \end{dispListing} \end{docCommand} \begin{docMrcKey}[supply]{attribution}{=\meta{attribution text}}{no default, initially empty} Attribution text for the map source. Typically, it acknowledges the copyright of the map data provider. It may contain hyperlinks. It is used to set up \refKey{mermap/mapdef/attribution} afterwards and it is accessible as \docAuxCommand{mrcmapattribution} (use read-only).\par For technical reasons, do not use \verb+"+. \docAuxCommand{mrcumlaut} may be used for masking umlauts, e.g. use \verb+\mrcumlaut{u}+ instead of \verb+\"{u}+, but umlauts can also be used directly, e.g. as UTF-8 coded characters. \end{docMrcKey} \begin{docMrcKey}[supply]{attribution print}{=\meta{attribution text}}{no default, initially empty} Attribution text for the map source. In contrast to \refKey{mermap/supply/attribution} it is intended for media that does not support hyperlinks like printed posters, books, etc. It is used to set up \refKey{mermap/mapdef/attribution print} afterwards and it is accessible as \docAuxCommand{mrcmapattributionprint} (use read-only). \end{docMrcKey} \begin{docMrcKey}[supply]{basename}{=\meta{setup tile base name}}{no default, initially \texttt{tiles/tile}} Prefix for local tile files, e.g. '|tiles/map|' for '|tiles/map_10_10_10.png|'. \end{docMrcKey} \clearpage \begin{docMrcKey}[supply]{flex reference scale}{=\meta{scale denominator}}{no default} With the given \meta{scale denominator}, an appropriate \refKey{mermap/supply/zoom} and \refKey{mermap/tile size} is computed. Note that the \meta{scale denominator} always applies to the current \refKey{mermap/supply/latitude} and is used for map type \docValue{boundaries} and \docValue{reference}. For example, if the reference point is on the north side of the map, also the \meta{scale denominator} applies to the most northern latitude. Note to take special care to the order of the options. \begin{itemize} \item The reference point has to be set \emph{before} \refKey{mermap/supply/flex reference scale}, e.g. by \refKey{mermap/supply/latitude}, \refKey{mermap/supply/position}, \refKey{mermap/supply/named position}. \item \refKey{mermap/supply/tex height}, \refKey{mermap/supply/tex width} (only for map type \docValue{reference}) have to be set \emph{after} \refKey{mermap/supply/flex reference scale}, because the \refKey{mermap/tile size} is adapted. \end{itemize} Also see \refKey{mermap/flex tile size}, \refKey{mermap/flex zoom}, and \refKey{mermap/flex scale}. \tikzsetnextfilename{maptiles_flex_reference_scale}% \begin{dispExample} \begin{tikzpicture} \mrcmap[type=reference,latitude=48.14,longitude=11.57, flex reference scale=250000, source=opentopomap, tex width=\linewidth,tex height=5cm]{} \mrcdrawmap \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south) {\mrcmapattribution}; \mrcclipmap \path[draw] (mrcmap.south west) rectangle (mrcmap.north east); \node[below left=2mm,align=right,fill=white,fill opacity=0.5, text opacity=1] at (mrcmap.north east) {scale \mrcprettymapscale}; \end{tikzpicture} \end{dispExample} \end{docMrcKey} \begin{docMrcKey}[supply]{flex area scale}{=\meta{scale denominator}}{no default} This is a shortcut for setting \refKey{mermap/supply/area to reference} and \refKey{mermap/supply/flex reference scale}=\meta{scale denominator}. Used for map type \docValue{boundaries} and \docValue{reference}. Note to take special care to the order of the options. \begin{itemize} \item The reference point has to be set \emph{before} \refKey{mermap/supply/flex area scale}. \item \refKey{mermap/supply/tex height}, \refKey{mermap/supply/tex width} (only for map type \docValue{reference}) have to be set \emph{after} \refKey{mermap/supply/flex reference scale}. \end{itemize} \end{docMrcKey} \clearpage \begin{docMrcKey}[supply]{flex area fit}{\colOpt{=\meta{size}}}{default |0pt|} This key can be used for map type \docValue{areafit} as \emph{final} option \emph{after} all other options. It applies a fine tuning to \refKey{mermap/tile size}, \refKey{mermap/supply/width}, and \refKey{mermap/supply/height} such that the defined area fits exactly into the map region. If a \meta{size} is specified, width and height are reduced for the calculation by this \meta{size}, e.g. \meta{size}|=1cm| ensures a border of |5mm| on each side. Also see \refKey{mermap/flex tile size} and \refKey{mermap/flex zoom}. \tikzsetnextfilename{maptiles_flex_area_fit}% \begin{dispExample} \begin{tikzpicture} \mrcNPdef{munich}{48.14}{11.58} \mrcNPdef{rio}{-22.91}{-43.20} \mrcNPdef{newyork}{40.71}{-74.01} \mrcmap[ type = areafit, area = {munich,rio,newyork}, source=topplusopen web grau, tex width=\linewidth, tex height=7cm, flex area fit=1cm ]{} \mrcdrawmap \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south) {\mrcmapattribution}; \draw[yellow] ([xshift=5mm,yshift=5mm]mrcmap.south west) rectangle ([xshift=-5mm,yshift=-5mm]mrcmap.north east); \draw[red,fill=red!50!gray!50!white,fill opacity=0.25] (\mrcNPcs{newyork}) -- (\mrcNPcs{rio}) -- (\mrcNPcs{munich}) -- cycle; \end{tikzpicture} \end{dispExample} \end{docMrcKey} \clearpage \begin{docMrcKey}[supply]{pixel}{=\meta{setup pixel size}}{no default, initially |256|} Pixel width (and height) of a tile. It is especially needed for target \docValue{mergedmap} and also \docValue{wmsmap}. For \docValue{wmsmap}, it is multiplied with a pseudo tile calculation to compute the actual picture size to download. \end{docMrcKey} \begin{docMrcKey}[supply]{dpi}{=\meta{dpi value}}{style, no default} This style sets \refKey{mermap/supply/pixel} such that the given \meta{dpi value} is resulting (approximately). \begin{itemize} \item Note that this only applies for WMS Servers and not for TMS (Tile Map Service) Servers, because there \refKey{mermap/supply/pixel} is a fixed number depending on Server settings and cannot be chosen arbitrarily. \item A high \meta{dpi value} results in large downloaded map files. If the server does not provide a high resolution map, you will get unnecessary large files with blurred content. \item The \meta{dpi value} for TMS data can be changed by adapting \refKey{mermap/tile size} or \refKey{mermap/flex tile size}. \end{itemize} \tikzsetnextfilename{maptiles_dpi_value} \begin{dispExample} \begin{tikzpicture} \mrcmap[type=reference,latitude=48.14,longitude=11.57, flex reference scale=250000, source=topplusopen p250, target=wmsmap, dpi=300, tex width=\linewidth,tex height=5cm]{dpi_value} \mrcdrawmap \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south) {\mrcmapattribution}; \mrcclipmap \path[draw] (mrcmap.south west) rectangle (mrcmap.north east); \end{tikzpicture} \end{dispExample} \end{docMrcKey} %------------------------------------------------------------------------------- \subsection{Map Apply} \begin{docCommand}{mrcapplymap}{\marg{definition}} A map which is supplied by \refCom{mrcsupplymap} is applied inside a |tikzpicture| environment by \refCom{mrcapplymap} where \meta{definition} identifies the map. \refCom{mrcapplymap} replaces a manual setup by \refCom{mrcdefinemap}. The same map can be applied more than once inside a document. Note that applying a map does not mean to draw the map, but to prepare everything for drawing. \end{docCommand} \begin{docCommand}{mrcmap}{\oarg{options}\marg{definition}} This is a combination of \refCom{mrcsupplymap} with the given \meta{options} followed immediately by \refCom{mrcapplymap}. If \meta{definition} is left empty, an automated unique identifier is inserted. If a map is to be used just once, \refCom{mrcmap} may be preferred. \end{docCommand} \clearpage %------------------------------------------------------------------------------- \subsection{Map Tile Server}\label{sec:maptileserver} To use map tiles with this package you obviously need access to a map tile server. Thanks to all the many contributors to \href{https://openstreetmap.org/copyright}{OpenStreetMap}, map data is free for everyone to use. \textbf{But, map tile servers based on OpenStreetMap are not necessarily free}. A list of online raster tile servers based on OpenStreetMap data is found here:\\ \url{https://wiki.openstreetmap.org/wiki/Raster_tile_providers} \begin{itemize} \item\bfseries I do not run a map tile server. \item I do not and cannot grant any permission to access a map tile server. \item I do not and cannot grant any permission to use map tiles in private, academic, free, or commercial publications. \item All operators of map tile servers require to mention an attribution for their maps. \end{itemize} The following option allows easy usage of very few selected tile servers. The tile server of \href{https://openstreetmap.org/copyright}{OpenStreetMap} is not included because of its \href{https://operations.osmfoundation.org/policies/tiles/}{Tile Usage Policy}. I am aware that the following list could be enlarged much more, but I do not want to add more to avoid any legal uncertainties. \begin{itemize} \item\bfseries I will remove an entry immediately, if the tile server operator asks for it. \item\mdseries If \textbf{YOU} operate a tile server and you want an entry here, I would be glad to add it to the following list. \end{itemize} \medskip \begin{docMrcKey}[supply]{source}{=\meta{source}}{style, no default} This style sets \refKey{mermap/supply/url}, \refKey{mermap/supply/attribution},\\ \refKey{mermap/supply/attribution print} and \refKey{mermap/supply/basename}.\\ Feasible values for \meta{source} are: %\mermapset{tile size=3.2512cm} \newcommand{\mapexample}[3][]{% \begingroup \mermapset{supply/source=#2}% \begin{itemize} \item Required attribution (\docAuxCommand{mrcmapattribution}): \begin{tcolorbox}[sharp corners,size=fbox,colback=yellow!8,colframe=yellow!80!gray,halign=flush left,before skip=2pt] \mrcmapattribution\end{tcolorbox} \item Required attribution for media without hyperlinks (\docAuxCommand{mrcmapattributionprint}): \begin{tcolorbox}[sharp corners,size=fbox,colback=yellow!8,colframe=yellow!80!gray,halign=flush left,before skip=2pt] \mrcmapattributionprint\end{tcolorbox} %\par\smallskip\ \end{itemize} \endgroup\par\smallskip\tikzsetnextfilename{maptiles_#3}% \begin{tikzpicture} \mrcmap[source=#2, type=reference,latitude=48.14,longitude=11.58,zoom=7, tex width=\linewidth,tex height=2cm,#1]{#3} \mrcdrawmap \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south) {\mrcmapattribution}; \end{tikzpicture}\par% }% \begin{itemize} \item\docValue{dummy}:\\ Dummy tile server at loopback |127.0.0.1| for test purposes. \item\docValue{opentopomap}:\\ Tile server (TMS) of \href{https://opentopomap.org/}{OpenTopoMap}. \begin{itemize} \item Usage (German language): \url{https://opentopomap.org/about#verwendung} \end{itemize} \mapexample{opentopomap}{opentopomap} \clearpage \item\docValue{thunderforest opencyclemap}:\\ Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ A registered \meta{api-key} is needed (free plan available) which is applied by\\ \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. \begin{itemize} \item Usage: \url{https://www.thunderforest.com/terms} \item API documentation: \url{https://www.thunderforest.com/maps/opencyclemap} \end{itemize} \mapexample{thunderforest opencyclemap}{thunderforest_opencyclemap} \item\docValue{thunderforest transport}:\\ Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ A registered \meta{api-key} is needed (free plan available) which is applied by\\ \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. \begin{itemize} \item Usage: \url{https://www.thunderforest.com/terms} \item API documentation: \url{https://www.thunderforest.com/maps/transport} \end{itemize} \mapexample{thunderforest transport}{thunderforest_transport} \item\docValue{thunderforest landscape}:\\ Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ A registered \meta{api-key} is needed (free plan available) which is applied by\\ \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. \begin{itemize} \item Usage: \url{https://www.thunderforest.com/terms} \item API documentation: \url{https://www.thunderforest.com/maps/landscape} \end{itemize} \mapexample{thunderforest landscape}{thunderforest_landscape} \clearpage \item\docValue{thunderforest outdoors}:\\ Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ A registered \meta{api-key} is needed (free plan available) which is applied by\\ \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. \begin{itemize} \item Usage: \url{https://www.thunderforest.com/terms} \item API documentation: \url{https://www.thunderforest.com/maps/outdoors} \end{itemize} \mapexample{thunderforest outdoors}{thunderforest_outdoors} \item\docValue{thunderforest atlas}:\tcbdocmarginnote{\tcbdocnew{2024-07-29}}\\ Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ A registered \meta{api-key} is needed (free plan available) which is applied by\\ \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. \begin{itemize} \item Usage: \url{https://www.thunderforest.com/terms} \item API documentation: \url{https://www.thunderforest.com/maps/atlas} \end{itemize} \mapexample{thunderforest atlas}{thunderforest_atlas} \item\docValue{thunderforest transport-dark}:\\ Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ A registered \meta{api-key} is needed (free plan available) which is applied by\\ \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. \begin{itemize} \item Usage: \url{https://www.thunderforest.com/terms} \item API documentation: \url{https://www.thunderforest.com/maps/transport-dark} \end{itemize} \mapexample{thunderforest transport-dark}{thunderforest_transport-dark} \clearpage \item\docValue{thunderforest spinal-map}:\\ Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ A registered \meta{api-key} is needed (free plan available) which is applied by\\ \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. \begin{itemize} \item Usage: \url{https://www.thunderforest.com/terms} \item API documentation: \url{https://www.thunderforest.com/maps/spinal-map} \end{itemize} \mapexample{thunderforest spinal-map}{thunderforest_spinal-map} \item\docValue{thunderforest pioneer}:\\ Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ A registered \meta{api-key} is needed (free plan available) which is applied by\\ \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. \begin{itemize} \item Usage: \url{https://www.thunderforest.com/terms} \item API documentation: \url{https://www.thunderforest.com/maps/pioneer} \end{itemize} \mapexample{thunderforest pioneer}{thunderforest_pioneer} \item\docValue{thunderforest mobile-atlas}:\\ Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ A registered \meta{api-key} is needed (free plan available) which is applied by\\ \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. \begin{itemize} \item Usage: \url{https://www.thunderforest.com/terms} \item API documentation: \url{https://www.thunderforest.com/maps/mobile-atlas} \end{itemize} \mapexample{thunderforest mobile-atlas}{thunderforest_mobile-atlas} \clearpage \item\docValue{thunderforest neighbourhood}:\\ Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ A registered \meta{api-key} is needed (free plan available) which is applied by\\ \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. \begin{itemize} \item Usage: \url{https://www.thunderforest.com/terms} \item API documentation: \url{https://www.thunderforest.com/maps/neighbourhood} \end{itemize} \mapexample{thunderforest neighbourhood}{thunderforest_neighbourhood} \item\docValue{topplusopen web}:\\ Tile server (TMS) of \href{https://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}. \begin{itemize} \item Covers world / Europe / Germany depending on zoom level \item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/topplusopen-produkte.html} \end{itemize} \mapexample{topplusopen web}{topplusopen_web} \item\docValue{topplusopen web grau}:\\ Tile server (TMS) of \href{https://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}. \begin{itemize} \item Covers world / Europe / Germany depending on zoom level \item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/topplusopen-produkte.html} \end{itemize} \mapexample{topplusopen web grau}{topplusopen_web_grau} \clearpage \item\docValue{topplusopen web light}:\tcbdocmarginnote{\tcbdocnew{2024-07-29}}\\ Tile server (TMS) of \href{https://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}. \begin{itemize} \item Covers world / Europe / Germany depending on zoom level \item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/topplusopen-produkte.html} \end{itemize} \mapexample{topplusopen web light}{topplusopen_web_light} \item\docValue{topplusopen web light grau}\tcbdocmarginnote{\tcbdocnew{2024-07-29}}:\\ Tile server (TMS) of \href{https://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}. \begin{itemize} \item Covers world / Europe / Germany depending on zoom level \item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/topplusopen-produkte.html} \end{itemize} \mapexample{topplusopen web light grau}{topplusopen_web_light_grau} \end{itemize} \vfill \begin{tcolorbox}[spartan,colback=white] The following sources are Web map server (WMS). Therefore, \refKey{mermap/supply/target} can only be set to \docValue{wmsmap} or \docValue{none}. \end{tcolorbox} \clearpage \begingroup \ExplSyntaxOn \int_gzero:N \g_tmpa_int \NewDocumentCommand \cleanstep {} { \fp_compare:nNnT { \g_tmpa_int-trunc(\g_tmpa_int/3)*3 } = 0 { \int_compare:nNnT \g_tmpa_int > 0 { \clearpage } } \int_gincr:N \g_tmpa_int } \ExplSyntaxOff \begin{itemize} \foreach \name / \scdenom / \xtra in {p5/5000,p10/10000,p17.5/17500,p25/25000,p50/50000,p100/100000,p250/250000} { \cleanstep \item\docValue{topplusopen \name}:\\ Web map server (WMS) of \href{https://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}. \begin{itemize} \item 1:\scdenom, covers Europe / Germany depending on zoom level \item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/topplusopen-produkte.html} \end{itemize} \mapexample[target=wmsmap]{topplusopen \name}{topplusopen_\name} \cleanstep \item\docValue{topplusopen \name\ grau}:\\ Web map server (WMS) of \href{https://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}. \begin{itemize} \item 1:\scdenom, covers Europe / Germany depending on zoom level \item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/topplusopen-produkte.html} \end{itemize} \def\grau{ grau}% \mapexample[target=wmsmap]{topplusopen \name\grau}{topplusopen_\name_grau} } \end{itemize} \endgroup \end{docMrcKey} \begin{docCommand}{mrcnewsupplysource}{\marg{source}\marg{options}} Adds a new \meta{source} value to \refKey{mermap/supply/source}. The \meta{options} should set the keys \refKey{mermap/supply/url}, \refKey{mermap/supply/attribution},\\ \refKey{mermap/supply/attribution print} and \refKey{mermap/supply/basename}. It is recommend to use |x ...| for \meta{source} to avoid conflicts with future official additions to \refKey{mermap/supply/source}. \begin{dispListing} \mrcnewsupplysource{x example} { url = https://127.0.0.1/dummy/{z}/{x}/{y}.png, attribution = {Dummy tile server}, attribution print = {Dummy tile server}, basename = tiles/dummy, } \end{dispListing} \end{docCommand}