1VIKING(1) Viking 1.10 VIKING(1)
2
6 viking - program to manage GPS data
7
9 viking [-d | --debug] [-V | --verbose]
10 [--latitude degrees] [--longitude degrees]
11 [-z | --zoom ZoomLevelOSM] [-m | --map MapId] [-x | --external]
12 [file...] | [-]
13 viking [-h | --help]
15 viking [-v | --version]
17
19 Viking is a program to manage GPS data.
20 You can import and plot tracks, routes and waypoints, show
22 OpenStreetMap (OSM) and/or other maps, generate maps (using Mapnik),
23 geotag images, add coordinate lines, make new tracks, routes and
24 waypoints, hide different things, etc. It is written mainly in C with
25 some C++ and uses the GTK+ 3 toolkit. It is available for Linux, other
26 POSIX operating systems and Windows.
27 Homepage: http://viking.sf.net
29 Viking is licensed under the GNU GPL.
31
33 file
34 Specify file(s) to load at start.
35 If a filename is in the 'geo' URI sheme (RFC5870[1]) then the
37 positional information will be used (and it will not attempt to
38 load it as a file)
39 -
41 Read input from standard in.
42 -d, --debug
44 Enable debug output.
45 -V, --verbose
47 Enable verbose output.
48 -?, --help
50 Show help options.
51 -v, --version
53 Show version.
54 --latitude
56 Set the initial position to the specified latitude in decimal
57 degrees.
58 --longitude
60 Set the initial position to the specified longitude in decimal
61 degrees.
62 -z, --zoom
64 Set the initial zoom level. The value is the OSM zoom level (0 -
65 22).
66 -m, --map
68 Add a map layer by specifying the map id. The value needs to match
69 one of the internal ids or an id from the maps configuration
70 extension (see below). Specifying a value of 0 will use the map
71 layer default.
72 Internal Map Ids:
74 OSM Mapnik = 13
76 OSM Cycle = 17
78 OSM Transport = 20
80 OSM Humanitarian = 22
82 -e, --external
84 Load all specified GPX files in 'external' mode.
85 This is in contrast to importing the data and storing it in the
87 Viking file.
88
90 Currently, viking has some extension points based on configuration
91 files. The file format is heavily inspired by the GtkBuilder file
92 format: you specify the class of the GObject to build and set its
93 properties. Technically, it is a XML file containing a "objects" root
94 element. Inside this element, you set a collection of "object".
95 Here is an example:
97 <objects>
99 <object class="ClassName">
100 <property name="property_name1">Property value</property>
101 <property name="property_name2">Property value</property>
102 </object>
103 ...
104 <objects>
105 You can find more examples in the documentation part of the
108 distribution.
109 The User Configuration File Location directory is ~/.viking for
111 versions up to v1.8. For new installs from v1.9 onwards it is
112 ~/.config/viking If the legacy location exists then Viking will use
113 that in preference to the new location.
114 Map Source. It is possible to add new map sources. The file is maps.xml
116 in User Configuration File Location directory. An example of the file
117 in the distribution doc/examples/maps.xml. The VikSlippyMapSource
118 allows declaration of any map source working like OpenStreetMap. It
119 supports the following properties:
120 id
122 this is an integer and should be unique as it used to identify the
123 map source
124 name
126 a string (should be unique) that is used for the OSM style cache
127 directory name when the Map Cache directory is the default (up to
128 v1.8 ~/.viking-maps or v1.9 onwards~/.cache/viking)
129 label
131 the text displayed in the map's source selection dialog
132 hostname
134 the server's hostname (eg. "tile.openstreetmap.org")
135 url
137 the parametrized address of the tile, in the spirit of C printf
138 format, with 3 "%d" fields for Z, X and Y (in that order) (eg.
139 "/%d/%d/%d.png")
140 Note
142 The full parametrized address can just be put in the URL field
143 and the hostname field doesn't need specifying.
144 e.g. "https://tile.openstreetmap.org/%d/%d/%d.png"
146 custom-http-headers (optional)
148 Custom HTTP headers to be added to the download request. The
149 default is none.
150 Multiple headers can be specified by separating each part with an
152 '\n'.
153 The header allows of substition of values of the positional Z, X
155 and Y (in that order) values, as per the url option above. Using
156 multiple and/or different ordered values can be acheived via
157 printf() positional argument specifiers. For example:
158 DNT: 1\nLine2: %d %d %d\nReordered: %3$d %1$d %2$d
160 copyright (optional)
162 The copyright of the map source.
163 license (optional)
165 The license of the map source.
166 license-url (optional)
168 The URL of the license of the map source.
169 zoom-min (optional)
171 The minimum zoom value supported by the tile server. The Default is
172 0 if not specified.
173 zoom-max (optional)
175 The maximum zoom value supported by the tile server. The Default is
176 18 if not specified.
177 See Zoom Levels[2]
179 lat-min (optional)
181 The minimum latitude value in degrees supported by the tile server.
182 The Default is -90 degrees if not specified.
183 lat-max (optional)
185 The maximum latitude value in degrees supported by the tile server.
186 The Default is 90 degrees if not specified.
187 lon-min (optional)
189 The minimum longitude value in degrees supported by the tile
190 server. The Default is -180 degrees if not specified.
191 lon-max (optional)
193 The maximum longitude value in degrees supported by the tile
194 server. The Default is 180 degrees if not specified.
195 file-extension (optional)
197 The file extension of the files on disk. The default is .png
198 If the tile source URL ends in something other than .png, then this
200 parameter will need to match it.
201 This can also be useful in reading a tileset from other software
203 which may name tiles in an alternative form, e.g. for Mobile Atlas
204 creator it names them .png.tile
205 Note
207 The file types actually usable are those supported by GDK
208 Pixbuf Library, which includes at least PNG and JPEG.
209 Note
211 Remember to include the beginning '.' when specifying this
212 parameter.
213 offset-x (optional)
215 The offset of the map in the x plane (towards east) in metres. The
216 default is 0.0 if not specified.
217 Use negative numbers to adjust in a westerly direction.
219 Typical usage would be aligning differing maps, e.g. aerial imagery
221 may be offset from cadastral maps.
222 Currently this is a single value that applies to all zoom levels.
224 offset-y (optional)
226 The offset of the map in the y plane (towards north) in metres. The
227 default is 0.0 if not specified.
228 Use negative numbers to adjust in a southerly direction.
230 switch-xy (optional)
232 Swap the X,Y values around in the URL parametrized ordering.
233 The default is false.
235 check-file-server-time (optional)
237 Sends the timestamp of the tile to the server, so the server can
238 decide whether it should send a new tile or not.
239 The default is false.
241 use-etag (optional)
243 Use and compare the ETag[3] value in determining whether to
244 download a newer tile. The default is false.
245 The ETag value is stored in a separate file in the same directory
247 as the tile to enable checking the value across multiple runs of
248 the program.
249 referer (optional)
251 A URL to serve as referer for the HTTP request (eg.
252 "http://hostname/")
253 follow-location (optional)
255 The maximum number of redirects allowed. The default is 0, i.e. no
256 redirection. Use -1 for an unlimited number of redirects.
257 tilesize-x (optional)
259 The tile x size. The default is 256 pixels if not specified.
260 tilesize-y (optional)
262 The tile y size. The default is 256 pixels if not specified.
263 scale (optional)
265 The tile scale. The scale is 1 if not specified.
266 Note
268 Use a value of 2 to represent high res tiles. Don't change the
269 tilesize as the internal display size is still based on 256
270 pixels.
271 The VikTmsMapSource allows declaration of any TMS service. A TMS (Tile
273 Map Service) is defined in OSGeo wiki[4]. The configuration supports
274 the following properties (as per VikSlippyMapSource above):
275 id
276 label
277 hostname
278 url
279 custom-http-headers (optional)
280 copyright (optional)
281 license (optional)
282 license-url (optional)
283 check-file-server-time (optional)
284 follow-location (optional)
285 referer (optional)
286 zoom-min (optional)
287 zoom-max (optional)
288 lat-min (optional)
289 lat-max (optional)
290 lon-min (optional)
291 lon-max (optional)
292 file-extension (optional)
293 scale (optional)
294 tilesize-x (optional)
295 tilesize-y (optional)
296 offset-x (optional)
297 offset-y (optional)
298 The VikWmscMapSource allows declaration of any WMS or WMS-C service. A
300 WMS (Web Map Service) is defined in WMS Tile Caching[5]. The
301 configuration supports the following properties (as per
302 VikSlippyMapSource above):
303 id
304 label
305 hostname
306 url
307 custom-http-headers (optional)
308 copyright (optional)
309 license (optional)
310 license-url (optional)
311 check-file-server-time (optional)
312 follow-location (optional)
313 referer (optional)
314 zoom-min (optional)
315 zoom-max (optional)
316 lat-min (optional)
317 lat-max (optional)
318 lon-min (optional)
319 lon-max (optional)
320 file-extension (optional)
321 scale (optional)
322 tilesize-x (optional)
323 tilesize-y (optional)
324 offset-x (optional)
325 offset-y (optional)
326 Go-to search engines. It is possible to add new new search engines for
328 the "Go-To" feature. The file is goto_tools.xml in User Configuration
329 File Location directory. An example of the file in the distribution
330 doc/examples/goto_tools.xml. Currently, there is a single object class
331 available: VikGotoXmlTool. This feature allows one to declare any
332 search engine using a XML format as result. The related properties
333 are:
334 label
336 the text displayed in the Go-To dialog
337 url-format
339 the parametrized address of the query, in the spirit of C printf
340 format, with a single "%s" field (replaced by the query string)
341 lat-path
343 XML path of the latitude (eg. /root/parent/elem)
344 lat-attr (optional)
346 name of the attribute (of previous element) containing the latitude
347 lon-path
349 XML path of the longitude (eg. /root/parent/elem)
350 lon-attr (optional)
352 name of the attribute (of previous element) containing the longiude
353 As a facility (or readability) it is possible to set both path and
354 attribute name in a single property, like an XPath expression. To do
355 so, simply set both info in lat-path (or lon-path) in the following
356 format: /root/parent/elem@attribute.
357 External tools. It is possible to add new external tools. The file is
359 external_tools.xml in User Configuration File Location directory. An
360 example of the file in the distribution
361 doc/examples/external_tools.xml. The VikWebtoolCenter allows one to
362 declare any Webtool using a logic based on center coordinates and zoom
363 level value. The related properties are:
364 label
366 the text displayed in the menu entry
367 url
369 the parametrized URL to open, in the spirit of C printf format,
370 with 2 "%s" and a "%d" fields for X, Y and Z (zoom level) (eg.
371 "http://hostname/?lat=%s&lon=%s&zoom=%d")
372 The VikWebtoolBounds allows one to declare any Webtool using a logic
373 based on bounds coordinates. The related properties are:
374 label
376 the text displayed in the menu entry
377 url
379 the parametrized address of the tile, in the spirit of C printf
380 format, with 4 "%s" fields for left, right, bottom and top (eg.
381 "http://hostname:8111/load_and_zoom?left=%s&right=%s&bottom=%s&top=%s")
382 Routing engine. It is possible to declare new routing engines. The file
384 is routing.xml in User Configuration File Location directory. An
385 example of the file in the distribution doc/examples/routing.xml. The
386 VikRoutingWebEngine allows one to declare a routing engine available
387 via HTTP. The related properties are:
388 id
390 a string, should be unique as it used to identify the routing
391 engine
392 label
394 the text displayed in the menu entry
395 format
397 The GPSBabel format code to interpret the service response. By
398 default a GPX response is expected and processed internally.
399 However if the service returns different format then GPSBabel is
400 used to transform the text into something that Viking can
401 understand. Only formats that GPSBabel supports can be used: e.g.
402 'gpx', 'kml', 'gtrnctr' (for Garmin Training Center .tcx files),
403 etc...
404 Use gpsbabel --help on the command line to find out the supported
406 file types and their codes to process them.
407 url-base
409 the base URL of the web service (eg. "http://hostname/service?")
410 url-start-ll
412 the part of the URL setting the starting point location,
413 parametrized in the spirit of C printf format, with 2 "%s" for
414 coordinates (eg. "&start=%s,%s")
415 url-stop-ll
417 the part of the URL setting the end point location, parametrized in
418 the spirit of C printf format, with 2 "%s" for coordinates (eg.
419 "&stop=%s,%s")
420 url-via-ll (optional)
422 the part of the URL setting via point location, parametrized in the
423 spirit of C printf format, with 2 "%s" for coordinates (eg.
424 "&via=%s,%s")
425 url-start-dir (optional)
427 the part of the URL setting the starting point location for
428 direction based routing, parametrized in the spirit of C printf
429 format, with one "%s" for direction (eg. "&start=%s")
430 url-stop-dir (optional)
432 the part of the URL setting the end point location for direction
433 based routing, parametrized in the spirit of C printf format, with
434 one "%s" for direction (eg. "&start=%s")
435 url-ll-lat-first (optional)
437 The ordering of the lat/long terms in the Start, Stop and Via URL
438 settings. By default this is TRUE.
439 For instance using Brouter services, the URL uses a pair of values
441 which is longitude and then latitude. Thus setting this value to
442 FALSE ensures the value substitution is performed in the necessary
443 order.
444 referer (optional)
446 A URL to serve as referer for the HTTP request (eg.
447 "http://hostname/")
448 follow-location (optional)
450 The maximum number of redirects allowed. The default is 0, i.e. no
451 redirection. Use -1 for an unlimited number of redirects.
452 Remote File Datasources. It is possible to add web references expected
454 to return a file which can then be opened directly or converted via
455 GPSBabel. The file is datasources.xml in your User Configuration File
456 Location directory. An example of the file is in the source
457 distribution doc/examples/datasources.xml. The VikWebtoolDatasource
458 allows one to declare any URL using logic based on coordinates. The
459 related properties are:
460 label
462 the text displayed in the menu entry
463 url
465 the parametrized URL to open in the spirit of C printf format, with
466 up to 7 "%s" values. e.g. http://hostname/getfile?lat=%s&lon=%s
467 The order and meaning of these parameters is given by the
469 url_format_code below
470 url_format_code
472 A string describing the parametrized URL substitution parameters,
473 each character represents how to translate each term.
474 B = Bottom of the current view i.e. minimum latitude
476 L = Left of the current view i.e. minimum longitude
478 T = Top of the current view i.e. maximum latitude
480 R = Right of the current view i.e. maximum longitude
482 A = center lAtitude of the current view
484 O = center lOngitude of the current view
486 Z = OSM Zoom value of the current view. See Zoom Levels[2]
488 S = A user specified input string requested from the user via a
490 dialog box
491 Thus for the url example above then the format code should be AO
493 file_type
495 This value is passed on for the -i parameter in interfacing with
496 GPSBabel.
497 If it is not defined then the returned file is interpreted
499 internally as a GPX file.
500 Possible values such as 'kml', 'mapsource' etc.. can be used. See
502 GPSBabel File Formats[6] for the full list.
503 babel_filter_args
505 This value is passed on for the filter arguments interfacing with
506 GPSBabel.
507 E.g. "-x nuketypes,routes" can be used to filter all routes from
509 the results.
510 input_label
512 This value is used when requesting input from the user.
513 It is the label of the text input box.
515
517 The User Configuration File Location directory is ~/.viking for
518 versions up to v1.8. For new installs it is ~/.config/viking from v1.9
519 onwards. If the legacy location exists then Viking will use that in
520 preference to the new location.
521 Configuration: maps.xml
523 File containing definition of map sources.
524 See previous section for details.
526 Configuration: goto_tools.xml
528 File containing definition of "Go-to" services.
529 See previous section for details.
531 Configuration: external_tools.xml
533 File containing definition of external tools.
534 See previous section for details.
536 Configuration: datasources.xml
538 File containing definition of remote file datasources.
539 See previous section for details.
541 Configuration: routing.xml
543 File containing definition of routing sources.
544 See previous section for details.
546 Configuration: viking.prefs
548 Preferences for viking.
549 Configuration: viking_layer_defaults.ini
551 Layer default values for viking.
552 Configuration: viking.ini
554 Values for viking automatically saved between sessions.
555 Not generally intended to be manually edited.
557 However some finer control of default internal values can be set.
559 Configuration: keys.rc
561 File containing short cut key accelerators.
562 This is in the standard GTK Accelerator map format.
564 Up to v1.8 ~/.viking-maps/, v1.9 onwards ~/.cache/viking/
566 Default location of the map cache of tiles downloaded or created by
567 viking.
568 If the legacy location exists then Viking will use that in
570 preference.
571 Extension files (maps.xml, goto_tools.xml, datasources.xml,
573 external_tools.xml, routing.xml) are also searched in /etc/viking and
574 /usr/share/viking directories (or related in your system).
575
577 XDG_DATA_HOME
578 Optional directory to look for extension files (maps.xml,
579 goto_tools.xml, datasources.xml, external_tools.xml, routing.xml).
580 XDG_DATA_DIRS
582 Path used to change the directories scanned for extension files
583 (maps.xml, goto_tools.xml, datasources.xml, external_tools.xml,
584 routing.xml).
585 VIKING_MAPS
587 The path used for the default root location of maps.
588
590 This manual page was originally written by Ralf Meyer
591 <ranfyy@gmail.com> for the Debian(TM) system (but may be used by
592 others). Permission is granted to copy, distribute and/or modify this
593 document under the terms of the GNU General Public License, Version 2
594 any later version published by the Free Software Foundation.
595 On Debian systems, the complete text of the GNU General Public License
597 can be found in /usr/share/common-licenses/GPL.
598
600 Copyright © 2007 Ralf Meyer
601 Copyright © 2010 Guilhem Bonnefille
602 Copyright © 2021 Rob Norris
603
605 1. RFC5870
606 https://tools.ietf.org/html/rfc5870
607 2. Zoom Levels
609 http://wiki.openstreetmap.org/wiki/Zoom_levels
610 3. ETag
612 http://en.wikipedia.org/wiki/HTTP_ETag
613 4. OSGeo wiki
615 https://wiki.osgeo.org/wiki/Tile_Map_Service_Specification
616 5. WMS Tile Caching
618 https://wiki.osgeo.org/wiki/WMS_Tile_Caching
619 6. GPSBabel File Formats
621 http://www.gpsbabel.org/capabilities.html
622Viking 2023-07-22 VIKING(1)
