summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/mercatormap/mercatormap.doc.scales.tex
blob: 4c139d14490015da6a463e488905ba4dd712090c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
% !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{Scales and Sizes}%

Inside a defined map several size values and scaling options are
available. Please note that due to the nature of the Mercator projection and several
simplifying assumptions all specifications for map scale, map width, map height,
etc. are imprecise in the best case and even misleading in the worst case.
They are suited for representative diagrams,
but not for critical navigation purposes etc.

\subsection{Map Sizes and Document Sizes}

\begin{docCommand}{mrctexwidth}{}
  \TeX\ length denoting the document width of the current map.
\end{docCommand}

\begin{docCommand}{mrctexheight}{}
  \TeX\ length denoting the document width of the current map.
\end{docCommand}

\begin{docCommand}{mrcscale}{}
  Scaling factor between map and real world.
  A \TeX\ length given in |pt|, but stripped from that unit,
  multiplied by \refCom{mrcscale} corresponds to a real world length
  given in kilometers.
  Note that this is \emph{not} the map scale.
  Actually, it is reciprocal proportional to the map scale
  and proportional to the map scale denominator, see \refCom{mrcmapscaledenominator}.
\end{docCommand}

\begin{docCommand}{mrctextokm}{\marg{length}}
  Computes a given \TeX\ \meta{length} (with unit) into the corresponding
  real world length in kilometers (without unit).
  \begin{dispListing}
  Map width: \mrctextokm{\mrctexwidth}\,km
  \end{dispListing}
\end{docCommand}

\begin{docCommand}{mrctextomile}{\marg{length}}
  Computes a given \TeX\ \meta{length} (with unit) into the corresponding
  real world length in miles (without unit).
  \begin{dispListing}
  Map width: \mrctextomile{\mrctexwidth}\,mi
  \end{dispListing}
\end{docCommand}

\begin{docCommand}{mrckmtotex}{\marg{number}}
  Computes real world length \meta{number} in kilometers (without unit)
  to a \TeX\ length (with unit).
  \begin{dispListing}
  % draw a circle with radius 20km
  \draw (mrcpos) circle (\mrckmtotex{20});
  \end{dispListing}
\end{docCommand}

\begin{docCommand}{mrcmiletotex}{\marg{number}}
  Computes real world length \meta{number} in miles (without unit)
  to a \TeX\ length (with unit).
  \begin{dispListing}
  % draw a circle with radius 20 miles
  \draw (mrcpos) circle (\mrcmiletotex{20});
  \end{dispListing}
\end{docCommand}

\begin{docCommand}{mrcmapscaledenominator}{}
  Approximate map scale denominator.
  \SI{1}{cm} on the map corresponds approximately to
  \mbox{\refCom{mrcmapscaledenominator}$\cdot$\SI{1}{cm}} in the real world.
  Do not confuse with \refCom{mrcscale}.
  \begin{dispListing}
  Map scale: 1:\mrcmapscaledenominator
  \end{dispListing}
\end{docCommand}


\subsection{Pretty Size Output}


\begin{docCommand}{mrcprettymapscale}{}
  Approximate map scale given with three valid digits
  with a representation like |1:1000|.
  \begin{dispListing}
  Map scale: \mrcprettymapscale
  \end{dispListing}
\end{docCommand}

\begin{docCommand}{mrcprettymapwidth}{}
  Approximate map width in kilometers (or meters) with three valid digits:
  \begin{dispListing}
  Map width: \mrcprettymapwidth
  \end{dispListing}
  To create a pretty printing to your own liking, you can do like the
  following:
  \begin{dispListing}
  \newcommand{\myprettymapwidth}{\SI[round-mode=figures,round-precision=3]%
    {\mrctextokm{\mrctexwidth}}{km}}
  \end{dispListing}
\end{docCommand}

\begin{docCommand}{mrcprettymapheight}{}
  Approximate map height in kilometers (or meters) with three valid digits:
  \begin{dispListing}
  Map height: \mrcprettymapheight
  \end{dispListing}
\end{docCommand}


\begin{docCommand}{mrcprettymapresolution}{}
  Approximate map resolution in dpi (dots per inch):
  \begin{dispListing}
  Map resolution: \mrcprettymapresolution
  \end{dispListing}
\end{docCommand}

\begin{docCommand}{mrcprettytilesize}{}
  Approximate tile size inside the document (\TeX\ size) in millimeters:
  \begin{dispListing}
  \TeX\ tile size: \mrcprettytilesize
  \end{dispListing}
\end{docCommand}


\tikzsetnextfilename{scales_example}%
\begin{dispExample}
\begin{tikzpicture}
  \mrcNPdef{rome}{41.89300}{12.48557}
  \mermapset{named flex scale=2000000:rome}
  \mrcmap[type=reference, named position=rome, source=topplusopen web,
    tex width=\linewidth, tex height=10cm]{scales_example}
  \mrcdrawmap
  \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south)
        {\mrcmapattribution};
  \mrcclipmap
  \path[draw] (\mrcNPcs{rome}) circle (\mrckmtotex{50});
  \node[above] at ([yshift=\mrckmtotex{50}]\mrcNPcs{rome}) {\SI{50}{km}};
  \node[above right,fill=white,fill opacity=0.5,text opacity=1,align=center,
    line width=0pt, inner sep=2mm]
    at (mrcmap.south west) { \begin{tabular}{rl}
      scale:           & \mrcprettymapscale\\
      map width:       & \mrcprettymapwidth\\
      map height:      & \mrcprettymapheight\\
      \TeX\ tile size: & \mrcprettytilesize\\
      resolution:      & \mrcprettymapresolution
      \end{tabular}\\
      \begin{tikzpicture}
      \mrcdrawscalebar[width-in-km=100]
      \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.2]{20} node[pos=0.4]{40} node[pos=0.6]{60}
        node[pos=0.8]{80} node[pos=1]{100} node[pos=1,right,yshift=-1mm]{km};
      \end{tikzpicture}
    };
\end{tikzpicture}
\end{dispExample}


\clearpage
\subsection{Scale Bars}


\begin{docCommand}{mrcdrawscalebar}{\oarg{options}}
  Draws a scale bar according to the given \meta{options}.
  All \meta{options} share the common prefix |/mermap/scalebar/|.
  The most essential option is the \emph{width} of the scale bar.

  \tikzsetnextfilename{scales_scalebar1}
  \begin{dispExample}
  \begin{tikzpicture}
    \mrcNPdef{munich}{48.137222}{11.575556}
    \mrcNPdef{vienna}{48.208333}{16.373056}
    \mrcmap[tex width=\linewidth, tex height=4cm, target=none,
      type=areafit, area={munich,vienna}, flex area fit=2cm]{}
    \mrcdrawmap
    \mrcmarker{named position=munich, contents={M\"unchen}}
    \mrcmarker{named position=vienna, contents={Wien}}
    \mrcdrawscalebar[width-in-km=100, solid,
      at={([xshift=-10mm,yshift=5mm]mrcmap.south east)},
      placement={above left},  ]
  \end{tikzpicture}
  \end{dispExample}

  The size, position, and appearance of the scale bar can be customized by
  setting the various \meta{options}. The shape of the scale bar
  is denoted by a \tikzname\ node \docNode{mrcscalebar} which can be used
  for lettering.

  \enlargethispage*{1cm}
  \tikzsetnextfilename{scales_scalebar2}
  \begin{dispExample}
  \begin{tikzpicture}
    \mrcNPdef{munich}{48.137222}{11.575556}
    \mrcNPdef{vienna}{48.208333}{16.373056}
    \mrcmap[tex width=\linewidth, tex height=4cm, target=none,
      type=areafit, area={munich,vienna}, flex area fit=2cm]{}
    \mrcdrawmap
    \mrcmarker{named position=munich, contents={M\"unchen}}
    \mrcmarker{named position=vienna, contents={Wien}}
    \mrcdrawscalebar[width-in-km=100,solid,south-west-inside=10mm;3mm ]
    \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.2]{20} node[pos=0.4]{40} node[pos=0.6]{60}
      node[pos=0.8]{80} node[pos=1]{100} node[pos=1,right,yshift=-1mm]{km};
  \end{tikzpicture}
  \end{dispExample}

\end{docCommand}


\begin{docMrcKey}{scalebar/width-in-km}{=\meta{number}}{no default, initially |0|}
  Sets the width of the scale bar to match the real word length \meta{number}
  in kilometers.
\end{docMrcKey}

\begin{docMrcKey}{scalebar/width-in-kilometer}{=\meta{number}}{no default, initially |0|}
  Alias for \refKey{/mermap/scalebar/width-in-km}
\end{docMrcKey}

\begin{docMrcKey}{scalebar/width-in-meter}{=\meta{number}}{no default, initially |0|}
  Sets the width of the scale bar to match the real word length \meta{number}
  in meters.
\end{docMrcKey}

\begin{docMrcKey}{scalebar/width-in-mile}{=\meta{number}}{no default, initially |0|}
  Sets the width of the scale bar to match the real word length \meta{number}
  in miles.
\end{docMrcKey}

\begin{docMrcKey}{scalebar/width-in-yard}{=\meta{number}}{no default, initially |0|}
  Sets the width of the scale bar to match the real word length \meta{number}
  in yards.
\end{docMrcKey}

\begin{docMrcKey}{scalebar/partitions}{=\meta{number}}{no default, initially |5|}
  Determines the \meta{number} of partitions for the scale bar. If \meta{number}
  is set to 1, there is no partitioning.
\end{docMrcKey}

\begin{docMrcKey}{scalebar/height}{=\meta{length}}{no default, initially |2mm|}
  Sets the height of the scale bar to the given \TeX\ \meta{length}.
\end{docMrcKey}


\begin{docMrcKey}{scalebar/at}{=\marg{\tikzname\ coordinate}}{no default,
    initially \texttt{\brackets{(0,0)}}}
  The scale bar is positioned at the given \meta{\tikzname\ coordinate}.
  The placement is done with the \refKey{/mermap/scalebar/placement} option.
  Both option correspond to the \tikzname\ options for positioning nodes.
  The scale bar can be positioned outside the map (e.g. below), but
  remember to use \refCom{mrcclipmap} \emph{after} the scale bar
  in this case, if needed.

%  \begin{dispListing}
%  \mrcdrawscalebar[
%     at        = {([xshift=-10mm,yshift=5mm]mrcmap.south east)},
%     placement = above left,
%    ]
%  \end{dispListing}

  \tikzsetnextfilename{scales_scalebar3}
  \begin{dispExample}
  \begin{tikzpicture}
    \mrcNPdef{munich}{48.137222}{11.575556}
    \mrcNPdef{vienna}{48.208333}{16.373056}
    \mrcmap[tex width=\linewidth, tex height=4cm, target=none,
      type=areafit, area={munich,vienna}, flex area fit=2cm]{}
    \mrcdrawmap
    \mrcmarker{named position=munich, contents={M\"unchen}}
    \mrcmarker{named position=vienna, contents={Wien}}
    \mrcdrawscalebar[width-in-km=200, partitions=8,
      at={([xshift=5mm,yshift=-2mm]mrcmap.south west)},
      placement=below right   ]
    \path[every node/.style={below,inner sep=0.5mm,font=\sffamily\tiny}]
      (mrcscalebar.south west) -- (mrcscalebar.south east)
      node[pos=0]{0} node[pos=0.25]{50} node[pos=0.5]{100} node[pos=0.75]{150}
      node[pos=1]{200} node[pos=1,right,yshift=1mm]{km};
  \end{tikzpicture}
  \end{dispExample}
\end{docMrcKey}

\pagebreak

\begin{docMrcKey}{scalebar/placement}{=\meta{\tikzname\ positioning}}{no default, initially empty}
  \meta{\tikzname\ positioning} of a scale bar in combination with
  \refKey{/mermap/scalebar/at}. All \tikzname\ placement options for nodes
  can be used, e.g. \texttt{above left} or \texttt{anchor=mid west}, etc.
  Actually, \emph{any} node option could be applied here, but the intended use
  is for placement options only.
\end{docMrcKey}


\begin{docMrcKey}{scalebar/south-east-inside}{\colOpt{=\meta{x shift};\meta{y shift}}}{default |0pt;0pt|, initially unset}
  Shortcut for placing the scale bar at the south east corner of the map.
  The optional \mbox{\meta{x shift}} and \meta{y shift} denote the
  absolute shift values in each direction, i.e. the algebraic sign is
  automatically complemented.
  If only \meta{x shift} is given, then \meta{y shift} is set
  to the same value. \refKey{/mermap/scalebar/at} and \refKey{/mermap/scalebar/placement}
  are set by this option.
\end{docMrcKey}

\begin{docMrcKey}{scalebar/south-east-outside}{\colOpt{=\meta{x shift};\meta{y shift}}}{default |0pt;0pt|, initially unset}
  Shortcut for placing the scale bar below the south east corner of the map.
\end{docMrcKey}

\begin{docMrcKey}{scalebar/south-west-inside}{\colOpt{=\meta{x shift};\meta{y shift}}}{default |0pt;0pt|, initially unset}
  Shortcut for placing the scale bar at the south west corner of the map.
\end{docMrcKey}

\begin{docMrcKey}{scalebar/south-west-outside}{\colOpt{=\meta{x shift};\meta{y shift}}}{default |0pt;0pt|, initially unset}
  Shortcut for placing the scale bar below the south west corner of the map.
\end{docMrcKey}

\begin{docMrcKey}{scalebar/north-west-inside}{\colOpt{=\meta{x shift};\meta{y shift}}}{default |0pt;0pt|, initially unset}
  Shortcut for placing the scale bar at the north west corner of the map.
\end{docMrcKey}

\begin{docMrcKey}{scalebar/north-west-outside}{\colOpt{=\meta{x shift};\meta{y shift}}}{default |0pt;0pt|, initially unset}
  Shortcut for placing the scale bar above the north west corner of the map.
\end{docMrcKey}

\begin{docMrcKey}{scalebar/north-east-inside}{\colOpt{=\meta{x shift};\meta{y shift}}}{default |0pt;0pt|, initially unset}
  Shortcut for placing the scale bar at the north east corner of the map.
\end{docMrcKey}

\begin{docMrcKey}{scalebar/north-east-outside}{\colOpt{=\meta{x shift};\meta{y shift}}}{default |0pt;0pt|, initially unset}
  Shortcut for placing the scale bar above the north east corner of the map.
\end{docMrcKey}


\begin{docMrcKey}{scalebar/major style}{=\marg{\tikzname\ options}}{no default, initially empty}
  The \emph{major} part of the scale bar is a single \tikzname\ path object
  which can be customized by the given \meta{\tikzname\ options}.
  The \emph{major} part consists of the black area in the default case.
  \tikzsetnextfilename{scales_scalebar4}
  \begin{dispExample}
  \begin{tikzpicture}
    \mrcdrawscalebar[scale=2000000, width-in-km=100,
        major style={left color=red,right color=blue}   ]
  \end{tikzpicture}
  \end{dispExample}
\end{docMrcKey}


\begin{docMrcKey}{scalebar/minor style}{=\marg{\tikzname\ options}}{no default, initially empty}
  The \emph{minor} part of the scale bar is a single \tikzname\ path object
  which can be customized by the given \meta{\tikzname\ options}.
  The \emph{minor} part is seen as holes in the default case.
  \refKey{/mermap/scalebar/minor style} has only an effect, if
  the minor part is drawn \refKey{/mermap/scalebar/solid}.
  \tikzsetnextfilename{scales_scalebar5}
  \begin{dispExample}
  \begin{tikzpicture}
    \mrcdrawscalebar[scale=2000000, width-in-km=100, solid,
         minor style={yellow}  ]
  \end{tikzpicture}
  \end{dispExample}
\end{docMrcKey}


\pagebreak
\begin{docMrcKey}{scalebar/double}{\colOpt{=true\textbar false}}{default |true|, initially |true|}
  If set to |true|, the scale bar is drawn as a double ruler.
\end{docMrcKey}


\begin{docMrcKey}{scalebar/single}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
  If set to |true|, the scale bar is drawn as a single ruler.
  \refKey{/mermap/scalebar/single} is inverse to \refKey{/mermap/scalebar/double}.
  \tikzsetnextfilename{scales_scalebar6}
  \begin{dispExample}
  \begin{tikzpicture}
    \mrcdrawscalebar[scale=2000000, width-in-km=100, single, height=1mm]
  \end{tikzpicture}
  \end{dispExample}
\end{docMrcKey}


\begin{docMrcKey}{scalebar/transparent}{\colOpt{=true\textbar false}}{default |true|, initially |true|}
  If set to |true|, the \emph{minor} part of the scale bar is drawn transparent,
  i.e. as holes inside the ruler.
\end{docMrcKey}


\begin{docMrcKey}{scalebar/solid}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
  If set to |true|, the \emph{minor} part of the scale bar is drawn opaque.
  It is drawn white or according to \refKey{/mermap/scalebar/minor style}.
  \refKey{/mermap/scalebar/solid} is inverse to \refKey{/mermap/scalebar/transparent}.
\end{docMrcKey}


\begin{docMrcKey}{scalebar/scale}{=\meta{scale denominator}}{no default, initially unset}
  Sets or overwrites the \meta{scale denominator} setting.
  \textbf{Using this key is not needed and may even lead to erroneous displays
    inside a |tikzpicture| with a defined map setting.}
  This key is helpful, if a scale bar is used without a defined map.
\end{docMrcKey}