Debian Codegraph @

texmf-dist/doc/latex/mercatormap/mercatormap.doc.intro.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{Introduction}%
7
8 The \texttt{mercatormap} package enables map drawing with the
9 Web Mercator projection. This is done as an extension to
10 \tikzname\ \cite{package:tikz} with is complemented by a map
11 coordinate system and many additional commands and options to add elements
12 like markers, geodetic networks, bar scales, routes, orthodrome
13 pieces, distance calculations, etc. Also, the seamless integration of graphics
14 from public map tile servers is provided through a Python script.
15
16 If you are interested in the mathematical background of the Web Mercator projection
17 and the algorithms of this packages, you are invited to read
18 \enquote{\fullcite{Sturm:2020}}.
19
20 With very few exceptions, the package is programmed with the
21 L3 programming layer for \LaTeX3 \cite{package:interface3}.
22
23 \medskip
24
25
26 \tikzsetnextfilename{intro_example}%
27 \begin{tikzpicture}
28 \mrcmap[
29 type=reference,
30 position=48.1579577:11.4980376,
31 align=west,
32 flex reference scale=20000,
33 tex width=\linewidth,
34 tex height=5cm,
35 source=topplusopen web
36 ]{intro_example}
37 \mrcdrawmap
38 \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south) {\mrcmapattribution};
39 \node[above right, font=\sffamily\footnotesize] at (mrcmap.north west) {\mrcprettymapscale};
40 \mrcdrawscalebar[width-in-meter=800,partitions=8,north-east-outside=5mm;1.5mm,
41 major style={black!75}]
42 \path[every node/.style={above,inner sep=0.5mm,font=\sffamily\tiny}]
43 (mrcscalebar.north west) -- (mrcscalebar.north east)
44 node[pos=0]{0} node[pos=0.25]{200} node[pos=0.5]{400} node[pos=0.75]{600}
45 node[pos=1]{800} node[pos=1,right,yshift=-1mm]{m};
46 \mrcdrawnetwork
47 \mrcmarker{type=pin, draw=Blue_Gray, fill=Blue_Gray!10, font=\sffamily\footnotesize,
48 position=48.1582513:11.5032997, contents={Nymphenburg}}
49 \mrcclipmap
50 \draw (mrcmap.south west) rectangle (mrcmap.north east);
51 \end{tikzpicture}
52
53
54
55 %-------------------------------------------------------------------------------
56 \subsection{Quick Start}
57
58 The package is accompanied with a Python script. You should read
59 \Fullref{sec:python} for the Python preparations.
60 The package can be used in three ways:
61 \begin{itemize}
62 \item Completely without the Python script.
63 This is not recommended, because the usage will be quite restricted.
64 \item With Python script, but without map tile download.
65 There is no usage restriction, but you have to create all content yourself.
66 To prevent map tile download, set
67 \begin{dispListing}
68 \mermapset{supply/target=none}
69 \end{dispListing}
70 \item With Python script and map tile download.
71 You need permission and access to a map tile server.
72 \Fullref{sec:maptileserver} lists a selection of servers with free
73 access (some require registration of an API key).
74 \end{itemize}
75
76 Once Python has been set up, you can try compiling |mercatormap-example.tex|
77 (located in the documentation directory), which contains a map of Bavaria
78 including map tile downloads.
79
80 \Fullref{sec:examples} presents additional examples that may serve as tutorials
81 illustrating what can be achieved.
82 Following the examples, the package reference manual is provided.
83
84 \clearpage
85 %-------------------------------------------------------------------------------
86 \subsection{Installation of Python and Packages}\label{sec:python}
87
88 A Python~3 script is part of the |mercatormap| package.
89 The main purpose of this script is to download selected map tiles for
90 the maps of the document. Also, some coordinate system computation is
91 done by this script.
92
93 \subsubsection{Python 3}
94 Python 3 is a required prerequisite and can be downloaded from\\
95 \url{https://www.python.org/downloads/}\\
96 On systems like Linux Python is typically already installed.\par
97 To test your installation, type into a command or terminal window:
98 \begin{dispListing}
99 python --version
100 \end{dispListing}
101 This should give a version number starting with 3. Otherwise, try
102 \begin{dispListing}
103 python3 --version
104 \end{dispListing}
105 If this is successful, \refKey{mermap/python} has to be adapted to |python3|
106
107 \subsubsection{Python Packages}
108 The Python packages |Pillow| (\url{https://pypi.org/project/pillow/})
109 and |Requests| (\url{https://pypi.org/project/requests/}) have to be present.
110 With some luck, they are already installed. With
111 \begin{dispListing}
112 pip list
113 \end{dispListing}
114 the installed packages are listed. If |Pillow| and |Requests| are not
115 among these package, they have to be added by
116 \begin{dispListing}
117 pip install pillow requests
118 \end{dispListing}
119
120 As an alternative to a system-wide or user-level installation, a virtual environment
121 can be created and used within the document directory, for example:
122 \begin{dispListing}
123 python -m venv .venv
124 .venv\Scripts\python -m pip install pillow requests # Windows
125 .venv/bin/python -m pip install pillow requests # Linux
126 \end{dispListing}
127 \refKey{mermap/python} has to be adapted for this virtual environment.
128 For Windows this is done by
129 \begin{dispListing}
130 \ExplSyntaxOn
131 \mermapset{python=.venv \c_backslash_str Scripts \c_backslash_str python}
132 \ExplSyntaxOff
133 \end{dispListing}
134 and for Linux by
135 \begin{dispListing}
136 \mermapset{python=.venv/bin/python}
137 \end{dispListing}
138 Pythonians know further installation methods.
139
140 \subsubsection{Document Setup}
141 For your map document you need the following:
142 \begin{itemize}
143 \item Add \refCom{mrcactivatescript} to the document preamble.
144 Without this command, the script is not active.
145 \item Compile the map document with the |--shell-escape| compiler option.
146 This allows to execute external programs like the Python script.\\
147 \textbf{Be aware that |-||-shell-escape| should only be used
148 with trusted documents. Note that external programs can do anything!}
149 \end{itemize}
150
151
152
153
154 %\subsection{Tutorial: Map without external Graphics}
155
156
157 %\subsection{Tutorial: Map with downloaded Map Tiles}