% !TeX root = mercatormap.tex
% !TeX encoding=UTF-8
% !TeX spellcheck=en_US
% include file of mercatormap.tex (manual of the LaTeX package mercatormap)
\clearpage
\section{Introduction}%

The \texttt{mercatormap} package enables map drawing with the
Web Mercator projection. This is done as an extension to
\tikzname\ \cite{package:tikz} with is complemented by a map
coordinate system and many additional commands and options to add elements
like markers, geodetic networks, bar scales, routes, orthodrome
pieces, distance calculations, etc. Also, the seamless integration of graphics
from public map tile servers is provided through a Python script.

If you are interested in the mathematical background of the Web Mercator projection
and the algorithms of this packages, you are invited to read
\enquote{\fullcite{Sturm:2020}}.

With very few exceptions, the package is programmed with the
L3 programming layer for \LaTeX3 \cite{package:interface3}.

\medskip


\tikzsetnextfilename{intro_example}%
\begin{tikzpicture}
  \mrcmap[
      type=reference,
      position=48.1579577:11.4980376,
      align=west,
      flex reference scale=20000,
      tex width=\linewidth,
      tex height=5cm,
      source=topplusopen web
    ]{intro_example}
  \mrcdrawmap
  \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south) {\mrcmapattribution};
  \node[above right, font=\sffamily\footnotesize] at (mrcmap.north west) {\mrcprettymapscale};
  \mrcdrawscalebar[width-in-meter=800,partitions=8,north-east-outside=5mm;1.5mm,
    major style={black!75}]
  \path[every node/.style={above,inner sep=0.5mm,font=\sffamily\tiny}]
    (mrcscalebar.north west) -- (mrcscalebar.north east)
    node[pos=0]{0} node[pos=0.25]{200} node[pos=0.5]{400} node[pos=0.75]{600}
    node[pos=1]{800} node[pos=1,right,yshift=-1mm]{m};
  \mrcdrawnetwork
  \mrcmarker{type=pin, draw=Blue_Gray, fill=Blue_Gray!10, font=\sffamily\footnotesize,
    position=48.1582513:11.5032997, contents={Nymphenburg}}
  \mrcclipmap
  \draw (mrcmap.south west) rectangle (mrcmap.north east);
\end{tikzpicture}



%-------------------------------------------------------------------------------
\subsection{Quick Start}

The package is accompanied with a Python script. You should read
\Fullref{sec:python} for the Python preparations.
The package can be used in three ways:
\begin{itemize}
\item Completely without the Python script.
  This is not recommended, because the usage will be quite restricted.
\item With Python script, but without map tile download.
  There is no usage restriction, but you have to create all content yourself.
  To prevent map tile download, set
  \begin{dispListing}
  \mermapset{supply/target=none}
  \end{dispListing}
\item With Python script and map tile download.
  You need permission and access to a map tile server.
  \Fullref{sec:maptileserver} lists a selection of servers with free
  access (some require registration of an API key).
\end{itemize}

Once Python has been set up, you can try compiling |mercatormap-example.tex|
(located in the documentation directory), which contains a map of Bavaria
including map tile downloads.

\Fullref{sec:examples} presents additional examples that may serve as tutorials
illustrating what can be achieved.
Following the examples, the package reference manual is provided.

\clearpage
%-------------------------------------------------------------------------------
\subsection{Installation of Python and Packages}\label{sec:python}

A Python~3 script is part of the |mercatormap| package.
The main purpose of this script is to download selected map tiles for
the maps of the document. Also, some coordinate system computation is
done by this script.

\subsubsection{Python 3}
Python 3 is a required prerequisite and can be downloaded from\\
\url{https://www.python.org/downloads/}\\
On systems like Linux Python is typically already installed.\par
To test your installation, type into a command or terminal window:
\begin{dispListing}
  python --version
\end{dispListing}
This should give a version number starting with 3. Otherwise, try
\begin{dispListing}
  python3 --version
\end{dispListing}
If this is successful, \refKey{mermap/python} has to be adapted to |python3|

\subsubsection{Python Packages}
The Python packages |Pillow| (\url{https://pypi.org/project/pillow/})
and |Requests| (\url{https://pypi.org/project/requests/}) have to be present.
With some luck, they are already installed. With
\begin{dispListing}
  pip list
\end{dispListing}
the installed packages are listed. If |Pillow| and |Requests| are not
among these package, they have to be added by
\begin{dispListing}
  pip install pillow requests
\end{dispListing}

As an alternative to a system-wide or user-level installation, a virtual environment
can be created and used within the document directory, for example:
\begin{dispListing}
  python -m venv .venv
  .venv\Scripts\python -m pip install pillow requests    # Windows
  .venv/bin/python -m pip install pillow requests        # Linux
\end{dispListing}
\refKey{mermap/python} has to be adapted for this virtual environment.
For Windows this is done by
\begin{dispListing}
\ExplSyntaxOn
\mermapset{python=.venv \c_backslash_str Scripts \c_backslash_str python}
\ExplSyntaxOff
\end{dispListing}
and for Linux by
\begin{dispListing}
\mermapset{python=.venv/bin/python}
\end{dispListing}
Pythonians know further installation methods.

\subsubsection{Document Setup}
For your map document you need the following:
\begin{itemize}
\item Add \refCom{mrcactivatescript} to the document preamble.
  Without this command, the script is not active.
\item Compile the map document with the |--shell-escape| compiler option.
  This allows to execute external programs like the Python script.\\
  \textbf{Be aware that |-||-shell-escape| should only be used
    with trusted documents. Note that external programs can do anything!}
\end{itemize}




%\subsection{Tutorial: Map without external Graphics}


%\subsection{Tutorial: Map with downloaded Map Tiles}