VIKING(1)

📦
version 1.11+git20261003.e3b3814f · 11 versions
, in ubuntu stonking

🧭 VIKING(1) — viking, Viking 1.11 💅

okay so bestie, sit down, hydrate, because this is the manual page for viking, and it's a whole vibe. This is the section 1 (general commands) man page for Viking 1.11, and we're gonna get through it together, no cap. 🫶

✨ NAME ✨

viking — program to manage GPS data 🗺️

🌸 SYNOPSIS 🌸

like, here's how you actually call her:

viking [-d | --debug] [-V | --verbose]
       [--latitude degrees --longitude degrees]
       [-z | --zoom ZoomLevelOSM] [-m | --map MapId]
       [-c | --config-dir directory] [-e | --external] [-r |
       --running-instance]
       [file...] | [-]

and also, separately:

viking [-h | --help]

and ALSO:

viking [-v | --version]

three whole moods. pick your fighter. 💖

🦋 DESCRIPTION 🦋

Viking is a program to manage GPS data. that's the whole pitch, and honestly? iconic.

You can import and plot tracks, routes and waypoints, show OpenStreetMap (OSM) and/or other maps, generate maps (using Mapnik), geotag images, add coordinate lines, make new tracks, routes and waypoints, hide different things, etc. Literally so much. It is written mainly in C with some C++ and uses the GTK+ 3 toolkit. It is available for Linux, other POSIX operating systems and Windows. cross-platform queen 👑

Homepage: http://viking.sf.net

Viking is licensed under the GNU GPL. 📜

Viking also provides a more extensive manual accessible via the program that expands on some of the concepts introduced here. so if this page is giving appetizer, the in-app manual is the full meal, iykyk. 🍓

🎀 DETAILS 🎀

Details.sp Table 1. File Reference

^(yes bestie, that's literally what's written there — we leave it exactly as-is 🙈)

here's the file reference table, but make it a list because we're cute like that ✨:

  • file(s) — Read the specified files in sequence left to right. order matters, bestie, do not skip ahead. 👀
  • - — Read input from standard in. No other files should be specified. just the one. don't be greedy. 💅

Note that the ordering of files can be important depending on their file type. Subsequent non Viking project files are loaded into the previous Viking project, with the files being processed left to right. so basically, read it like a sentence: left ➡️ right. Some examples:

  • viking file1.gpx file2.gpx file3.gpx

Here all GPX files are loaded into a new Viking project in one window. one window, three files, zero drama. 🫶

  • viking file1.vik file2.vik

Each Viking project file is opened in a new window. two projects, two windows, we love a separate era. 🪟🪟

  • viking file1.vik file2.gpx file3.gpx

The GPX files are loaded into the Viking project in one window. the .vik grabs the .gpx besties and they all vibe together. 💖

  • viking file2.gpx file3.gpx file1.vik

The GPX files are loaded into a new Viking project in a one window and the Viking project is loaded seperately in a seperate window. yeah — same files, different order, completely different outcome. the way that order is the main character here 😭

okay that's part 1, and there's SO much more coming — options, all 40-ish of them, don't you dare leave 💜

📋 Table 2. Command Line Reference 📋

okay bestie, this is the whole roster of command line flags. every single one. grab a snack 🍓

  • -h, --help — shows you the command line options and then dips out (exits). 💅
  • -V, --verbose — run in verbose mode. some info about what Viking is doing gets shown in stdout. not a ton, just the vibes.
  • -d, --debug — run in debug mode. even more info about what Viking is doing shows up in stdout. this also turns on some extra information features in the GUI itself, which is mainly of interest to developers. 🧚 (so if you're not a dev, you're gonna be reading a lot of nerd lore)
  • -v, --version — shows the version and then exits. short king energy.
  • N/A, --latitude — (no short version, sorry babe 🎀) set the initial position to the specified latitude in decimal degrees.
  • N/A, --longitude — (again, no short one) set the initial position to the specified longitude in decimal degrees.
  • -z, --zoom — sets the initial zoom level. the value is the OSM zoom level, which goes from 0 to 22.
  • -m, --map — adds a map layer by specifying the map id. the value needs to match one of the internal ids, or an id from the Map Source Extensions.
    • specifying a value of 0 will use the map layer default.
    • specifying any negative value, e.g. -2, will not show a map (and yes, this overrides the GUI preference that automatically adds one at startup).
  • -e, --external — the files specified on the command line will be loaded in as external files, as per the External reference:??? method. (yes the ??? is literally in the source, iykyk 😭)
    • applies to GPX, FIT, KML or TCX types, so it has no effect on .vik files.
  • -c, --config-dir — use an alternate location for the configuration directory (which will be created if it does not exist).
    • this is useful for using/trying specific configuration values for a particular session, without changing your normal settings. lowkey the best feature for "i wanna test something but i also don't wanna wreck my setup" 🫶
  • -r, --running-instance — opens the specified files in an already running instance of Viking. if no instance is available, then the files will just... not be opened. 💀
    • positional and map option parameters are not used or passed on to the running instance.
    • > Note — this option is not available on Windows(TM).

Table 3. Internal Map Ids 👑 — these are the built-in cuties, bestie, and their secret little numbers:

  • 4UMaps — 801
  • Bing Aerial — 212
  • Blue Marble — 15
  • CalTopo — 29
  • CyclOSM — 65
  • pnvkarte Public Transport — 101
  • OpenSeaMap — 600
  • OpenTopo — 901 (current default) ✨
  • OSM Cycle — 17
  • OSM Humanitarian — 22
  • OSM Mapnik — 13
  • OSM Transport — 20
  • OSM GPS Traces — 33
  • Waymarked Trails Cycling — 702
  • Waymarked Trails Hiking — 701
  • Waymarked Trails MTB — 703
  • Waymarked Trails Riding — 705
  • Waymarked Trails Skating — 704
  • Waymarked Trails Winter — 706

The current list of available Maps and their Id — including the built in ones listed above plus any additional ones added by extended configuration — can be viewed in the main program by going to Help → Maps Information 🫶

An example to open at a specified location with an OSM Mapnik map layer:

viking --latitude 51.4 --longitude -1.3 --zoom 12 --map 13

If a file is also specified on the command line, the command line location and zoom parameters will take precedence. (Command line stays the main character, periodt. 👑)

Viking supports RFC5870[1], the 'geo' URI scheme 🌍. Every 'file' on the command line is checked to see if in fact it is a geo URI. Thus the above example in geo URI format is:

viking geo:51.4,-1.3?z=12 --map 13
Note 💀 As a special combination when both -V and -d are both enabled at the same time, Viking will not delete some of the temporary files created during the program run. This is especially useful to monitor results of download requests (which need to be interpreted) if they suddenly start failing, as the file will have often more detailed information about the failure mode. Lowkey a debugging cheat code, ngl. 🔍

Viking being a GTK+ program means some options are processed by GTK+ itself such as --display. Use the following to find out what they are for your system:

viking --help-gtk

🌈 EXTENDING VIKING 🌈

Extending Viking

Overview

Currently, Viking has some extension points based on configuration files. The file format is heavily inspired by the GtkBuilder file format: you specify the class of the GObject to build and set its properties. Technically, it is a XML file containing a "objects" root element. Inside this element, you set a collection of "object". 🧚

Here is an example:

<objects>
  <object class="ClassName">
    <property name="property_name1">Property value</property>
    <property name="property_name2">Property value</property>
  </object>
  ...
<objects>

You can find more examples as installed on your system and in the documentation part of the distribution. Typically these will be installed into one of the $XDG_DATA_DIR locations, such as /usr/share/viking/ or C:\Program Files\Viking\data depending on the Operating System. 🖥️

It is also possible to override the internal defaults e.g. to update any parameters should they change over time, by adding the values into your configuration file. When you define object group that already exists (and for Maps this means by a repeated Id key, but you may have to examine the source code to work out what the relevant Id values are) then you need to define all the other keys as well, otherwise they will be reset to the defaults. ⚠️ (Yes bestie, all of them. No half-sending it. 💅)

Map Sources

It is possible to add new map sources. The file is maps.xml placed in your User Configuration File Location. 🗺️

An example of the file is in the distribution doc/examples/maps.xml. Further examples and values are online in the Maps Wiki[2] 🌸

The VikSlippyMapSource allows declaration of any map source working like OpenStreetMap. It supports the following properties:

  • id — this is an integer and should be unique as it used to identify the map source 🔢
  • name — a string (should be unique) that is used for the OSM style cache directory name when the Map Cache directory is the default (~/.viking-maps)
  • label — the text displayed in the map's source selection dialog
  • hostname — the server's hostname (eg. "tile.openstreetmap.org")
  • url — the parameterised address of the tile, in the spirit of C printf format, with 3 "%d" fields for Z, X and Y (in that order) (eg. "/%d/%d/%d.png")
Note 🎀 The full parameterised address can just be put in the URL field and the hostname field doesn't need specifying. e.g. "https://tile.openstreetmap.org/%d/%d/%d.png"
  • user-agent (optional) — Override the default user-agent used in the HTTP request.
  • custom-http-headers (optional) — Custom HTTP headers to be added to the download request. The default is none.

Multiple headers can be specified by separating each part with an '\n'.

The header allows of substitutions of values of the positional Z, X and Y (in that order) values, as per the url option above. Using multiple and/or different ordered values can be acheived via printf() positional argument specifiers. For example:

DNT: 1\nLine2: %d %d %d\nReordered: %3$d %1$d %2$d
  • copyright (optional) — The copyright of the map source.
  • license (optional) — The license of the map source.
  • license-url (optional) — The URL of the license of the map source.
  • zoom-min (optional) — The minimum Tiled Web Map zoom value supported by the tile server. The Default is 0 if not specified.
  • zoom-max (optional) — The maximum Tiled Web Map zoom value supported by the tile server. The Default is 18 if not specified.
  • lat-min (optional) — The minimum latitude value in degrees supported by the tile server. The Default is -90 degrees if not specified.
  • lat-max (optional) — The maximum latitude value in degrees supported by the tile server. The Default is 90 degrees if not specified.
  • lon-min (optional) — The minimum longitude value in degrees supported by the tile server. The Default is -180 degrees if not specified.
  • lon-max (optional) — The maximum longitude value in degrees supported by the tile server. The Default is 180 degrees if not specified.
  • file-extension (optional) — The file extension of the files on disk. The default is .png

If the tile source is not a PNG file, then this parameter can be used to specify the naming to give consistent extension filenames on disk.

This can also be useful in reading a tileset from other software which may name tiles in an alternative form, e.g. for Mobile Atlas creator it names them .png.tile

Note ✨ The file types actually usable are those supported by GDK Pixbuf Library, which includes at least PNG and JPEG.
Note 💜 Remember to include the beginning . when specifying this parameter.
  • use-direct-file-access (optional) — Only use files on disk. The default is FALSE 🙈

This can also be useful for tilesets already on disk, because it'll stop Viking from even trying to download any tiles. Slay.

So with this type, the hostname and url parameters are literally not needed and get ignored. Bye.

  • offset-x (optional) — the offset of the map in the x plane (towards east), measured in metres. Default is 0.0 if you don't say anything.

Use negative numbers to nudge it in a westerly direction.

Typical usage: lining up maps that don't line up, e.g. aerial imagery might be offset from cadastral maps. Classic.

Currently this is a single value that applies to all zoom levels. One number to rule them all.

  • offset-y (optional) — the offset of the map in the y plane (towards north), in metres. The default is 0.0 if not specified.

Negative numbers adjust it in a southerly direction.

  • switch-xy (optional) — swaps the X,Y values around in the URL parameterised ordering. The default is false.
  • check-file-server-time (optional) — sends the timestamp of the tile off to the server, so the server can decide whether it should send a new tile or not. The default is true.
  • use-etag (optional) — use and compare the ETag[3] value when working out whether to download a newer tile. The default is false.

The ETag value gets stored in a separate file in the same directory as the tile, so the value can be checked across multiple runs of the program. Persistence, bb.

  • referer (optional) — a URL to serve as referrer for the HTTP request (eg. "http://hostname/").
  • follow-location (optional) — the maximum number of redirects allowed. The default is -1 for an unlimited number of redirects. Use 0 if you do not want to follow redirects.
  • tilesize-x (optional) — the tile x size. The default is 256 pixels if not specified.
  • tilesize-y (optional) — the tile y size. The default is 256 pixels if not specified.
  • scale (optional) — the tile scale. The scale is 1 if not specified.
Note — use a value of 2 to represent high res tiles. Don't change the tilesize, because the internal display size is still based on 256 pixels. Like. Don't.

The VikTmsMapSource lets you declare literally any TMS service. A TMS (Tile Map Service) is defined in Tile Map Service Specification[4]. The config supports the following properties (as per VikSlippyMapSource above):

  • id
  • label
  • hostname
  • url
  • custom-http-headers (optional)
  • copyright (optional)
  • license (optional)
  • license-url (optional)
  • check-file-server-time (optional)
  • follow-location (optional)
  • referer (optional)
  • user-agent (optional)
  • zoom-min (optional)
  • zoom-max (optional)
  • lat-min (optional)
  • lat-max (optional)
  • lon-min (optional)
  • lon-max (optional)
  • file-extension (optional)
  • scale (optional)
  • tilesize-x (optional)
  • tilesize-y (optional)
  • offset-x (optional)
  • offset-y (optional)

The VikWmscMapSource lets you declare any WMS or WMS-C service. A WMS (Web Map Service) is defined in WMS Tile Caching[5]. The config supports the following properties (as per VikSlippyMapSource above):

  • id
  • label
  • hostname
  • url
  • custom-http-headers (optional)
  • copyright (optional)
  • license (optional)
  • license-url (optional)
  • check-file-server-time (optional)
  • follow-location (optional)
  • referer (optional)
  • user-agent (optional)
  • zoom-min (optional)
  • zoom-max (optional)
  • lat-min (optional)
  • lat-max (optional)
  • lon-min (optional)
  • lon-max (optional)
  • file-extension (optional)
  • scale (optional)
  • tilesize-x (optional)
  • tilesize-y (optional)
  • offset-x (optional)
  • offset-y (optional)

🎀 Go-to Search Engines 🎀

It is possible to add new new search engines for the "Go-To" feature. (yes, "new new", the original said it like that, we respect the icon). The file is goto_tools.xml, placed in your User Configuration File Location.

An example of the file lives in the distribution at doc/examples/goto_tools.xml.

Right now there's a single object class available: VikGotoXmlTool. This feature lets you declare any search engine using a XML format as result.

The related properties are:

  • label — the text displayed in the Go-To dialog.
  • url-format — the parameterised address of the query, in the spirit of C printf format, with a single "%s" field (replaced by the query string).
  • lat-path — XML path of the latitude (eg. /root/parent/elem).
  • lat-attr (optional) — name of the attribute (of previous element) containing the latitude.
  • lon-path — XML path of the longitude (eg. /root/parent/elem).
  • lon-attr (optional) — name of the attribute (of previous element) containing the longitude.
  • referer (optional) — a URL to serve as referer for the HTTP request (eg. "http://hostname/").
  • follow-location (optional) — the maximum number of redirects allowed. The default is -1 for an unlimited number of redirects. Use 0 if you do not want to follow redirects.
  • user-agent (optional) — override the default user-agent used in the HTTP request.
  • custom-http-headers (optional) — custom HTTP headers to be added to the HTTP request. The default is none.
Note that unlike custom-http-headers for Tile download requests, it does not perform any value substitutions in this string. Fr fr, none.

As a facility (or just for readability, bestie), it's possible to set both the path and the attribute name in a single property, like an XPath expression. To do that, simply set both bits of info in lat-path (or lon-path) in the following format: /root/parent/elem@attribute.

🛠️ External Tools 🛠️

It is possible to add new external tools. The file is external_tools.xml, placed in your User Configuration File Location.

An example of the file is in the distribution at doc/examples/external_tools.xml.

The VikWebtoolCenter lets you declare any Webtool using a logic based on center coordinates and zoom level value.

The related properties are:

  • label — the text displayed in the menu entry.
  • url — the parametrized URL to open, in the spirit of C printf format, with 2 "%s" and a "%d" fields for X, Y and Z (zoom level) (eg. "http://hostname/?lat=%s&lon=%s&zoom=%d").

The VikWebtoolBounds lets you declare any Webtool using a logic based on bounds coordinates.

The related properties are:

🧭 Routing Engines 🧭

It is possible to declare new routing engines. The file is routing.xml, placed in your User Configuration File Location.

An example of the file is in the distribution at doc/examples/routing.xml.

The VikRoutingWebEngine lets you declare a routing engine that's available via HTTP.

The related properties are:

  • id — a string, and it should be unique because it's used to identify the routing engine.
  • label — the text displayed in the menu entry.
  • format — the GPSBabel format code used to interpret the service response. By default a GPX response is expected and processed internally. But if the service returns a different format, then GPSBabel is used to transform the text into something Viking can understand. Only formats that GPSBabel supports can be used: e.g. gtrnctr (for Garmin Training Center .tcx files), etc...

Use gpsbabel --help on the command line to find out the supported file types and their codes to process them.

Some format codes are handled natively by Viking, such as gpx and kml.

A special format code of viking-geojson-osrm is available for handling responses by OSRM[6] route servers.

  • url-base — the base URL of the web service (eg. "http://hostname/service?").
  • url-start-ll — the part of the URL setting the starting point location, parameterised in the spirit of C printf format, with 2 "%s" for coordinates (eg. "&start=%s,%s").
  • url-stop-ll — the part of the URL setting the end point location, parameterised in the spirit of C printf format, with 2 "%s" for coordinates (eg. "&stop=%s,%s").
  • url-via-ll (optional) — the part of the URL setting via point location, parameterised in the spirit of C printf format, with 2 "%s" for coordinates (eg. "&via=%s,%s").
  • url-start-dir (optional) — the part of the URL setting the starting point location for direction based routing, parameterised in the spirit of C printf format, with one "%s" for direction (eg. "&start=%s").
  • url-stop-dir (optional) — the part of the URL setting the end point location for direction based routing, parameterised in the spirit of C printf format, with one "%s" for direction (eg. "&stop=%s").
  • url-ll-lat-first (optional) — the ordering of the lat/long terms in the Start, Stop and Via URL settings. By default this is TRUE.

For instance, using Brouter services, the URL uses a pair of values which is longitude and then latitude. So setting this value to FALSE makes sure the value substitution is performed in the necessary order.

  • referer (optional) — a URL to serve as referer for the HTTP request (eg. "http://hostname/").
  • follow-location (optional) — the maximum number of redirects allowed. The default is -1 for an unlimited number of redirects. Use 0 if you do not want to follow redirects.
  • user-agent (optional) — override the default user-agent used in the HTTP request.
  • custom-http-headers (optional) — custom HTTP headers to be added to the HTTP request. The default is none.
Note that unlike custom-http-headers for Tile download requests, it does not perform any value substitutions in this string.

📥 Remote File Datasources 📥

It is possible to add web references that are expected to return a file which can then be opened directly, or converted via GPSBabel.

The file is datasources.xml, placed in your User Configuration File Location.

An example of the file is in the source distribution at doc/examples/datasources.xml.

The VikWebtoolDatasource lets you declare any URL using logic based on coordinates.

The related properties are:

  • label — the text displayed in the menu entry.
  • url — the parameterised URL to open, in the spirit of C printf format, with up to 9 "%s" values. e.g. http://hostname/getfile?lat=%s&lon=%s

like, the order and the meaning of every single one of these parameters is literally given by the url_format_code right below, so do not skip this, bestie 👇

  • url_format_code — a string that describes the parameterised URL substitution parameters. Every character tells you how to translate one term. It's giving mad-libs but for coordinates. 🗺️
    • B = Bottom of the current view i.e. minimum latitude
    • L = Left of the current view i.e. minimum longitude
    • T = Top of the current view i.e. maximum latitude
    • R = Right of the current view i.e. maximum longitude
    • A = center lAtitude of the current view
    • O = center lOngitude of the current view
    • Z = OSM Zoom value of the current view. See Zoom Levels[7]
    • P = selected Point's latitude
    • N = selected poiNt's longitude
    • S = A user specified input string requested from the user via a dialog box

So for the url example above, the format code should be AO. periodt. ✨

  • file_type — this value gets passed on as the -i parameter when interfacing with GPSBabel. 🚲

If it's not defined, then the returned file is interpreted internally as a GPX file.

Possible values such as 'kml', 'mapsource' etc.. can be used. See GPSBabel File Formats[8] for the full list.

  • babel_filter_args — this value gets passed on as the filter arguments when interfacing with GPSBabel.

E.g. "-x nuketypes,routes" can be used to filter all routes from the results. bye routes ✂️

  • input_label — this value is used when requesting input from the user.

It is the label of the text input box. 🏷️

  • referer (optional) — a URL to serve as referrer for the HTTP request (eg. "http://hostname/")
  • follow-location (optional) — the maximum number of redirects allowed. The default is -1 for an unlimited number of redirects. Use 0 if you do not want to follow redirects.
  • user-agent (optional) — override the default user-agent used in the HTTP request.
  • custom-http-headers (optional) — custom HTTP headers to be added to the HTTP request. The default is none.

🌍 System Extension File Locations 🌍

okay so heads up: on UNIX(TM) like systems, the extension files (maps.xml, goto_tools.xml, datasources.xml, external_tools.xml, routing.xml) are also searched in /etc/viking and /usr/share/viking directories (or related in your system). 🔍

The $XDG_DATA_DIRS environment variable can be used to change these directories.

The $XDG_DATA_HOME environment variable is also used (if set) to look for these extension files.

🗂️ FILES 🗂️

⚙️ Configuring Viking ⚙️

📁 User Configuration File Location 📁

Viking looks for its configuration files (viking.prefs, viking.ini, viking.ini and keys.rc) in a specific directory, searching legacy locations first before trying new locations. So if you upgrade Viking it will continue to use your existing setup. no config drama, iykyk 💅

For UNIX(TM) like systems:

  • Up to v1.8
    • ~/.viking/
    • (typically /home/username/.viking)
  • From v1.9 onwards
    • XDG Base Directory compliant[9]
    • Typically ~/config/viking/

For Windows(TM) systems:

  • v1.8 or earlier
    • C:\Users\username\.viking
  • v1.9 onwards
    • C:\Users\username\AppData\Local\viking

For Mac(TM):

  • /Library/Application Support/Viking
Note If you've upgraded Viking to v1.9 and want it to use the new location, you will have to manually move the existing directory (when Viking is not running). e.g. in the command line: mv ~/.viking ~/.config/viking
Note The User Configuration File Location directory can be overridden for the current session by explicitly setting the configuration directory via the --config-dir command line option. See the section called “Details” for more detail.

🎀 Primary Settings 🎀

Viking's primary configuration options are controllable via the GUI as previously covered in Preferences:???. 🖱️

These values are stored in the plain text file viking.prefs

✨ Miscellaneous Settings ✨

Various individual values are automatically saved between Viking sessions in the viking.ini file placed in your User Configuration File Location.

This file is not intended to be manually edited, but since it is a plain text file it can be changed if desired. 🙈

Some values in this file are non-GUI, in the sense that there is no way to set it other than by manually entering in the keys and values (the key will not exist in the file otherwise). This allows some fine tuning of Viking behaviours, without resorting to recompiling the code. However is it not expected that these values should need to be changed for a normal user, hence no GUI options for these have been provided.

Here is the list of the non-GUI keys and their default values. 👑

  • curl_cainfo=NULL
    • See CURLOPT_CAINFO[10]
  • For UNIX(TM) like systems: curl_ssl_verifypeer=1
    • For Windows(TM) systems: curl_ssl_verifypeer=0
    • See CURLOPT_SSL_VERIFYPEER[11]
Note If you encounter issues downloading from https sources, setting this to 0 should get HTTPS connections to work. For UNIX(TM) like operating systems SSL Certificate management is typically handled system wide and trusted certificate issuers updated regularly. Whereas for Viking under Windows this is only done at installation/version update time and so may become out of date or encounter unknown sources and thus more likely to raise verification failures. Hence this is why is is turned off by default on Windows(TM) - especially to ensure the default Maps of OpenTopoMap work without manual user intervention.
  • curl_user_agent=NULL
    • Override the default HTTP User-Agent (which is otherwise generated automatically from a combination of Viking's name, the version and curl information) set in all download requests with the value specified.
    • Also see CURLOPT_USERAGENT[12]
    • NB The User Agent for individual downloads/requests can be set via the relevant user-agent property when defining use of additional resources.
  • export_gpsmapper_option=false
    • To enable the export to the little used GPS Mapper format option, set this to true.
  • export_gpspoint_option=false
    • To enable the export to the little used GPS Point format option, set this to true.
  • geoclue_accuracy_level=4
    • Set the integer value for the accuracy level request to the GeoClue service. Values to match the GClueAccuracyLevel[13]:
      • 0 = GCLUE_ACCURACY_LEVEL_NONE
      • 1 = GCLUE_ACCURACY_LEVEL_COUNTRY
      • 4 = GCLUE_ACCURACY_LEVEL_CITY
      • 5 = GCLUE_ACCURACY_LEVEL_NEIGHBORHOOD
      • 6 = GCLUE_ACCURACY_LEVEL_STREET
      • 8 = GCLUE_ACCURACY_LEVEL_EXACT
  • gpx_tidy_points=true
    • ATM Only attempts to remove a suspicious first point of a GPX track (as opposed to any points within a track). 🧹
  • gpx_tidy_points_max_speed=340
    • Over this speed (in metres per second) for the first pair of points - the first point is removed.
  • layers_create_trw_auto_default=false
    • Create new TrackWaypoint layers without showing the layer properties dialog first.
  • layers_panel_calendar_markup_mode=3
    • 0=No markups. 1=Day marked. 2=Day marked and tooltips created. 3=Auto (timed tooltip creation, so if too slow it reverts to 1).
    • If the following message is shown in the message log: vik_layers_panel_calendar_update: detail level reduced as taking too long then consider setting this value to 2 - although with the caveat that calendar refreshes may introduce noticable delays.
  • maps_cache_status_no_file_color=red
  • maps_cache_status_expired_color=yellow
  • maps_cache_status_download_error_color=darkred
  • maps_cache_status_okay_color=teal
Note maps_cache_status_*_color value strings are passed directly into the low level function gdk_color_parse()[14]. The string can either one of a large set of standard names (taken from the X11 rgb.txt file), or it can be a hexadecimal value in the form "#rgb" "#rrggbb", "#rrrgggbbb" or "#rrrrggggbbbb" where 'r', 'g' and 'b' are hex digits of the red, green, and blue components of the color, respectively.
  • maps_max_tiles=1000
  • maps_min_shrinkfactor=0.0312499
  • maps_max_shrinkfactor=8.0000001
  • maps_real_min_shrinkfactor=0.0039062499
  • maps_scale_inc_down=4
  • maps_scale_inc_up=2
  • maps_scale_smaller_zoom_first=true
  • modifications_ignore_visibility_toggle=false
    • Particularly if one often views large .vik files, then changing the visibility of items may be considered just part of the viewing process. Thus maybe you don't want to be notified on exit about such things - in this case you can set this value to true.
  • srtm_http_base_url=https://dds.cr.usgs.gov/srtm/version2_1/SRTM3
    • Allows using an alternative service for acquiring DEM SRTM files. Note that the layout on the server needs to be split into Continent directories.
  • mapnik_buffer_size=128 (in pixels)
  • osm_basic_auth=false
    • Set to true to force the use of HTTP Basic Authentication even when OAuth is available
  • background_max_threads=10
  • background_max_threads_local=Number of CPUs
  • window_default_tool=Select
    • Options are: Pan, Zoom, Ruler or Select
  • window_menubar=true
  • window_copy_centre_full_format=false
  • window_move_scroll_timeout=5 (milliseconds)
    • Time to wait between move scroll events before redrawing
  • window_zoom_scroll_timeout=150 (milliseconds)
    • Time to wait between zoom scroll events before redrawing
  • window_pinch_gesture_factor=1.5
    • Sensitivity factor for pinch zooming. Best to use keep this value somewhere between 0.5 and 3.0 - a higher value is more sensitive.
  • window_mount_device_id=NULL
    • If your desktop environment doesn't automatically mount USB storage devices or you wish to also manage it in Viking - then set this to a device's drive label e.g GARMIN or UUID value.
    • Viking will then put menu entries under Help so you can be manually perform operations as required.
    • This is provided as a very basic opt in feature, only allowing specification and management of just one device via some additional menu entries. Presently no intention to make this a more fully fledged feature; USB device management is left to other programs.
  • version_check_period_days=14
  • trackwaypoint_start_end_distance_diff=100.0
  • trackwaypoint_tab_default=0

This one's the lil switch that decides which tab is showing first when the layer property dialog pops up. 🎀

  • gps_statusbar_format=GSA — this string lives in the Message Format Code ✨
  • geoclue_statusbar_format=SA — also a Message Format Code string
  • trkpt_selected_statusbar_format=KEATDN — yep, Message Format Code again, love that for us
  • utils_nearest_tz_factor=1.0 — no notes attached, it just vibes
  • viewport_history_size=20 — also just vibing here
  • viewport_history_diff_dist=500 — this is in metres. A Go Back or Go Forward request that's further than this range from the last history location will move back to that position. If the request is within this range, it skips over this location and moves on to the next saved history location. 🦋
  • viewport_scale=1 — if Viking doesn't automatically detect a high resolution display, you can force the setting here — typically by setting this to 2.
  • viewport_popup_delay=200 — in milliseconds. Viking should show a popup with the name of the current track selected. If it does not show up (maybe you have a slowish machine 🐌), try increasing this value.
  • external_diary_program=rednotebook[15] — or in Windows it uses C:/Progra~1/Rednotebook/rednotebook.exe. This string value must use Unix separators and must not have spaces. 💀
  • external_astro_program=stellarium[16] — or in Windows use C:/Progra~1/Stellarium/stellarium.exe. Same rules bestie: Unix separators, no spaces. Needs to be version 0.15.0 or greater (otherwise, because of this Bug[17], it does not actually work 🙈).
  • external_text_program=gedit — or in Windows it uses notepad. Unix separators, no spaces, you know the drill.
  • bfilter_simplify=100 — no description, she's mysterious
  • bfilter_compress=0.001 — same, no notes 📎
  • list_date_format=%Y-%m-%d %H:%M — a date format description[18] as passed on to strftime(). Heads up though: when it's displayed in tables, sorting by this column just uses the text value, rather than the underlying date/time value. 😭
  • export_device_path=OS Specific — UNIX = "/media/user/GARMIN/Garmin/GPX", WINDOWS = ":/Garmin/GPX"
  • export_device_trackpoint_limit=10000 (Typical Garmin Edge limit) — older Garmins' limits are typically much lower — the Etrex 20/30 is 500
  • export_device_routepoint_limit=250 — that's the whole thing, no extra lore
  • kmz_default_maps_dir=Empty — you may want to use something like "/media/user/GARMIN/Garmin/CustomMaps"
  • geotag_photo_dir="/home/user/Pictures" — overrides the base search location for photographs. A matching dated directory corresponding to the track is attempted, of the format /geotag_photo_dir/YYYY/MM/DD
  • gpx_comment_time_format="%d-%B-%y %H:%M:%S" — the fallback format used in generating timestamps for waypoints from their comment
  • use_env_browser=false — okay this one's a whole saga, sit down:
    • By default Viking uses the low level function gtk_show_uri_on_window() to open URLs, which typically results in opening a new instance of a web browser.
    • You can override that by setting this configuration value to true and setting the environment variable BROWSER to invoke the browser you want, optionally including command line parameters to invoke the desired behaviour, like "firefox --new-tab".
    • You could even have a more complicated string to run a specific version with a specific profile, e.g.
BROWSER="/home/rob/Downloads/firefox/firefox -P 'Nightly' --new-tab" viking
Note that if you set BROWSER, other programs may also use this value. 👀
  • This is not applicable on Windows, as currently Viking uses the low level function ShellExecute() method to open URLs there.

💬 Message Format Code

Okay so right now, for ease of implementation, the message format code is just a string of characters. 🧵

Each character represents what should be inserted in relation to a Trackpoint.

One day it might evolve into something more user friendly, with a frontend to control it, perhaps allowing arbitrary text too. But for now, at least some control is offered :)

🔤 Character Code

  • G = Some text to display at the start of the message - GPSD
  • K = Some text to display at the start of the message - Trkpt
  • A = Altitude of a Trackpoint
  • S = Speed of a Trackpoint
  • B = Vertical Speed (Climb)
  • C = Course of a Trackpoint
  • L = Location of a Trackpoint
  • T = Time of a Trackpoint
  • M = Time diff of a Trackpoint from the previous trackpoint
  • X = Number of satellites used in the trackpoint fix
  • D = Distance of the trackpoint from the start of a track (following along the track)
  • F = Distance of the trackpoint from the finish (end) of a track (following along the track)
  • P = Distance difference of the trackpoint from the previous trackpoint
  • N = Name of track to which the trackpoint belongs
  • E = Name of the trackpoint

📝 Output Notes

  • If the output has * after it, then the value has been calculated via interpolation (such as speed when the Trackpoint does not contain a speed value).
  • If the output has ** after it, then difficulties were encountered in trying to work out the value, so probably a default of 0 will be shown. 😭

⌨️ Keyboard Shortcuts (Accelerator) Settings

This is held in the file keys.rc in your User Configuration File Location. 💅

It's in the standard GTK Accelerator map format. Values are automatically read in and saved between Viking sessions.

This file is not intended to be manually edited, but since it's a plain text file it can be changed if desired. 🫶

🌍 ENVIRONMENT

  • XDG_DATA_HOME — optional directory to look for extension files (maps.xml, goto_tools.xml, datasources.xml, external_tools.xml, routing.xml).
  • XDG_DATA_DIRS — path used to change the directories scanned for extension files (maps.xml, goto_tools.xml, datasources.xml, external_tools.xml, routing.xml).
  • VIKING_MAPS — the path used for the default root location of maps.

✍️ AUTHOR

This manual page was originally written by Ralf Meyer <ranfyy@gmail.com> for the Debian(TM) system (but may be used by others). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL.

  • Copyright © 2007 Ralf Meyer
  • Copyright © 2010 Guilhem Bonnefille
  • Copyright © 2021 Rob Norris

📎 NOTES

  1. RFC5870 — https://tools.ietf.org/html/rfc5870
  2. Maps Wiki — https://sourceforge.net/p/viking/wikiallura/Maps/
  3. ETag — https://en.wikipedia.org/wiki/HTTP_ETag
  4. Tile Map Service Specification — https://wiki.osgeo.org/wiki/Tile_Map_Service_Specification
  5. WMS Tile Caching — https://wiki.osgeo.org/wiki/WMS_Tile_Caching
  6. OSRM — http://project-osrm.org/
  7. Zoom Levels — https://wiki.openstreetmap.org/wiki/Zoom_levels
  8. GPSBabel File Formats — https://www.gpsbabel.org/capabilities.html
  9. XDG Base Directory compliant — https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
  10. CURLOPT_CAINFO — https://curl.haxx.se/libcurl/c/CURLOPT_CAINFO.html
  11. CURLOPT_SSL_VERIFYPEER — https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html
  12. CURLOPT_USERAGENT — https://curl.se/libcurl/c/CURLOPT_USERAGENT.html
  13. GClueAccuracyLevel — https://www.freedesktop.org/software/geoclue/docs/libgeoclue/libgeoclue-gclue-enums.html#GClueAccuracyLevel
  14. gdk_color_parse() — https://docs.gtk.org/gdk3/type_func.Color.parse.html
  15. rednotebook — https://rednotebook.sourceforge.io/
  16. stellarium — https://stellarium.org/
  17. Bug — https://bugs.launchpad.net/stellarium/+bug/1410529
  18. date format description — https://pubs.opengroup.org/onlinepubs/007908799/xsh/strftime.html

and that's the whole page bestie, we did it 🎉 this one's Viking, dated 2026-10-04, and it's VIKING(1) — periodt. 💖✨

📦 where this page comes from