| 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} |