Debian Codegraph @

texmf-dist/doc/latex/mercatormap/mercatormap.doc.animations.tex

raw
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{Animations}\label{sec:animations}%
7
8 An animation in the context of map drawing is considered to be a direct movement
9 from a starting position to a final position with possible adaption of
10 scale denominators.
11
12 This package does not provide animation production, but allows to create a
13 PDF with a sequence of maps (frames) following such an animation path.
14
15
16 %-------------------------------------------------------------------------------
17 \subsection{Animation Environment}
18
19 \begin{docEnvironment}[doc new=2024-07-31]{mrcAnimation}{\marg{options}}
20 According to the given \meta{options}, the environment loops over the
21 \meta{environment content} several times generating \textit{frames}
22 for an external animation program.
23 A detailed description for the \meta{options} is found in \Fullref{ref:animOptions}.
24 \begin{itemize}
25 \item Basically, the position is moved from
26 a given \refKey{mermap/anim/start-position} with time index |0|
27 following an orthodrome
28 to a \refKey{mermap/anim/final-position} with time index |1|.
29 \item
30 This time interval $[0,1]$ is divided into \refKey{mermap/anim/frames}.
31 The current frame number is denoted by \refCom{mrcAnimFrame},
32 the current time is denoted by \refCom{mrcAnimTime}, and
33 the current position is denoted by
34 \refCom{mrcAnimLatitude} and \refCom{mrcAnimLongitude},
35 alternatively by the named positon \docValue{AnimNP}.
36 \item
37 During movement, a time dependent sequence of \refKey{mermap/anim/scale-denominators}
38 defines the current scale denominator \refCom{mrcAnimScaleDenom}.
39 \item
40 The frames may have an equal time distance or have different time
41 distances using a \refKey{mermap/anim/timewarp}. This could be used
42 to slow down movement near ground and to speed up with more height.
43 \end{itemize}
44 The generated sequence of frames is applicable for
45 \begin{itemize}
46 \item Movement along an orthodrome from starting to final position with an unchanged
47 common scale denominator.
48 \item Zoom in or out on a fixed position.
49 \item Combination of both animations.
50 \item Animated orthodrome drawing on a static map.
51 \end{itemize}
52 For more complex animations, several \refEnv{mrcAnimation} environments may be
53 used consecutively.
54 \end{docEnvironment}
55
56 \clearpage
57 \begin{dispExample*}{breakable}
58 \mrcNPdef{heathrow}{51.4678}{-0.4548}
59 \mrcNPdef{fiumicino}{41.8151}{12.2508}
60
61 \begin{tcbraster}[raster height=22cm,raster columns=4,raster rows=7,
62 tile,size=minimal,boxsep=1pt,colback=black!20 ]
63 \begin{mrcAnimation}
64 {
65 named-start-position = heathrow,
66 named-final-position = fiumicino,
67 frames = 36,
68 scale-denominators = 0/1000000 - 0.3/8000000 - 0.7/8000000 - 1/1000000,
69 timewarp-slow-start-final = 1.5,
70 }
71 \begin{tcolorbox}
72 \begin{tikzpicture}
73 \mermapset
74 {
75 named flex scale = \mrcAnimScaleDenom:AnimNP,
76 }
77 \mrcmap
78 [
79 type = reference,
80 named position = AnimNP,
81 source = topplusopen web,
82 tex width = \tcbtextwidth,
83 tex height = \tcbtextheight
84 ]{london-roma-\mrcAnimFrame}
85 \mrcdrawmap
86 \node[above left,font=\fontsize{3.5pt}{3.5pt}\sffamily]
87 at (mrcmap.south east) {\mrcmapattribution};
88 \mrcclipmap
89 \end{tikzpicture}
90 \end{tcolorbox}
91 \end{mrcAnimation}
92 \end{tcbraster}
93 \end{dispExample*}
94
95
96
97 \clearpage
98 \begin{dispExample*}{breakable}
99 % \usepackage{fontawesome5}
100 \mrcNPdef{heathrow}{51.4678}{-0.4548}
101 \mrcNPdef{lax}{33.9421}{-118.4088}
102 \mrcNPdef{reykjavik}{64.1289}{-21.9369}
103
104 \begin{tcbraster}[raster height=22cm,raster columns=2,raster rows=4,
105 tile,size=minimal,boxsep=1pt,colback=black!20 ]
106 \begin{mrcAnimation}
107 {
108 named-start-position = heathrow,
109 named-final-position = lax,
110 frames = 8,
111 }
112 \begin{tcolorbox}
113 \begin{tikzpicture}
114 \mrcmap
115 [
116 type = areafit,
117 area = {heathrow,lax,reykjavik},
118 source = topplusopen web,
119 tex width = \tcbtextwidth,
120 tex height = \tcbtextheight,
121 flex area fit = 8mm,
122 ]{london-lax-\mrcAnimFrame}
123 \mrcdrawmap
124 \node[above left,font=\fontsize{3.5pt}{3.5pt}\sffamily]
125 at (mrcmap.south east) {\mrcmapattribution};
126 \mrcclipmap
127 \mrcNPdraworthodrome[red,very thick]{heathrow}{AnimNP}
128 \node[red!70!black,rotate=\mrcAnimAngle]
129 at (\mrcNPcs{AnimNP}) {\large\faPlane};
130 \end{tikzpicture}
131 \end{tcolorbox}
132 \end{mrcAnimation}
133 \end{tcbraster}
134 \end{dispExample*}
135
136
137 \clearpage
138 %-------------------------------------------------------------------------------
139 \subsection{Animation Options}\label{ref:animOptions}
140
141 \begin{docMrcKeys}[
142 doc keypath = anim,
143 doc new = 2024-07-31,
144 ]{
145 {
146 doc name = start-position,
147 doc parameter = {=\meta{latitude}/\meta{longitude}},
148 doc description = initially |51.4779/0|
149 },
150 {
151 doc name = named-start-position,
152 doc parameter = {=\meta{name}},
153 }
154 }
155 Starting position of the animation given by
156 \meta{latitude} and \meta{longitude} or by a named position using \meta{name}.
157 \end{docMrcKeys}
158
159
160 \begin{docMrcKeys}[
161 doc keypath = anim,
162 doc new = 2024-07-31,
163 ]{
164 {
165 doc name = final-position,
166 doc parameter = {=\meta{latitude}/\meta{longitude}},
167 doc description = initially |51.4779/0|
168 },
169 {
170 doc name = named-final-position,
171 doc parameter = {=\meta{name}},
172 }
173 }
174 Final position of the animation given by
175 \meta{latitude} and \meta{longitude} or by a named position using \meta{name}.
176 \end{docMrcKeys}
177
178
179 \begin{docMrcKeys}[
180 doc keypath = anim,
181 doc new = 2024-07-31,
182 ]{
183 {
184 doc name = position,
185 doc parameter = {=\meta{latitude}/\meta{longitude}},
186 doc description = initially |51.4779/0|
187 },
188 {
189 doc name = named-position,
190 doc parameter = {=\meta{name}},
191 }
192 }
193 Fixed position of the animation given by
194 \meta{latitude} and \meta{longitude} or by a named position using \meta{name}.
195 This sets \refKey{mermap/anim/start-position} and
196 \refKey{mermap/anim/final-position} to the identical value.
197 \end{docMrcKeys}
198
199
200
201 \begin{docMrcKeys}[
202 doc keypath = anim,
203 doc new = 2024-07-31,
204 ]{
205 {
206 doc name = frames,
207 doc parameter = {=\meta{frame number}},
208 doc description = initially |20|
209 },
210 }
211 Integer \meta{frame number} for the animation, at least |2|. For maps made with tiles,
212 even a large \meta{frame number} typically results in limited downloads,
213 because the tiles a reused as far as possible. For WMS maps, every frame
214 could give another download!
215 \end{docMrcKeys}
216
217
218 \begin{docMrcKeys}[
219 doc keypath = anim,
220 doc new = 2024-07-31,
221 doc parameter = {\colOpt{=true\textbar false}},
222 doc description = {default |true|, initially |false|},
223 ]{
224 {
225 doc name = drop-first-frame,
226 },
227 {
228 doc name = drop-last-frame,
229 },
230 }
231 If several \refEnv{mrcAnimation} environments are used consecutively,
232 the end frame of one animation is identical to the start frame of the
233 next animation. These options allow to remove one superfluous connecting frame.
234 \end{docMrcKeys}
235
236
237 \begin{docMrcKeys}[
238 doc keypath = anim,
239 doc new = 2024-07-31,
240 ]{
241 {
242 doc name = drop-no-frame,
243 doc description = {no value, initially set},
244 },
245 }
246 Reset to drop no frames.
247 \end{docMrcKeys}
248
249
250 \begin{docMrcKeys}[
251 doc keypath = anim,
252 doc new = 2024-07-31,
253 ]{
254 {
255 doc name = scale-denominators,
256 doc parameter = {=\marg{time and scale sequence}},
257 doc description = {initially |0/25000-1/25000|},
258 },
259 }
260 The \meta{time and scale sequence} has to obey the following pattern:
261 \par
262 \meta{time$_1$}|/|\meta{scale$_1$} |-|
263 \meta{time$_2$}|/|\meta{scale$_2$} |-| $\ldots$ |-|
264 \meta{time$_n$}|/|\meta{scale$_n$}
265 \par
266 The time values have to be taken from the interval $[0,1]$ and have to be
267 strictly monotonically increasing, i.e.
268 \par
269 $0\le$ \meta{time$_1$} $<$
270 \meta{time$_2$} $<$ $\ldots$ $<$
271 \meta{time$_n$} $\le 1$
272 \par
273 If not given, time and scale for time $0$ and $1$ are automatically added
274 as constant continuation.\par
275 Depending on the current time value \refCom{mrcAnimTime}, the current
276 scale denominator \refCom{mrcAnimScaleDenom} is interpolated from this
277 sequence using a logarithmic approach.
278 \end{docMrcKeys}
279
280
281 \begin{docMrcKeys}[
282 doc keypath = anim,
283 doc new = 2024-07-31,
284 ]{
285 {
286 doc name = common-scale-denominator,
287 doc parameter = {=\marg{scale denominator}},
288 doc description = {initially |25000|},
289 },
290 }
291 This is a shortcut for\par
292 \refKey{mermap/anim/scale-denominators} |=|\\
293 \hspace*{5mm} |0/|\marg{scale denominator} |- 1/|\marg{scale denominator}
294 \par
295 Thereby, a fixed \marg{scale denominator} is set for the animation.
296 \end{docMrcKeys}
297
298
299 \clearpage
300 \begin{docMrcKeys}[
301 doc keypath = anim,
302 doc new = 2024-07-31,
303 ]{
304 {
305 doc name = timewarp,
306 doc parameter = {=\meta{macro}},
307 doc description = initially \texttt{\textbackslash mrcTimewarpIdentity}
308 },
309 }
310 \meta{macro} has to be a fully expandable \LaTeX\ macro with one parameter.
311 The expansion has to be a valid |expl3| \meta{floating point expression}
312 denoting a strictly monotonically increasing function mapping from
313 the interval \mbox{$[0,1]$} into \mbox{$[0,1]$} again.
314 This timewarp may slow down and accelerate time over the span from $0$ to $1$.
315 \end{docMrcKeys}
316
317
318 \begin{docCommands}[
319 doc new = 2024-07-31,
320 ]{
321 {
322 doc name = mrcTimewarpIdentity,
323 doc parameter = {=\marg{time}},
324 },
325 }
326 Identity function from \mbox{$[0,1]$} into \mbox{$[0,1]$}.
327 \end{docCommands}
328
329
330 \begin{docMrcKeys}[
331 doc keypath = anim,
332 doc new = 2024-07-31,
333 ]{
334 {
335 doc name = timewarp-identity,
336 doc description = {no value, initially set}
337 },
338 }
339 Sets \refKey{mermap/anim/timewarp} to \refCom{mrcTimewarpIdentity}.
340 This means that time flows constantly.
341 \end{docMrcKeys}
342
343
344 \begin{docCommands}[
345 doc new = 2024-07-31,
346 ]{
347 {
348 doc name = mrcTimewarpSlowStart,
349 doc parameter = {=\marg{exponent}\marg{time}},
350 doc description = {default |2|}
351 },
352 }
353 Function term $t^{\text{\meta{exponent}}}$
354 \end{docCommands}
355
356
357 \begin{docMrcKeys}[
358 doc keypath = anim,
359 doc new = 2024-07-31,
360 ]{
361 {
362 doc name = timewarp-slow-start,
363 doc parameter = \colOpt{=\meta{exponent}},
364 doc description = {default |2|}
365 },
366 }
367 Sets \refKey{mermap/anim/timewarp} to \refCom{mrcTimewarpSlowStart}\marg{exponent}.
368 \par
369 If $\text{\meta{exponent}}>1$ is used, time flows slower at the begin of the
370 interval \mbox{$[0,1]$}. This can be used, if a low scale denominator is
371 present at begin of a movement and is becoming larger later. Here, for smoothness,
372 you may want this to have slower speed near ground and larger speed later.
373 \end{docMrcKeys}
374
375
376 \begin{docCommands}[
377 doc new = 2024-07-31,
378 ]{
379 {
380 doc name = mrcTimewarpSlowFinal,
381 doc parameter = {=\marg{exponent}\marg{time}},
382 doc description = {default |2|}
383 },
384 }
385 Function term $1 - (1-t)^{\text{\meta{exponent}}}$
386 \end{docCommands}
387
388
389 \begin{docMrcKeys}[
390 doc keypath = anim,
391 doc new = 2024-07-31,
392 ]{
393 {
394 doc name = timewarp-slow-final,
395 doc parameter = \colOpt{=\meta{exponent}},
396 doc description = {default |2|}
397 },
398 }
399 Sets \refKey{mermap/anim/timewarp} to \refCom{mrcTimewarpSlowFinal}\marg{exponent}.
400 \par
401 If $\text{\meta{exponent}}>1$ is used, time flows slower at the end of the
402 interval \mbox{$[0,1]$}. This can be used, if a large scale denominator is
403 present at begin of a movement and is becoming lower later. Here, for smoothness,
404 you may want this to have slower speed near ground at the end.
405 \end{docMrcKeys}
406
407
408 \begin{docCommands}[
409 doc new = 2024-07-31,
410 ]{
411 {
412 doc name = mrcTimewarpSlowStartFinal,
413 doc parameter = {=\marg{exponent}\marg{time}},
414 doc description = {default |2|}
415 },
416 }
417 Combination of \refCom{mrcTimewarpSlowStart} and \refCom{mrcTimewarpSlowFinal}
418 using case discrimination for the first and the second half of the intervall.
419 \end{docCommands}
420
421
422 \begin{docMrcKeys}[
423 doc keypath = anim,
424 doc new = 2024-07-31,
425 ]{
426 {
427 doc name = timewarp-slow-start-final,
428 doc parameter = \colOpt{=\meta{exponent}},
429 doc description = {default |2|}
430 },
431 }
432 Sets \refKey{mermap/anim/timewarp} to \refCom{mrcTimewarpSlowStartFinal}\marg{exponent}.
433 \par
434 If $\text{\meta{exponent}}>1$ is used, time flows slower at the begin and at the end of the
435 interval \mbox{$[0,1]$}. This can be used, if a low scale denominator is
436 present at begin of a movement, becomes larger in the middle, and finally
437 is becoming lower later. Here, for smoothness,
438 you may want this to have slower speed near ground at the begin and the end.
439 \end{docMrcKeys}
440
441
442 \clearpage
443 %-------------------------------------------------------------------------------
444 \subsection{Macros inside the Animation Environment}\label{ref:animMacros}
445
446 \begin{docCommands}[
447 doc new = 2024-07-31,
448 ]{
449 {
450 doc name = mrcAnimFrame,
451 },
452 {
453 doc name = l_mermap_anim_frame_int,
454 },
455 }
456 The current frame number ranging from $1$ to \refKey{mermap/anim/frames}.
457 \end{docCommands}
458
459
460 \begin{docCommands}[
461 doc new = 2024-07-31,
462 ]{
463 {
464 doc name = mrcAnimTime,
465 },
466 {
467 doc name = l_mermap_anim_time_fp,
468 },
469 }
470 The current time ranging from $0$ to $1$.
471 \end{docCommands}
472
473
474 \begin{docCommands}[
475 doc new = 2024-07-31,
476 ]{
477 {
478 doc name = mrcAnimScaleDenom,
479 },
480 {
481 doc name = l_mermap_anim_scaledenom_fp,
482 },
483 }
484 The current scale denominator according to \refKey{mermap/anim/scale-denominators}.
485 \end{docCommands}
486
487
488 \begin{docCommands}[
489 doc new = 2024-07-31,
490 ]{
491 {
492 doc name = mrcAnimLatitude,
493 },
494 {
495 doc name = l_mermap_anim_lat_fp,
496 },
497 }
498 The latitude of the current position.
499 \end{docCommands}
500
501
502 \begin{docCommands}[
503 doc new = 2024-07-31,
504 ]{
505 {
506 doc name = mrcAnimLongitude,
507 },
508 {
509 doc name = l_mermap_anim_lon_fp,
510 },
511 }
512 The longitude of the current position.
513 \end{docCommands}
514
515
516 \begin{docCommands}[
517 doc new = 2024-08-05,
518 ]{
519 {
520 doc name = mrcAnimAngle,
521 },
522 {
523 doc name = l_mermap_anim_angle_fp,
524 },
525 }
526 Current angle between the tangent vector to the orthodrome and
527 the current parallel circle.
528 \end{docCommands}
529
530
531
532
533 \docValue{AnimNP}\tcbdocmarginnote{\tcbdocnew{2024-07-31}}:
534 The current named position.
535
536
537
538