| 1 |
% !TeX root = mercatormap.tex |
| 2 |
% !TeX encoding=UTF-8 |
| 3 |
% !TeX spellcheck=en_US |
| 4 |
% include file of mercatormap.tex (manual of the LaTeX package mercatormap) |
| 5 |
\clearpage |
| 6 |
\section{Automated Map Definition and Map Tiles}\label{sec:automated_map}% |
| 7 |
|
| 8 |
\begin{center} |
| 9 |
\begin{tikzpicture}[every node/.style={minimum width=3cm,minimum height=2cm, |
| 10 |
align=center,fill=red!5,draw=red!50!gray}] |
| 11 |
\node (A) {Map Supply}; |
| 12 |
\node[at=(A.east),right=8mm] (B) {Python Script}; |
| 13 |
\node[at=(B.east),right=8mm] (C) {Map Apply}; |
| 14 |
\node[at=(C.east),right=8mm] (D) {Map Drawing}; |
| 15 |
\begin{scope}[->,very thick,Blue_Gray] |
| 16 |
\draw (A)--(B); \draw (B)--(C); \draw (C)--(D); |
| 17 |
\end{scope} |
| 18 |
\end{tikzpicture} |
| 19 |
\end{center} |
| 20 |
|
| 21 |
As illustrated above, the script aided map definition is a process with |
| 22 |
several stages. |
| 23 |
|
| 24 |
\begin{itemize} |
| 25 |
\item Map Supply: \refCom{mrcsupplymap} is the replacement of the manual setup by |
| 26 |
\refCom{mrcdefinemap}. Actually, it is quite similar to \refCom{mrcdefinemap}. |
| 27 |
With \refCom{mrcsupplymap} directions for the following Python script |
| 28 |
are formulated. |
| 29 |
\item Python Script: The script is executed by \refCom{mrcsupplymap} during |
| 30 |
compilation. It does some coordinate system computations and downloads |
| 31 |
map tiles from a Web server. Finally, it writes a map definition into |
| 32 |
a file \meta{id}|.def|. |
| 33 |
\item Map Apply: \refCom{mrcapplymap} reads and applies the |
| 34 |
map definition from \meta{id}|.def|. |
| 35 |
\item Map Drawing: Afterwards, the map can be drawn by \refCom{mrcdrawmap} |
| 36 |
and other commands. |
| 37 |
\end{itemize} |
| 38 |
|
| 39 |
A map can be applied more than once, e.g. reused later in the document. |
| 40 |
If this is not needed, map supply and map apply can be combined by |
| 41 |
\refCom{mrcmap}. |
| 42 |
|
| 43 |
|
| 44 |
%------------------------------------------------------------------------------- |
| 45 |
\subsection{Script Activation} |
| 46 |
|
| 47 |
Remember to install Python beforehand, see \Fullref{sec:python}. |
| 48 |
|
| 49 |
\begin{docCommand}{mrcactivatescript}{} |
| 50 |
Use this inside the preamble of your document to activate the |
| 51 |
accompanying Python script. |
| 52 |
Without this command, the script is not executed! |
| 53 |
If the document is final (or the maps are final), |
| 54 |
this line could be removed and the document |
| 55 |
should be compilable without script. |
| 56 |
\end{docCommand} |
| 57 |
|
| 58 |
|
| 59 |
\begin{docMrcKey}{python}{=\meta{python}}{no default, initially |python|} |
| 60 |
Names the Python~3 interpreter as \meta{python}. If your Python~3 interpreter |
| 61 |
is not called |python|, but e.g. |python3|, then use |
| 62 |
\begin{dispListing} |
| 63 |
\mermapset{python=python3} |
| 64 |
\end{dispListing} |
| 65 |
\end{docMrcKey} |
| 66 |
|
| 67 |
|
| 68 |
\clearpage |
| 69 |
%------------------------------------------------------------------------------- |
| 70 |
\subsection{Map Types} |
| 71 |
Currently, there are three methods provided how a map is computed by the |
| 72 |
accompanying Python script. The technical background is documented in |
| 73 |
\cite[Section~5]{Sturm:2020}. |
| 74 |
|
| 75 |
\begin{enumerate} |
| 76 |
\item \refKey{mermap/supply/type}|=|\docValue{reference}: |
| 77 |
\tcbsidebyside[sidebyside adapt=left,blankest,grow to left by=1cm] |
| 78 |
{ |
| 79 |
\tikzexternaldisable |
| 80 |
\begin{tikzpicture} |
| 81 |
\useasboundingbox (0,0) rectangle (3,2); |
| 82 |
\path[draw,fill=yellow!10] (0,0) rectangle (3,2); |
| 83 |
\path[fill=red] (1.5,1) circle [radius=1mm]; |
| 84 |
\end{tikzpicture} |
| 85 |
}{ |
| 86 |
The default method determines the map dimensions from a reference |
| 87 |
position and given document map dimensions. |
| 88 |
Also, a zoom level \refKey{mermap/supply/zoom} |
| 89 |
is required which relates to the Web Mercator map tile covering of the Earth. |
| 90 |
A higher zoom level gives a growing number of smaller map tiles. |
| 91 |
Alternative to the zoom level, a \meta{scale denominator} can be provided |
| 92 |
by \refKey{mermap/supply/flex area scale}, \refKey{mermap/flex scale} |
| 93 |
or \refKey{mermap/supply/flex reference scale} which determines |
| 94 |
the zoom level implicitly. |
| 95 |
As default, the reference position is the center of the map, but can be |
| 96 |
aligned at the map borders. This method is quite safe to use and could |
| 97 |
be the preferred one for many applications like showing the neighborhood |
| 98 |
of a route target. |
| 99 |
Finding the best reference point for depicting a certain area could |
| 100 |
be more tricky. |
| 101 |
} |
| 102 |
|
| 103 |
\item \refKey{mermap/supply/type}|=|\docValue{areafit}: |
| 104 |
\tcbsidebyside[sidebyside adapt=left,blankest,grow to left by=1cm] |
| 105 |
{ |
| 106 |
\tikzexternaldisable |
| 107 |
\begin{tikzpicture} |
| 108 |
\useasboundingbox (0,0) rectangle (3,2); |
| 109 |
\path[draw,fill=yellow!10] (0,0) rectangle (3,2); |
| 110 |
\path[draw=red,line width=0.5mm] (0.2,0.5) rectangle (2.8,1.5); |
| 111 |
\end{tikzpicture} |
| 112 |
} |
| 113 |
{ |
| 114 |
The map dimensions are determined by an area with |
| 115 |
latitude and longitude boundaries which is fitted into given |
| 116 |
document map dimensions. The zoom level is computed accordingly |
| 117 |
for a fixed document tile size or by \refKey{mermap/supply/flex area fit}. |
| 118 |
In any case, the map contains the target area plus some protrusion. |
| 119 |
This method is also quite safe to use and may be |
| 120 |
the preferred one for many applications like showing a map which contains |
| 121 |
a bunch of markers (e.g. for locations of universities). |
| 122 |
If the map borders are required to exactly meet the boundaries, |
| 123 |
the third method can be regarded. |
| 124 |
} |
| 125 |
|
| 126 |
\item \refKey{mermap/supply/type}|=|\docValue{boundaries}: |
| 127 |
\tcbsidebyside[sidebyside adapt=left,blankest,grow to left by=1cm] |
| 128 |
{ |
| 129 |
\tikzexternaldisable |
| 130 |
\begin{tikzpicture} |
| 131 |
\useasboundingbox (0,0) rectangle (3,2); |
| 132 |
\path[draw=red,line width=0.5mm,fill=yellow!10] (0.2,0.5) rectangle (2.8,1.5); |
| 133 |
\end{tikzpicture} |
| 134 |
}{ |
| 135 |
The most obvious method determines the map dimensions from |
| 136 |
latitude and longitude boundaries. For this, a corresponding zoom level |
| 137 |
\refKey{mermap/supply/zoom} |
| 138 |
is required which relates to the Web Mercator map tile covering of the Earth. |
| 139 |
Alternative to the zoom level, a \meta{scale denominator} can be provided |
| 140 |
by \refKey{mermap/supply/flex area scale} |
| 141 |
or \refKey{mermap/supply/flex reference scale} which determines |
| 142 |
the zoom level implicitly. |
| 143 |
Note that a too high zoom level imposes the risk of downloading an unwanted |
| 144 |
high quantity of map tiles resulting in a much too large document map. |
| 145 |
Therefore, this most obvious method is \emph{not recommended} for the |
| 146 |
beginner and may be explored after some experience. |
| 147 |
} |
| 148 |
\end{enumerate} |
| 149 |
|
| 150 |
|
| 151 |
|
| 152 |
\clearpage |
| 153 |
%------------------------------------------------------------------------------- |
| 154 |
\subsection{Map Supply} |
| 155 |
|
| 156 |
\begin{docCommand}{mrcsupplymap}{\oarg{options}\marg{definition}} |
| 157 |
The \meta{options} provide parameters for the Python~3 script to supply all |
| 158 |
materials for a map. |
| 159 |
All options share the common prefix |mermap/supply/|.\par |
| 160 |
The map is identified by\\ |
| 161 |
\meta{id}=\refKey{mermap/definition prefix}+\meta{definition}\\ |
| 162 |
for later drawing. |
| 163 |
This identifier \meta{id} has to be unique for the document. |
| 164 |
It corresponds to generated files \meta{id}|.def|, \meta{id}|.md5|, and |
| 165 |
possibly \meta{id}|.png|. |
| 166 |
Do not use spaces or special characters like umlauts for \meta{definition}. |
| 167 |
\par |
| 168 |
If \refCom{mrcactivatescript} is used inside the preamble, |
| 169 |
\refCom{mrcsupplymap} executes the Python~3 script, otherwise nothing happens. |
| 170 |
\end{docCommand} |
| 171 |
|
| 172 |
|
| 173 |
\begin{docCommand}{mermapsetsupply}{\marg{options}} |
| 174 |
Sets \meta{options} for all following maps inside the current \TeX\ group. |
| 175 |
All options share the common prefix |mermap/supply/|, e.g. for setting |
| 176 |
\refKey{mermap/supply/type} use |
| 177 |
\begin{dispListing} |
| 178 |
\mermapsetsupply{type=reference} |
| 179 |
\end{dispListing} |
| 180 |
Also see \refCom{mermapset} and \refCom{mermapsetmarker}. |
| 181 |
\end{docCommand} |
| 182 |
|
| 183 |
|
| 184 |
\begin{docMrcKey}{definition prefix}{=\meta{definition prefix}}{no default, initially |maps/|} |
| 185 |
Prefix for map identifiers and generated map files, see \refCom{mrcsupplymap} |
| 186 |
and \refCom{mrcapplymap}. |
| 187 |
Note that \refKey{mermap/definition prefix} is not to be used inside |
| 188 |
the option list for \refCom{mrcsupplymap}. |
| 189 |
\end{docMrcKey} |
| 190 |
|
| 191 |
\begin{docMrcKey}[supply]{type}{=\meta{type}}{no default, initially |reference|} |
| 192 |
The \meta{type} defines the basic computation for the map. Feasible values are |
| 193 |
\begin{itemize} |
| 194 |
\item\docValue{reference}: \flqq map with reference position\frqq\\ |
| 195 |
The map is constructed from a given reference position |
| 196 |
\refKey{mermap/supply/latitude},\\ |
| 197 |
\refKey{mermap/supply/longitude},\\ |
| 198 |
a zoom level \refKey{mermap/supply/zoom},\\ |
| 199 |
map dimensions\\ |
| 200 |
\refKey{mermap/supply/width},\\ |
| 201 |
\refKey{mermap/supply/height},\\ |
| 202 |
and alignment \refKey{mermap/supply/align}. |
| 203 |
\item\docValue{areafit}: \flqq map fitting an area\frqq\\ |
| 204 |
The map is constructed from a given area boundaries\\ |
| 205 |
\refKey{mermap/supply/west},\\ |
| 206 |
\refKey{mermap/supply/east},\\ |
| 207 |
\refKey{mermap/supply/north},\\ |
| 208 |
\refKey{mermap/supply/south},\\ |
| 209 |
map dimensions\\ |
| 210 |
\refKey{mermap/supply/width},\\ |
| 211 |
\refKey{mermap/supply/height},\\ |
| 212 |
and alignment \refKey{mermap/supply/align}. |
| 213 |
\item\docValue{boundaries}: \flqq map with boundaries\frqq\\ |
| 214 |
The map is constructed from given boundaries\\ |
| 215 |
\refKey{mermap/supply/west},\\ |
| 216 |
\refKey{mermap/supply/east},\\ |
| 217 |
\refKey{mermap/supply/north},\\ |
| 218 |
\refKey{mermap/supply/south},\\ |
| 219 |
and zoom level \refKey{mermap/supply/zoom}. |
| 220 |
\end{itemize} |
| 221 |
\end{docMrcKey} |
| 222 |
|
| 223 |
\pagebreak |
| 224 |
|
| 225 |
\begin{docMrcKey}[supply]{zoom}{=\meta{setup zoom}}{no default, initially |9|} |
| 226 |
Map tile zoom factor alias $z$ coordinate of the map tiles. |
| 227 |
Used for map types \docValue{boundaries} and \docValue{reference}. |
| 228 |
\end{docMrcKey} |
| 229 |
|
| 230 |
\begin{docMrcKey}[supply]{north}{=\meta{setup north latitude}}{no default, initially |50|} |
| 231 |
Northern latitude degree, possibly negative for the southern hemisphere, |
| 232 |
lower than $90$ but always larger than \refKey{mermap/supply/south}. |
| 233 |
Used for map types \docValue{boundaries} and \docValue{areafit}. |
| 234 |
\end{docMrcKey} |
| 235 |
|
| 236 |
\begin{docMrcKey}[supply]{south}{=\meta{setup south latitude}}{no default, initially |48|} |
| 237 |
Southern latitude degree, possibly negative for the southern hemisphere, |
| 238 |
larger than $-90$ but always lower than \refKey{mermap/supply/north}. |
| 239 |
Used for map types \docValue{boundaries} and \docValue{areafit}. |
| 240 |
\end{docMrcKey} |
| 241 |
|
| 242 |
\begin{docMrcKey}[supply]{west}{=\meta{setup west longitude}}{no default, initially |11|} |
| 243 |
Western longitude degree, possibly negative for the western hemisphere, |
| 244 |
possibly shifted periodically, but always lower than \refKey{mermap/supply/east}. |
| 245 |
Used for map types \docValue{boundaries} and \docValue{areafit}. |
| 246 |
\end{docMrcKey} |
| 247 |
|
| 248 |
\begin{docMrcKey}[supply]{east}{=\meta{setup east longitude}}{no default, initially |13|} |
| 249 |
Eastern longitude degree, possibly negative for the western hemisphere, |
| 250 |
possibly shifted periodically, but always larger than \refKey{mermap/supply/west}. |
| 251 |
Used for map types \docValue{boundaries} and \docValue{areafit}. |
| 252 |
\end{docMrcKey} |
| 253 |
|
| 254 |
|
| 255 |
\begin{docMrcKeys}[ |
| 256 |
doc keypath = supply, |
| 257 |
doc parameter = {=\marg{comma separated list of named positions}}, |
| 258 |
doc description = {no default}, |
| 259 |
%doc new = 2020-05-04, |
| 260 |
]{ |
| 261 |
{ doc name = area }, |
| 262 |
{ doc name = add area }, |
| 263 |
} |
| 264 |
Sets |
| 265 |
\refKey{mermap/supply/north}, \refKey{mermap/supply/south}, |
| 266 |
\refKey{mermap/supply/west}, \refKey{mermap/supply/east} |
| 267 |
according to the given \meta{comma separated list of named positions}, i.e. |
| 268 |
the described area contains all these positions.\\ |
| 269 |
\refKey{mermap/supply/area} resets the current area which requires |
| 270 |
at least two points inside the list.\\ |
| 271 |
\refKey{mermap/supply/add area} does not reset the current area, |
| 272 |
i.e. the positions are added to the |
| 273 |
current area which possibly grows to fit all positions.\\ |
| 274 |
Also note to take special care, if the international dateline is on your |
| 275 |
resulting map, see \Fullref{sec:dateline}. |
| 276 |
Used for map types \docValue{boundaries} and \docValue{areafit} |
| 277 |
or in combination with \refKey{mermap/supply/area to reference} also |
| 278 |
for for map type \docValue{reference}. |
| 279 |
\end{docMrcKeys} |
| 280 |
|
| 281 |
|
| 282 |
|
| 283 |
\begin{docMrcKeys}[ |
| 284 |
doc keypath = supply, |
| 285 |
doc parameter = {=\marg{file name}}, |
| 286 |
doc description = {no default}, |
| 287 |
doc new = 2020-05-08, |
| 288 |
]{ |
| 289 |
{ doc name = area from marker input }, |
| 290 |
{ doc name = add area from marker input }, |
| 291 |
} |
| 292 |
Sets |
| 293 |
\refKey{mermap/supply/north}, \refKey{mermap/supply/south}, |
| 294 |
\refKey{mermap/supply/west}, \refKey{mermap/supply/east} |
| 295 |
according to the given \refCom{mrcmarker} positions contained in a |
| 296 |
file with the given \meta{file name}.\\ |
| 297 |
\refKey{mermap/supply/area from marker input} resets the current area which requires |
| 298 |
at least two marker positions inside the file.\\ |
| 299 |
\refKey{mermap/supply/add area from marker input} does not reset the current area, |
| 300 |
i.e. the positions are added to the |
| 301 |
current area which possibly grows to fit all positions.\\ |
| 302 |
Also note to take special care, if the international dateline is on your |
| 303 |
resulting map, see \Fullref{sec:dateline}. |
| 304 |
Used for map types \docValue{boundaries} and \docValue{areafit} |
| 305 |
or in combination with \refKey{mermap/supply/area to reference} also |
| 306 |
for for map type \docValue{reference}. |
| 307 |
\end{docMrcKeys} |
| 308 |
|
| 309 |
|
| 310 |
|
| 311 |
\begin{docMrcKey}[supply]{area to reference}{}{no value, initially unset} |
| 312 |
The map settings |
| 313 |
\refKey{mermap/supply/north}, \refKey{mermap/supply/south}, |
| 314 |
\refKey{mermap/supply/west}, \refKey{mermap/supply/east} |
| 315 |
are taken to compute the map center. This center position is saved |
| 316 |
to \refKey{mermap/supply/latitude} and \refKey{mermap/supply/longitude}. |
| 317 |
Used for map type \docValue{reference}. |
| 318 |
\end{docMrcKey} |
| 319 |
|
| 320 |
|
| 321 |
\clearpage |
| 322 |
|
| 323 |
\begin{docMrcKey}[supply]{latitude}{=\meta{setup latitude}}{no default, initially |49|} |
| 324 |
Latitude degree of a reference point, possibly negative for the southern hemisphere. |
| 325 |
Used for map type \docValue{reference}. |
| 326 |
\end{docMrcKey} |
| 327 |
|
| 328 |
\begin{docMrcKey}[supply]{longitude}{=\meta{setup longitude}}{no default, initially |12|} |
| 329 |
Longitude degree of a reference point, possibly negative for the western hemisphere. |
| 330 |
Used for map type \docValue{reference}. |
| 331 |
\end{docMrcKey} |
| 332 |
|
| 333 |
|
| 334 |
\begin{docMrcKey}[supply]{position}{=\meta{setup latitude}:\meta{setup longitude}}{no default, initially |49:12|} |
| 335 |
Latitude degree and longitude of a reference point. |
| 336 |
Used for map type \docValue{reference}. |
| 337 |
\end{docMrcKey} |
| 338 |
|
| 339 |
|
| 340 |
\begin{docMrcKey}[supply]{named position}{=\meta{name}}{style, no default} |
| 341 |
The \emph{named position} given by \meta{name} describes |
| 342 |
a reference point, see \Fullref{sec:names_positions}. |
| 343 |
Used for map type \docValue{reference}. |
| 344 |
\end{docMrcKey} |
| 345 |
|
| 346 |
|
| 347 |
|
| 348 |
\begin{docMrcKey}[supply]{width}{=\meta{setup width in tiles}}{no default, initially |4|} |
| 349 |
Width of the map as multiplicity of map tiles. |
| 350 |
Used for map types \docValue{reference} and \docValue{areafit}. |
| 351 |
\end{docMrcKey} |
| 352 |
|
| 353 |
\begin{docMrcKey}[supply]{tex width}{=\meta{width}}{style, no default} |
| 354 |
Width of the map as \TeX\ dimension. |
| 355 |
This is a style to compute \refKey{mermap/supply/width} according to |
| 356 |
the current \refKey{mermap/tile size}. |
| 357 |
\end{docMrcKey} |
| 358 |
|
| 359 |
\begin{docMrcKey}[supply]{height}{=\meta{setup height in tiles}}{no default, initially |4|} |
| 360 |
Height of the map as multiplicity of map tiles. |
| 361 |
Used for map types \docValue{reference} and \docValue{areafit}. |
| 362 |
\end{docMrcKey} |
| 363 |
|
| 364 |
\begin{docMrcKey}[supply]{tex height}{=\meta{width}}{style, no default} |
| 365 |
Height of the map as \TeX\ dimension. |
| 366 |
This is a style to compute \refKey{mermap/supply/height} according to |
| 367 |
the current \refKey{mermap/tile size}. |
| 368 |
\end{docMrcKey} |
| 369 |
|
| 370 |
\begin{docMrcKey}[supply]{align}{=\meta{setup alignment}}{no default, initially |center|} |
| 371 |
Alignment of reference point or area for map types \docValue{reference} and \docValue{areafit}. |
| 372 |
Feasible values are |
| 373 |
\docValue{northwest}, \docValue{north}, \docValue{northeast}, \docValue{west}, |
| 374 |
\docValue{center}, \docValue{east}, \docValue{southwest},\docValue{south}, \docValue{southeast}. |
| 375 |
\end{docMrcKey} |
| 376 |
|
| 377 |
\begin{docMrcKey}[supply]{target}{=\meta{setup target}}{no default, initially |tiles|} |
| 378 |
Defines the type of output for the Python~3 script. Feasible values are: |
| 379 |
\begin{itemize} |
| 380 |
\item\docValue{none}: No tiles are downloaded and no merged map is generated, just map computation. |
| 381 |
This is the fastest method and needs no tile supplier. |
| 382 |
\item\docValue{tiles}: Download map tiles from a tile map service (TMS) \refKey{mermap/supply/url}. |
| 383 |
Compilation of a document with map tile takes longer than compilation |
| 384 |
with a merged map and transparency should not be used with tiles, |
| 385 |
but the resulting document is smaller than a document with merged maps. |
| 386 |
\item\docValue{mergedmap}: Download map tiles from a tile map service (TMS) |
| 387 |
\refKey{mermap/supply/url} and merge them into a single map picture. |
| 388 |
This speeds compilation and allows transparency effects, but |
| 389 |
the resulting document is possibly larger than a document with map tiles, |
| 390 |
because map tiles often are optimized 8-bit image files while the merged |
| 391 |
image is a 24-bit PNG file. Additionally, synergy effects of using the same map tiles |
| 392 |
for different maps are lost. |
| 393 |
Also, since the pixel map is clipped to full pixels, the resulting map |
| 394 |
may differ (shift/size) from the more accurate tile representation by |
| 395 |
one pixel. |
| 396 |
\item\docValue{wmsmap}: Download a single map from a web map service (WMS) |
| 397 |
\refKey{mermap/supply/url}. Internally, the package treats a WMS like |
| 398 |
a tile map service including all tile calculations. Actually, a single |
| 399 |
file is downloaded. |
| 400 |
\end{itemize} |
| 401 |
\end{docMrcKey} |
| 402 |
|
| 403 |
\enlargethispage*{1cm} |
| 404 |
|
| 405 |
\begin{docMrcKey}[][doc new=2020-08-06]{fail on missing resource}{\colOpt{=true\textbar false}}{default |true|, initially |true|} |
| 406 |
If set to |true|, compilation stops with an error, if |
| 407 |
\refKey{mermap/supply/target} and \refKey{mermap/mapdef/resource} are different. |
| 408 |
Typically, this means that something went wrong while trying to download |
| 409 |
map tiles. Set this option temporarily to |false|, |
| 410 |
if the map tile service or the internet |
| 411 |
connection is expected to be unavailable only temporarily. |
| 412 |
\end{docMrcKey} |
| 413 |
|
| 414 |
|
| 415 |
|
| 416 |
\clearpage |
| 417 |
\begin{docMrcKey}[supply]{url}{=\meta{setup URL}}{no default, initially empty} |
| 418 |
Here, the url format with placeholder |{z}{x}{y}| for map tile download is defined. |
| 419 |
\textbf{Be sure that you have the permission to download, save, and use |
| 420 |
the map tiles from that URL. Illegal downloads are not endorsed in any |
| 421 |
way.} |
| 422 |
\begin{dispListing} |
| 423 |
url={https://abc.efg.hij/{z}/{x}/{y}.png?apikey=12345678}, |
| 424 |
\end{dispListing} |
| 425 |
See \Fullref{sec:maptileserver} for predefined URLs. |
| 426 |
\end{docMrcKey} |
| 427 |
|
| 428 |
|
| 429 |
\begin{docMrcKey}[supply]{url with api key}{=\marg{prefix}\marg{name}\marg{postfix}}{no default} |
| 430 |
This is an alternative version of \refKey{mermap/supply/url}. |
| 431 |
The URL is constructed from some fixed \meta{prefix} and \meta{postfix} with |
| 432 |
an API key in between. The API key is retrieved by \meta{name} from a |
| 433 |
repository filled by \refCom{mrcsetapikey}. |
| 434 |
\begin{dispListing} |
| 435 |
url={https://abc.efg.hij/{z}/{x}/{y}.png?apikey=}{myservice}{}, |
| 436 |
\end{dispListing} |
| 437 |
See \Fullref{sec:maptileserver} for predefined URLs. |
| 438 |
\end{docMrcKey} |
| 439 |
|
| 440 |
|
| 441 |
\begin{docCommand}{mrcsetapikey}{\marg{name}\marg{value}} |
| 442 |
Stores an API key \meta{value} for access with the given \meta{name}. |
| 443 |
Typically, \meta{value} is a received ID from a map tile service provider |
| 444 |
after personal registration. \meta{name} is a placeholder which is used |
| 445 |
inside \refKey{mermap/supply/url with api key} to mark the insertion |
| 446 |
point for the API key. |
| 447 |
\begin{dispListing} |
| 448 |
\mrcsetapikey{myservice}{....K942XY....} |
| 449 |
\end{dispListing} |
| 450 |
\end{docCommand} |
| 451 |
|
| 452 |
|
| 453 |
|
| 454 |
\begin{docMrcKey}[supply]{attribution}{=\meta{attribution text}}{no default, initially empty} |
| 455 |
Attribution text for the map source. Typically, it acknowledges the copyright |
| 456 |
of the map data provider. It may contain hyperlinks. |
| 457 |
It is used to set up \refKey{mermap/mapdef/attribution} afterwards |
| 458 |
and it is accessible as \docAuxCommand{mrcmapattribution} (use read-only).\par |
| 459 |
For technical reasons, do not use \verb+"+. \docAuxCommand{mrcumlaut} |
| 460 |
may be used for masking umlauts, e.g. use \verb+\mrcumlaut{u}+ instead of |
| 461 |
\verb+\"{u}+, but umlauts can also be used directly, e.g. as UTF-8 coded characters. |
| 462 |
\end{docMrcKey} |
| 463 |
|
| 464 |
\begin{docMrcKey}[supply]{attribution print}{=\meta{attribution text}}{no default, initially empty} |
| 465 |
Attribution text for the map source. |
| 466 |
In contrast to \refKey{mermap/supply/attribution} it is intended for media |
| 467 |
that does not support hyperlinks like printed posters, books, etc. |
| 468 |
It is used to set up \refKey{mermap/mapdef/attribution print} afterwards |
| 469 |
and it is accessible as \docAuxCommand{mrcmapattributionprint} (use read-only). |
| 470 |
\end{docMrcKey} |
| 471 |
|
| 472 |
\begin{docMrcKey}[supply][doc new=2026-02-17]{attribution print topplusopen}{=\meta{TT}.\meta{MM}.\meta{JJJJ}}{style} |
| 473 |
Specialized version of \refKey{mermap/supply/attribution print} |
| 474 |
as required for maps from |
| 475 |
\href{https://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}, |
| 476 |
see Section~\ref{sec:maptileserver}. |
| 477 |
\meta{TT}, \meta{MM}, and \meta{JJJJ} have to take the values of day, month, and year |
| 478 |
of the download. |
| 479 |
\begin{dispExample} |
| 480 |
\mermapsetsupply{attribution print topplusopen=17.02.2026} |
| 481 |
\mrcmapattributionprint |
| 482 |
\end{dispExample} |
| 483 |
\end{docMrcKey} |
| 484 |
|
| 485 |
|
| 486 |
\begin{docMrcKey}[supply]{basename}{=\meta{setup tile base name}}{no default, initially \texttt{tiles/tile}} |
| 487 |
Prefix for local tile files, e.g. '|tiles/map|' for '|tiles/map_10_10_10.png|'. |
| 488 |
\end{docMrcKey} |
| 489 |
|
| 490 |
|
| 491 |
\clearpage |
| 492 |
\begin{docMrcKey}[supply]{flex reference scale}{=\meta{scale denominator}}{no default} |
| 493 |
With the given \meta{scale denominator}, an appropriate \refKey{mermap/supply/zoom} |
| 494 |
and \refKey{mermap/tile size} is computed. Note that |
| 495 |
the \meta{scale denominator} |
| 496 |
always applies to the current \refKey{mermap/supply/latitude} |
| 497 |
and is used for map type \docValue{boundaries} and \docValue{reference}. |
| 498 |
For example, if the reference point is on the north side of the map, |
| 499 |
also the \meta{scale denominator} |
| 500 |
applies to the most northern latitude. |
| 501 |
|
| 502 |
Note to take special care to the order of the options. |
| 503 |
\begin{itemize} |
| 504 |
\item The reference point has to be set \emph{before} |
| 505 |
\refKey{mermap/supply/flex reference scale}, e.g. by |
| 506 |
\refKey{mermap/supply/latitude}, \refKey{mermap/supply/position}, |
| 507 |
\refKey{mermap/supply/named position}. |
| 508 |
\item \refKey{mermap/supply/tex height}, \refKey{mermap/supply/tex width} |
| 509 |
(only for map type \docValue{reference}) |
| 510 |
have to be set \emph{after} \refKey{mermap/supply/flex reference scale}, |
| 511 |
because the \refKey{mermap/tile size} is adapted. |
| 512 |
\end{itemize} |
| 513 |
Also see \refKey{mermap/flex tile size}, \refKey{mermap/flex zoom}, |
| 514 |
and \refKey{mermap/flex scale}. |
| 515 |
\tikzsetnextfilename{maptiles_flex_reference_scale}% |
| 516 |
\begin{dispExample} |
| 517 |
\begin{tikzpicture} |
| 518 |
\mrcmap[type=reference,latitude=48.14,longitude=11.57, |
| 519 |
flex reference scale=250000, |
| 520 |
source=opentopomap, |
| 521 |
tex width=\linewidth,tex height=5cm]{flex_reference_scale} |
| 522 |
\mrcdrawmap |
| 523 |
\node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south) |
| 524 |
{\mrcmapattribution}; |
| 525 |
\mrcclipmap |
| 526 |
\path[draw] (mrcmap.south west) rectangle (mrcmap.north east); |
| 527 |
\node[below left=2mm,align=right,fill=white,fill opacity=0.5, |
| 528 |
text opacity=1] at (mrcmap.north east) {scale \mrcprettymapscale}; |
| 529 |
\end{tikzpicture} |
| 530 |
\end{dispExample} |
| 531 |
\end{docMrcKey} |
| 532 |
|
| 533 |
|
| 534 |
\begin{docMrcKey}[supply]{flex area scale}{=\meta{scale denominator}}{no default} |
| 535 |
This is a shortcut for setting \refKey{mermap/supply/area to reference} |
| 536 |
and \refKey{mermap/supply/flex reference scale}=\meta{scale denominator}. |
| 537 |
Used for map type \docValue{boundaries} and \docValue{reference}. |
| 538 |
|
| 539 |
Note to take special care to the order of the options. |
| 540 |
\begin{itemize} |
| 541 |
\item The reference point has to be set \emph{before} |
| 542 |
\refKey{mermap/supply/flex area scale}. |
| 543 |
\item \refKey{mermap/supply/tex height}, \refKey{mermap/supply/tex width} |
| 544 |
(only for map type \docValue{reference}) |
| 545 |
have to be set \emph{after} \refKey{mermap/supply/flex reference scale}. |
| 546 |
\end{itemize} |
| 547 |
\end{docMrcKey} |
| 548 |
|
| 549 |
|
| 550 |
\clearpage |
| 551 |
\begin{docMrcKey}[supply]{flex area fit}{\colOpt{=\meta{size}}}{default |0pt|} |
| 552 |
This key can be used for map type \docValue{areafit} as \emph{final} |
| 553 |
option \emph{after} all other options. |
| 554 |
It applies a fine tuning to \refKey{mermap/tile size}, |
| 555 |
\refKey{mermap/supply/width}, and \refKey{mermap/supply/height} such |
| 556 |
that the defined area fits exactly into the map region. |
| 557 |
If a \meta{size} is specified, width and height are reduced for the |
| 558 |
calculation by this \meta{size}, e.g. \meta{size}|=1cm| ensures a |
| 559 |
border of |5mm| on each side. |
| 560 |
Also see \refKey{mermap/flex tile size} and \refKey{mermap/flex zoom}. |
| 561 |
|
| 562 |
\tikzsetnextfilename{maptiles_flex_area_fit}% |
| 563 |
\begin{dispExample} |
| 564 |
\begin{tikzpicture} |
| 565 |
\mrcNPdef{munich}{48.14}{11.58} |
| 566 |
\mrcNPdef{rio}{-22.91}{-43.20} |
| 567 |
\mrcNPdef{newyork}{40.71}{-74.01} |
| 568 |
\mrcmap[ type = areafit, area = {munich,rio,newyork}, |
| 569 |
source=topplusopen web grau, |
| 570 |
tex width=\linewidth, tex height=7cm, |
| 571 |
flex area fit=1cm ]{flex_area_fit} |
| 572 |
\mrcdrawmap |
| 573 |
\node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south) |
| 574 |
{\mrcmapattribution}; |
| 575 |
\draw[yellow] ([xshift=5mm,yshift=5mm]mrcmap.south west) rectangle |
| 576 |
([xshift=-5mm,yshift=-5mm]mrcmap.north east); |
| 577 |
\draw[red,fill=red!50!gray!50!white,fill opacity=0.25] |
| 578 |
(\mrcNPcs{newyork}) -- (\mrcNPcs{rio}) -- (\mrcNPcs{munich}) -- cycle; |
| 579 |
\end{tikzpicture} |
| 580 |
\end{dispExample} |
| 581 |
\end{docMrcKey} |
| 582 |
|
| 583 |
|
| 584 |
|
| 585 |
|
| 586 |
\clearpage |
| 587 |
\begin{docMrcKey}[supply]{pixel}{=\meta{setup pixel size}}{no default, initially |256|} |
| 588 |
Pixel width (and height) of a tile. It is especially needed for |
| 589 |
target \docValue{mergedmap} and also \docValue{wmsmap}. |
| 590 |
For \docValue{wmsmap}, it is multiplied with a pseudo tile calculation |
| 591 |
to compute the actual picture size to download. |
| 592 |
\end{docMrcKey} |
| 593 |
|
| 594 |
|
| 595 |
\begin{docMrcKey}[supply]{dpi}{=\meta{dpi value}}{style, no default} |
| 596 |
This style sets \refKey{mermap/supply/pixel} such that the given \meta{dpi value} |
| 597 |
is resulting (approximately). |
| 598 |
\begin{itemize} |
| 599 |
\item Note that this only applies for WMS Servers and not for |
| 600 |
TMS (Tile Map Service) Servers, |
| 601 |
because there \refKey{mermap/supply/pixel} is a fixed number depending on |
| 602 |
Server settings and cannot be chosen arbitrarily. |
| 603 |
\item A high \meta{dpi value} results in large downloaded map files. |
| 604 |
If the server does not provide a high resolution map, you will get |
| 605 |
unnecessary large files with blurred content. |
| 606 |
\item The \meta{dpi value} for TMS data can be changed by adapting |
| 607 |
\refKey{mermap/tile size} or \refKey{mermap/flex tile size}. |
| 608 |
\end{itemize} |
| 609 |
|
| 610 |
\tikzsetnextfilename{maptiles_dpi_value} |
| 611 |
\begin{dispExample} |
| 612 |
\begin{tikzpicture} |
| 613 |
\mrcmap[type=reference,latitude=48.14,longitude=11.57, |
| 614 |
flex reference scale=250000, |
| 615 |
source=topplusopen p250, target=wmsmap, dpi=300, |
| 616 |
tex width=\linewidth,tex height=5cm]{dpi_value} |
| 617 |
\mrcdrawmap |
| 618 |
\node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south) |
| 619 |
{\mrcmapattribution}; |
| 620 |
\mrcclipmap |
| 621 |
\path[draw] (mrcmap.south west) rectangle (mrcmap.north east); |
| 622 |
\end{tikzpicture} |
| 623 |
\end{dispExample} |
| 624 |
|
| 625 |
\end{docMrcKey} |
| 626 |
|
| 627 |
|
| 628 |
|
| 629 |
|
| 630 |
|
| 631 |
%------------------------------------------------------------------------------- |
| 632 |
\subsection{Map Apply} |
| 633 |
|
| 634 |
\begin{docCommand}{mrcapplymap}{\marg{definition}} |
| 635 |
A map which is supplied by \refCom{mrcsupplymap} is applied |
| 636 |
inside a |tikzpicture| environment by |
| 637 |
\refCom{mrcapplymap} where \meta{definition} identifies the map. |
| 638 |
\refCom{mrcapplymap} replaces a manual setup by \refCom{mrcdefinemap}. |
| 639 |
The same map can be applied more than once inside a document. |
| 640 |
Note that applying a map does not mean to draw the map, but to prepare |
| 641 |
everything for drawing. |
| 642 |
\end{docCommand} |
| 643 |
|
| 644 |
|
| 645 |
\begin{docCommand}{mrcmap}{\oarg{options}\marg{definition}} |
| 646 |
This is a combination of |
| 647 |
\refCom{mrcsupplymap} with the given \meta{options} |
| 648 |
followed immediately by \refCom{mrcapplymap}. |
| 649 |
If \meta{definition} is left empty, an automated unique identifier is |
| 650 |
inserted. |
| 651 |
If a map is to be used just once, \refCom{mrcmap} may be preferred. |
| 652 |
\end{docCommand} |
| 653 |
|
| 654 |
|
| 655 |
|
| 656 |
|
| 657 |
|
| 658 |
\clearpage |
| 659 |
%------------------------------------------------------------------------------- |
| 660 |
\subsection{Map Tile Server}\label{sec:maptileserver} |
| 661 |
|
| 662 |
|
| 663 |
To use map tiles with this package you obviously need access to a map tile server. |
| 664 |
Thanks to all the many contributors to |
| 665 |
\href{https://openstreetmap.org/copyright}{OpenStreetMap}, |
| 666 |
map data is free for everyone to use. |
| 667 |
\textbf{But, map tile servers based on OpenStreetMap are not necessarily free}. |
| 668 |
|
| 669 |
A list of online raster tile servers based on OpenStreetMap data is found here:\\ |
| 670 |
\url{https://wiki.openstreetmap.org/wiki/Raster_tile_providers} |
| 671 |
|
| 672 |
\begin{itemize} |
| 673 |
\item\bfseries I do not run a map tile server. |
| 674 |
\item I do not and cannot grant any permission to access a map tile server. |
| 675 |
\item I do not and cannot grant any permission to use map tiles in |
| 676 |
private, academic, free, or commercial publications. |
| 677 |
\item All operators of map tile servers require to mention an attribution |
| 678 |
for their maps. |
| 679 |
\end{itemize} |
| 680 |
|
| 681 |
The following option allows easy usage of very few selected tile servers. |
| 682 |
The tile server of \href{https://openstreetmap.org/copyright}{OpenStreetMap} |
| 683 |
is not included because of its |
| 684 |
\href{https://operations.osmfoundation.org/policies/tiles/}{Tile Usage Policy}. |
| 685 |
I am aware that the following list could be enlarged much more, but I do not |
| 686 |
want to add more to avoid any legal uncertainties. |
| 687 |
|
| 688 |
\begin{itemize} |
| 689 |
\item\bfseries I will remove an entry immediately, if the tile server operator |
| 690 |
asks for it. |
| 691 |
\item\mdseries If \textbf{YOU} operate a tile server and you want an entry here, I would be |
| 692 |
glad to add it to the following list. |
| 693 |
\end{itemize} |
| 694 |
|
| 695 |
\medskip |
| 696 |
\begin{docMrcKey}[supply]{source}{=\meta{source}}{style, no default} |
| 697 |
This style sets \refKey{mermap/supply/url}, \refKey{mermap/supply/attribution},\\ |
| 698 |
\refKey{mermap/supply/attribution print} and \refKey{mermap/supply/basename}.\\ |
| 699 |
Feasible values for \meta{source} are: |
| 700 |
%\mermapset{tile size=3.2512cm} |
| 701 |
\newcommand{\mapexample}[3][]{% |
| 702 |
\begingroup |
| 703 |
\mermapset{supply/source=#2}% |
| 704 |
\begin{itemize} |
| 705 |
\item Required attribution (\docAuxCommand{mrcmapattribution}): |
| 706 |
\begin{tcolorbox}[sharp corners,size=fbox,colback=yellow!8,colframe=yellow!80!gray,halign=flush left,before skip=2pt] |
| 707 |
\mrcmapattribution\end{tcolorbox} |
| 708 |
\item Required attribution for media without hyperlinks (\docAuxCommand{mrcmapattributionprint}): |
| 709 |
\begin{tcolorbox}[sharp corners,size=fbox,colback=yellow!8,colframe=yellow!80!gray,halign=flush left,before skip=2pt] |
| 710 |
\mrcmapattributionprint\end{tcolorbox} |
| 711 |
%\par\smallskip\ |
| 712 |
\end{itemize} |
| 713 |
\endgroup\par\smallskip\tikzsetnextfilename{maptiles_#3}% |
| 714 |
\begin{tikzpicture} |
| 715 |
\mrcmap[source=#2, |
| 716 |
type=reference,latitude=48.14,longitude=11.58,zoom=7, |
| 717 |
tex width=\linewidth,tex height=2cm,#1]{#3} |
| 718 |
\mrcdrawmap |
| 719 |
\node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south) |
| 720 |
{\mrcmapattribution}; |
| 721 |
\end{tikzpicture}\par% |
| 722 |
}% |
| 723 |
\newcommand{\mapexampletop}[3][]{% |
| 724 |
\begingroup |
| 725 |
\mermapset{supply/source=#2}% |
| 726 |
\begin{itemize} |
| 727 |
\item Required attribution (\docAuxCommand{mrcmapattribution}): |
| 728 |
\begin{tcolorbox}[sharp corners,size=fbox,colback=yellow!8,colframe=yellow!80!gray,halign=flush left,before skip=2pt] |
| 729 |
\mrcmapattribution\end{tcolorbox} |
| 730 |
\item Required attribution for media without hyperlinks (\docAuxCommand{mrcmapattributionprint}): |
| 731 |
\begin{tcolorbox}[sharp corners,size=fbox,colback=yellow!8,colframe=yellow!80!gray,halign=flush left,before skip=2pt,after skip=3pt] |
| 732 |
\mrcmapattributionprint\end{tcolorbox} |
| 733 |
Replace JJJJ by year, MM by month, TT by day of the download.\\ |
| 734 |
Also see \refKey{mermap/supply/attribution print topplusopen} |
| 735 |
%\par\smallskip\ |
| 736 |
\end{itemize} |
| 737 |
\endgroup\par\smallskip\tikzsetnextfilename{maptiles_#3}% |
| 738 |
\begin{tikzpicture} |
| 739 |
\mrcmap[source=#2, |
| 740 |
type=reference,latitude=48.14,longitude=11.58,zoom=7, |
| 741 |
tex width=\linewidth,tex height=2cm,#1]{#3} |
| 742 |
\mrcdrawmap |
| 743 |
\node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south) |
| 744 |
{\mrcmapattribution}; |
| 745 |
\end{tikzpicture}\par% |
| 746 |
}% |
| 747 |
\begin{itemize} |
| 748 |
|
| 749 |
\item\docValue{dummy}:\\ |
| 750 |
Dummy tile server at loopback |127.0.0.1| for test purposes. |
| 751 |
|
| 752 |
\item\docValue{opentopomap}:\\ |
| 753 |
Tile server (TMS) of \href{https://opentopomap.org/}{OpenTopoMap}. |
| 754 |
\begin{itemize} |
| 755 |
\item Usage (German language): \url{https://opentopomap.org/about#verwendung} |
| 756 |
\end{itemize} |
| 757 |
\mapexample{opentopomap}{opentopomap} |
| 758 |
|
| 759 |
\clearpage |
| 760 |
\item\docValue{thunderforest opencyclemap}:\\ |
| 761 |
Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ |
| 762 |
A registered \meta{api-key} is needed (free plan available) |
| 763 |
which is applied by\\ |
| 764 |
\refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. |
| 765 |
\begin{itemize} |
| 766 |
\item Usage: \url{https://www.thunderforest.com/terms} |
| 767 |
\item API documentation: \url{https://www.thunderforest.com/maps/opencyclemap} |
| 768 |
\end{itemize} |
| 769 |
\mapexample{thunderforest opencyclemap}{thunderforest_opencyclemap} |
| 770 |
|
| 771 |
\item\docValue{thunderforest transport}:\\ |
| 772 |
Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ |
| 773 |
A registered \meta{api-key} is needed (free plan available) |
| 774 |
which is applied by\\ |
| 775 |
\refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. |
| 776 |
\begin{itemize} |
| 777 |
\item Usage: \url{https://www.thunderforest.com/terms} |
| 778 |
\item API documentation: \url{https://www.thunderforest.com/maps/transport} |
| 779 |
\end{itemize} |
| 780 |
\mapexample{thunderforest transport}{thunderforest_transport} |
| 781 |
|
| 782 |
\item\docValue{thunderforest landscape}:\\ |
| 783 |
Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ |
| 784 |
A registered \meta{api-key} is needed (free plan available) |
| 785 |
which is applied by\\ |
| 786 |
\refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. |
| 787 |
\begin{itemize} |
| 788 |
\item Usage: \url{https://www.thunderforest.com/terms} |
| 789 |
\item API documentation: \url{https://www.thunderforest.com/maps/landscape} |
| 790 |
\end{itemize} |
| 791 |
\mapexample{thunderforest landscape}{thunderforest_landscape} |
| 792 |
|
| 793 |
\clearpage |
| 794 |
\item\docValue{thunderforest outdoors}:\\ |
| 795 |
Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ |
| 796 |
A registered \meta{api-key} is needed (free plan available) |
| 797 |
which is applied by\\ |
| 798 |
\refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. |
| 799 |
\begin{itemize} |
| 800 |
\item Usage: \url{https://www.thunderforest.com/terms} |
| 801 |
\item API documentation: \url{https://www.thunderforest.com/maps/outdoors} |
| 802 |
\end{itemize} |
| 803 |
\mapexample{thunderforest outdoors}{thunderforest_outdoors} |
| 804 |
|
| 805 |
\item\docValue{thunderforest atlas}:\tcbdocmarginnote{\tcbdocnew{2024-07-29}}\\ |
| 806 |
Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ |
| 807 |
A registered \meta{api-key} is needed (free plan available) |
| 808 |
which is applied by\\ |
| 809 |
\refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. |
| 810 |
\begin{itemize} |
| 811 |
\item Usage: \url{https://www.thunderforest.com/terms} |
| 812 |
\item API documentation: \url{https://www.thunderforest.com/maps/atlas} |
| 813 |
\end{itemize} |
| 814 |
\mapexample{thunderforest atlas}{thunderforest_atlas} |
| 815 |
|
| 816 |
\item\docValue{thunderforest transport-dark}:\\ |
| 817 |
Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ |
| 818 |
A registered \meta{api-key} is needed (free plan available) |
| 819 |
which is applied by\\ |
| 820 |
\refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. |
| 821 |
\begin{itemize} |
| 822 |
\item Usage: \url{https://www.thunderforest.com/terms} |
| 823 |
\item API documentation: \url{https://www.thunderforest.com/maps/transport-dark} |
| 824 |
\end{itemize} |
| 825 |
\mapexample{thunderforest transport-dark}{thunderforest_transport-dark} |
| 826 |
|
| 827 |
\clearpage |
| 828 |
\item\docValue{thunderforest spinal-map}:\\ |
| 829 |
Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ |
| 830 |
A registered \meta{api-key} is needed (free plan available) |
| 831 |
which is applied by\\ |
| 832 |
\refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. |
| 833 |
\begin{itemize} |
| 834 |
\item Usage: \url{https://www.thunderforest.com/terms} |
| 835 |
\item API documentation: \url{https://www.thunderforest.com/maps/spinal-map} |
| 836 |
\end{itemize} |
| 837 |
\mapexample{thunderforest spinal-map}{thunderforest_spinal-map} |
| 838 |
|
| 839 |
\item\docValue{thunderforest pioneer}:\\ |
| 840 |
Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ |
| 841 |
A registered \meta{api-key} is needed (free plan available) |
| 842 |
which is applied by\\ |
| 843 |
\refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. |
| 844 |
\begin{itemize} |
| 845 |
\item Usage: \url{https://www.thunderforest.com/terms} |
| 846 |
\item API documentation: \url{https://www.thunderforest.com/maps/pioneer} |
| 847 |
\end{itemize} |
| 848 |
\mapexample{thunderforest pioneer}{thunderforest_pioneer} |
| 849 |
|
| 850 |
\item\docValue{thunderforest mobile-atlas}:\\ |
| 851 |
Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ |
| 852 |
A registered \meta{api-key} is needed (free plan available) |
| 853 |
which is applied by\\ |
| 854 |
\refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. |
| 855 |
\begin{itemize} |
| 856 |
\item Usage: \url{https://www.thunderforest.com/terms} |
| 857 |
\item API documentation: \url{https://www.thunderforest.com/maps/mobile-atlas} |
| 858 |
\end{itemize} |
| 859 |
\mapexample{thunderforest mobile-atlas}{thunderforest_mobile-atlas} |
| 860 |
|
| 861 |
\clearpage |
| 862 |
\item\docValue{thunderforest neighbourhood}:\\ |
| 863 |
Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\ |
| 864 |
A registered \meta{api-key} is needed (free plan available) |
| 865 |
which is applied by\\ |
| 866 |
\refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}. |
| 867 |
\begin{itemize} |
| 868 |
\item Usage: \url{https://www.thunderforest.com/terms} |
| 869 |
\item API documentation: \url{https://www.thunderforest.com/maps/neighbourhood} |
| 870 |
\end{itemize} |
| 871 |
\mapexample{thunderforest neighbourhood}{thunderforest_neighbourhood} |
| 872 |
|
| 873 |
\item\docValue{topplusopen web}:\tcbdocmarginnote{\tcbdocupdated{2026-02-17}}\\ |
| 874 |
Tile server (TMS) of \href{https://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}. |
| 875 |
\begin{itemize} |
| 876 |
\item Covers world / Europe / Germany depending on zoom level |
| 877 |
\item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/topplusopen-produkte.html} |
| 878 |
\end{itemize} |
| 879 |
\mapexampletop{topplusopen web}{topplusopen_web} |
| 880 |
|
| 881 |
\clearpage |
| 882 |
\item\docValue{topplusopen web grau}:\tcbdocmarginnote{\tcbdocupdated{2026-02-17}}\\ |
| 883 |
Tile server (TMS) of \href{https://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}. |
| 884 |
\begin{itemize} |
| 885 |
\item Covers world / Europe / Germany depending on zoom level |
| 886 |
\item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/topplusopen-produkte.html} |
| 887 |
\end{itemize} |
| 888 |
\mapexampletop{topplusopen web grau}{topplusopen_web_grau} |
| 889 |
|
| 890 |
\item\docValue{topplusopen web light}:\tcbdocmarginnote{\tcbdocnew{2024-07-29}\\\tcbdocupdated{2026-02-17}}\\ |
| 891 |
Tile server (TMS) of \href{https://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}. |
| 892 |
\begin{itemize} |
| 893 |
\item Covers world / Europe / Germany depending on zoom level |
| 894 |
\item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/topplusopen-produkte.html} |
| 895 |
\end{itemize} |
| 896 |
\mapexampletop{topplusopen web light}{topplusopen_web_light} |
| 897 |
|
| 898 |
\clearpage |
| 899 |
\item\docValue{topplusopen web light grau}\tcbdocmarginnote{\tcbdocnew{2024-07-29}\\\tcbdocupdated{2026-02-17}}:\\ |
| 900 |
Tile server (TMS) of \href{https://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}. |
| 901 |
\begin{itemize} |
| 902 |
\item Covers world / Europe / Germany depending on zoom level |
| 903 |
\item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/topplusopen-produkte.html} |
| 904 |
\end{itemize} |
| 905 |
\mapexampletop{topplusopen web light grau}{topplusopen_web_light_grau} |
| 906 |
|
| 907 |
\end{itemize} |
| 908 |
|
| 909 |
|
| 910 |
\clearpage |
| 911 |
\begin{tcolorbox}[spartan,colback=white] |
| 912 |
The following sources are Web map server (WMS). Therefore, |
| 913 |
\refKey{mermap/supply/target} can only be set to \docValue{wmsmap} |
| 914 |
or \docValue{none}. |
| 915 |
\end{tcolorbox} |
| 916 |
|
| 917 |
|
| 918 |
\begingroup |
| 919 |
\ExplSyntaxOn |
| 920 |
\int_gzero_new:N \l__mermap_doc_tmpa_int |
| 921 |
\NewDocumentCommand \cleanstep {} |
| 922 |
{ |
| 923 |
\bool_lazy_and:nnT |
| 924 |
{ |
| 925 |
\int_compare_p:nNn \l__mermap_doc_tmpa_int > 0 |
| 926 |
} |
| 927 |
{ |
| 928 |
\int_compare_p:nNn { \int_mod:nn { \l__mermap_doc_tmpa_int }{ 2 } } = 0 |
| 929 |
} |
| 930 |
{ |
| 931 |
\clearpage |
| 932 |
} |
| 933 |
\int_gincr:N \l__mermap_doc_tmpa_int |
| 934 |
} |
| 935 |
\ExplSyntaxOff |
| 936 |
|
| 937 |
\begin{itemize} |
| 938 |
|
| 939 |
\foreach \name / \scdenom / \xtra in {p5/5000,p10/10000,p17.5/17500,p25/25000,p50/50000,p100/100000,p250/250000} |
| 940 |
{ |
| 941 |
\cleanstep |
| 942 |
\item\docValue{topplusopen \name}:\tcbdocmarginnote{\tcbdocupdated{2026-02-17}}\\ |
| 943 |
Web map server (WMS) of \href{https://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}. |
| 944 |
\begin{itemize} |
| 945 |
\item 1:\scdenom, covers Europe / Germany depending on zoom level |
| 946 |
\item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/topplusopen-produkte.html} |
| 947 |
\end{itemize} |
| 948 |
\mapexampletop[target=wmsmap]{topplusopen \name}{topplusopen_\name} |
| 949 |
|
| 950 |
\cleanstep |
| 951 |
\item\docValue{topplusopen \name\ grau}:\tcbdocmarginnote{\tcbdocupdated{2026-02-17}}\\ |
| 952 |
Web map server (WMS) of \href{https://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}. |
| 953 |
\begin{itemize} |
| 954 |
\item 1:\scdenom, covers Europe / Germany depending on zoom level |
| 955 |
\item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/digitale-geodaten/topplusopen-produkte.html} |
| 956 |
\end{itemize} |
| 957 |
\def\grau{ grau}% |
| 958 |
\mapexampletop[target=wmsmap]{topplusopen \name\grau}{topplusopen_\name_grau} |
| 959 |
} |
| 960 |
|
| 961 |
\end{itemize} |
| 962 |
\endgroup |
| 963 |
|
| 964 |
\end{docMrcKey} |
| 965 |
|
| 966 |
|
| 967 |
|
| 968 |
\begin{docCommand}{mrcnewsupplysource}{\marg{source}\marg{options}} |
| 969 |
Adds a new \meta{source} value to \refKey{mermap/supply/source}. |
| 970 |
The \meta{options} should set the keys |
| 971 |
\refKey{mermap/supply/url}, \refKey{mermap/supply/attribution},\\ |
| 972 |
\refKey{mermap/supply/attribution print} and \refKey{mermap/supply/basename}. |
| 973 |
It is recommend to use |x ...| for \meta{source} to avoid conflicts |
| 974 |
with future official additions to \refKey{mermap/supply/source}. |
| 975 |
\begin{dispListing} |
| 976 |
\mrcnewsupplysource{x example} |
| 977 |
{ |
| 978 |
url = https://127.0.0.1/dummy/{z}/{x}/{y}.png, |
| 979 |
attribution = {Dummy tile server}, |
| 980 |
attribution print = {Dummy tile server}, |
| 981 |
basename = tiles/dummy, |
| 982 |
} |
| 983 |
\end{dispListing} |
| 984 |
\end{docCommand} |
| 985 |
|
| 986 |
|