% !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{Orthodromes and Loxodromes}\label{sec:orthodromes}%

A loxodrome is a curve which crosses all meridians with
a constant angle. On Mercator maps, loxodromes are depicted as straight lines
and can be drawn by simple \tikzname\ |path| elements.

On a sphere, the shortest path
from one point to another runs along an orthodrome where
an orthodrome is a great-circle.

The mathematical background and further information are found in \cite{Sturm:2020}.


%-------------------------------------------------------------------------------
\subsection{Orthodrome Drawing}

\begin{docMrcKey}{samples}{=\meta{number}}{no default, initially |100|}
  An orthodrome curve is approximated by a polygon trajectory with
  \meta{number} pieces.
\end{docMrcKey}


\begin{docTikzKey}{mermap samples}{=\meta{number}}{style, no default}
  \tikzname\ variant to set \refKey{mermap/samples}.
\end{docTikzKey}

\enlargethispage*{1cm}

\begin{docCommand}{mrcdraworthodrome}{\oarg{options}\marg{lat1}\marg{lon1}\marg{lat2}\marg{lon2}}
  Draws an orthodrome curve from a point with
  latitude \meta{lat1} and longitude \meta{lon1}
  to a point with
  latitude \meta{lat2} and longitude \meta{lon2}.
  This is a \tikzname\ path object where \meta{options} are
  \tikzname\ settings for this path. There are two orthodrome pieces connecting
  two positions (forming a great-circle). \refCom{mrcdraworthodrome} does
  not necessarily choose the shorter one, see \cite{Sturm:2020}.
  The drawn orthodrome is a spherical approximation instead of an ellipsoidal
  one.
  \tikzsetnextfilename{ortho_orthodrome1}%
  \begin{dispExample}
    \begin{tikzpicture}
      \mrcmap[type=areafit,
          south=40.7,north=48.2,west=-74.1,east=11.6,
          source=topplusopen web,
          tex width=\linewidth,tex height=6cm,
        ]{ortho_orthodrome1}
        \mrcdrawmap
        \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south)
          {\mrcmapattribution};
        \mrcclipmap
      \draw (mrcmap.south west) rectangle (mrcmap.north east);
      \mrcdraworthodrome[red,very thick,mermap samples=100]
         {48.14}{11.58}{40.71}{-74.01}
      \node[red,fill=white] at ([above=1.3cm]mrcmap) {
        \mrcprettyorthodistance{48.14}{11.58}{40.71}{-74.01} };
    \end{tikzpicture}
  \end{dispExample}
\end{docCommand}


\clearpage
\begin{docCommand}{mrcNPdraworthodrome}{\oarg{options}\marg{name1}\marg{name2}}
  Identical to \refCom{mrcdraworthodrome}, but the start and end point are
  described by named positions \meta{name1} and \meta{name2}.

  \tikzsetnextfilename{ortho_orthodrome2}%
  \begin{dispExample}
    \begin{tikzpicture}
      \mrcNPdef{munich}{48.14}{11.58}
      \mrcNPdef{newyork}{40.71}{-74.01}
      \mrcmap[type=areafit, area={munich,newyork},
          source=topplusopen web,
          tex width=\linewidth,tex height=6cm,
          ]{ortho_orthodrome2}
        \mrcdrawmap
        \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south)
          {\mrcmapattribution};
        \mrcclipmap
      \draw (mrcmap.south west) rectangle (mrcmap.north east);
      \mrcmarker{type=pin,named position=munich,contents={M\"unchen}}
      \mrcmarker{type=pinflip,shift=5mm,named position=newyork,
        contents={New York City}}
      \mrcNPdraworthodrome[red,very thick] {munich}{newyork}
      \draw[blue,very thick] (\mrcNPcs{munich}) -- (\mrcNPcs{newyork});
      \node[red,fill=white] at ([above=1.3cm]mrcmap) {
        \mrcNPprettyorthodistance{munich}{newyork} };
      \node[blue,fill=white] at ([below=5mm]mrcmap) {
        \mrcNPprettyloxodistance{munich}{newyork} };
    \end{tikzpicture}
  \end{dispExample}
\end{docCommand}


\clearpage
%-------------------------------------------------------------------------------
\subsection{Orthodrome Points}

\begin{docCommands}[
  ]{
    {
      doc new and updated = {2024-08-01}{2024-08-05},
      doc name        = mrcNPfromOrthoFraction,
      doc parameter   = \marg{name}\oarg{\textbackslash angle}\marg{lat1}\marg{lon1}\marg{lat2}\marg{lon2}\marg{fraction},
    },
    {
      doc name        = mrcNPfromOrthoFractionNamed,
      doc parameter   = \marg{name}\oarg{\textbackslash angle}\marg{name1}\marg{name2}\marg{fraction},
    },
  }
  Defines a new named position \meta{name} which is located on a \meta{fraction}
  from the starting point of the orthodromic curve
  from a point with
  latitude \meta{lat1} and longitude \meta{lon1} (or described by a named position \meta{name1})
  to a point with
  latitude \meta{lat2} and longitude \meta{lon2} (or described by a named position \meta{name2}).
  The given starting and final point of the orthodrome need to have a distance of more than
  \SI{1}{\meter}.
  If \meta{\textbackslash angle} is given, this macro is set to the
  angle between the tangent vector to the orthodrome and
  the current parallel circle.

\tikzsetnextfilename{ortho_orthodrome3}%
\begin{dispExample}
  \begin{tikzpicture}
    \mrcNPdef{munich}{48.14}{11.58}
    \mrcNPdef{newyork}{40.71}{-74.01}
    \mrcmap[type=areafit, area={munich,newyork},
        source=topplusopen web,
        tex width=\linewidth,tex height=6cm,
        ]{ortho_orthodrome3}
      \mrcdrawmap
      \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south)
        {\mrcmapattribution};
      \mrcclipmap
    \draw (mrcmap.south west) rectangle (mrcmap.north east);
    \mrcmarker{type=pin,named position=munich,contents={M\"unchen}}
    \mrcmarker{type=pinflip,shift=5mm,named position=newyork,
      contents={New York City}}
    \mrcNPdraworthodrome[red,very thick] {munich}{newyork}
    \foreach \fraction in { 0.1,0.3,0.5,0.7,1.0,1.1 }
      {
        \mrcNPfromOrthoFractionNamed{waypoint}[\myangle]
          {munich}{newyork}{\fraction}
        \mrcmarker{type=pin,named position=waypoint,
          contents={\fraction: \fpeval{round(\myangle)}\textdegree }}
      }
  \end{tikzpicture}
\end{dispExample}
\end{docCommands}

\clearpage

\begin{docCommands}[
  ]{
    {
      doc new and updated = {2024-08-01}{2024-08-05},
      doc name        = mrcNPfromOrthoDistance,
      doc parameter   = \marg{name}\oarg{\textbackslash angle}\marg{lat1}\marg{lon1}\marg{lat2}\marg{lon2}\marg{distance},
    },
    {
      doc name        = mrcNPfromOrthoDistanceNamed,
      doc parameter   = \marg{name}\oarg{\textbackslash angle}\marg{name1}\marg{name2}\marg{distance},
    },
  }
  Defines a new named position \meta{name} which is located on a \meta{distance}
  from the starting point of the orthodromic curve
  from a point with
  latitude \meta{lat1} and longitude \meta{lon1} (or described by a named position \meta{name1})
  to a point with
  latitude \meta{lat2} and longitude \meta{lon2} (or described by a named position \meta{name2}).
  The given starting and final point of the orthodrome need to have a distance of more than
  \SI{1}{\meter}. The unit for the \meta{distance} is kilometer.
  If \meta{\textbackslash angle} is given, this macro is set to the
  angle between the tangent vector to the orthodrome and
  the current parallel circle.

\tikzsetnextfilename{ortho_orthodrome4}%
\begin{dispExample}
  \begin{tikzpicture}
    \mrcNPdef{munich}{48.14}{11.58}
    \mrcNPdef{newyork}{40.71}{-74.01}
    \mrcmap[type=areafit, area={munich,newyork},
        source=topplusopen web,
        tex width=\linewidth,tex height=6cm,
        ]{ortho_orthodrome4}
      \mrcdrawmap
      \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south)
        {\mrcmapattribution};
      \mrcclipmap
    \draw (mrcmap.south west) rectangle (mrcmap.north east);
    \mrcmarker{type=pin,named position=munich,contents={M\"unchen}}
    \mrcmarker{type=pinflip,shift=5mm,named position=newyork,
      contents={New York City}}
    \mrcNPdraworthodrome[red,very thick] {munich}{newyork}
    \foreach \distance in { 1000,2000,3000,4000,5000,6000 }
      {
        \mrcNPfromOrthoDistanceNamed{waypoint}{munich}{newyork}{\distance}
        \mrcmarker{type=pin,named position=waypoint,
            contents={\SI{\distance}{\kilo\meter}}}
      }
  \end{tikzpicture}
\end{dispExample}
\end{docCommands}




\clearpage
%-------------------------------------------------------------------------------
\subsection{Orthodromic and Loxodromic Distances}

\begin{docCommand}{mrcprettyorthodistance}{\marg{lat1}\marg{lon1}\marg{lat2}\marg{lon2}}
  Approximate orthodromic distance between two points
  with latitude \meta{lat1}, longitude \meta{lon1}
  and latitude \meta{lat2}, longitude \meta{lon2}
  with three valid digits.
  \begin{dispExample}
  \mrcprettyorthodistance{48.14}{11.58}{40.71}{-74.01}
  \end{dispExample}
\end{docCommand}


\begin{docCommand}{mrcNPprettyorthodistance}{\marg{name1}\marg{name2}}
  Approximate orthodromic distance between two named positions
  \meta{name1} and \meta{name2} with three valid digits.
  \begin{dispExample}
  \mrcNPdef{munich}{48.14}{11.58}
  \mrcNPdef{newyork}{40.71}{-74.01}
  \mrcNPprettyorthodistance{munich}{newyork}
  \end{dispExample}
\end{docCommand}


\begin{docCommand}{mrcstoreorthodistance}{\marg{macro}\marg{lat1}\marg{lon1}\marg{lat2}\marg{lon2}}
  Stores the approximate orthodromic distance (in kilometers) between two points
  with latitude \meta{lat1}, longitude \meta{lon1}
  and latitude \meta{lat2}, longitude \meta{lon2}
  to a given \meta{macro}.
  \begin{dispExample}
  \mrcstoreorthodistance\mydist{48.14}{11.58}{40.71}{-74.01}
  \mydist
  \end{dispExample}
\end{docCommand}


\begin{docCommand}{mrcprettyloxodistance}{\marg{lat1}\marg{lon1}\marg{lat2}\marg{lon2}}
  Approximate loxodromic distance between two points
  with latitude \meta{lat1}, longitude \meta{lon1}
  and latitude \meta{lat2}, longitude \meta{lon2}
  with three valid digits.
  \begin{dispExample}
  \mrcprettyloxodistance{48.14}{11.58}{40.71}{-74.01}
  \end{dispExample}
\end{docCommand}


\begin{docCommand}{mrcNPprettyloxodistance}{\marg{name1}\marg{name2}}
  Approximate loxodromic distance between two named positions
  \meta{name1} and \meta{name2} with three valid digits.
  \begin{dispExample}
  \mrcNPdef{munich}{48.14}{11.58}
  \mrcNPdef{newyork}{40.71}{-74.01}
  \mrcNPprettyloxodistance{munich}{newyork}
  \end{dispExample}
\end{docCommand}

\enlargethispage*{1cm}

\begin{docCommand}{mrcstoreloxodistance}{\marg{macro}\marg{lat1}\marg{lon1}\marg{lat2}\marg{lon2}}
  Stores the approximate loxodromic distance (in kilometers) between two points
  with latitude \meta{lat1}, longitude \meta{lon1}
  and latitude \meta{lat2}, longitude \meta{lon2}
  to a given \meta{macro}.
  \begin{dispExample}
  \mrcstoreloxodistance\mydist{48.14}{11.58}{40.71}{-74.01}
  \mydist
  \end{dispExample}
\end{docCommand}