-
Notifications
You must be signed in to change notification settings - Fork 8
/
help.txt
1604 lines (1549 loc) · 107 KB
/
help.txt
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
# ./map_matching_2 --help
Available Options:
--help show this help, can be combined with an
application mode for more help
--version show the version of this software
-c [ --config ] arg (=options.conf) configuration file, can contain settings
for all options;
explicitly specified command line options
override configuration file settings;
if explicitly specified, file needs to
exist
--verbose show more output during operation
--quiet silent mode, deactivates any output,
overrides verbose
Application Modes:
--prepare prepare mode for importing and converting
network data into the application
specific network format; usually, this
mode needs to be run first at once, since
all other modes need the resulting binary
files from this mode.
--match map matching mode for command line
operation for fitting GNSS tracks to the
prepared road network.
--server map matching server mode for running the
map matching interface as a HTTP web
service.
(NOT YET IMPLEMENTED)
--compare compare mode for computing the accuracy,
similarities, and differences from two
different map matching runs;
a typical use case is evaluating map
matching results against given ground
truth routes.
# ./map_matching_2 --prepare --help
Available Options:
--help show this help, can be combined with an
application mode for more help
--version show the version of this software
-c [ --config ] arg (=options.conf) configuration file, can contain
settings for all options;
explicitly specified command line
options override configuration file
settings;
if explicitly specified, file needs to
exist
--verbose show more output during operation
--quiet silent mode, deactivates any output,
overrides verbose
Application Modes:
--prepare prepare mode for importing and
converting network data into the
application specific network format;
usually, this mode needs to be run
first at once, since all other modes
need the resulting binary files from
this mode.
--match map matching mode for command line
operation for fitting GNSS tracks to
the prepared road network.
--server map matching server mode for running
the map matching interface as a HTTP
web service.
(NOT YET IMPLEMENTED)
--compare compare mode for computing the
accuracy, similarities, and differences
from two different map matching runs;
a typical use case is evaluating map
matching results against given ground
truth routes.
Prepare Network Options:
-i [ --file ] arg paths to input network files, can be
specified multiple times for multiple
files;
for OSM files, imports all files one
after another, strips duplicate
entries,
and tries to combine the networks, if
possible, else contains them as
individual isles;
in arc-node file format, first file is
the arcs file, second file is the nodes
file,
can also be specified in pairs multiple
times for importing all arc-node files
at once
into a large network, duplicates are
removed by spatial location
-o [ --output ] arg output folder for the prepared network
data in binary files and the
configuration
--format arg (=osm) input network format, see the following
options:
"osm"
OpenStreetMap (OSM) file format, for
example for .osm.pbf, .osm.bz2, and
others
multiple OSM files via --file can be
imported at once, if they overlap,
use --remove-duplicate-edges.
"arc-node"
arc-node file format for the map
matching dataset from Kubicka, M. et
al. (2016)
"Dataset for testing and training
map-matching methods"
first --file needs to be the nodes
file, second --file the arcs file,
because nodes are imported in advance
of arcs
this pair-wise declaration can be
repeated multiple times for importing
all arc-node files at once.
"seattle"
seattle file format for the ground
truth dataset from Newson and Krumm
(2009)
"Hidden Markov Map Matching through
Noise and Sparseness"
multiple --file can be imported in
case it is needed.
automatically enables
--remove-duplicate-nodes due to the
original data containing such.
"melbourne"
melbourne file format for the ground
truth dataset from Li, Hengfeng
(2014)
"Spatio-temporal trajectory
simplification for inferring travel
paths"
first --file needs to be the vertex
file, second --file the edges file,
third --file the streets file
this triple-wise declaration can be
repeated multiple times in case it is
needed.
"giscup"
giscup file format for the map
matching dataset from Ali, M. et al.
(2012)
"ACM SIGSPATIAL GIS Cup 2012"
first --file needs to be the nodes
file, second --file the edges file,
third --file the edge-geometry file
this triple-wise declaration can be
repeated multiple times in case it is
needed.
default is "osm"
Prepare OSM Import Options:
--osm-profile arg (=car) profile for osm import, default is car
road network, can be set to:
"car": car road network profile
"manual": manual profile with tags
explicitely specified
--osm-query arg (=true) osm tag specification string for ways
that are kept when they match the
specified filter
filter specification in Backus-Naur
Form (BNF):
<SPEC> ::= <DEFAULT> { "|" <RULE> }*
<DEFAULT> ::= "true" | "false"
<RULE> ::= <DEFAULT> "," <TAG> [ "="
<VALUE> ]
<TAG> ::= <string>
<VALUE> ::= <string>
Examples:
"true"
accepts all tags
"false|true,highway"
accepts only highway tags
"false|false,highway=construction|tru
e,highway"
accepts only highways that are not
construction (the order is important)
--osm-filter arg (=true) osm tag specification string for ways
that are filtered after they were
queried, so this removes ways in a
second pass that were previously loaded
see osm-query for filter specification
Example:
"true|false,access=no|false,access=pr
ivate"
accept all tags except ways that are
not accessible or private
--osm-oneway arg (=false) osm tag specification string for oneway
description, a queried and not filtered
way is set to a directed oneway edge in
the graph if it matches this filter,
all non-oneway ways become two-way
edges, i.e., two directed edges in both
directions in the graph
see osm-query for filter specification
Example:
"false|true,oneway=yes|true,oneway=tr
ue"
all ways tagged with oneway=yes or
oneway=true become directed edges
--osm-oneway-reverse arg (=false) osm tag specification string for oneway
reverse description, some oneways are
tagged reversed, so if this filter
matches, only the opposing directed
edge is kept in the same manner as if
it had a normal oneway tag initially
see osm-query for filter specification
Example:
"false|true,oneway=reverse"
all ways tagged with oneway=reverse
become directed edges in the opposing
direction
Prepare Spatial Reference System Options:
Spatial Reference System Options:
--srs arg (=4326) spatial reference system (srs) as EPSG
code, default is WGS84 (EPSG 4326)
--srs-type arg srs type, can be set to 'geographic',
'spherical-equatorial', or 'cartesian';
by default automatically detects
'geographic' for srs with latitude and
longitude
and 'cartesian' for srs with x and y
coordinates;
'spherical-equatorial' can be set for
coordinates in latitude and longitude
for faster
but less accurate length and angle
calculations (using haversine) than
'geographic'
Spatial Reference System Reprojection Options:
--transform-srs arg transform spatial reference system
(srs) as EPSG code;
when defined, data is transformed to
given srs;
use EPSG code 3857 as recommendation
for cartesian WGS84 Pseudo-Mercator
projected coordinate system
--transform-srs-type arg transform srs type, can be set to
'geographic', 'spherical-equatorial',
or 'cartesian';
by default automatically detects type,
see '--srs-type' for details
Prepare Files Options:
--graph-file arg (=graph.bin) memory mapped or binary persistent file
for graph storage;
used for storing the finalized
compressed sparse row road network
after modifications are made
--tags-file arg (=tags.bin) memory mapped or binary persistent file
for tags storage;
used for storing the final tags that
are actually referenced from the final
graph road network
--index-file arg (=index.bin) memory mapped or binary persistent file
for spatial index storage;
used for storing the spatial points and
segments indices for the graph road
network
--graph-import-file arg (=tmp_graph.bin)
memory mapped temporary file for graph
storage during import;
used for storing the mutable adjacency
list road network, needed for making
modifications to the graph, (e.g.,
simplify, remove-unconnected),
automatically deleted when no longer
needed;
is only used when memory-mapped-graph-i
mport is on
--tags-import-file arg (=tmp_tags.bin)
memory mapped temporary file for osm
tags storage during graph import;
used for storing the osm tags that are
actually imported from the osm data,
depending on the tag filters used,
automatically deleted when no longer
needed;
is only used when memory-mapped-tags-im
port is on
--index-build-file arg (=tmp_index_build.bin)
memory mapped temporary file for
spatial index build storage;
used for storing the spatial points and
segments data extracted from the final
graph that are then used to pack-build
the spatial indices, automatically
deleted when no longer needed;
is only used when memory-mapped-index-b
uild is on
--osm-vertices-file arg (=tmp_osm_vertices.bin)
memory mapped temporary file for osm
vertices storage;
used for storing the point geometries
that the osm ways reference to,
automatically deleted when no longer
needed;
is only used when memory-mapped-osm-ver
tices is on
--osm-tags-file arg (=tmp_osm_tags.bin)
memory mapped temporary file for osm
tags storage;
used for storing the osm tags that are
seen during osm import, which are later
used as reference for the graph,
automatically deleted when no longer
needed;
is only used when memory-mapped-osm-tag
s is on
--initial-file-size arg (=134217728) initial file size in bytes for sparse
memory mapped files;
the higher the value the less often a
file needs to be flushed, closed,
grown, and reopened during import,
the sparse files do not actually
consume the whole space, only the used
part is actually consumed,
the files are deleted if no longer
needed or shrunken to the actual size
after the import is finished;
default value is 128 MiB = 128 * 1024 *
1024 bytes;
in some memory-mapping configurations,
the initial-file-size is automatically
set to the disk limit,
because some data structures cannot be
resized and need a large enough target
space in advance,
therefore, memory-mapping should be
used with caution on filesystems that
don't support sparse files
Prepare Export Options:
--export-nodes-csv-file arg filename for exporting the finalized
network nodes in CSV-format;
the file (for example "nodes.csv") is
created in the output folder.
--export-edges-csv-file arg filename for exporting the finalized
network edges in CSV-format;
the file (for example "edges.csv") is
created in the output folder.
--export-network-osm-file arg export final network to .osm.pbf file
format;
might contain the data in different
order than the import file;
in case of third-party input networks
without tags, the ways are given the
highway tag
Prepare Process Options:
--simplify arg (=all) simplify network graph, highly
recommended for improving routing and
matching speed drastically;
initially the osm data needs to be
imported with graph nodes for every
straight segment,
simplify merges adjacent straight
segments to lines and remains only the
graph nodes needed for routing,
for example at junctions; the spatial
information (for example curves) of the
graph is not altered;
the following options can be used:
"all"
simplify as much as possible, even
combine roads with different osm ids
and tags, recommended
"none"
do not simplify, road network remains
bigger and slower, but might be
needed to improve accuracy
in special cases, e.g., when
comparing the results to ground-truth
that is based on the original edges
"osm-aware"
simplify, but don't combine roads
with different osm ids and tags,
this mode is usually not recommended,
except special .csv extracts are of
interest
or when the map matching metrics
later down the line respect the osm
tags,
which they do not by design currently
default is "all"
--remove-unconnected arg (=off) remove weakly unconnected components so
that only the largest subgraph remains;
when multiple isle networks are
imported, only the largest isle
remains;
usually is only interesting for
removing tiny network isles in large
networks
--remove-duplicate-nodes arg (=off) remove duplicate nodes by comparing
exact coordinates;
usually is needed if networks were
split in multiple parts with
overlapping nodes on the outer border
--remove-duplicate-edges arg (=off) remove duplicate edges by comparing id,
geometric line, and tags;
usually is needed if multiple networks
with overlapping parts are imported at
once
Memory Options:
--memory-mapping arg (=on) this tool uses memory-mapped files for
graph, index, and OSM import storage by
default, by disabling memory-mapping,
the data can be processed completely in
the main memory (RAM), in this case
binary files consisting of memory dumps
of the graph and indices are used,
during the memory mapped preparation,
some files are only temporary and
discarded after;
the later steps of this tool suite need
to have the same memory-mode
configuration
for example, non-memory-mapped graph
and indices files cannot be used in
memory-mapped mode;
starting up from a memory dump is
slower than starting up from
memory-mapped files, but processing
speed is faster with in-memory
configuration compared to memory-mapped
files;
we recommend using memory-mapped files,
especially when the underlying storage
is of SSD or NVMe type, because the
main memory usage grows very large when
using in-memory configuration
--memory-mapped-graph arg (=on) option for disabling memory mapping for
the final graph;
when specified overrides global
memory-mapping configuration
--memory-mapped-indices arg (=on) option for disabling memory mapping for
the final indices;
when specified overrides global
memory-mapping configuration
--memory-mapped-tags arg (=on) option for disabling memory mapping for
the final tags;
when specified overrides global
memory-mapping configuration
Prepare Memory Options:
--memory-mapped-preparation arg (=on) option for disabling memory mapping for
the intermediate temporary preparation
files;
the final memory mapped files needed
for the map matching software will be
created, but the intermediate temporary
ones, which would automatically be
deleted after import, are not used;
this drastically increases the
importing speed and drastically reduces
the disk writes, also the resulting
files are the same, but a lot more main
memory is needed during preparation
compared to this option disabled, so
use only wich enough main memory;
when specified overrides global
memory-mapping configuration
--memory-mapped-graph-import arg (=on)
option for disabling memory mapping for
the temporary graph import file;
when specified overrides global
memory-mapping-preparation
configuration
--memory-mapped-tags-import arg (=on) option for disabling memory mapping for
the temporary import tags file;
when specified overrides global
memory-mapping-preparation
configuration
--memory-mapped-index-build arg (=on) option for disabling memory mapping for
the temporary index build file;
when specified overrides global
memory-mapping-preparation
configuration
--memory-mapped-osm-vertices arg (=on)
option for disabling memory mapping for
the temporary OSM vertices file;
when specified overrides global
memory-mapping-preparation
configuration
--memory-mapped-osm-tags arg (=on) option for disabling memory mapping for
the temporary OSM tags file;
when specified overrides global
memory-mapping-preparation
configuration
# ./map_matching_2 --match --help
Available Options:
--help show this help, can be combined with an
application mode for more help
--version show the version of this software
-c [ --config ] arg (=options.conf) configuration file, can contain
settings for all options;
explicitly specified command line
options override configuration file
settings;
if explicitly specified, file needs to
exist
--verbose show more output during operation
--quiet silent mode, deactivates any output,
overrides verbose
Application Modes:
--prepare prepare mode for importing and
converting network data into the
application specific network format;
usually, this mode needs to be run
first at once, since all other modes
need the resulting binary files from
this mode.
--match map matching mode for command line
operation for fitting GNSS tracks to
the prepared road network.
--server map matching server mode for running
the map matching interface as a HTTP
web service.
(NOT YET IMPLEMENTED)
--compare compare mode for computing the
accuracy, similarities, and differences
from two different map matching runs;
a typical use case is evaluating map
matching results against given ground
truth routes.
Console Options:
--read-line read-line mode, read WKT track from
console input, overrides track input
files
--console console output mode, write WKT match
result to console, overrides output
files and enables quiet mode for log
messages
Performance Options:
--threads arg (=128) threads that are used for parallel
(i.e., multi-threading) matching or
comparing;
set to 1 for disabling multi-threading,
by default uses the available system
threads
Input Options:
-i [ --input ] arg input folder with the prepared network
data binary files
Spatial Reference System Options:
--network-srs arg (=4326) spatial reference system (srs) as EPSG
code, default is WGS84 (EPSG 4326)
--network-srs-type arg srs type, can be set to 'geographic',
'spherical-equatorial', or 'cartesian';
by default automatically detects
'geographic' for srs with latitude and
longitude
and 'cartesian' for srs with x and y
coordinates;
'spherical-equatorial' can be set for
coordinates in latitude and longitude
for faster
but less accurate length and angle
calculations (using haversine) than
'geographic'
Files Options:
--graph-file arg (=graph.bin) memory mapped or binary persistent
graph file
--tags-file arg (=tags.bin) memory mapped or binary persistent tags
file
--index-file arg (=index.bin) memory mapped or binary persistent
index file
Memory Options:
--memory-mapping arg (=on) this tool uses memory-mapped files for
graph, index, and OSM import storage by
default, by disabling memory-mapping,
the data can be processed completely in
the main memory (RAM), in this case
binary files consisting of memory dumps
of the graph and indices are used,
during the memory mapped preparation,
some files are only temporary and
discarded after;
the later steps of this tool suite need
to have the same memory-mode
configuration
for example, non-memory-mapped graph
and indices files cannot be used in
memory-mapped mode;
starting up from a memory dump is
slower than starting up from
memory-mapped files, but processing
speed is faster with in-memory
configuration compared to memory-mapped
files;
we recommend using memory-mapped files,
especially when the underlying storage
is of SSD or NVMe type, because the
main memory usage grows very large when
using in-memory configuration
--memory-mapped-graph arg (=on) option for disabling memory mapping for
the final graph;
when specified overrides global
memory-mapping configuration
--memory-mapped-indices arg (=on) option for disabling memory mapping for
the final indices;
when specified overrides global
memory-mapping configuration
--memory-mapped-tags arg (=on) option for disabling memory mapping for
the final tags;
when specified overrides global
memory-mapping configuration
Output Options:
-o [ --output ] arg output folder for the application
results
-f [ --filename ] arg (=matches.csv) output filename in the output folder
for the application results
Match Output Options:
--columns arg (=id,duration,track,prepared,match,track_length,prepared_length,match_length,edge_ids)
output columns in order for the
application results, separated by
comma;
id: id of the track, aggregated in
case of multiple ids were specified
duration: matching duration in
seconds
track: original track as it was
imported as WKT
prepared: prepared track as WKT after
track sanitation, i.e., remove
duplicates, median-merge
match: map matching result as WKT
track_length: track length in meter
prepared_length: prepared track
length in meter
match_length: match length in meter
edge_ids: list of original edge IDs
--export-edges arg (=off) export matched routes based on the
complete network edges instead of the
actual parts, this is only useful if
the routes are later compared to
matches that come from a list of edge
IDs, it returns routes with parts in
the beginning and ending of the track,
and at turns, that have no equivalent
part in the track, however, the
resulting routes overlap the network
edges perfectly since they do not
start, end, and turn within the edges
at new points matching the track
--join-merges arg (=on) by default, the routes between
candidates are concatenated, this
parameter removes additional joint
points when possible, so all joint
points are removed except when reverse
movements within an edge happen
Tracks Options:
--tracks arg path to track(s) file;
can be specified multiple times for
multiple track files
--tracks-file-type arg track file type;
by default is automatically detected
from (the first) filename extension;
can be manually overridden to the
following supported file types:
"csv"
"gpx"
"list" (only for matching)
"seattle" (only for matching)
the "list" and "seattle" file types are
special extensions, they are meant to
be specified manually with specific
input files, and they only work in
matching mode, not in comparison mode;
the "list" type awaits as input a list
of network edge IDs, it then exports
the track as WKT, based on the given
network, used for route files from Li,
Hengfeng (2014), Kubicka, M. et al.
(2016), and Ali, M. et al. (2012),
automatically resolves gaps, duplicate
node ids, and duplicate edge ids, if
there are multiple columns, use
--delimiter and --id with a number for
the edge ID column, --skip-lines is
also supported for skipping headers as
they are not needed and unsupported
the "seattle" type is for exporting the
ground truth route as WKT track from
the seattle dataset from Newson and
Krumm (2009), the first file is the
road network file, the second file the
ground truth file, the additional
option is because the "seattle" format
needs a special handling for the
direction
Spatial Reference System Options:
--tracks-srs arg (=4326) spatial reference system (srs) as EPSG
code, default is WGS84 (EPSG 4326)
--tracks-srs-type arg srs type, can be set to 'geographic',
'spherical-equatorial', or 'cartesian';
by default automatically detects
'geographic' for srs with latitude and
longitude
and 'cartesian' for srs with x and y
coordinates;
'spherical-equatorial' can be set for
coordinates in latitude and longitude
for faster
but less accurate length and angle
calculations (using haversine) than
'geographic'
Spatial Reference System Reprojection Options:
--tracks-transform-srs arg transform spatial reference system
(srs) as EPSG code;
when defined, data is transformed to
given srs;
use EPSG code 3857 as recommendation
for cartesian WGS84 Pseudo-Mercator
projected coordinate system
--tracks-transform-srs-type arg transform srs type, can be set to
'geographic', 'spherical-equatorial',
or 'cartesian';
by default automatically detects type,
see '--srs-type' for details
CSV Options:
--delimiter arg (=,) delimiter for .csv tracks file, only
for import, export always uses ','
(because csv means 'comma' separated);
for tabulator you can also use '\t',
and for space '\s', they are replaced
with the true characters before being
applied
--grouped arg (=yes) whether the .csv file is grouped by id,
which is beneficial in coordinates read
mode (non-WKT mode) for faster parsing
of tracks with reduced memory
footprint; grouped means that the id
column is sorted in such a way that all
rows with the same id are put together,
not mixed or interrupted by rows with
different ids; in case grouped is
disabled, the whole .csv file needs to
be parsed and grouped by id before the
matching starts; this setting is
ignored in WKT read mode
--skip-lines arg (=0) skip specified number of lines at the
head of the tracks .csv file, works
also in combination with no-header,
e.g., set to 1 with no-header to skip
an existing header to use number
indices for columns instead
--no-header csv has no header, column
specifications are interpreted as
indices of columns
--no-id csv has no id column, in this case, the
id is an incrementing integer starting
from 0, see also --no-id-whole-file
setting
--no-id-whole-file when active, the whole file, i.e., all
rows get the same id, when disabled
(default), the id is incremented with
each row of data; use this setting with
x,y coordinate points when --no-id is
specified so that the whole file
becomes one track, i.e., combine all
points or the whole file into one track
--id arg (=id) id column(s) of tracks .csv file, can
be specified multiple times for
composite primary keys over multiple
columns, internally, the id-aggregator
field is then used for concatenation of
the values
--id-aggregator arg (=_) used for aggregating the values of
composite primary keys, see id
--wkt use WKT read mode for .csv tracks file
instead of default x,y coordinates read
mode
--x arg (=x) x column (or longitude) of tracks .csv
file in coordinates read mode
--y arg (=y) y column (or latitude) of tracks .csv
file in coordinates read mode
--geometry arg (=geometry) geometry column of tracks .csv file in
WKT read mode can either be of type
POINT or LINESTRING, in POINT mode,
points are sorted ascending by time
column, if available, else by
appearance, in LINESTRING mode,
timestamp is just an incremented value
for each point
--selector arg track selector for matching a specific
track from the tracks file, can be
specified multiple times
CSV/GPX Time Options:
--time arg (=time) time column(s) of tracks .csv file, is
optional if no such column exists, for
example in WKT LINESTRING read mode,
currently, the time column(s) are only
used for sorting points while reading
tracks .csv file, is ignored for .gpx
files; can be specified multiple times
similarly as --id, the time columns are
first aggregated by --time--aggregator
and then parsed by the --time-format,
so the aggregator must be part of the
format, if multiple time columns exist
--time-aggregator arg (=_) used for aggregating the values of
composite time keys, see time
--time-format arg (=%FT%T%Oz) time format for parsing the time value
in the time column into unix timestamp
format, please review
std::chrono::parse documentation for
syntax, default reads ISO 8601 date and
time with time zone
--no-parse-time do not parse time, for example when the
time is already in unix timestamp
format (seconds), or when the time is
not parsable at all (in this case,
increments 1 per second starting from
0), or with .gpx files with invalid
time attribute
Export Options:
--candidates arg export candidates to the given
filename, if no filename is given, no
candidates are exported;
filename is appended to output folder
--candidates-columns arg (=id,part_index,set_index,candidate_index,projection,distance,from,to,edge_id,is_result)
output columns in order for the
candidate exports, separated by comma;
id: id of the track, aggregated in
case of multiple ids were specified
part_index: index of the track part
(i.e., for multi-line tracks)
set_index: index of the candidate set
candidate_index: index of the
candidate within a candidate set
projection: candidate projection from
track point to road network point
distance: distance in meter
from: route from start of the road
network edge to the candidate point
as WKT
to: route from the candidate point to
the end of the road network edge as
WKT
edge_id: original edge ID the
candidate lies on
is_result: true if this candidate is
part of the resulting match
Matching Options:
--filter-duplicates arg (=on) filter duplicate (adjacent spatially
equal) points in tracks before
matching, is recommended
--simplify-track arg (=on) simplify track with Douglas-Peucker
algorithm
--simplify-track-distance-tolerance arg (=5.0)
distance tolerance in meters around
line for Douglas-Peucker algorithm
--median-merge arg (=on) simplify track by merging point clouds
to their median point coordinates, this
reduces the amount of points when
vehicles emit positions from static
positions
--median-merge-distance-tolerance arg (=10.0)
distance tolerance in meters around a
point to merge all points within the
given radius
--adaptive-median-merge arg (=on) adapt median-merge-distance-tolerance
automatically for point clouds that are
far from streets, the distance can be
raised up to half the distance of the
nearest road edge for merging
--within-edge-turns arg (=off) enables turns within edges, when
disabled, turns are only possible at
crossroads and junctions (nodes of the
graph), when enables, turns within
edges (roads of the graph) become
possible, this is done by trimming the
path from the current position to the
next node and back, by default this is
disabled, because it reduces
correctness of results with
candidate-adoption enabled as large
detours are needed for making the
optimizer collapsing candidates, it is,
however, enabled by default when all
candidate-adoption features are
disabled, because then it raises the
correctness of the results as no larger
detours are taken that could not be
collapsed without candidate-adoption
--routing-max-distance-factor arg (=5.0)
max distance factor for upper bound for
routing algorithm, removes all nodes
from routing that are too far away from
the search area between a start and end
node, dramatically reduces routing
duration in networks significantly
larger than the given track
--candidate-adoption-siblings arg (=on)
for each measurement, adopt candidates
from preceding and succeeding
candidate, in other words, each
measurement can choose from at least
three road positions and each road
position is referenced by three
candidates, gives much better results
but has a huge calculation speed impact
--candidate-adoption-nearby arg (=on) for each measurement, adopt candidates
from searching nearby candidates
intersecting a search circle with
distance of the farthest current
candidate, in dense areas with very
near records this exchanges all
candidates between all records, gives
much better results in dense record
areas but has a very huge calculation
speed impact
--candidate-adoption-reverse arg (=off)
for each nearby adoption, inject
current candidate into candidate sets
of adopting candidates this is
especially useful when adaptive
optimization rounds are enabled, new
found candidates are then deployed to
preceding and following locations
around the high error location, has the
highest calculation speed impact
--candidate-search arg (=combined) candidate search algorithm to use,
possible options:
"circle"
searches for all edges around a point
intersecting a circle with at least
given radius
"nearest"
searches the k-nearest edges around a
point
"combined"
searches with a combination of
k-nearest and circle, so that only
the k-nearest points within the
circle radius are retained
"next"
searches only the next nearest edge
(within the nearest and adjacent as
well as reversed edges),
very fast but often inaccurate except
for high precision tracks
--radius arg (=200.0) radius in meters for candidate search
when circle or combined algorithm is
selected, is automatically doubled each
time when no candidates within given
radius are found, radius is starting
radius if adaptive-radius is enabled
(which is by default)
--radius-upper-limit arg (=10000.0) radius upper limit in meters for
candidate search when adaptive-radius
is used, eventually stops automatically
doubling of radius when no candidates
are found
--radius-lower-limit arg (=200.0) radius lower limit in meters for
candidate search when adaptive-radius
is used, prevents too small search
radii in areas with dense track
measurements
--adaptive-radius arg (=on) adaptive-radius is only used when
circle or combined algorithm is
selected, the radius is then reduced to
the minimum distance to the next and
previous candidate, the
radius-lower-limit is never undershot,
when no candidate is found, the radius
is doubled until radius-upper-limit,
this reduces the amount of candidates
in dense road network areas, it works
best with candidate-adoption enabled
--k-nearest arg (=16) k-nearest edges to search for in
candidate search when nearest or
combined algorithm is selected