Debian Codegraph @

texmf-dist/doc/latex/mercatormap/mercatormap.doc.maptiles.tex

raw
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