Ubuntu Manpage: viking - program to manage GPS data

NAME

       viking - program to manage GPS data

SYNOPSIS


       viking [-d | --debug] [-V | --verbose]
              [--latitude degrees] [--longitude degrees]
              [-z | --zoom ZoomLevelOSM] [-m | --map MapId] [-x | --external]
              [file...] | [-]

       viking [-h | --help]

       viking [-v | --version]

DESCRIPTION

       Viking is a program to manage GPS data.

       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+ 3 toolkit. It is
       available for Linux, other POSIX operating systems and Windows.

       Homepage: http://viking.sf.net

       Viking is licensed under the GNU GPL.

OPTIONS

       file
           Specify file(s) to load at start.

           If a filename is in the 'geo' URI sheme (RFC5870[1]) then the positional information will be used
           (and it will not attempt to load it as a file)

       -
           Read input from standard in.

       -d, --debug
           Enable debug output.

       -V, --verbose
           Enable verbose output.

       -?, --help
           Show help options.

       -v, --version
           Show version.

       --latitude
           Set the initial position to the specified latitude in decimal degrees.

       --longitude
           Set the initial position to the specified longitude in decimal degrees.

       -z, --zoom
           Set the initial zoom level. The value is the OSM zoom level (0 - 22).

       -m, --map
           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 map layer
           default.

               Internal Map Ids:

               OSM Mapnik = 13

               OSM Cycle = 17

               OSM Transport = 20

               OSM Humanitarian = 22

       -e, --external
           Load all specified GPX files in 'external' mode.

           This is in contrast to importing the data and storing it in the Viking file.

EXTENDING VIKING

       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 in the documentation part of the distribution.

       The User Configuration File Location directory is ~/.viking for versions up to v1.8. For new installs
       from v1.9 onwards it is ~/.config/viking If the legacy location exists then Viking will use that in
       preference to the new location.

       Map Source. It is possible to add new map sources. The file is maps.xml in User Configuration File
       Location directory.  An example of the file in the distribution doc/examples/maps.xml.  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 (up to v1.8 ~/.viking-maps or v1.9 onwards~/.cache/viking)

       label
           the text displayed in the map's source selection dialog

       hostname
           the server's hostname (eg. "tile.openstreetmap.org")

       url
           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")

               Note
               The full parametrized 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"

       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 substition 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 zoom value supported by the tile server. The Default is 0 if not specified.

       zoom-max (optional)
           The maximum zoom value supported by the tile server. The Default is 18 if not specified.

           See Zoom Levels[2]

       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 URL ends in something other than .png, then this parameter will need to match it.

           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.

       offset-x (optional)
           The offset of the map in the x plane (towards east) in metres. The default is 0.0 if not specified.

           Use negative numbers to adjust in a westerly direction.

           Typical usage would be aligning differing maps, e.g. aerial imagery may be offset from cadastral
           maps.

           Currently this is a single value that applies to all zoom levels.

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

           Use negative numbers to adjust in a southerly direction.

       switch-xy (optional)
           Swap the X,Y values around in the URL parametrized ordering.

           The default is false.

       check-file-server-time (optional)
           Sends the timestamp of the tile to the server, so the server can decide whether it should send a new
           tile or not.

           The default is false.

       use-etag (optional)
           Use and compare the ETag[3] value in determining whether to download a newer tile. The default is
           false.

           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.

       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 0, i.e. no redirection. Use -1 for an
           unlimited number of 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 as the internal display
               size is still based on 256 pixels.

       The VikTmsMapSource allows declaration of any TMS service. A TMS (Tile Map Service) is defined in OSGeo
       wiki[4]. The configuration 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)
           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 allows declaration of any WMS or WMS-C service. A WMS (Web Map Service) is defined
       in WMS Tile Caching[5]. The configuration 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)
           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. The file is
       goto_tools.xml in User Configuration File Location directory.  An example of the file in the distribution
       doc/examples/goto_tools.xml.  Currently, there is a single object class available: VikGotoXmlTool. This
       feature allows one to 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 parametrized 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 longiude
       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.

       External tools. It is possible to add new external tools. The file is external_tools.xml in User
       Configuration File Location directory.  An example of the file in the distribution
       doc/examples/external_tools.xml.  The VikWebtoolCenter allows one to 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 allows one to declare any Webtool using a logic based on bounds coordinates.  The
       related properties are:

       label
           the text displayed in the menu entry

       url
           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")

       Routing engine. It is possible to declare new routing engines. The file is routing.xml in User
       Configuration File Location directory.  An example of the file in the distribution
       doc/examples/routing.xml.  The VikRoutingWebEngine allows one to declare a routing engine available via
       HTTP.  The related properties are:

       id
           a string, should be unique as it used to identify the routing engine

       label
           the text displayed in the menu entry

       format
           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. 'gpx', 'kml', '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.

       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, parametrized 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, parametrized 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, parametrized 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, parametrized 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, parametrized in the
           spirit of C printf format, with one "%s" for direction (eg. "&start=%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. Thus setting this value to FALSE ensures 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 0, i.e. no redirection. Use -1 for an
           unlimited number of redirects.

       Remote File Datasources. 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 datasources.xml in your User Configuration File
       Location directory.  An example of the file is in the source distribution doc/examples/datasources.xml.
       The VikWebtoolDatasource allows one to declare any URL using logic based on coordinates.  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 up to 7 "%s" values. e.g.
           http://hostname/getfile?lat=%s&lon=%s

           The order and meaning of these parameters is given by the url_format_code below

       url_format_code
           A string describing the parametrized URL substitution parameters, each character represents how to
           translate each term.

           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[2]

           S = A user specified input string requested from the user via a dialog box

           Thus for the url example above then the format code should be AO

       file_type
           This value is passed on for the -i parameter in interfacing with GPSBabel.

           If it is 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[6] for the
           full list.

       babel_filter_args
           This value is passed on for the filter arguments interfacing with GPSBabel.

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

       input_label
           This value is used when requesting input from the user.

           It is the label of the text input box.

FILES

The User Configuration File Location directory is ~/.viking for versions up to v1.8. For new installs it
is ~/.config/viking from v1.9 onwards. If the legacy location exists then Viking will use that in
preference to the new location.

Configuration: maps.xml
File containing definition of map sources.