'\" t
.\" Title: VIKING
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 2021-01-11
.\" Manual: Viking 1.8
.\" Source: Viking
.\" Language: English
.\"
.TH "VIKING" "1" "2021\-01\-11" "Viking" "Viking 1.8"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
viking \- program to manage GPS data
.SH "SYNOPSIS"
.HP \w'\fBviking\fR\ 'u
\fBviking\fR [\fB\-d\fR | \fB\-\-debug\fR] [\fB\-V\fR | \fB\-\-verbose\fR]
.br
[\fB\-\-latitude\fR\ \fIdegrees\fR] [\fB\-\-longitude\fR\ \fIdegrees\fR]
.br
[\fB\-z\fR | \fB\-\-zoom\fR\ \fIZoomLevelOSM\fR] [\fB\-m\fR | \fB\-\-map\fR\ \fIMapId\fR] [\fB\-x\fR | \fB\-\-external\fR]
.br
[\fIfile\fR...] | [\fI\-\fR]
.HP \w'\fBviking\fR\ 'u
\fBviking\fR [\fB\-h\fR | \fB\-\-help\fR]
.HP \w'\fBviking\fR\ 'u
\fBviking\fR [\fB\-v\fR | \fB\-\-version\fR]
.SH "DESCRIPTION"
.PP
Viking is a program to manage GPS data\&.
.PP
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\&. It is written mainly in C with some C++ and uses the GTK+ 2 toolkit\&. It is available for Linux, other POSIX operating systems and Windows\&.
.PP
Homepage:
\m[blue]\fBhttp://viking\&.sf\&.net\fR\m[]
.PP
Viking is licensed under the GNU GPL\&.
.SH "OPTIONS"
.PP
\fBfile\fR
.RS 4
Specify file to load at start\&.
.RE
.PP
\fB\-\fR
.RS 4
Read input from standard in\&.
.RE
.PP
\fB\-d\fR, \fB\-\-debug\fR
.RS 4
Enable debug output\&.
.RE
.PP
\fB\-V\fR, \fB\-\-verbose\fR
.RS 4
Enable verbose output\&.
.RE
.PP
\fB\-?\fR, \fB\-\-help\fR
.RS 4
Show help options\&.
.RE
.PP
\fB\-v\fR, \fB\-\-version\fR
.RS 4
Show version\&.
.RE
.PP
\fB\-\-latitude\fR
.RS 4
Set the initial position to the specified latitude in decimal degrees\&.
.RE
.PP
\fB\-\-longitude\fR
.RS 4
Set the initial position to the specified longitude in decimal degrees\&.
.RE
.PP
\fB\-z\fR, \fB\-\-zoom\fR
.RS 4
Set the initial zoom level\&. The value is the OSM zoom level (0 \- 22)\&.
.RE
.PP
\fB\-m\fR, \fB\-\-map\fR
.RS 4
Add a map layer by specifying the map id\&. The value needs to match one of the internal ids or an id from the maps configuration extension (see below)\&. Specifying a value of 0 will use the configured map layer default\&.
.PP
.RS 4
Internal Map Ids:
.RE
.PP
.RS 4
OSM Mapnik = 13
.RE
.PP
.RS 4
OSM Cycle = 17
.RE
.PP
.RS 4
Mapquest OSM = 19
.RE
.RE
.PP
\fB\-e\fR, \fB\-\-external\fR
.RS 4
Load all specified GPX files in \*(Aqexternal\*(Aq mode\&.
.sp
This is in contrast to importing the data and storing it in the Viking file\&.
.RE
.SH "EXTENDING VIKING"
.PP
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"\&.
.PP
Here is an example:
.sp
.if n \{\
.RS 4
.\}
.nf
\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.PP
You can find more examples in the documentation part of the distribution\&.
.PP
\fBMap Source\fR. It is possible to add new map\*(Aqs sources\&. The file is
~/\&.viking/maps\&.xml\&.
An example of the file in the distribution
doc/examples/maps\&.xml\&.
The VikSlippyMapSource allows to declare any map\*(Aqs source working like OpenStreetMap\&. It supports the following properties:
.PP
id
.RS 4
this is an integer and should be unique as it used to identify the map source
.RE
.PP
name
.RS 4
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)
.RE
.PP
label
.RS 4
the text displayed in the map\*(Aqs source selection dialog
.RE
.PP
hostname
.RS 4
the server\*(Aqs hostname (eg\&. "tile\&.openstreetmap\&.org")
.RE
.PP
url
.RS 4
the parametrized 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")
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
The full parametrized address can just be put in the URL field and the hostname field doesn\*(Aqt need specifying\&.
.sp
e\&.g\&. "https://tile\&.openstreetmap\&.org/%d/%d/%d\&.png"
.sp .5v
.RE
.RE
.PP
zoom\-min (optional)
.RS 4
The minimum zoom value supported by the tile server\&. The Default is 0 if not specified\&.
.RE
.PP
zoom\-max (optional)
.RS 4
The maximum zoom value supported by the tile server\&. The Default is 18 if not specified\&.
.sp
See
\m[blue]\fBZoom Levels\fR\m[]\&\s-2\u[1]\d\s+2
.RE
.PP
lat\-min (optional)
.RS 4
The minimum latitude value in degrees supported by the tile server\&. The Default is \-90 degrees if not specified\&.
.RE
.PP
lat\-max (optional)
.RS 4
The maximum latitude value in degrees supported by the tile server\&. The Default is 90 degrees if not specified\&.
.RE
.PP
lon\-min (optional)
.RS 4
The minimum longitude value in degrees supported by the tile server\&. The Default is \-180 degrees if not specified\&.
.RE
.PP
lon\-max (optional)
.RS 4
The maximum longitude value in degrees supported by the tile server\&. The Default is 180 degrees if not specified\&.
.RE
.PP
file\-extension (optional)
.RS 4
The file extension of the files on disk\&. The default is
\fI\&.png\fR
.sp
If the tile source URL ends in something other than \&.png, then this parameter will need to match it\&.
.sp
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
\fI\&.png\&.tile\fR
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
The file types actually usable are those supported by GDK Pixbuf Library, which includes at least PNG and JPEG\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
Remember to include the beginning
\fI\*(Aq\&.\*(Aq\fR
when specifying this parameter\&.
.sp .5v
.RE
.RE
.PP
switch\-xy (optional)
.RS 4
Swap the X,Y values around in the URL parametrized ordering\&.
.sp
The default is false\&.
.RE
.PP
check\-file\-server\-time (optional)
.RS 4
Sends the timestamp of the tile to the server, so the server can decide whether it should send a new tile or not\&.
.sp
The default is false\&.
.RE
.PP
use\-etag (optional)
.RS 4
Use and compare the
\m[blue]\fBETag\fR\m[]\&\s-2\u[2]\d\s+2
value in determining whether to download a newer tile\&. The default is false\&.
.sp
The ETag value is stored in a separate file in the same directory as the tile to enable checking the value across multiple runs of the program\&.
.RE
.PP
tilesize\-x (optional)
.RS 4
The tile x size\&. The default is 256 pixels if not specified\&.
.RE
.PP
tilesize\-y (optional)
.RS 4
The tile y size\&. The default is 256 pixels if not specified\&.
.RE
.PP
scale (optional)
.RS 4
The tile scale\&. The scale is 1 if not specified\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
Use a value of 2 to represent high res tiles\&. Don\*(Aqt change the tilesize as the internal display size is still based on 256 pixels\&.
.sp .5v
.RE
.RE
The VikTmsMapSource allows to declare any TMS service\&. It supports the following properties (as per VikSlippyMapSource above):
.PP
id
.RS 4
.RE
.PP
label
.RS 4
.RE
.PP
hostname
.RS 4
.RE
.PP
url
.RS 4
.RE
.PP
check\-file\-server\-time (optional)
.RS 4
.RE
.PP
zoom\-min (optional)
.RS 4
.RE
.PP
zoom\-max (optional)
.RS 4
.RE
.PP
lat\-min (optional)
.RS 4
.RE
.PP
lat\-max (optional)
.RS 4
.RE
.PP
lon\-min (optional)
.RS 4
.RE
.PP
lon\-max (optional)
.RS 4
.RE
The VikWmscMapSource allows to declare any WMS or WMS\-C service\&. It supports the following properties (as per VikSlippyMapSource above):
.PP
id
.RS 4
.RE
.PP
label
.RS 4
.RE
.PP
hostname
.RS 4
.RE
.PP
url
.RS 4
.RE
.PP
check\-file\-server\-time (optional)
.RS 4
.RE
.PP
zoom\-min (optional)
.RS 4
.RE
.PP
zoom\-max (optional)
.RS 4
.RE
.PP
lat\-min (optional)
.RS 4
.RE
.PP
lat\-max (optional)
.RS 4
.RE
.PP
lon\-min (optional)
.RS 4
.RE
.PP
lon\-max (optional)
.RS 4
.RE
.PP
\fBGo-to search engines\fR. It is possible to add new new search engines for the "Go\-To" feature\&. The file is
~/\&.viking/goto_tools\&.xml\&.
An example of the file in the distribution
doc/examples/goto_tools\&.xml\&.
Currently, there is a single object class available: VikGotoXmlTool\&. Such feature allows to declare any search engine using a XML format as result\&.
The related properties are:
.PP
label
.RS 4
the text displayed in the
Go\-To
dialog
.RE
.PP
url\-format
.RS 4
the parametrized address of the query, in the spirit of C
\fBprintf\fR
format, with a single "%s" field (replaced by the query string)
.RE
.PP
lat\-path
.RS 4
XML path of the latitude (eg\&.
/root/parent/elem)
.RE
.PP
lat\-attr (optional)
.RS 4
name of the attribute (of previous element) containing the latitude
.RE
.PP
lon\-path
.RS 4
XML path of the longitude (eg\&.
/root/parent/elem)
.RE
.PP
lon\-attr (optional)
.RS 4
name of the attribute (of previous element) containing the longiude
.RE
As a facility (or readability) it is possible to set both path and attribute name in a single property, like an XPath expression\&. To do so, simply set both info in lat\-path (or lon\-path) in the following format:
/root/parent/elem@attribute\&.
.PP
\fBExternal tools\fR. It is possible to add new external tools\&. The file is
~/\&.viking/external_tools\&.xml\&.
An example of the file in the distribution
doc/examples/external_tools\&.xml\&.
The VikWebtoolCenter allows to declare any Webtool using a logic based on center coordinates and zoom level value\&.
The related properties are:
.PP
label
.RS 4
the text displayed in the menu entry
.RE
.PP
url
.RS 4
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")
.RE
The VikWebtoolBounds allows to declare any Webtool using a logic based on bounds coordinates\&.
The related properties are:
.PP
label
.RS 4
the text displayed in the menu entry
.RE
.PP
url
.RS 4
the parametrized address of the tile, in the spirit of C printf format, with 4 "%s" fields for left, right, bottom and top (eg\&. "http://hostname:8111/load_and_zoom?left=%s&right=%s&bottom=%s&top=%s")
.RE
.PP
\fBRouting engine\fR. It is possible to declare new routing engines\&. The file is
~/\&.viking/routing\&.xml\&.
An example of the file in the distribution
doc/examples/routing\&.xml\&.
The
VikRoutingWebEngine
allows to declare a routing engine available via HTTP\&.
The related properties are:
.PP
id
.RS 4
a string, should be unique as it used to identify the routing engine
.RE
.PP
label
.RS 4
the text displayed in the menu entry
.RE
.PP
format
.RS 4
The
GPSBabel
format code to interpret the service response\&. By default a GPX response is expected and processed internally\&. However if the service returns different format then
GPSBabel
is used to transform the text into something that Viking can understand\&. Only formats that
GPSBabel
supports can be used: e\&.g\&. \*(Aqgpx\*(Aq, \*(Aqkml\*(Aq, \*(Aqgtrnctr\*(Aq (for Garmin Training Center \&.tcx files), etc\&.\&.\&.
.sp
Use
\fBgpsbabel \-\-help\fR
on the command line to find out the supported file types and their codes to process them\&.
.RE
.PP
url\-base
.RS 4
the base URL of the web service (eg\&. "http://hostname/service?")
.RE
.PP
url\-start\-ll
.RS 4
the part of the URL setting the starting point location, parametrized in the spirit of C printf format, with 2 "%s" for coordinates (eg\&. "&start=%s,%s")
.RE
.PP
url\-stop\-ll
.RS 4
the part of the URL setting the end point location, parametrized in the spirit of C printf format, with 2 "%s" for coordinates (eg\&. "&stop=%s,%s")
.RE
.PP
url\-via\-ll (optional)
.RS 4
the part of the URL setting via point location, parametrized in the spirit of C printf format, with 2 "%s" for coordinates (eg\&. "&via=%s,%s")
.RE
.PP
url\-start\-dir (optional)
.RS 4
the part of the URL setting the starting point location for direction based routing, parametrized in the spirit of C printf format, with one "%s" for direction (eg\&. "&start=%s")
.RE
.PP
url\-stop\-dir (optional)
.RS 4
the part of the URL setting the end point location for direction based routing, parametrized in the spirit of C printf format, with one "%s" for direction (eg\&. "&start=%s")
.RE
.PP
url\-ll\-lat\-first (optional)
.RS 4
The ordering of the lat/long terms in the Start, Stop and Via URL settings\&. By default this is TRUE\&.
.sp
For instance using Brouter services, the URL uses a pair of values which is longitude and then latitude\&. Thus setting this value to FALSE ensures the value substitution is performed in the necessary order\&.
.RE
.PP
referer (optional)
.RS 4
A URL to serve as referer for the HTTP request (eg\&. "http://hostname/")
.RE
.PP
follow\-location (optional)
.RS 4
the max depth of recursive redirections
.RE
.PP
\fBRemote File Datasources\fR. It is possible to add web references expected to return a file which can then be opened directly or converted via GPSBabel\&.
The file is
~/\&.viking/datasources\&.xml\&.
An example of the file is in the source distribution
doc/examples/datasources\&.xml\&.
The VikWebtoolDatasource allows to declare any URL using logic based on coordinates\&.
The related properties are:
.PP
label
.RS 4
the text displayed in the menu entry
.RE
.PP
url
.RS 4
the parametrized URL to open in the spirit of C printf format, with up to 7 "%s" values\&. e\&.g\&.
http://hostname/getfile?lat=%s&lon=%s
.sp
The order and meaning of these parameters is given by the url_format_code below
.RE
.PP
url_format_code
.RS 4
A string describing the parametrized URL substitution parameters, each character represents how to translate each term\&.
.sp
B = Bottom of the current view i\&.e\&. minimum latitude
.sp
L = Left of the current view i\&.e\&. minimum longitude
.sp
T = Top of the current view i\&.e\&. maximum latitude
.sp
R = Right of the current view i\&.e\&. maximum longitude
.sp
A = center lAtitude of the current view
.sp
O = center lOngitude of the current view
.sp
Z = OSM Zoom value of the current view\&. See
\m[blue]\fBZoom Levels\fR\m[]\&\s-2\u[1]\d\s+2
.sp
S = A user specified input string requested from the user via a dialog box
.sp
Thus for the url example above then the format code should be
\fIAO\fR
.RE
.PP
file_type
.RS 4
This value is passed on for the \-i parameter in interfacing with GPSBabel\&.
.sp
If it is not defined then the returned file is interpreted internally as a GPX file\&.
.sp
Possible values such as \*(Aqkml\*(Aq, \*(Aqmapsource\*(Aq etc\&.\&. can be used\&. See
\m[blue]\fBGPSBabel File Formats\fR\m[]\&\s-2\u[3]\d\s+2
for the full list\&.
.RE
.PP
babel_filter_args
.RS 4
This value is passed on for the filter arguments interfacing with GPSBabel\&.
.sp
E\&.g\&. "\-x nuketypes,routes" can be used to filter all routes from the results\&.
.RE
.PP
input_label
.RS 4
This value is used when requesting input from the user\&.
.sp
It is the label of the text input box\&.
.RE
.SH "FILES"
.PP
~/\&.viking/maps\&.xml
.RS 4
File containing definition of map sources\&.
.sp
See previous section for details\&.
.RE
.PP
~/\&.viking/goto_tools\&.xml
.RS 4
File containing definition of "Go\-to" services\&.
.sp
See previous section for details\&.
.RE
.PP
~/\&.viking/external_tools\&.xml
.RS 4
File containing definition of external tools\&.
.sp
See previous section for details\&.
.RE
.PP
~/\&.viking/datasources\&.xml
.RS 4
File containing definition of remote file datasources\&.
.sp
See previous section for details\&.
.RE
.PP
~/\&.viking/routing\&.xml
.RS 4
File containing definition of routing sources\&.
.sp
See previous section for details\&.
.RE
.PP
~/\&.viking/viking\&.prefs
.RS 4
Preferences for viking\&.
.RE
.PP
~/\&.viking/viking_layer_defaults\&.ini
.RS 4
Layer default values for viking\&.
.RE
.PP
~/\&.viking/viking\&.ini
.RS 4
Values for viking automatically saved between sessions\&.
.sp
Not generally intended to be manually edited\&.
.sp
However some finer control of default internal values can be set\&.
.RE
.PP
~/\&.viking/keys\&.rc
.RS 4
File containing short cut key accelerators\&.
.sp
This is in the standard GTK Accelerator map format\&.
.RE
.PP
~/\&.viking\-maps/
.RS 4
Default location of the map cache of tiles downloaded or created by viking\&.
.RE
.PP
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)\&.
.SH "ENVIRONMENT"
.PP
\fBXDG_DATA_HOME\fR
.RS 4
Optional directory to look for extension files (maps\&.xml,
goto_tools\&.xml,
datasources\&.xml,
external_tools\&.xml,
routing\&.xml)\&.
.RE
.PP
\fBXDG_DATA_DIRS\fR
.RS 4
Path used to change the directories scanned for extension files (maps\&.xml,
goto_tools\&.xml,
datasources\&.xml,
external_tools\&.xml,
routing\&.xml)\&.
.RE
.SH "AUTHOR"
.PP
This manual page was originally written by Ralf Meyer
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\&.
.PP
On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common\-licenses/GPL\&.
.SH "COPYRIGHT"
.br
Copyright \(co 2007 Ralf Meyer
.br
Copyright \(co 2010 Guilhem Bonnefille
.br
Copyright \(co 2013 Rob Norris
.br
.SH "NOTES"
.IP " 1." 4
Zoom Levels
.RS 4
\%http://wiki.openstreetmap.org/wiki/Zoom_levels
.RE
.IP " 2." 4
ETag
.RS 4
\%http://en.wikipedia.org/wiki/HTTP_ETag
.RE
.IP " 3." 4
GPSBabel File Formats
.RS 4
\%http://www.gpsbabel.org/capabilities.html
.RE