"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY appname "Viking">
<!ENTITY app "<application>Viking</application>">
- <!ENTITY appversion "1.5">
- <!ENTITY manrevision "1.5">
- <!ENTITY date "October 2013">
+ <!ENTITY appversion "1.6.1">
+ <!ENTITY manrevision "1.6.1">
+ <!ENTITY date "November 2015">
]>
<!--
(Do not remove this comment block.)
</listitem>
<listitem>
<para>
-Making maps with coordinate lines.
+Making maps with using <ulink url="http://mapnik.org/">Mapnik</ulink>.
+Not on <trademark>Windows</trademark> at the moment.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
-Import track, route and waypoint files of various types via <application>GPSBabel</application>
+Import
and export track, route and waypoint files of various types via <application>GPSBabel</application>
</para>
</listitem>
<listitem>
</tip>
</section>
+<section><title>Open Recent File</title>
+<para>
+Located on the <menuchoice><guimenu>File</guimenu><guisubmenu>Open Recent File</guisubmenu></menuchoice> menu only.
+</para>
+<para>
+The most recently opened files are available for opening again.
+The number of files remembered is controlled by a value in the <xref linkend="prefs_advanced"/>.
+</para>
+<para>
+Note that files imported via the Acquire mechanism are not available in this list.
+</para>
+</section>
+
<section><title>Save</title>
<para>
Located on the <menuchoice><guimenu>File</guimenu><guisubmenu>Save</guisubmenu></menuchoice> menu and on the toolbar <guibutton>Save</guibutton>.
</para>
</section>
-<section><title>Append</title>
+<section><title>Append File</title>
<para>
-Located on the <menuchoice><guimenu>File</guimenu><guisubmenu>Append</guisubmenu></menuchoice> menu only.
+Located on the <menuchoice><guimenu>File</guimenu><guisubmenu>Append File...</guisubmenu></menuchoice> menu only.
</para>
<para>
Selecting a <emphasis>Viking</emphasis> file from this method will join the file contents to the current window (instead of creating a new one).
</para>
</section>
+<section><title>Properties</title>
+<para>
+Located on the <menuchoice><guimenu>File</guimenu><guisubmenu>Properties</guisubmenu></menuchoice> menu only.
+</para>
+<para>
+Displays some simple properties about the loaded Viking project file (if any), such as full filename including the path, the filesize and the date/time of the file.
+</para>
+</section>
+
+<section><title>Export All</title>
+<para>
+Located on the <menuchoice><guimenu>File</guimenu><guisubmenu>Export All</guisubmenu></menuchoice> menu only.
+Choose either the <menuchoice><guimenu>GPX</guimenu></menuchoice> or <menuchoice><guimenu>KML</guimenu></menuchoice> option.</para>
+<para>
+This allows converting every <xref linkend="TrackWaypoint"/> layer from the existing project into files of the type choosen.
+You will be prompted for a directory into which a new file for each layer will be saved.
+</para>
+<para>
+The KML option uses <application>GPSBabel</application> and so will not be available if <application>GPSBabel</application> can not be detected.
+</para>
+<para>
+Note that some data properties are not supported by the target export file type. Such as item visibility or track colours.
+</para>
+</section>
+
<section id="acquire" xreflabel="acquire"><title>Acquire</title>
<para>
</note>
</section>
+<section><title>KMZ Map File Overview</title>
+<para>
+A <ulink url="https://developers.google.com/kml/documentation/kmzarchives">KMZ file</ulink> is a compressed version of a KML file and associated supporting files.
+</para>
+<para>
+A <ulink url="https://garminbasecamp.wikispaces.com/Custom+Maps">KMZ Map file</ulink> is a KMZ file with an image overlay often for use as a Custom Map on Garmin GPSr devices.
+</para>
+<para>
+&appname; only supports basic properties in KMZ Map files, primarily intended for use with Garmin GPSr devices although KMZ exports are known to be work with Google Earth.
+</para>
+</section>
+
+<section><title>Import KMZ Map File</title>
+<para>
+Located on the <menuchoice><guimenu>File</guimenu></menuchoice> menu only.
+</para>
+<para>
+Enables loading of a selected KMZ map file.
+This generates a new <xref linkend="GeoRef"/> map layer using the overlay image contained within the KMZ file.
+</para>
+</section>
+
+<section><title>Generate KMZ Map File</title>
+<para>
+Located on the <menuchoice><guimenu>File</guimenu></menuchoice> menu only.
+</para>
+<para>
+Enables exporting the current viewport as a KMZ map file.
+The area and zoom level covered by the KMZ map can be adjusted before saving.
+</para>
+<para>
+Note that Garmin GPSr devices have limits in using images if they are too large (e.g. over 3Mb big) in KMZ files.
+&appname; does not enforce any limits on the KMZ files it generates.
+</para>
+</section>
+
</section> <!-- End File Types -->
<section><title>Layers</title>
<listitem><para><xref linkend="Coordinate"/></para></listitem>
<listitem><para><xref linkend="Maps"/></para></listitem>
<listitem><para><xref linkend="GeoRef"/></para></listitem>
+<listitem><para><xref linkend="MapnikRendering"/></para></listitem>
</itemizedlist>
<para>
For each layer there are a few standard options:
</itemizedlist>
<para>Also gives other options for handling multiple items:</para>
<itemizedlist>
-<listitem><para>Sort. Gives the ability to sort the items in the treeview alphabetically</para></listitem>
+<listitem><para>Sort. Gives the ability to sort the items in the treeview alphabetically or by date.</para></listitem>
<listitem><para>Visibility. Offers options to quickly control the visibility of all items within the sublayer, as per <xref linkend="vis_options"/></para></listitem>
</itemizedlist>
</section>
</para>
</note>
</section>
+<section>
+<title>Interpolate Times</title>
+<para>
+Trackpoint timestamps between the first and last points are calculated such that track is travelled at equal speed.
+This is mostly useful when tracks don't have timestamps and you wish to recreate your trip (e.g. you've forgotten to turn on your GPS or the batteries have run out)
+Thus edit the first and last trackpoints to set the approximate times of your trip and then use this to give approximate times along the track.
+When used on tracks with timestamps this will overwrite the existing timestamps.
+</para>
+<note>
+<para>
+This is not available for routes, as they have no timestamps.
+</para>
+</note>
+</section>
</section>
<section><title>Export Track as GPX</title>
<listitem><para>Delete Waypoints from Selection. Same as the layer <link linkend="delete_selection_waypoints">Delete Waypoints from Selection</link></para></listitem>
<listitem><para>List Waypoints. Opens a new dialog with the list. As described in the Aggregrate layer <xref linkend="waypoint_list"/></para></listitem>
</itemizedlist>
+<para>Also gives other options for handling multiple items:</para>
+<itemizedlist>
+<listitem><para>Sort. Gives the ability to sort the items in the treeview alphabetically or by date.</para></listitem>
+<listitem><para>Visibility. Offers options to quickly control the visibility of all items within the sublayer, as per <xref linkend="vis_options"/></para></listitem>
+</itemizedlist>
</section>
<section><title>Waypoint Properties</title>
</para>
</formalpara>
<itemizedlist>
-<listitem><para>Bing Bird's Eye (Aerial) Maps (&appname; Version1.2+)</para></listitem>
-<listitem><para>OpenStreetMap (Mapquest) - This is the default (&appname; Version1.3+)</para></listitem>
+<listitem><para>Bing Aerial Maps (&appname; Version1.2+)</para></listitem>
+<listitem><para>Mapbox Outdoors - This is the default (&appname; Version1.7+)</para></listitem>
<listitem><para>OpenStreetMap (Mapnik)</para></listitem>
<listitem><para>OpenStreetMap (Cycle)</para></listitem>
<listitem><para>OpenStreetMap (Transport) (&appname; Version1.3+)</para></listitem>
The list within the treeview can be sorted.
</para>
<para>
-Currently alphabetical (A to Z or Z to A) sorts are available, since only the name can be seen in the treeview.
+Alphabetical and Date sorts are available.
</para>
+<note>
+<para>
+Generally it is not useful to sort the Top most layer. Sort is mainly intended for Aggregate groups of TrackWaypoint layers.
+</para>
+</note>
</section>
<section id="track_list" xreflabel="Track List"><title>Track List</title>
<para>
Selecting this opens a dialog listing all the tracks in a table along side statistics such as track length and maximum speed.
Each column header is clickable and will reorder the list according to that particular column.
+You can also rearrange the columns via dragging the column header to the new location.
</para>
<para>
This table may be invoked from a variety of different layer levels and will then list only the relevant tracks (and/or routes).
<itemizedlist>
<listitem><para>View. Move the viewport to the area of the item and highlight it.</para></listitem>
<listitem><para>Statistics. Opens the Properties dialog on the <xref linkend="track_statistics"/> tab. Note this will close the track list dialog.</para></listitem>
+<listitem><para>Copy Data. Copy the data fields as text.</para></listitem>
</itemizedlist>
</para>
+<para>
+If multiple entries are selected the only right click option is <emphasis>Copy Data</emphasis>.
+This copies the individual data fields as plain text separated by tab characters, ideal for pasting into other applications in particular spreadsheet programs.
+Note that the order of the fields copied is the default column ordering (irrespective to how they may have been rearranged).
+</para>
</section>
<section id="waypoint_list" xreflabel="Waypoint List"><title>Waypoint List</title>
<para>
Selecting this opens a dialog listing all the waypoints to give a overview of the waypoint information.
Each column header is clickable and will reorder the list according to that particular column.
+You can also rearrange the columns via dragging the column header to the new location.
</para>
<para>
This table may be invoked from a variety of different layer levels and will then list only the relevant waypoints.
<listitem><para>View. Move the viewport to the area of the item and highlight it.</para></listitem>
<listitem><para>Properties. This will open the properties dialog. Note this will close the waypoint list dialog.</para></listitem>
<listitem><para>Show Picture. If enabled, this will open the associated image in an external Image Viewer program.</para></listitem>
+<listitem><para>Copy Data. Copy the data fields as text.</para></listitem>
</itemizedlist>
</para>
+<para>
+If multiple entries are selected the only right click option is <emphasis>Copy Data</emphasis>.
+This copies the individual data fields as plain text separated by tab characters, ideal for pasting into other applications in particular spreadsheet programs.
+Note that the order of the fields copied is the default column ordering (irrespective to how they may have been rearranged).
+</para>
</section>
<section id="vis_options" xreflabel="Visibility Options"><title>Visibility Options</title>
<xi:include href="georef_layer.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+<xi:include href="mapnik_rendering_layer.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
<section id="Coordinate" xreflabel="Coordinate"><title>Coordinate Layer</title>
<para>
This layer is allows drawing of grid lines on the viewport.
</section>
</section>
+<section id="prefs_advanced" xreflabel="Advanced Preferences"><title>Advanced</title>
+<section><title>Save File Reference Mode</title>
+<para>
+ Files referenced within project files can be saved with either absolute or relative paths.
+ Using relative paths can be useful when copying the project file and the associated files between different systems.
+</para>
+</section>
+<section><title>Ask for Name before Track Creation</title>
+<para>A setting to control whether an automatic name is used when creating a new track or route, or whether you are asked to enter a name.</para>
+</section>
+<section><title>Show Tooltip during Track Creation</title>
+<para>A setting to control whether the tooltip with the cumulative track or route distance is shown when creating tracks and routes.</para>
+</section>
+<section><title>The number of recent files</title>
+<para>
+ The number of recent files shown in the <menuchoice><guimenu>File</guimenu><guisubmenu>Open Recent File</guisubmenu></menuchoice> menu.
+ A value of -1 means all files. The new value applies to New Windows only (or on application restart).
+</para>
+</section>
+</section>
+
<section id="prefs_osm" xreflabel="OpenStreetMap Traces Preferences"><title>OpenStreetMap Traces</title>
<section><title>OSM Username + Password</title>
<para>Store your OSM details here, so that you don't need to enter it in every time in the <xref linkend="osm_upload"/> procedure.</para>
</section>
</section>
+<section id="prefs_mapnik" xreflabel="Mapnik Preferences"><title>Mapnik</title>
+<note>
+<para>If any changes to these settings are made, you will need to restart &appname; to make them be applied.
+</para>
+</note>
+<section><title>Plugins Directory</title>
+<para>The location of Mapnik plugins. An attempt is made to automatically determine the initial value,
+ however if this is wrong or Mapnik is upgraded then the directory can be set here.</para>
+</section>
+<section><title>Fonts Directory</title>
+<para>
+The location of fonts for use with Mapnik. Normally it is best to simply use the System's font directory.
+</para>
+</section>
+<section><title>Recurse Fonts Directory</title>
+<para>Load fonts in any sub-directories of the main font directory.</para>
+</section>
+<section><title>Rerender Timeout</title>
+<para>The time in hours before any tile is rerendered.</para>
+<para>This is useful in case the underlying source data for the tiles changes (e.g. OSM data is continually evovling).
+ &appname; normally has no way of knowing when the data has changed, so this simple timeout method is provided to maintain consistency of the tile images.</para>
+</section>
+<section><title>CartoCSS</title>
+<para>This allows setting the specific location of the <emphasis>carto</emphasis> executable.</para>
+</section>
+<section><title>Threads</title>
+<para>
+ The number of threads to use for Mapnik rendering tasks.
+ By default the value is set to the 1 in case of any multi-threading rendering code chain crashes.
+ Otherwise trying setting the value to the number of the CPUs of the system minus one (so as not to overload the system), in order to minimise the overall rendering times.
+</para>
+</section>
+</section>
+
<section id="prefs_routing" xreflabel="Routing Preferences"><title>Routing</title>
<section><title>Routing engine</title>
<para>You can select the routing engine used by default, ie by features that do not propose a live selection, like <xref linkend="route_finder"/>.</para>
</programlisting>
</para>
<para>You can find more examples in the documentation part of the distribution.</para>
- <section>
+ <para>
+ 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.
+ </para>
+ <section id="map_source" xreflabel="Map Source Extensions">
<title>Map Source</title>
<para>It is possible to add new map's sources. The file is <filename>~/.viking/maps.xml</filename> for <trademark>UNIX</trademark> like systems, <filename>C:\Documents and Settings\<replaceable>username</replaceable>\.viking\maps.xml</filename> on <trademark>Windows XP</trademark> or <filename>C:\Users\<replaceable>username</replaceable>\.viking\maps.xml</filename> on <trademark>Windows 7</trademark> onwards.</para>
<para>An example of the file is in the distribution <filename>doc/examples/maps.xml</filename>. Further examples and values are online in the <ulink url="http://sourceforge.net/apps/mediawiki/viking/index.php?title=Maps">Maps Wiki</ulink></para>
</varlistentry>
<varlistentry>
<term>url</term>
- <listitem><para>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")</para></listitem>
+ <listitem>
+ <para>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")</para>
+ <note>
+ <para>The full parametrized address can just be put in the URL field and the hostname field doesn't need specifying.</para>
+ <para>e.g. "https://tile.openstreetmap.org/%d/%d/%d.png"</para>
+ </note>
+ </listitem>
</varlistentry>
<varlistentry>
<term>zoom-min (optional)</term>
<para>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.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>tilesize-x (optional)</term>
+ <listitem><para>The tile x size. The default is 256 pixels if not specified.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>tilesize-y (optional)</term>
+ <listitem><para>The tile y size. The default is 256 pixels if not specified.</para></listitem>
+ </varlistentry>
</variablelist>
</para>
<para>The <classname>VikTmsMapSource</classname> allows to declare any TMS service. It supports the following properties (as per VikSlippyMapSource above):
<term>label</term>
<listitem><para>the text displayed in the menu entry</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term>format</term>
+ <listitem>
+ <para>The <application>GPSBabel</application> 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 <application>GPSBabel</application> is used to transform the text into something that &appname; can understand. Only formats that <application>GPSBabel</application> supports can be used: e.g. 'gpx', 'kml', 'gtrnctr' (for Garmin Training Center .tcx files), etc...</para>
+ <para>Use <command>gpsbabel --help</command> on the command line to find out the supported file types and their codes to process them.</para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term>url-base</term>
<listitem><para>the base URL of the web service (eg. "http://hostname/service?")</para></listitem>
<varlistentry>
<term>url</term>
<listitem>
- <para>the parametrized URL to open in the spirit of C printf format, with up to 7 "%s" values. e.g. <literal>http://hostname/getfile?lat=%s&lon=%s</literal></para>
+ <para>the parametrized URL to open in the spirit of C printf format, with up to 9 "%s" values. e.g. <literal>http://hostname/getfile?lat=%s&lon=%s</literal></para>
<para>The order and meaning of these parameters is given by the url_format_code below</para>
</listitem>
</varlistentry>
<para>A = center lAtitude of the current view</para>
<para>O = center lOngitude of the current view</para>
<para>Z = OSM Zoom value of the current view. See <ulink url="http://wiki.openstreetmap.org/wiki/Zoom_levels">Zoom Levels</ulink></para>
+ <para>P = selected Point's latitude</para>
+ <para>N = selected poiNt's longitude</para>
<para>S = A user specified input string requested from the user via a dialog box</para>
<para>Thus for the url example above then the format code should be <emphasis>AO</emphasis></para>
</listitem>
<para>This file is not intended to be manually edited, but since it is a plain text file it can be changed if desired.</para>
<para>Some values in this file are <emphasis>read only</emphasis>, 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 &app; 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.</para>
<para>Here is the list of the <emphasis>read only</emphasis> keys and their default values.</para>
- <orderedlist>
+ <itemizedlist>
+ <listitem>
+ <para>gpx_tidy_points=true</para>
+ <para>ATM Only attempts to remove a suspicious first point of a GPX track
+ (as opposed to any points within a track).</para>
+ </listitem>
+ <listitem>
+ <para>gpx_tidy_points_max_speed=340</para>
+ <para>Over this speed (in metres per second) for the first pair of points - the first point is removed.</para>
+ </listitem>
+ <listitem>
+ <para>layers_create_trw_auto_default=false</para>
+ <para>Create new TrackWaypoint layers without showing the layer properties dialog first.</para>
+ </listitem>
<listitem>
<para>maps_max_tiles=1000</para>
</listitem>
<listitem>
<para>maps_scale_smaller_zoom_first=true</para>
</listitem>
+ <listitem>
+ <para>srtm_http_base_url=https://dds.cr.usgs.gov/srtm/version2_1/SRTM3</para>
+ <para>Allows using an alternative service for acquiring DEM SRTM files.
+ Note that the layout on the server needs to be split into Continent directories.</para>
+ </listitem>
+ <listitem>
+ <para>mapnik_buffer_size=128 (in pixels)</para>
+ </listitem>
<listitem>
<para>background_max_threads=10</para>
</listitem>
+ <listitem>
+ <para>background_max_threads_local=<emphasis>Number of CPUs</emphasis></para>
+ </listitem>
<listitem>
<para>window_menubar=true</para>
</listitem>
</para>
</listitem>
<listitem>
- <para>external_diary_program=rednotebook</para>
+ <para>external_diary_program=<ulink url="http://rednotebook.sourceforge.net/">rednotebook</ulink></para>
<para>Or in Windows it uses <filename>C:/Progra~1/Rednotebook/rednotebook.exe</filename> - This string value must use Unix separators and not have spaces.</para>
</listitem>
<listitem>
- <para>external_astro_program=stellarium</para>
+ <para>external_astro_program=<ulink url="http://stellarium.org/">stellarium</ulink></para>
<para>Or in Windows use <filename>C:/Progra~1/Stellarium/stellarium.exe</filename> - This string value must use Unix separators and not have spaces.
- Further note due to this <ulink url="https://bugs.launchpad.net/stellarium/+bug/1410529">Bug</ulink> in Stellarium means this does not actually work. You will need to reference a shortcut, rather than the executable directly.</para>
+ Needs to be version 0.15.0 or greater (otherwise due to this <ulink url="https://bugs.launchpad.net/stellarium/+bug/1410529">Bug</ulink> means this does not actually work.</para>
+ </listitem>
+ <listitem>
+ <para>bfilter_simplify=100</para>
+ </listitem>
+ <listitem>
+ <para>bfilter_compress=0.001</para>
+ </listitem>
+ <listitem>
+ <para>list_date_format=%Y-%m-%d %H:%M</para>
+ <para>A <ulink url="http://pubs.opengroup.org/onlinepubs/007908799/xsh/strftime.html">date format description</ulink> as passed on to strftime().
+ Note that when displayed in tables sorting by this column simply uses the text value, rather than the underlying date/time value.
+ </para>
</listitem>
- </orderedlist>
+ </itemizedlist>
<section>
<title>Message Format Code</title>
projects / andy / viking.git / blobdiff