From 36db81e567665da0b8e92831b69d2a71971312f3 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 20 Apr 2020 21:10:20 +0000 Subject: mercatormap (20apr20) git-svn-id: svn://tug.org/texlive/trunk@54812 c570f23f-e606-0410-a88d-b1316a301751 --- .../latex/mercatormap/mercatormap.doc.intro.tex | 150 +++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/mercatormap/mercatormap.doc.intro.tex (limited to 'Master/texmf-dist/doc/latex/mercatormap/mercatormap.doc.intro.tex') diff --git a/Master/texmf-dist/doc/latex/mercatormap/mercatormap.doc.intro.tex b/Master/texmf-dist/doc/latex/mercatormap/mercatormap.doc.intro.tex new file mode 100644 index 00000000000..294f5e278fc --- /dev/null +++ b/Master/texmf-dist/doc/latex/mercatormap/mercatormap.doc.intro.tex @@ -0,0 +1,150 @@ +% !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 +|expl3| \cite{package:expl3} programming interface for \LaTeX3 +and loads the packages +|xparse| \cite{package:xparse} and |siunitx| \cite{package:siunitx}. + +\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} + +After Python is prepared, you may try to compile +|mercatormap-example.tex| (found in the documentation directory) +which contains a map of Bavaria with map tile download. +\Fullref{sec:examples} exhibits further examples which may serve as +tutorials what can be done. After the examples you find the reference +manual for the package. + +\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} + pip3 list +\end{dispListing} +and/or +\begin{dispListing} + pip3 list --user +\end{dispListing} +the installed packages are listed. If |Pillow| and |requests| are not +among these package, they have to be added by +\begin{dispListing} + pip3 install --user Pillow + pip3 install --user requests +\end{dispListing} +or +\begin{dispListing} + pip3 install Pillow + pip3 install requests +\end{dispListing} +The second choice needs administrative rights and may give conflicts +with package managers. Pythonians know furthers 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} -- cgit v1.2.3