"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY appname "Viking">
<!ENTITY app "<application>Viking</application>">
- <!ENTITY appversion "1.0">
- <!ENTITY manrevision "0.1">
- <!ENTITY date "October 2010">
+ <!ENTITY appversion "1.2">
+ <!ENTITY manrevision "0.2">
+ <!ENTITY date "June 2011">
]>
<!--
(Do not remove this comment block.)
<para role="author">Guilhem Bonnefille <email>guilhem.bonnefille@gmail.com</email></para>
<para role="publisher">GNOME Documentation Project</para>
</revdescription>
- </revision>
+ </revision>
</revhistory>
<releaseinfo>This manual describes version &appversion; of &appname;.</releaseinfo>
</listitem>
<listitem>
<para>
-Downloading and storing OSM and/or Terraserver maps on your hard drive and looking at them later.
+Downloading and storing OpenStreetMap and/or Terraserver maps on your hard drive and looking at them later.
</para>
</listitem>
<listitem>
Show the live GPS position on the map (for use on a mobile device - e.g. a laptop)
</para>
</listitem>
+<listitem>
+<para>
+Import track+waypoint files of various types via GPSBabel
+</para>
+</listitem>
</itemizedlist>
<note>
<para>
<section><title>Layers</title>
+<para>
+Layers supported by &appname; are:
+</para>
+<itemizedlist>
+<listitem><para>Aggregate</para></listitem>
+<listitem><para>TrackWaypoint</para></listitem>
+<listitem><para>GPS</para></listitem>
+<listitem><para>DEM</para></listitem>
+<listitem><para>Coord</para></listitem>
+<listitem><para>Map</para></listitem>
+<listitem><para>GeoRef</para></listitem>
+</itemizedlist>
+<para>
+For each layer there are a few standard options:
+</para>
+<itemizedlist>
+<listitem><para>Properties - Layer setup / configuration settings</para></listitem>
+<listitem><para>Cut</para></listitem>
+<listitem><para>Copy</para></listitem>
+<listitem><para>Paste</para></listitem>
+<listitem><para>Delete</para></listitem>
+<listitem><para>Visibility - This checkbox on the Layers Panel controls whether the layer is shown in the viewport or not</para></listitem>
+</itemizedlist>
+<para>
+The cut/copy/paste options can be accessed in a variety of ways once the layer has been selected:
+</para>
+<itemizedlist>
+<listitem><para>Standard keys: <keycap>Ctrl+x|c|v</keycap></para></listitem>
+<listitem><para>Main menu <guimenuitem>Edit</guimenuitem></para></listitem>
+<listitem><para>From the right click menu</para></listitem>
+<listitem><para>Buttons at the bottom of the Layers Panel</para></listitem>
+</itemizedlist>
+<para>
+See the individual section for detail about each layer.
+</para>
+
<section><title>TrackWaypoint Layer</title>
<para>
TrackWaypoint layers display GPS data (tracks and waypoints).
<section><title>Export Layer</title>
<para>
-The layer (all tracks and waypoints) can be exported to a file GPX, GPSPoint or GPSMapper format.
+The layer (all tracks and waypoints) can be exported to a file GPX, GPSPoint, GPSMapper or Google's KML format.
</para>
<para>
Version1.1+: An individual track can be exported to a GPX file via the track menu.
<section id="osm_upload"><title>Upload To OSM</title>
<para>
-This opens a dialog to upload all tracks and waypoints to OSM traces.
-Useful if you are an OSM contributor (you will need an OSM account), these details can be stored in &appname; preferences.
+This opens a dialog to upload all tracks and waypoints to <ulink url="http://openstreetmap.org/">OpenStreetMap</ulink> traces.
+Useful if you are an OpenStreetMap contributor (you will need an OpenStreetMap account), these details can be stored in &appname; preferences.
</para>
<para>
- &appname; allows you to edit a track, e.g. remove duplicate points, perhaps remove track points leading to your home and then upload it to OSM.
+ &appname; allows you to edit a track, e.g. remove duplicate points, perhaps remove track points leading to your home and then upload it to OpenStreetMap.
</para>
<note>
<para>
<emphasis role="bold">Warning!</emphasis>
-The password is transferred <emphasis role="bold">unencrypted</emphasis> in every request sent to the OSM server. This is due to OSM's basic authentication method.
+The password is transferred <emphasis role="bold">unencrypted</emphasis> in every request sent to the OpenStreetMap server. This is due to OpenStreetMap's basic authentication method.
</para>
</note>
</section>
</para>
</section>
+<section><title>Split By Number of Points</title>
+<para>
+Version1.2+: This operation will split a single track into segments by the number of points specified.
+This can be useful with devices which may have limits on the number of points it supports.
+</para>
+</section>
+
<section><title>Apply DEM data</title>
<para>
If any DEM data is loaded, this will apply the DEM data to give the track elevation data.
</para>
</section>
-<section><title>Extend Using Magic Scissors</title>
+<section><title>Extend Using Route Finder</title>
<para>
-Enables the Magic Scissors tool. Thus on a subsequent left click in the viewport, a route is calculated from the end of track to that point using Google's route service and applied to the track.
+Enables the Route Finder tool. Thus on a subsequent left click in the viewport, a route is calculated from the end of track to that point using Google's route service and applied to the track.
</para>
</section>
<section><title>View Google Directions</title>
<para>
-This option is only available on a track created using the Magic Scissors tool.
+This option is only available on a track created using the Route Finder tool.
</para>
<para>
Launch a web browser to see the Google directions page which yielded the route.
</para>
<note>
<para>
-The record of the Google route is stored in the track's comment, so if the comment is changed (or the route was created by something other than the Magic Scissors tool) this will not work correctly.
+The record of the Google route is stored in the track's comment, so if the comment is changed (or the route was created by something other than the Route Finder tool) this will not work correctly.
</para>
</note>
</section>
</section><!-- End GPS -->
-<section><title>(Digital Elevation Model) DEM Layer (todo)</title>
+<section><title>DEM (Digital Elevation Model) Layer</title>
+<para>
+This layer provides elevation data from the <ulink url="http://www2.jpl.nasa.gov/srtm/">Shuttle Radar Topography Mission (SRTM)</ulink>
+</para>
<para>
-The current NASA SRTM server is: http://dds.cr.usgs.gov/srtm/version2_1/
+Elevation data can be useful in planning trips, as you many wish to avoid/minimise the hills encountered. [OSM Cyclemap is also useful this way too]
+</para>
+<para>
+To download the data use the DEM Download tool (shown on the toolbar), and then click on a area of the viewport. Once files have been downloaded they can then be loaded from disk via the DEM properties in future application runs.
+</para>
+<para>
+The current data server is: <ulink url="http://dds.cr.usgs.gov/srtm/version2_1/">NASA STRM 2.1</ulink>.
+</para>
+<para>
+ATM &appname; does not auto download DEM data. If you want to get lots of data blocks, you may wish to use some other program get such as <application>curl</application> or <application>wget</application> to download them for an area.
+</para>
+<note>
+<para>
+Using many DEMs is CPU/memory intensive. Depending on your computer's capability, &appname; will be less responsive when about 50+ DEM blocks are loaded. It is probably unwise to attempt using 200+ blocks, so trying to use DEMs covering large countries/continents (USA, Australia etc...) is unlikely to work. In these conditions under Linux, &appname; may be automatically stopped by the "<ulink url="http://en.wikipedia.org/wiki/Out_of_memory/">OOM</ulink> Killer"
+</para>
+</note>
+
+</section><!-- End DEM -->
+
+
+<section><title>Maps Layer</title>
+<para>
+This layer provides a single map resource, you may have multiple map layers but only top one (if enabled) will be visible.
+You will need an open internet connection when you are downloading maps, but once downloaded they are available from the hard disk cache. When map are avaliable from the disk cache it is much faster and can be used offline.
+</para>
+<para>
+Some maps are continually improving over time (e.g. OpenStreetMap) and so in order to not to have to (re)download the data all the time &appname; employs a timeout method - 'Tile Age' to determine whether to access the server. However a forced refresh for the current view can be made via the <guilabel>Reload All Onscreen Maps</guilabel> option.
+</para>
+<para>
+Inbuilt maps include various <ulink url="http://en.wikipedia.org/wiki/TerraServer-USA">Terraserver</ulink> (Primarily USA coverage) and <ulink url="http://openstreetmap.org/">OpenStreetMap (OSM)</ulink> ones and more:
+</para>
+<itemizedlist>
+<listitem><para>Terraserver Topos</para></listitem>
+<listitem><para>Terraserver Aerials</para></listitem>
+<listitem><para>Terraserver Urban Areas</para></listitem>
+<listitem><para>OpenStreetMap (Osmarender)</para></listitem>
+<listitem><para>OpenStreetMap (Mapnik) - This is the default</para></listitem>
+<listitem><para>OpenStreetMap (Maplint)</para></listitem>
+<listitem><para>OpenStreetMap (Cycle)</para></listitem>
+<listitem><para>NASA BlueMarble</para></listitem>
+<listitem><para>SpotMap (&appname; Version1.1+)</para></listitem>
+</itemizedlist>
+
+<para>
+&appname; can be configured to handle additional maps. See <link linkend="extend_viking">Extending &appname;</link> for further detail.
</para>
+<section><title>Layer Operations</title>
+<section><title>Download Missing Onscreen Maps</title>
+<para>
+This requests map tiles for areas of the viewport that do not currently have one.
+</para>
+</section>
+
+<section><title>Download New Onscreen Maps</title>
+<para>
+This requests map tiles only if the maps are older than the Tile Age preference.
+</para>
</section>
+<section><title>Reload All Onscreen Maps</title>
+<para>
+Force a refresh of all visible map tiles.
+</para>
+</section>
+</section>
+
+
+</section><!-- End Maps -->
+
+<section><title>Aggregrate Layer</title>
+<para>
+This layer is a container layer to hold other layers. There is always an initial and controlling 'Top Layer' that can not be removed, although it can be renamed.
+</para>
+<para>
+This layer type is useful for grouping other layers, especially TrackWaypoint layers, in whatever categories are relevant to you: such as by activity, location or date.
+Here are some suggestions:
+<itemizedlist>
+<listitem><para>Hiking</para></listitem>
+<listitem><para>Mountain Biking</para></listitem>
+<listitem><para>Road Cycling</para></listitem>
+<listitem><para>Car Trips</para></listitem>
+<listitem><para>Sailing</para></listitem>
+<listitem><para>Holidays</para></listitem>
+<listitem><para>UK Points of Interest</para></listitem>
+<listitem><para>USA Points of Interest</para></listitem>
+<listitem><para>etc...</para></listitem>
+</itemizedlist>
+</para>
+<para>
+Thus one can have a list of all your tracks, but groups can be shown or not using the relevant layers visibility checkbox.
+</para>
+
+<para>
+This layer only has one operation: <guilabel>New Layer</guilabel>
+</para>
+
+<section><title>New Layer</title>
+<para>
+Add a new layer of the selected type.
+</para>
+</section>
+
+</section><!-- End Agg -->
+
+<section><title>GeoRef Layer</title>
+<para>
+This layer allows one to use any image as a map. You will need to tell it how to align the map to a position in the world and the scale of map.
+</para>
+<section><title>Layer Operations</title>
+<section><title>Zoom to Fit Map</title>
+<para>
+Automatically set a zoom level to see the entire map coverage.
+</para>
+</section>
+
+<section><title>Goto Map Center</title>
+<para>
+Center the viewport on this map.
+</para>
+
+</section>
+<section><title>Export to World File</title>
+<para>
+Opens a file save dialog to save the scale and position information as a <ulink url="http://en.wikipedia.org/wiki/World_file">World File</ulink>.
+</para>
+</section>
+</section>
+
+</section><!-- End GeoRef -->
+
+<section><title>Coord Layer</title>
+<para>
+This layer is allows drawing of grid lines on the viewport.
+</para>
+</section><!-- End Coord -->
+
</section>
<section><title>Tools</title>
<para>
Left click to create a new trackpoint. If it's the initial trackpoint you will be asked to enter a name for the track.
If <keycap>Ctrl</keycap> is held at the same time, it will jump the new trackpoint position to a nearby existing trackpoint.
-Right click or <keycap>Backspace</keycap> : undo one point.
+Right click or <keycap>Backspace</keycap>: undo one point.
</para>
<para>
-Double click or <keycap>Escape</keycap> : finish track creation.
+Double click or <keycap>Escape</keycap>: finish track creation.
</para>
</section>
</para>
</section>
-<section><title>Magic Scissors</title>
+<section><title>Route Finder</title>
<para>Creates a track using Google maps routing between two points.
Requires an internet connection. Click one point, then click another to
create a track.
<procedure>
<title>Method C</title>
<step>
-<para>Get data from files in GPX format. For other formats (kml,
-ozi...), use a converter such as GPSBabel to convert the files to GPX
-format first.
+<para>
+Get data from files in GPX or KML format, which can be opened directly.
+Use <menuchoice><guimenu>File</guimenu><guimenuitem>Open</guimenuitem></menuchoice>
</para>
-</step>
-<step>
<para>
-Open up &appname; and use File - Open or File - Append
-file to open the file.
+Other formats can be imported that are supported by GPSBabel.
+<menuchoice><guimenu>File</guimenu><guimenuitem>Acquire</guimenuitem><guimenuitem>Import File With GPSBabel...</guimenuitem></menuchoice>
</para>
</step>
<step>
</para>
</step>
</procedure>
-<procedure>
-<title>Method D</title>
-<step>
-<para>
-Use File - Append File to add your track and waypoint data to
-&appname;. This has been tested with Geocaching.com's *.loc format,
-(others(?)).
-</para>
-</step>
-<step>
-<para>
-Expand Tracks or Waypoints. Right-click on the tack or
-point of interest and select <guimenuitem>Goto "Center"</guimenuitem>.
-</para>
-</step>
-</procedure>
</section>
<section><title>Add a map layer</title>
<para>
</section>
</section>
+<section><title>OpenStreetMap project</title>
+<para>
+<ulink url="http://openstreetmap.org/">OpenStreetMap (OSM)</ulink> is a collaborative project to create a free editable map of the world.
+One of sources of data for this project is GPS tracks.
+&appname; supports this project via the GPS Traces methods, both uploading and downloading such data.
+</para>
<section><title>Uploading data to OpenStreetMap</title>
<para>
It is possible to upload data directly from &appname; to OpenStreetMap.
<title>Fill in the form</title>
<para>
In both cases, &appname; will retain some information.
-The email field is the email you used to subscribed into OSM.
+The email field is the email you used to subscribed into OpenStreetMap.
The password field is the password you used with this account.
The filename is the name you want your upload has on the server. This information is displayed by the osm server.
The description is some descriptive information.
The tags field is a white separated list of tag.
</para>
</formalpara>
-
</section>
+<section><title>Downloading traces from OpenStreetMap</title>
+<para>
+It is possible to download GPS traces directly from OpenStreetMap into &appname;.
+This feature can be really useful for checking existing data before uploading new ones.
+</para>
+<formalpara>
+<title>Download all visible tracks</title>
+<para>One solution is to select
+<menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Acquire</guisubmenu>
+<guimenuitem>OSM traces...</guimenuitem>
+</menuchoice>.
+Each request can get up to 5,000 points.
+The dialog box allows setting which group of 5,000 points to get. These groups are known as 'Page Numbers' which start at 0.
+Increasing the page number parameter allows one to request the subsequent sets of point groups.
+See <ulink url="http://wiki.openstreetmap.org/wiki/API_v0.6#GPS_Traces"/> for further detail.
+</para>
+</formalpara>
+</section>
+</section>
+
<section><title>Geocoded Photo</title>
<para>
HOWTO GEOCODE YOUR PHOTOS AND SEE THEM IN VIKING
</para>
</section>
-<section>
+<section id="extend_viking">
<title>Extending Viking</title>
<para>Currently, &app; has some extention 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".</para>
<para>You can find more examples in the documentation part of the distribution.</para>
<section>
<title>Map Source</title>
- <para>It is possible to add new map's sources. The file is <filename>~/.viking/maps.xml</filename>.</para>
- <para>An example of the file in the distribution <filename>doc/examples/maps.xml</filename>.</para>
+ <para>It is possible to add new map's sources. The file is <filename>~/.viking/maps.xml</filename> for <trademark>UNIX</trademark> like systems and <filename>C:\Documents and Settings\<replaceable>username</replaceable>\.viking\maps.xml</filename> on <trademark>Windows XP</trademark>.</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>
+
<para>The VikSlippyMapSource allows to declare any map's source working like OpenStreetMap. It supports the following properties:
<variablelist>
<varlistentry>
</section>
+<section><title>Dependencies</title>
+<formalpara><title>gpsbabel</title>
+<para>&appname; uses <ulink url="http://gpsbabel.org/">GPSBabel</ulink> to convert data.</para>
+</formalpara>
+<formalpara><title>unbuffer (optional)</title>
+<para>&appname; uses unbuffer command to optimize conversion calls.</para>
+</formalpara>
+</section>
+
</article>
projects / andy / viking.git / blobdiff