-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathprocessGPX.html
More file actions
2485 lines (1560 loc) · 153 KB
/
processGPX.html
File metadata and controls
2485 lines (1560 loc) · 153 KB
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
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>processGPX</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@tahoea.local" />
</head>
<body>
<ul id="index">
<li><a href="#NAME">NAME</a></li>
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#VERSION">VERSION</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#DEPENDENCIES">DEPENDENCIES</a></li>
<li><a href="#SPECIFYING-INPUT-SOURCES">SPECIFYING INPUT SOURCES</a></li>
<li><a href="#OPTIONS">OPTIONS</a></li>
<li><a href="#EXAMPLES">EXAMPLES</a>
<ul>
<li><a href="#auto-option">-auto option</a></li>
<li><a href="#criterium-course">criterium course</a></li>
<li><a href="#out-and-back-course">out-and-back course</a></li>
<li><a href="#out-and-back-circuit">out-and-back circuit</a></li>
<li><a href="#road-course-w-out-and-back">road course w/ out-and-back</a></li>
<li><a href="#simplifying">simplifying</a></li>
<li><a href="#selective-smoothing">selective smoothing</a></li>
<li><a href="#multi-step-processing">multi-step processing</a></li>
<li><a href="#adjusting-gradient-for-bridges-or-tunnels">adjusting gradient for bridges or tunnels</a></li>
<li><a href="#shifting-a-route">shifting a route</a></li>
<li><a href="#segment-generation">segment generation</a></li>
<li><a href="#adding-time-to-an-activity">adding time to an activity</a></li>
<li><a href="#adding-gradient-signs">adding gradient signs</a></li>
<li><a href="#processing-a-BikeTerra-route-from-the-original-GPX">processing a BikeTerra route from the original GPX</a></li>
<li><a href="#processing-a-BikeTerra-route-from-route-data">processing a BikeTerra route from route data</a></li>
<li><a href="#specifying-metadata">specifying metadata</a></li>
<li><a href="#converting-an-RGT-route-to-BikeTerra">converting an RGT route to BikeTerra</a></li>
</ul>
</li>
<li><a href="#NAMED-SEGMENTS">NAMED SEGMENTS</a></li>
<li><a href="#BUGS-and-ISSUES">BUGS and ISSUES</a></li>
<li><a href="#AUTHORS">AUTHORS</a></li>
<li><a href="#LICENSE">LICENSE</a></li>
</ul>
<h1 id="NAME">NAME</h1>
<p>processGPX</p>
<h1 id="SYNOPSIS">SYNOPSIS</h1>
<p><b><code>processGPX</code></b> [options] <input files></p>
<h1 id="VERSION">VERSION</h1>
<p>0.64</p>
<h1 id="DESCRIPTION">DESCRIPTION</h1>
<p>processGPX is a series of algorithms to improve and create GPX files, in particular for cycling emulation platforms like Biketerra, and should work well with Training Peaks Virtual as well. It was originally written for RGT.</p>
<p>At the time of this writing, BikeTerra allows for the creation of custom routes whereby a GPX file can be submitted for conversion into a virtual environment. The GPX file can be initially generate by on-line mapping tools, among which one excellent option is Strava Route Editor, which exports GPX (consider using the <code>-fixSteps</code> option with Strava). However, these tools tend to produce GPX files with too low resolution in position, and small errors in altitude, so that corners are not sufficiently round, and the gradient between points can have anomalously large magnitude.</p>
<p>Additionally, BikeTerra requires the route to be specified continuously from start to finish, rather than allowing arbitrary navigation over a network of roads, and so sometimes the same section of road needs to be repeated, either in the same or in the opposite direction. If you repeat sections of roadway, make sure there is no overlap or road crossings, as as of this writing BikeTerra does not produce good results with these. Note point-to-point courses in BikeTerra automatically feature turn-around loops at each end, so there is no need to do anything to allow returning on a point-to-point route.</p>
<p>These are just some examples of the sort of processing which can be done to improve the quality and functionality of BikeTerra and presumibly other cycling emulators as well. There exist online tools such as GPXMagic, which is excellent, but requires extensive user interaction, and a command-line tool able to process an entire file at once has benefit. A nice approach is to general route editing with GPXMagic, then use <code>processGPX</code> to process the result.</p>
<p>The file takes GPX files on the command line, and generates a file with a suffix "<code>_processed</code>" for each, unless the <code>-out</code> option is used, in which case that is used as the output (this works for only one input file). So for example, if I type:</p>
<p><code>processGPX myFavoriteRoute.gpx</code></p>
<p>the result will be a file:</p>
<p><code>myFavoriteRoute_processed.gpx</code></p>
<p>This file will be essentially equivalent to the input file, in the absence of any command line options, although if there are any "zig-zags" identified, those will be removed. The file will also be checked for "loops", where the direction spins around within 100 meters, which might be from a poorly placed control point with mapping software.</p>
<p>If an alternate filename were desired for the output, that could be specified with the <code>-out</code> option:</p>
<p><code>processGPX myFavoriteRoute.gpx -out myFavoriteRouteCopy.gpx</code></p>
<p>where the order of command line options does not matter, except that the same option listed more than once will result in parameters specified last being used.</p>
<p>Typically GPX file contain a single "track", each of which contains multiple "segments", each of which contains multiple connected "points". Segments are connected as well as points within the segments. However, GPX file may also contain multiple tracks. processGPX is set up to process one track at a time within a GPX file. By default, this is the first track, or track #1 counting 1, 2, 3 ... If you want to specify a track other than 1, then use either the <code>-track</code> option (followed by a number 1, 2, 3...), or put the number after a ":" at the end of a filename. So for example, if I wanted track #2 in a file <code>file.gpx</code>, I could specify either "<code>-track 2</code>", or "<code>file.gpx:2</code>". For the <code>-join</code> option only the filename suffix works, so "<code>-join file.gpx:2</code>".</p>
<p>The program will calculate a quality of both the original GPX file, and of the result of processing, which is based on how much the grade changes point-to-point and also how much the direction changes point-to-point. The goal is to only have abrupt gradient changes where they actually exist in the real-life course, and to smooth corners so the direction does not abruptly change. This quality score can provide guidance to if altitude smoothing and point density are sufficient.</p>
<p>It also reports the length of the course, calculated treating the earth as a sphere of a given radius. The calculation in BikeTerra may differ slightly, so distances may differ by a few meters.</p>
<p>There are a number of options, but a key one is <code>-auto</code>. It is designed to generate a decent result in a large fraction of the cases. If you only use this option, you should still be happy with results. Other options, however, allow for fine-tuning of the amount of route processing. They can be used in conjunction with <code>-auto</code> to override those settings.</p>
<p>One important difference is how point-to-point routes and lappable routes are treated. You can specify a loop course as <code>-lap</code>. IF you want the code to automatically determine whether a course is a point-to-point or lappable, use <code>-autoLap</code>. This option is implied with the <code>-auto</code> option, and is the general default. To negate it, you can specify <code>-noautoLap</code>.</p>
<p>There are a number of options to create "out-and-back" routes. These were required by RGT. However, BikeTerra automatically puts turn-around loops at each end of a point-to-point course. So you do not usually need use these options with BikeTerra.</p>
<h1 id="DEPENDENCIES">DEPENDENCIES</h1>
<p>This code uses the following Perl modules, which must be installed, for example with the "cpan" command-line tool:</p>
<pre><code>Getopt::Long : used for processing command-line options
Geo::Gpx : parsing and generating GPX files
XML::Descent : processing XML (required by Geo::Gpx, as well)
POSIX : floor function
Date::Parse : for parsing time, with the -startTime option
Pod::Usage : for the -help option</code></pre>
<p>For processing BikeTerra routes or GPX files directly you need:</p>
<pre><code>HTTP::Tiny : used for downloading data from the web.</code></pre>
<p>and for BikeTerra route data (as opposed to GPX files) you need:</p>
<pre><code>JSON : used for parsing JSON-formatted files.</code></pre>
<h1 id="SPECIFYING-INPUT-SOURCES">SPECIFYING INPUT SOURCES</h1>
<p>There are a number of ways to specify input sources.</p>
<p>The most common way is to provide an input filename for a GPX file. So, for example, if you have a file <code>myFavoriteRoute.gpx</code>, you'd list that as a command-line element.</p>
<p>Optionally a track number can be specified, if the default of using the first (or only) track isn't wanted. So <code>myFavoriteRoute.gpx:2</code> would use the second track in the file.</p>
<p><b><code>BikeTerraGPX</code></b>: For BikeTerra users, routes can be downloaded from BikeTerra directly and used as input. There's two sources. One is to use the GPX file which was sent to Biketerra. BikeTerra takes other data formats, like FIT, but this only works here with GPX files. This is specified with <code>BikeTerraGPX:</code> followed by the route number. So for example, <code>BikeTerraGPX:10605</code> would use the GPX file ssociated with BikeTerra route 10605. Again, the track number can be appended, so if <code>BikeTerraRoute:10605:1</code> specified the first track in the GPX file associated with route 10605.</p>
<p><b><code>BikeTerraRoute</code></b>: An alternate approach with BikeTerra routes is to download data for a simplified version of the BikeTerra route after edits. This is not the version used in the game, but further simplified for drawing maps, etc. It's useful as an input to processGPX, but may lack sufficient detail. It is specified with <code>BikeTerraRoute:</code> followed by the route number. You can additionally specify a track number but there will only be one track (as of this writing: maybe that will change at some point).</p>
<p><b><code>BikeTerraJSON</code></b>: A third option is the prefix to use a JSON file accessable for BikeTerra routes, for example the following for route 1: <code>https://biketerra.com/ride/__data.json?route=1</code> This file will include the full resolution BikeTerra route used in the game. This is not officially supported so may fail at some future point. It requires authentication with a BikeTerra account so you'll need to save it to a file then specify the filename with a <code>BikeTerraJSON:</code> prefix.</p>
<p>You can shortcut these as <code>BTGPX:</code> and <code>BTRoute:</code> and <code>BTJSON</code>, for example. Generally the "Bike" can be shortened to B, and/or the "Terra" to T. Case does not matter.</p>
<p>Another option is to omit a filename, or to specify an empty dash <code>-</code>. This indicates that the standard input is to be used, for example with a pipe. As with filenames, a track number can be appended to the dash, for example <code>-:2</code> would pick the second track from the GPX provided as standard input. This is assumed to be a GPX file (not a BikeTerra JSON file).</p>
<h1 id="OPTIONS">OPTIONS</h1>
<p>The program is generally invoked:</p>
<p><code>processGPX</code> [options] <inputfilename> ...</p>
<p>where multiple input file names may be specified, and zero or more options may be specified.</p>
<p>Options are case-insensitive and come in three varieties:</p>
<dl>
<dt id="flags:-specifying-the-option-by-itself-invokes-the-option.-For-example--splineInterpolation-specifies-that-spline-fitting-is-enabled.-Flag-options-can-be-negated-with-the-same-option-but-with-no-preceding-for-example--nosplineInterpolation-disables-spline-fitting.-Flags-have-3-states:-true-false-and-undefined.-If-undefined-they-will-be-assigned-a-default-by-the-program.-If-set-true-or-false-that-value-will-be-used"><b>flags</b>: specifying the option by itself invokes the option. For example, <code>-splineInterpolation</code> specifies that spline fitting is enabled. Flag options can be negated with the same option but with "no" preceding, for example, <code>-nosplineInterpolation</code> disables spline fitting. Flags have 3 states: true, false, and undefined. If undefined they will be assigned a default by the program. If set true or false, that value will be used.</dt>
<dd>
</dd>
<dt id="values:-the-option-specification-is-followed-by-a-value.-This-may-simultaneously-invoke-an-option.-For-example--spacing-10-sets-the-spacing-for-point-interpolation-to-10-meters-and-additionally-turns-on-point-interpolation"><b>values</b>: the option specification is followed by a value. This may simultaneously invoke an option. For example, <code>-spacing 10</code> sets the spacing for point interpolation to 10 meters, and additionally turns on point interpolation.</dt>
<dd>
</dd>
<dt id="lists:-Some-options-allow-for-multiple-values-for-example--uniformGradient-or--autoSegments.-See-details-in-the-description-of-the-specific-option"><b>lists</b>: Some options allow for multiple values, for example <code>-uniformGradient</code> or <code>-autoSegments</code>. See details in the description of the specific option.</dt>
<dd>
</dd>
</dl>
<p>The options are the following, excluding negations, which for flags are the option with <code>no</code> preceding the keyword.</p>
<dl>
<dt id="addCurvature"><b><code>-addCurvature</code></b></dt>
<dd>
<p>This option adds a "curvature" extension field (in inverse meters) to the GPX file. Curvature is calculated as the ratio of the rate of change of angle with distance. Note for a unit circle (radius = 1) the rate of change of angle (in radians) with position (along the perimeter) is 1. In general this is the reciprical of the circle radius.</p>
</dd>
<dt id="addDirection"><b><code>-addDirection</code></b></dt>
<dd>
<p>This option adds an extensions "direction" field relative to east (in degrees) to the GPX file.</p>
<p>examples:</p>
<dl>
<dt id="degrees:-east">0 degrees: east</dt>
<dd>
</dd>
<dt id="degrees:-north">90 degrees: north</dt>
<dd>
</dd>
<dt id="degrees:-west">180 degrees: west</dt>
<dd>
</dd>
<dt id="degrees-south">270 degrees south</dt>
<dd>
</dd>
</dl>
<p>Note this is not "heading", as it is relative to east.</p>
<p>Direction is calculated for each point as the average of the directions ahead and behind. The direction of the first or last points in a point-to-point course are calculated in only one direction. Directions for loop courses are calculated assuming the loop. The direction never changes by more than +/- 180 degrees from one point to the next, so the direction has no limits: it can be positive, negative, and outside the range from -360 to +360 degrees. For example, if a route started east (0) then lapped around counterclockwise 10 times, the final direction would be approximately 3600 degrees.</p>
</dd>
<dt id="addCornerWaypoints"><b><code>-addCornerWaypoints</code></b></dt>
<dd>
<p>This option places waypoints at positions of relatively high curvature, marking them as corners. They can be viewed, for example. in <i>GPXStudio</i>. The future intent is for them to be useful in a game such as BikeTerra for generating roadside signs.</p>
<p>It is likely this option will need to be tuned with <code>-cornerThreshold</code>, and possibly <code>-cornerSmoothing</code>, depending on the route.</p>
</dd>
<dt id="addGradient"><b><code>-addGradient</code></b></dt>
<dd>
<p>This option adds a forward "gradient" extensions field, which is calculated for each point as the ratio of the altitude change to the horizontal distance to the next point.</p>
</dd>
<dt id="addGradientSigns"><b><code>-addGradientSigns</code></b></dt>
<dd>
<p>This flag is an option to calculate regions of exceptional gradient and place "gradient signs". At present this is equivalent to <code>-addGradientWaypoints</code>, although in future versions it may be changed to support a feature on a virtual game such as <i>BikeTerra</i>.</p>
</dd>
<dt id="addGradientWaypoints"><b><code>-addGradientWaypoints</code></b></dt>
<dd>
<p>This flag is an option to calculate regions of exceptional gradient and place GPX waypoints. These are visible, for example, with <i>GPXStudio</i>. Waypoints are tagged depending on if they are associated with the forward or reverse direction of travel.</p>
</dd>
<dt id="addHeading"><b><code>-addHeading</code></b></dt>
<dd>
<p>This adds a heading field which is 0 = north, 90 = east, etc. Due to floating point precision values will not be exact.</p>
</dd>
<dt id="addSigma"><b><code>-addSigma</code></b></dt>
<dd>
<p>This writes the autosmoothing "sigma" to the GPX file as an extensions field, but only if <code>-autosmoothingZ</code> is positive. It is useful for tuning the autosmoothing scale length.</p>
</dd>
<dt id="align-option"><b><code>-align</code></b> <option></dt>
<dd>
<p>Synonym for <code>-snap</code></p>
</dd>
<dt id="alignAltitude-meters"><b><code>-alignAltitude</code></b> <meters></dt>
<dd>
<p>Synonym for <code>-snapAltitudes</code></p>
</dd>
<dt id="alignDistance-meters"><b><code>-alignDistance</code></b> <meters></dt>
<dd>
<p>Synonym for <code>-snapDistance</code></p>
</dd>
<dt id="alignTransition-meters"><b><code>-alignTransition</code></b> <meters></dt>
<dd>
<p>Synonym for <code>-snapTransition</code></p>
</dd>
<dt id="alignZ-meters"><b><code>-alignZ</code></b> <meters></dt>
<dd>
<p>This is a synonym for <code>-snapAltitude</code>.</p>
</dd>
<dt id="anchorSF"><b><code>-anchorSF</code></b></dt>
<dd>
<p>For point-to-point routes, this specifies that the start and finish points should be anchored. Smoothing would otherwise cause these points to shift somewhat.</p>
</dd>
<dt id="append-meters"><b><code>-append</code></b> <meters></dt>
<dd>
<p>A distance in meters which should be added to point-to-point courses. In RGT, the finish line was typically placed 140 meters prior to the end of a point-to-point course, so if for example you design a course to be exactly 10 miles, (a typical UK time trial distance), then to put the finish line at the end of those 10 miles, the option "<code>-append 140</code>" would add 140 meters. This buffer was needed by RGT because riders group along the road-side after crossing the finish. Note the start line would also need to be extended, via <code>-prepend</code>, by 60 meters, in the case of RGT.</p>
<p>Extended points will be set to the altitude of the final point.</p>
<p>Since BikeTerra tends to create loop courses when start and finish points are close, the code may put a bend in the road it creates with this command, if both <code>-append</code> and <code>-prepend</code> are specified (perhaps via <code>-extend</code>).</p>
<p>Negative values crop the course by the negative distance. So "<code>-append -100</code>" will move the finish line back 100 meters.</p>
</dd>
<dt id="arcInterpolation"><b><code>-arcInterpolation</code></b></dt>
<dd>
<p>This is essentially equivalent to <code>-arcInterpolationDegs 10</code>. It turns on arc interpolation with a reasonable default value.</p>
</dd>
<dt id="arcInterpolationAngle-degrees"><b><code>-arcInterpolationAngle</code></b> <degrees></dt>
<dd>
<p>Alias for <code>-arcInterpolationDegs</code>.</p>
</dd>
<dt id="arcInterpolationDegs-degrees"><b><code>-arcInterpolationDegs</code></b> <degrees></dt>
<dd>
<p>If arc interpolation is desired, specifying this will cause arc fit interpolation to be done for corners turning at least this much, but less than the <code>-arcInterpolationMaxDegs</code> option. A typical value is 5 degrees. This angle is the angle between interpolated course points</p>
<p>For a given 4 points <i>a</i>, <i>b</i>, <i>c</i>, and <i>d</i>, it interpolates between points <i>b</i> and <i>c</i> by fitting a circle through points <i>a</i>, <i>b</i>, and <i>c</i>, fitting a second circle between points <i>b</i>, <i>c</i>, and <i>d</i>, and then doing a weighted average of these two fits based on the relative distance of the interpolated point from points <i>b</i> and <i>c</i>. If starting with points forming the vertices of a polygon, for example, the resulting interpolation will yield a circular course, which may or may not be what you want.</p>
<p>This algorithm tends to result in more sweeping corners than spline interpolation, which may or may not reflect reality. Also if there are any anomalous points then there's the chance this algorithm will exaggerate these anomalies. It's recommended you very carefully check the results of applying this option. It's perhaps best for circuits with sweeping corners rather than straights connected with tighter turns.</p>
<p>There is a <code>-arcInterpolationMaxRatio</code> option which limits the application of arc interpolation to regions of relatively consistent point spacing. This is an option to consider raising or lowering from the default value if you are either getting excessive bow from arc interpolation (lower the ratio) or insufficient application of arc interpolation (raise the value).</p>
<p>See also <code>-arcInterpolationMaxDegs</code>.</p>
</dd>
<dt id="arcInterpolationEnd-meters"><b><code>-arcInterpolationEnd</code></b> <meters></dt>
<dd>
<p>Where to end arc interpolation, if any. The default is to end any arc fitting at the end of the course.</p>
</dd>
<dt id="arcInterpolationMaxAngle-degrees"><b><code>-arcInterpolationMaxAngle</code></b> <degrees></dt>
<dd>
</dd>
<dt id="arcInterpolationMaxDegs-degrees"><b><code>-arcInterpolationMaxDegs</code></b> <degrees></dt>
<dd>
<p>If a <code>-arcInterpolationDegs</code> option is specified, specifying this limit the maximum angle corner for which arc fit interpolation will be applied. Arc interpolation is good for gradual, rounded corners but is not good for sharp corners, so an upper bound in the 60 degree range (which is the default) works generally well. Arc interpolation has the advantage of rounding corners without "blunting" them, but sometimes they create "S" shapes where they are not wanted. Make sure to check the results if using arc fit interpolation: strange results can occur if the corner is too sharp and not using <code>-cornerCrop</code>.</p>
<p>Arc interpolation is a variation on spline interpolation where corners are fit to circles rather than splines. If this option is set too large then there's a risk of getting dramatically incorrect trajectories for sharp corners. See also the notes in <code>-arcInterpolationDegs</code>.</p>
</dd>
<dt id="arcInterpolationMaxRatio-ratio"><b><code>-arcInterpolationMaxRatio</code></b> <ratio></dt>
<dd>
<p>Arc interpolation tends to create excessive bow when the spacing between points varies by a lot. It's best with more uniform point spacing. This option limits the ratio of point spacings over which arc interpolation will be applied. The default is 2. Specify 0 for no limit.</p>
</dd>
<dt id="arcInterpolationStart-meters"><b><code>-arcInterpolationStart</code></b> <meters></dt>
<dd>
<p>Where to start arc interpolation, if any. The default is to start any arc interpolation at the start of the course. This can be after <code>-arcInterpolationEnd</code> in which case the region will wrap around.</p>
</dd>
<dt id="author-string"><b><code>-author</code></b> <string></dt>
<dd>
<p>Provide the author of the GPX, as a string. The default will preserve the author of the source GPX.</p>
</dd>
<dt id="auto"><b><code>-auto</code></b></dt>
<dd>
<p>This option automatically turns on options based on "best practices". It will not turn anything off, so can be used in conjunction with other options. Options specifically listed over-ride the -auto option. So for example, to specify that a course is point-to-point and to skip auto-loop detection normally done with <code>-auto</code>, you can do:</p>
<p><code>-processGPX -noloop -auto</code></p>
</dd>
<dt id="autoLap"><b><code>-autoLap</code></b></dt>
<dd>
<p>Synonym for <code>-autoLoop</code></p>
</dd>
<dt id="autoLoop"><b><code>-autoLoop</code></b></dt>
<dd>
<p>Automatically determine if the -loop option should be invoked based on the relative position and orientation of the beginning and end of the GPX track. This is the default: use <code>-noautoLoop</code> to negate it.</p>
</dd>
<dt id="autoSegments-threshold-optional-power"><b><code>-autoSegments</code></b> <threshold> <optional power></dt>
<dd>
<p>Whether to automatically generate segments for the climb. The threshold is the vertical meters of a 10% gradient climb, where climbs at alternate gradients are adjusted by a term (gradient / 10%)^power, where the default power is 0.5. The names can be set with "autoSegmentNames", with a generic default.</p>
<p>This was designed for use in RGT and has no application in any present program other than GPXMagic.</p>
<p>If in the future BikeTerra supports a similar function then it may be adopted to BikeTerra GPX support.</p>
</dd>
<dt id="autoSegmentFinishMargin-meters"><b><code>-autoSegmentFinishMargin</code></b> <meters></dt>
<dd>
<p>A minimum buffer between an auto-generated segment and the finish banner. The default is 0. 20 meters was a good value with RGT.</p>
<p>This was designed for use in RGT and has no application in any present program other than GPXMagic.</p>
</dd>
<dt id="autoSegmentMargin-meters"><b><code>-autoSegmentMargin</code></b> <meters></dt>
<dd>
<p>A minimum buffer between auto-generated segments. The default is 0 meters. The default in RGT days was 400 meters.</p>
<p>This was designed for use in RGT and has no application in any present program other than GPXMagic.</p>
</dd>
<dt id="autoSegmentNames-list-of-names"><b><code>-autoSegmentNames</code></b> <list of names></dt>
<dd>
<p>A list of names for automatically generated segments, separated by commas or semicolons. The default is "climb" followed by a number. If there are more segments than names, the default will be used for the additional climbs.</p>
<p>This was designed for use in RGT and has no application in any present program other than GPXMagic.</p>
</dd>
<dt id="autoSegmentPower-number"><b><code>-autoSegmentPower</code></b> <number></dt>
<dd>
<p>If the gradient power for autosegments is not provided in the -autoSegments option as a second value, then use this value. The default is 0.5. Decent numbers are from 0.25 to 3, depending on how much focus you want to put on steepness in defining and rating climbs.</p>
<p>This was designed for use in RGT and has no application in any present program other than GPXMagic.</p>
</dd>
<dt id="autoSegmentStartMargin-meters"><b><code>-autoSegmentStartMargin</code></b> <meters></dt>
<dd>
<p>A minimum buffer between the start banner and the first segment. This defaults is 0, but was 340 meters in RGT days.</p>
<p>This was designed for use in RGT and has no application in any present program other than GPXMagic.</p>
</dd>
<dt id="autoSegmentStretch-relative-amount"><b><code>-autoSegmentStretch</code></b> <relative amount></dt>
<dd>
<p>The amount of distance increase one is willing to extend an auto-segment to reach a true peak or valley. This is applied to each side, so a value of 0.05 will result in up to a 10% increase in the total length of an automatically generated segment. The increase will not be applied if it would result in the loss of mandated margin (by -autoSegmentMargin) to an adjacent segment, or too close to the start (-autoSegmentStartMargin) or finish (-autoSegmentFinishMargin)</p>
<p>This was designed for use in RGT and has no application in any present program other than GPXMagic.</p>
</dd>
<dt id="autoSmoothG-scale-factor"><b><code>-autoSmoothG</code></b> <scale factor></dt>
<dd>
<p>This invokes gradient autosmoothing selectively along the course, using a similar syntax to <code>-autoSmooth</code> and <code>-autoSmoothZ</code>. For details on gradient smoothing, see the <code>-smoothG</code> option.</p>
</dd>
<dt id="autoSmoothZ-scale-factor"><b><code>-autoSmoothZ</code></b> <scale factor></dt>
<dd>
<p>This invokes an auto-smoothing algorithm whereby more altitude smoothing is applied where gradient changes rapidly point-to-point, less altitude smoothing where gradient changes slowly. This is done after the conventional position and altitude smoothing specified with <code>-smooth</code> and/or <code>-smoothZ</code>. So it allows the use of less of these fixed smoothings, and apply an additional smoothing where it is most needed. An application of this would be a course where the altitude is low quality on a subset of the total course, and one thus wants more averaging averaging focused on that subset.</p>
<p>The scale factor controls how much smoothing is applied. It is roughly calibrated so "1" works well, but you can try reducing that to 0.5, for example, and see if the results are still satisfactory, or increasing it to 2 if the gradient is still too spiky.</p>
<p>Consider using <code>-smoothZ</code> instead unless you think there's a reason the quality of the data is worse in some areas than in others: that applies uniform smoothing over the whole course. Or the two can be combined.</p>
</dd>
<dt id="autoSpacing"><b><code>-autoSpacing</code></b></dt>
<dd>
<p>Specify that points will be interpolated based on an algorithm. The key parameter is <code>-smoothAngle</code>, which determines where points are placed. This only makes sense if the a smoothing distance or a minRadius is also provided, via the <code>-smooth</code> or <code>-minRadius</code> options.</p>
<p>This option is highly recommended (either explicitly or implicitly via -auto or <code>-outAndBack</code>): it greatly improves the smoothness of corners.</p>
</dd>
<dt id="autoSplits-number"><b><code>-autoSplits</code></b> <number></dt>
<dd>
<p>Number of files into which the original should be automatically splot. So 1 here will do nothing. 2 would divide the original into two equal length routes.</p>
<p>These splits are in addition to splits generated by the <code>-splitAt</code> option. If you want to precisely place the split points, then the -splitAt option is better.</p>
<p>If you specify an output file and do not specify a specific split number with the <code>-splitNumber</code> option, then the output files will have a suffix of _split followed by a split number (1, 2, 3 ...).</p>
<p>If you want to base splits on modeled ride time instead of distance, use <code>-timeSplits</code>.</p>
<p>An alternate specification is <code>-distanceSplits</code>.</p>
</dd>
<dt id="autoStraighten-max-deviation-min-length"><b><code>-autoStraighten</code></b> <max deviation> <min length></dt>
<dd>
<p>This specifies the auto-straightening algorithm should be run. It looks for sections of road, at least the minimum length long, where the road deviates laterally no more than the listed amount, each in meters. This is done before any other smoothing.</p>
<p>This may have mixed results. If a minimum deviation is too large, you'll potentially lose details of the route. 2 meters is a decent number. 4 meters is relatively aggressive.</p>
<p>This is in particular designed for routes generated from bike computer data, where rider position will move back and forth across the road, even for straight sections of road. However, if the road doesn't have long straight sections, then this will likely only decrease accuracy.</p>
<p>This option should likely be used in conjunction with some smoothing, for example by additionally providing the <code>-auto</code> option.</p>
</dd>
<dt id="autoStraightenDeviation-meters"><b><code>-autoStraightenDeviation</code></b> <meters></dt>
<dd>
<p>This is an alternative approach to specifying the maximum deviation for auto-straightening. See <code>-autoStraighten</code> for details. The default is 0 (do not do auto-straightening). Good options are 1 to 4 meters, from less aggressive to more aggressive.</p>
</dd>
<dt id="autoStraightenLength-meters"><b><code>-autoStraightenLength</code></b> <meters></dt>
<dd>
<p>The minimum length of a road section to be auto-straightened, in meters. This is an alternative to providing a second argument to an <code>-autoStraighten</code> option. It can be used in conjunction with <code>-autoStraightenDeviation</code> to request auto-straightening.</p>
</dd>
<dt id="circle-meters-...-1-or-more"><b><code>-circle</code></b> <meters> ... (1 or more)</dt>
<dd>
<p>Provide segments to be fit with circles, alternating start distance from start of GPX, and finish distance from start of GPX. This is an alternative to providing values via <code>-circleStart</code> and/or <code>-circleEnd</code>. IF both methods are used, these will be processed first. So for example, <code>-circle</code> 400 500 100 200 will fit circles for points between 400 and 500 meters from the start, then between 100 and 200 meters from the start. Not the further points are listed first so the fit of a circle to these points does not affect the distance to the nearer points. If an odd number of values are specified, the end point of the final point will be the end of the route.</p>
<p>If you want endpoints to be determined automatically, consider using <code>-fitArcs</code> instead.</p>
</dd>
<dt id="circleEnd-meters-1-or-more"><b><code>-circleEnd</code></b> <meters> (1 or more)</dt>
<dd>
<p>Set one or more distances for circle fitting.</p>
<p>See <code>-circleStart</code></p>
</dd>
<dt id="circleStart-meters-1-or-more"><b><code>-circleStart</code></b> <meters> (1 or more)</dt>
<dd>
<p>Set one or more start distances for circle fitting.</p>
<p>This is an option which should be used with care. For the special case where a route includes circular sections, for example laps of the San Francisco Polo Fields, you can move points to a circle which passes thru the end-points of an interval, and a point approximately mid-way between the end-points. This should be followed up with a bit of smoothing over the interval to clean up the transitions to and from the circular arc. Be careful in defining the endpoints so the direction doesn't change suddenly. For example, you don't want the circular arc to overshoot, requiring the direction to correct in the opposite direction. Consider only fitting the circular arc to a center portion of the curve.</p>
<p>The circular arc is fit between points starting at <code>-circleStart</code> and ending at <code>-circleEnd</code> from the start. If the <code>-isLoop</code> option is used, the start may come after the end in which case it wraps around. The circular arc is generated after point interpolation but before smoothing.</p>
<p>If you want to generate multiple circular arcs (for example, the Polo fields have circular arcs at each end, separated by straight segments) then specify the same number of values for <code>-circleStart</code> and <code>-circleEnd</code>, for example two values each for an oval like the Polo Fields.</p>
<p>If multiple values are listed, then multiple sections will be replaced. Distances will be updated after each circular segment replacement. So if you want to do multiple circular replacements, list them from further to closer relative to the start to avoid the distances for later fits being affected by earlier fits.</p>
<p>An alternative to this is to use the <code>-fitArcs</code> option, which automatically searches for candidate sections.</p>
</dd>
<dt id="circuitFromPoint-meters-circuits-repeats-meters"><b><code>-circuitFromPoint</code></b> <meters> <circuits> [<repeats>] [<meters> ..]</dt>
<dd>
<p>This is an alias for <code>-circuitFromPosition</code>.</p>
</dd>
<dt id="circuitFromPosition-meters-circuits-repeats-meters"><b><code>-circuitFromPosition</code></b> <meters> <circuits> [<repeats>] [<meters> ..]</dt>
<dd>
<p>This option allows you to specify a circuit starting at a certain distance from the start of the track. The code will go to a point that distance from the start. It will then search forward to where the course returns to the specified point and define that as a circuit.</p>
<p>If the number of circuits is greater than 1, it will repeat these points to create multiple circuits. If the number is zero, it will delete the points. If the number is one, then nothing will change.</p>
<p>An optional number of repeats may be specified if the circuit returns to this point more than once, in which case it must return to the original point the specified number of times.</p>
</dd>
<dt id="circuitToPoint-meters-circuits-repeats-meters"><b><code>-circuitToPoint</code></b> <meters> <circuits> [<repeats>] [<meters> ..]</dt>
<dd>
<p>This is an alias for <code>-circuitToPosition</code>.</p>
</dd>
<dt id="circuitToPosition-meters-circuits-repeats-meters"><b><code>-circuitToPosition</code></b> <meters> <circuits> [<repeats>] [<meters> ..]</dt>
<dd>
<p>This is like circuitFromPosition, except the distance specified is from the end of the course rather than the beginning, and the circuit ends at the specified point rather than starts there. So for example specifying a distance of 0 would search for a circuit which ends at the end of the track.</p>
</dd>
<dt id="closed"><b><code>-closed</code></b></dt>
<dd>
</dd>
<dt id="closedLoop"><b><code>-closedLoop</code></b></dt>
<dd>
</dd>
<dt id="closeLoop"><b><code>-closeLoop</code></b></dt>
<dd>
<p>Equivalent to <code>-copyPoint</code> <code>-loop</code>. Negation negates <code>-copyPoint</code> and negates <code>-loop</code> unless it has already been been set.</p>
</dd>
<dt id="copyPoint"><b><code>-copyPoint</code></b></dt>
<dd>
<p>For <code>-loop</code> courses, copy the first point to the end of the list of points, so the circuit is explicitly closed. If this is used without <code>-loop</code> then the result will be the same but smooting will not extend across the S/F line. You probably want <code>-closeLoop</code> instead.</p>
</dd>
<dt id="copyright-string"><b><code>-copyright</code></b> <string></dt>
<dd>
<p>If you want to specify a copyright field in the GPX, list it here. The default will preserve the copyright of the source GPX.</p>
</dd>
<dt id="cornerCrop-meters"><b><code>-cornerCrop</code></b> <meters></dt>
<dd>
<p>If there is a sharp corner, defined as an angle in the range between <code>-minCornerCropDegs</code><code> and -minCornerCropDegs</code>, then points are placed before and after the corner and the corner point itself is deleted, The cropped corner is then rounded with a circular arc. Corner cropping allows for a reduction in smoothing and avoids <code>-minAngle</code> causing corners to bow outward. This is only done if the straight segments before and after the corner have sufficient length for the interpolated points to be placed.</p>
</dd>
<dt id="cornerCropArcFit"><b><code>-cornerCropArcFit</code></b></dt>
<dd>
<p>Whether to do arc fits when corner cropping. This is the default, so to negate it use <code>-nocornerCropArcFit</code>. Without arc interpolation, the cropped corner will be angular.</p>
</dd>
<dt id="cornerCropEnd-meters"><b><code>-cornerCropEnd</code></b> <meters></dt>
<dd>
<p>Where to stop corner cropping</p>
</dd>
<dt id="cornerCropStart-meters"><b><code>-cornerCropStart</code></b> <meters></dt>
<dd>
<p>Where to begin corner cropping</p>
</dd>
<dt id="cornerEffect-number"><b><code>-cornerEffect</code></b> <number></dt>
<dd>
<p>This adjusts the corner effect on gradient smoothing, which maintains the original gradient in corners. The default is 1. A nonpositive number turns off the experimental algorithm. A number between 0 and 1 makes is weaker. A number greater than 1 makes it stronger. In some cases using a value of 2 may help pin down a corner leading into or coming out of a steep climb, for example. However, larger numbers may lead to irregularities due to the rapid modification of smoothing.</p>
<p>This is not used in altitude or position smoothing.</p>
</dd>
<dt id="cornerSmoothing"><b><code>-cornerSmoothing</code></b></dt>
<dd>
<p>This controls how much curvature is smoothed before being applied to corner identification. The default is 10 meters. Increasing the number puts the emphasis on identifying larger-angle corners, and filtering out S-curves, for example.</p>
</dd>
<dt id="cornerThreshold"><b><code>-cornerThreshold</code></b></dt>
<dd>
<p>This is the threshold of smoothed corners for the marking of corners, for example via the <code>-addCornerWaypoints</code> option. Units are inverse meters. The reciprical of this number is the maximum effective centerline turning radius of the corners to be marked. The default is 0.05, avoiding gradual corners. Note if <code>-minRadius</code> or <code>-smooth</code> are set too high, no corners will be identified unless this value is decreased.</p>
</dd>
<dt id="crop-meters"><b><code>-crop</code></b> <meters></dt>
<dd>
<p>This is a short-cut for the <code>-cropMax</code> option.</p>
</dd>
<dt id="cropCorners-meters"><b><code>-cropCorners</code></b> <meters></dt>
<dd>
<p>This is an alias for <code>-cornerCrop</code>.</p>
</dd>
<dt id="cropMax-meters"><b><code>-cropMax</code></b> <meters></dt>
<dd>
<p>A point will be interpolated to this distance, if needed, and all points following will be discarded. Distances are calculated after smoothing but before <code>-append</code> or <code>-prepend</code>. It can be useful to design a course beyond the desired length, smooth it, and then crop it, since smoothing can have anomalous effects near the boundaries of the data. This is especially true for a route ending on a section of road previously encountered in the route.</p>
<p>Since smoothing is affected by points ahead of and behind the given point, it is good to extend the points a few smoothing lengths, then crop it back to the desired endpoints.</p>
<p>Negative values are referenced to the end of the route. So for example, <code>-cropMax -140</code> would set a value 140 meters from the end of the route.</p>
</dd>
<dt id="cropMin-meters"><b><code>-cropMin</code></b> <meters></dt>
<dd>
<p>Points prior to this will be stripped, and if needed, a point will be interpolated to this position. This shifts the start position of the GPX route. See <code>-cropMax</code> for more discussion.</p>
<p>Negative values are referenced to the end of the route. So for example, <code>-cropMin -10000</code> would set a value 10 km from the end of the route.</p>
</dd>
<dt id="cropStart-meters"><b><code>-cropStart</code></b> <meters></dt>
<dd>
<p>Alias for <code>-cropMin</code></p>
</dd>
<dt id="cropStop-meters"><b><code>-cropStop</code></b> <meters></dt>
<dd>
<p>Alias for <code>-cropMax</code></p>
</dd>
<dt id="crossingAngle-degees"><b><code>-crossingAngle</code></b> <degees></dt>
<dd>
<p>If set, then this is the minimum degrees by which segments need to intercept to be treated as crossings. If intercepting by less than this absolute angle, they are treated as separate. The default is 11.25. This can be increased since the default on twisty out-and-back sections might get marked as crossings otherwise.</p>
</dd>
<dt id="crossingHeight-meters"><b><code>-crossingHeight</code></b> <meters></dt>
<dd>
<p>If <code>-fixCrossings</code> is invoked, then the code will attempt to identify crossings and adjust the altitude at them. Typically crossings will be either level (same altitude each direction) or at some minimum height (bridges). That minumim height defaults to 2 meters, but can be adjusted with this parameter. If the GPX file has an altitude difference between zero and this number, it will force whichever is closer, and transition the altitude to either side, maintaining the same mean.</p>
<p>Altitude adjustment is handled by checking if the crossing elevations are close. If they are close, then they are averaged to make them equal. If they are not sufficiently close, they are stretched apart if they are not close enough for a reasonable overpass.</p>
</dd>
<dt id="crossingTransition-meters"><b><code>-crossingTransition</code></b> <meters></dt>
<dd>
<p>If <code>-fixCrossings</code> is invoked, then the altitude at crossings will be flattened over a length specified with <code>-rCrossings</code>. This flattening will be transitioned back to the original altitude over a transition length which defaults to 3 times rCrossing. However, this may be too short, resulting in excessive gradients. This option allows explicitly setting this transition length, specified in meters</p>
</dd>
<dt id="csv"><b><code>-csv</code></b></dt>
<dd>
<p>Specifies the output will be CSV rather than GPX. This is ignored if an output file is specified with either a "csv" or "gpx" suffix (case insensitive), in which case the suffix is used to determine the format. Other suffixes are ignored.</p>
</dd>
<dt id="curvatureSmoothing"><b><code>-curvatureSmoothing</code></b></dt>
<dd>
<p>Curvature is calculated for each point by calculating the angle change at the center point, divided by half the length of the path from the previous to the next point, ignoring interpolated points. If the spacing of points is close, this can cause an overestimation of effective cornering curvature (an underestimation of the cornering radius). In these cases, it may be helpful to smooth out the curvature with a Gaussian with sigma specified by this option. A good value is <code>-curvatureSmoothing 4</code>.</p>
<p>The downside is the <code>-minRadius</code> option may need to be boosted to deal with curves which are sharply pointed at their apex. So for example, instead of <code>-minRadius 6</code>, you might specify <code>-curvatureSmoothing 4 -minRadius 8</code>.</p>
</dd>
<dt id="deleteRange-meters-meters"><b><code>-deleteRange</code></b> <meters> <meters> ...></dt>
<dd>
<p>This allows the specification of position pairs marking ranges over which points should be deleted. If two points are provided, then the route is deleted starting at the first position and ending at the second position. Additional pairs may be provided to provide additional delete ranges. This deleting, unlike the deleting specified with <code>-deleteMin</code> and/or <code>-deleteMax</code>, is done before point interpolation, but after file joining. This is because it is likely that smoothing will need to be done after the delete. Additional clean-up with a GPX editor like GPXMagic may be useful.</p>
<p>This would be useful, for example, if a GPX file has an out-and-back portion that you want to remove from the route.</p>
<p>If multiple segments are provided the distances are not adjusted between deleting operations. So for example, if <code>-deleteMax 1000 2000 3000 4000</code> were specified, the section from 1000 meters to 2000 meters would be first deleted. This would reduce the distance to the point which was originally at 3000 meters. However, the point at 3000 meters is determined using the distances calculating before any deleting was done. Delete segments should not overlap. Distances should be specified with extreme care, ideally to provide a small gap between the end of what precedes the start of the delete, and what follows the end of the delete, to allow a smooth transition.</p>
<p>If there is only a single position provided, or if there are an odd number of positions, then the only or odd position will be considered a minimum position for deleting. So, for example, <code>-deleteRange 10000</code> would delete the route starting at 10 km, where positions are determined on the unprocessed GPX data.</p>
<p>If the second point of a range is less than the starting point of the range, then the range wraps around, so points at the end of the route (after the start point) and at the beginning of the route (before the finish point) may be deleted.</p>
<p>Deleting ranges doesn't create gaps in the route, of course. It deletes the control points within a given distance range. So the points at either end of the range will be connected. So for example, suppose I have a straight-line course with points at 0 meters, 500 meters, and 1000 meters. I then delete in the range 250 meters to 750 meters. I will now have points at 0, 250 meters, 750 meters, and 1000 meters. The points at 250 meters and 750 meters have been interpolated to define the deletion range, and the point at 500 meters has been deleted.</p>
</dd>
<dt id="description-string"><b><code>-description</code></b> <string></dt>
<dd>
<p>List a description for the GPX metadata. Since the description will likely contain spaces, remember to enclose the string in "quotes", or however else your command-line shell delimits spaces.</p>
</dd>
<dt id="distanceSplits-number"><b><code>-distanceSplits</code></b> <number></dt>
<dd>
<p>Alias for <code>-autoSplits</code>.</p>
</dd>
<dt id="extend-meters"><b><code>-extend</code></b> <meters></dt>
<dd>
<p>This is a simultaneous specificiation of both <code>-prepend</code> and <code>-append</code>.</p>
</dd>
<dt id="extendBack-meters"><b><code>-extendBack</code></b> <meters></dt>
<dd>
<p>This option creates a turn-around loop at the end of a point-to-point route and then truncates it so the extension in length is the specified number of meters. So, for example, <code>-extendBack 200</code> will result in a route 200 meters longer, where the additional length is provided by a turn-around loop, then added distance as needed backtracking along the main route.</p>
<p>This option was added for RGT, which used the final 140 meters of a point-to-point route as a zone for riders to group after the finish. It will likely generate undesirable results with BikeTerra.</p>
<p>This disables <code>-loop</code> or <code>-lap</code>: it's meaningless with a lap course</p>
</dd>
<dt id="finishCircuitDistance-meters"><b><code>-finishCircuitDistance</code></b> <meters></dt>
<dd>
<p>Often races end with finishing circuits after a lead-in. To accomodate this, you can start with a GPX route which includes at least one lap of the finishing circuit, and add finishing loops. This option allows specifying the start position where a lap of the finish circuit begins. The circuit is assumed to extend to the end of the GPX file. The code will add a number of copies of these points specified by the <b><code>-finishCircuits</code></b> option.</p>
<p>So if the course goes from A to B, then completes 3 circuits of the loop B-C-D, then find the distance in meters to point B, then specify that distance as <code>-finishCircuitDistance</code>, and specify <code>-finishCircuits</code> 2. This will add two copies of the loop B-C-D to the end of the data.</p>
<p>If the desired finish of the GPX is not at the same point as the end of the loop, then you'll need to specify a <code>-cropMax</code> value to remove some of the final circuit.</p>
<p>An alternative to this option is the newer <code>-circuitToPosition</code> which if specified with a position of 0 will generate finishing circuits without having to identify the position where the circuits begin. So for example <code>-circuitToPosition 0 3</code> would generate three finishing circuits automatically.</p>
<p>If <code>-finishCircuits</code> is specified but not <code>-finishCircuitDistance</code>, then the result is equivalent to <code>-circuitToPosition</code> to position 0 (counting from end) with one repeat (meaning the circuit starts the penultimate time it reaches the finish point).</p>
</dd>
<dt id="finishCircuits-count"><b><code>-finishCircuits</code></b> <count></dt>
<dd>
<p>A finishing circuit starting at the position specified by the <b><code>-finishCircuitDistance</code></b> option, in meters, will be appended to the initial data this number of times. A value of 1 here implies adding one copy, which will result in two laps of the circuit.</p>
<p>If <code>-finishCircuits</code> is specified but not <code>-finishCircuitDistance</code>, then the result is equivalent to <code>-circuitToPosition</code> to position 0 (counting from end) with one repeat (meaning the circuit starts the penultimate time it reaches the finish point).</p>
</dd>
<dt id="finishCircuitStart-meters"><b><code>-finishCircuitStart</code></b> <meters></dt>
<dd>
<p>Synonym for <code>-finishCircuitDistance</code>.</p>
</dd>
<dt id="fitArcs"><b><code>-fitArcs</code></b></dt>
<dd>
<p>This option says the code should look for regions of points with relatively constant curvature (relatively constant turn radius) and replace them with circular arcs before any other point interpolation or smoothing. The goal is to avoid corners "collapsing" inward after smoothing, which can result in steep switchbacks getting even steeper, while generating corners with relatively constant radius, which works well in games like Biketerra.</p>
<p>The criteria for arc fitting are fairly strict so a turn with relatively few points may be rejected. But on curves which follow a releatively constant radius with sufficient points in the turn, this may help.</p>
<p>The transition into and out of the arc may have an abrupt change of direction so this should be used in addition to, not a replacement for, other smoothing.</p>
</dd>
<dt id="fitArcsAngle-degs"><b><code>-fitArcsAngle</code></b> <degs></dt>
<dd>
<p>Alias for <code>-fitArcsDegs</code>.</p>
</dd>
<dt id="fitArcsDegs-degs"><b><code>-fitArcsDegs</code></b> <degs></dt>
<dd>
<p>This option specifies the number of points which will be used in arc fits. The default of 15 degrees should be fine, especially since the option is typically used in conjunction with additional smoothing.</p>
</dd>
<dt id="fitArcsEnd-meters"><b><code>-fitArcsEnd</code></b> <meters></dt>
<dd>
<p>Where to end fitting arcs, if any. The default is no restriction. On loop courses if the start position is after the end position, the fitting arc region crosses the start/finish.</p>
</dd>
<dt id="fitArcsDMax-meters"><b><code>-fitArcsDMax</code></b> <meters></dt>
<dd>
<p>With <code>-fitArcs</code> considers fitting a circular arc for a set of points, it will reject the fit if any of the points would shift radially by more than this distance with a constant-radius arc. The default is 2 (meters).</p>
</dd>
<dt id="fitArcsStart-meters"><b><code>-fitArcsStart</code></b> <meters></dt>
<dd>
<p>Where to start fitting arcs, if any. The default is no restriction. On loop courses if the start position is after the end position, the fitting arc region crosses the start/finish.</p>
</dd>
<dt id="fitArcsUniformGradient"><b><code>-fitArcsUniformGradient</code></b></dt>
<dd>
<p>Specify that a uniform gradient should be applied when fitting arcs thru corners. This is done before smoothing. The default is no.</p>
</dd>
<dt id="fixCrossings"><b><code>-fixCrossings</code></b></dt>
<dd>
<p>If a route contains crossings, for example a true figure 8, then it will flatten the road on either side of the crossing, and create a transition from the flattened profile back to the unaltered profile. The side of the flattening is determined by the <code>-rCrossing</code> option.</p>
</dd>
<dt id="fixSteps"><b><code>-fixSteps</code></b></dt>
<dd>
<p>Strava route editor is prone to produce points where proximate points have identical altitude, likely because of missing data. This option applies removes the step by applying a uniform gradient to merge the flat segment with the steeper of the two adjacent sides. Of course this is done early in the process, before any interpolation or smoothing.</p>
<p>If there are points with the same altitude you wish to protect from this process, then one approach is slightly change the altitude of the points, for example with the 1 cm "nudge" option in GPXMagic, to avoid equivalent altitudes.</p>
<p>This option is not invoked by <code>-auto</code>, so if you are using Strava Route Editor to generate GPX files, you will probably want to specify this option in addition to a possible <code>-auto</code>.</p>
</dd>
<dt id="flatten-start-meters-altitude-meters-end-meters-altitude-meters-transition-meters-bow-meters"><b><code>-flatten</code></b> <start-meters> <altitude-meters> <end-meters> <altitude-meters> <transition-meters> <bow-meters> ...</dt>
<dd>
<p>This option allows the route to be flattened over a specified coordinate range, with a specified transition length. It might be used for bridges or tunnels, for example, or to eliminate a section with anomalous altitude, for example from LIDAR data.</p>
<p>You sepecify a starting distance, then the altitude at that point, then a finish distance, then (optionally) an altitude at the second point (default is the same altitude as the first point), then optionally a transition length (default is to calculate a reasonable one).</p>
<p>The transition length is used to describe a distance over which a cosine weighting term is used to transition between the fixed altitude, and the prior altitude for those points. This should be made long enough to avoid excessive deviations in gradient.</p>
<p>Bow describes how far up (positive) or down (negative) the center of the segment is raised relative to the straight line connecting the endpoints. This may be useful for suspension bridges, for example.</p>
<p>Multiple sets of six numbers can be provided, in which case altitude flattening is done over each of the specified segments.</p>
<p>Distances are calculated <i>before</i> most route processing, after possible route reversal. So if you are using <code>-reverse</code>, specify the distance values from the start of the route after reversal. It is done before possibly adding circuits, so the adjusted altitudes will be available on all circuits.</p>
<p>If you want a uniform gradient but do not want to specify the endpoint altitudes, consider <code>-uniformGradient</code> instead.</p>
</dd>
<dt id="gAutoSmooth"><b><code>-gAutoSmooth</code></b></dt>
<dd>
<p>Synonym for <code>-autoSmoothG</code></p>
</dd>
<dt id="gSmooth"><b><code>-gSmooth</code></b></dt>
<dd>
<p>Synonym for <code>-smoothG</code></p>
</dd>
<dt id="gSigma"><b><code>-gSigma</code></b></dt>
<dd>
<p>Synonym for <code>-smoothG</code></p>
</dd>
<dt id="gradientPower"><b><code>-gradientPower</code></b></dt>
<dd>
<p>For gradient signs, how much of a power to apply to gradient in determining where signs go. If 0, then all that matters is altitude: put the signs between peaks and valleys. If 1, then a climb which is double the altitude but half the gradient scores the same. The higher this number, the more likely a gradient sign is to go on a short steep pitch versus a longer, more gradual climb containing the short steep pitch.</p>
</dd>
<dt id="gradientThreshold"><b><code>-gradientThreshold</code></b></dt>
<dd>
<p>This determines the threshold at which a gradient sign gets put in. The units are meters: a 10% climb needs to gain this much altitude to get a gradient sign. How much altitude steeper or less steep climbs need to be depends on <code>-gradientPower</code>.</p>
</dd>
<dt id="interpolate-meters"><b><code>-interpolate</code></b> <meters></dt>
<dd>
<p>Synonym for <code>-spacing</code></p>
</dd>
<dt id="join-filenames"><b><code>-join</code></b> <filenames></dt>
<dd>
<p>Add the points from the first track found in these files and append them to the selected track in the original file. The files must reasonably match up end-to-end. To specify alternate tracks than the first, append the selected track after a colon (":"). For example, <code>-join file.gpx:2</code> would select the second track in file <code>file.gpx</code>. This is done before route processing, so for example any smoothing will be applied to all joined files as well as the original file.</p>
</dd>
<dt id="keywords-meters"><b><code>-keywords</code></b> <meters></dt>
<dd>
<p>Add keywords to the GPX output. Multiple keywords can be separated with commas. If there are any spaces, make sure to enclose the string in quotes, or however your command-line shell specified strings should be delimited.</p>
<p>So for example, the following are allowed:</p>
<dl>
<dt id="keywords-test"><code>-keywords test</code></dt>
<dd>
</dd>
<dt id="keywords-test1-test2-test3"><code>-keywords test1,test2,test3</code></dt>
<dd>
</dd>
<dt id="keywords-test1-test2-test31"><code>-keywords "test1, test2, test3"</code></dt>
<dd>
</dd>
</dl>
<p>A "processGPX" keyword is automatically added.</p>
</dd>
<dt id="laneShift-meters"><b><code>-laneShift</code></b> <meters></dt>
<dd>
<p>This shifts the points of a road to the right (for a positive value) or the left (for a negative value) This is used for out-and-back sections, to provide separation between the outward and return legs of the road, which are otherwise described with the same coordinates. In RGT Cycling, a 4 meter shift caused the resulting inward and outward roads to abut, assuring that even if cyclists use the full road width, they will not visually collide. A larger value would result in a grass island between the two directions. A smaller value may result in the roadways overlapping. On BikeTerra, the default lane width is 3 meters, but a larger value is generally needed due to Biketerra's use of splines in connecting trackpoints.</p>
</dd>
<dt id="laneShiftEnd-meters"><b><code>-laneShiftEnd</code></b> <meters></dt>
<dd>
<p>This is an alias for <code>-shiftEnd</code>.</p>
</dd>
<dt id="laneShiftStart-meters"><b><code>-laneShiftStart</code></b> <meters></dt>
<dd>
<p>This is an alias for <code>-shiftStart</code>.</p>
</dd>
<dt id="laneShiftTransition-meters"><b><code>-laneShiftTransition</code></b> <meters></dt>
<dd>
<p>This is an alias for <code>-shiftTransition</code>.</p>
</dd>
<dt id="lap"><b><code>-lap</code></b></dt>
<dd>
<p>Synonym for <code>-loop</code></p>
</dd>
<dt id="lat"><b><code>-lat</code></b></dt>
<dd>
<p>Alias for <code>-newLat</code></p>
</dd>
<dt id="lon"><b><code>-lon</code></b></dt>
<dd>
<p>Alias for <code>-newLon</code></p>
</dd>
<dt id="loop"><b><code>-loop</code></b></dt>
<dd>
<p>The course is considered a loop course, or a circuit, and so smoothing and other operations can take place between the beginning and end of the loop.</p>
<p>This is typically not needed because <code>-autoLoop</code>, which is on by default, is good at determining whether a route should be considered a loop.</p>
</dd>
<dt id="loopLeft"><b><code>-loopLeft</code></b></dt>
<dd>
<p>Specify that turnaround loops should loop to the left (UK, for example). The default is to base it on the <code>-laneShift</code> (left for a negative lane shift, else positive).</p>
</dd>
<dt id="loopRight"><b><code>-loopRight</code></b></dt>
<dd>
<p>Specify that turnaround loops should loop to the right (US, for example). The default is to base it on the <code>-laneShift</code> (left for a negative lane shift, else positive).</p>
</dd>
<dt id="maxCornerCropAngles-degrees"><b><code>-maxCornerCropAngles</code></b> <degrees></dt>
<dd>
</dd>
<dt id="maxCornerCropDegs-degrees"><b><code>-maxCornerCropDegs</code></b> <degrees></dt>
<dd>
<p>The maximum angle at which corner cropping should be done, for example 120 degrees.</p>
</dd>
<dt id="maxSlope"><b><code>-maxSlope</code></b> <%></dt>
<dd>
<p>RGT supported a "maximum slope" option for magic roads. This option allows that to be changed from a default. It is specified in percent. If you specify a number < 1, then that will be assumed to not have been converted into percent, so the number will be multiplied by 100. It is retained here only in case another game implements a similar function.</p>
</dd>
<dt id="minCornerCropAngle-degrees"><b><code>-minCornerCropAngle</code></b> <degrees></dt>
<dd>
</dd>
<dt id="minCornerCropDegs-degrees"><b><code>-minCornerCropDegs</code></b> <degrees></dt>