gpxview/www/index.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
    "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head><title>GPXView - Geocaching with Maemo</title>
<link type="text/css" rel="stylesheet" href="style.css">
<link rel="icon" href="favicon.ico" type="image/x-icon">
<link rel="shortcut icon" href="favicon.ico" type="image/x-icon"> 
</head><body>

<center><img src="images/gpxview.png"></center>

<center><h1>GPXView - Geocaching with Maemo</h1></center>
<center>Till Harbaum <a href="mailto:till@harbaum.org">&lt;till@harbaum.org&gt;</a></center><p>

GPXView is a <a href="http://geocaching.com">geocaching</a>
application.  Its main purpose is to work with <a
href="http://www.geocaching.com/pocket/">pocket queries</a> in GPX
format (hence the name GPXView). GPXView allows you to conveniently
read the information stored in these files and navigates you to
geocaches using your devices built-in GPS. GPXView features many
advanced features including full HTML rendered cache descriptions, GPS
based voice navigation and a built-in map viewer.<p>

<h2>Did you know?</h2>

GPXView supports online download of geocaches using 
<a href="#geotoad">geotoad</a>. This even works without a premium
account!

<h2>Obtaining GPXView</h2>

GPXView is available for three different plattforms:

<ul>
<li>Maemo4 (codenamed Chinook/Diablo) on Nokia <a href="http://en.wikipedia.org/wiki/Nokia_N800">N800</a> and <a href="http://en.wikipedia.org/wiki/Nokia_N810">N810</a>
<li>Maemo5 (codenamed Fremantle) on <a href="http://maemo.nokia.com/n900/">Nokia N900</a>
<li>Desktop Linux
</ul>

The latest N810/N800 version is available from the 
<a href="http://maemo.org/downloads/product/raw/OS2008/gpxview/?get_installfile">Nokia repositories</a>.<p>

<center><img src="images/maemo4.gif"><h5>GPXView on N810</h5></center>

The N900 version is available from the extras repository and can be
installed from the Navigation section in the Application Manager on
that device. However, since there's a review process involved in
getting software into the repective repositories and since the review
process for the N900 is rather slow, it may take some time for the
latest version to show up on your device.<p>

<center><img src="images/cachelist.gif"><h5>GPXView on N900</h5></center>

There is no pre-packaged version for the Linux desktop. In order to install
GPXView on a desktop PC you'll have to download the <a href="http://repository.maemo.org/extras-devel/pool/diablo/free/source/g/gpxview/">source code</a>
and compile and install it yourself.<p>

<center><img src="images/desktop.gif"><h5>GPXView on Ubuntu Linux</h5></center>

<h2>Getting started</h2>

GPXView comes ready-to-run and even includes some little "welcome"
demo file. You can use this to learn about the basic usage of GPXView and
check out the various program features.<p>

<center><img src="images/welcome.gif"><h5>First start of GPXView</h5></center>

However, to start hunting geocaches near your location you
need to get the appropriate pocket queries in GPX or LOC format either
from geocaching.com where you have to be a paying member to be allowed
to download them. Or you check free services. Sources known to work
with GPXView are:

<ul>
<li><a href="http://www.geocaching.com/pocket/">Pocket queries</a> from geocaching.com, available to paying customers only
<li>LOC files from geocaching.com are available for free, but contain very limited information only
<li>GPX files from <a href="http://www.opencaching.de/">Opencaching.de</a>
</ul>

<h3>Installing GPX files</h3>

Once you got your GPX files you might install them anywhere on your 
device like e.g. the memory card on your N900. Files being downloaded
in ZIP format from geocaching.com can be left compressed. GPXView will 
uncompress them automatically.<p>

<h3><a name="gpxlist">The GPX list view</a></h3>

To import such files into GPXView you need to start GPXView and
and select "Import file" from the main menu. The GPX file will then 
be included into the main screens list of GPX files. The following 
session has two active GPX files and a closed one installed.<p>

<center><img src="images/gpxlist.gif"><h5>GPX list</h5></center>

These GPX list will be loaded whenever you restart GPXView. Since
these files may contain plenty caches, loading them may take a few
seconds. While loading you'll see a progress bar.<p>

<center><img src="images/loading.gif"><h5>Loading ...</h5></center>

You may wish to temporarily disable certain GPX files from this list
in order to speed up loading. In order to do so, just click the 
<img src="images/delete.png"> icon (on N800/N810 and desktop use the
Import->Close in the menu instead). A dialog will pop up to ask you
whether you want to remove that entry completely from the list or
whether you only want to close it.<p>

<center><img src="images/close_remove.gif"><h5>Close or Remove?</h5></center>

If you choose to close the file it will be displayed in "disabled" style
as visible in the GPX list screenshot above. These files will not be 
opened at startup and thus don't affect the startup time of GPXView. The
containing cache files are not imported and are e.g. not found when using
the Search function and are not displayed on the map. To reenable a closed
entry just select it.<p>

<h2><a name="coordinate_tool">Coordinate tool</a></h2>

Whenever GPXView deals with coordinates it will use the coordinate
tool. This tool consists of two buttons displaying the coordinates
(on N810, N800 and desktop linux these are text entry fields) and 
one or two additional buttons with icons.<p>

<center><img src="images/coordinate_tool.gif">
<h5>The coordinate tool</h5></center>

<a name="picker">You can change the coordinate directly by clicking
the coordinate buttons. On N810, N810 and desktop linux you can use
the text entry fields to enter a new coordinate. On the N900 the
coordinate picker will show up once you click one of the coordinate
buttons.</a><p>

<center><img src="images/coordinate_picker.gif">
<h5>The coordinate picker</h5></center>

The coordinate picker is designed for finger friendlyness and allows
you to enter coordinates without using a keyboard. Similar picker
also exist for distances<p>

<center><img src="images/distance_picker.gif">
<h5>The distance picker</h5></center>

and directions (angles).<p>

<center><img src="images/direction_picker.gif">
<h5>The direction picker</h5></center>

You can also import one of the various coordinates GPXView already
knows. In order to do this you just habe to click the coordinate
import button <img src="images/pos_get.png">. A picker with then
show up allowing you to select a coordinate source.<p>

<center><img src="images/coordinate_import.gif">
<h5>Import a coordinate</h5></center>

The number of sources available depends on the state GPXView is in.
Possible sources include:

<ul>
<li><img src="images/pos_gps.png"> The current GPS position
<li><img src="images/pos_home.png"> The home coordinate stored in the <a href="#settings">settings</a>
<li><img src="images/pos_wpt.png"> Additional waypoints stored in the <a href="#settings">settings</a>
<li><img src="images/pos_map.png"> The current <a href="#map">map</a> position
<li><img src="images/pos_geomath.png"> The current <a href="#geomath">geomath projection</a>
<li><img src="images/cache_type_traditional.png">, <img src="images/cache_type_multi.png">, ... The current caches coordinate and the <a href="#overwritten">overwritten one</a> if present
<li><img src="images/wpt_parking.png">, <img src="images/wpt_refpoint.png">, ... The current caches <a href="#waypoints">waypoints</a> if present
</ul>

In some occasions also a export button <img src="images/pos_set.png"> is present. This button opens the coordinate export tool.<p>

<center><img src="images/coordinate_export.gif">
<h5>Export a coordinate</h5></center>

Up to three choices may be present here:

<ul>
<li><img src="images/pos_map.png"> Show the position on the <a href="#map">map</a>
<li><img src="images/maemo_mapper.png"> Export the position to Maemo Mapper (needs to be supported by Maemo Mapper)
<li><img src="images/clipboard.png"> Copy the coordinate to the clipboard
</ul>

<h2>Main Menu</h2>

The main menu can be reached from the main screen (and e.g. not
from the map screen). It exact contents vary with the state of the
main screen and e.g. some menu entries may only be visible if the
main screen is in "GPX list" mode.<p>

<center><img src="images/menu.gif"><h5>The main menu</h5></center>

<h3><a name="settings">Settings</a></h3>

The settings dialog contains various global settings. Any change
made here is permanent.<p>

<center><img src="images/settings.gif"><h5>The settings</h5></center>

<h4>Enable GPS</h4>

This settings controls GPS globally. The major reason for disabling
GPS is to save energy. Since geocaching without precise location
information is not possible, you usually want to have the GPS
enables. However, if GPS is disabled, an alternatice coordinate is
being used instead. As a default only a home coordinate is stored. You
might add an unlimited number of additional locations (like your
workplace or other places you often use).  Just hit the add or edit
buttons while GPS is disabled to maintain this list. If GPS is
disabled, all coordinate calculation (e.g. in order to display the
distance of a cache) is then based on the selected alternative
coordinate in the list. In the example above the "Home" coordinate is
the active one.<p>

<center><img src="images/edit_location.gif"><h5>Manually edit a location</h5></center>

The alternate positions are also useful while having GPS as they can easily
be reached via the <a href="#coordinate_tool">coordinate tool</a>.<p>

<h4>Imperial Units</h4>

This settings changes the display between imperial (mi, in, ft) and 
metric units (km, m). These only affect the display. Any input
accepts both formats at any time. So you may enter inches while in
metric mode and meters while in imperial mode. However, these are
immediately converted into display units while being processed.<p>

<h4>Username</h4>

This is your geocaching.com user name. It's used to determine if
a geocache has been placed by you or has been found by you. The 
caches are then marked using the appropriate icons as finds
<img src="images/cache_type_ovl_found.png"> and owned
<img src="images/cache_type_ovl_mine.png">.<p>

Furthermore the username is being used when using the 
<a href="#geotoad">geotoad</a> feature.<p>

<h4>Visible GPX list items</h4>

This setting allows you to enable and disable columns in the
<a href="#gpxlist">GPX list view</a>. The original file name
(as opposed to the GPX name stored in that file), the date
of creation and the number of caches stored in that GPX files
can be toggled independently.<p>

<h4>Visible cache list items</h4>

This setting allows you to enable and disable columns in the
<a href="#cachelist">cache list view</a>. The waypoint name,
the cache size and the caches rating can be toggled.<p>

<h4>Cache list screensaver</h4>

The screensaver can be disabled while the 
<a href="#cachelist">cache list</a> is being displayed. This
is useful when e.g. driving with the cache list view active.
Since the cache list may optionally be sorted by distance,
the nearest cache is always the first one on screen.<p>

<h4>Cache list refresh</h4>

As pointed out before, the <a href="#cachelist">cache list</a>
can be refreshed automatically every 30 seconds. Since this
feature consumes CPU power (and thus battery), it can be 
disabled.<p>

<h4>Cache compass damping</h4>

The compass in the caches <a href="#goto">goto view</a> uses
track information from the GPS signal to determine the 
heading in order to re-create the functionality of a
magnetic compass. Depending on the precision of the GPS
receiver and the signal quality of the GPS signal the
tracking information may be rather inaccurate. Especially
when you are moving slowly the compass tends to jitter.
If you have this problem you might want to increase 
damping. This makes the compass a little less responsive
but it increases stability of the compass display.<p>

<h4>Use GCVote service</h4>

GPXView can retrieve cache quality ratings from the 
<a href="http://dosensuche.de/index.php">GCVote</a> service. If GCvote 
is enabled, an additional line of stars is shown in the caches main view
describing the quality of a cache like difficulty and terrain are
already displayed by default.<p>

<h4>Disable screen saver in goto view</h4>

Since the <a href="#goto">goto view</a> can be used to navigate to the
cache, it may be handy to keep the screen on all the time.  Be aware
that this may drain your battery if you leave the device for a longer
period in this mode with the goto view active.<p>

<h3>Tools Submenu</h3>

The tools submenu is reached via the main menu. It can be used to
invoke various geocaching related tools. The tools act as if they were
seperate programs but are tightly integrated into GPXView and
typically import or export data to or from GPXView.<p>

<center><img src="images/tools.gif"><h5>The tools submenu</h5></center>

<h4><name="geomath">Geomath</a></h4>

<center><img src="images/geomath.gif"><h5>The Geomath tool</h5></center>

The geomath tool allows very basic geocoordinate calculations.
Two coordinates can be entered into it as well as a distance and
a direction angle.<p>

Clicking the "Calculate" button calculates the distance between
the two given coordinates and projects the first coordinate (on the
screens left) by the given distance and direction. The resulting
projected coordinate is then be displayed in the bottom row.<p>

The resulting coordinate can be used within GPXView from the 
coordinate selector tool using the geocalc icon
<img src="images/pos_geomath.png">. This icon also shows up in the map
if a valid geomath result is present.

<h5>Usage example: "Go 120m in 65&deg;" from the given start coordinate</h5>

The cache description tells you to walk a certain distance into a
certain direction from a given coordinate. First you select the caches
main position <img src="images/cache_type_traditional.png"> from the
coordinate selector tool <img src="images/pos_get.png">. The start
coordinate should then be displayed in the left column. Now enter the
requested distance and direction into the appropriate fields (on
Maemo5 using the <a href="#picker">picker tools</a>). When done just
click "Calculate" and the "projection" row will contain your target
coordinate. This coordinate can now be selected in the caches "goto"
view and is also being shown in the map. You can even re-select the
projected coordinate in the Geomath dialog for further processing and
to e.g. walk another distance in another direction.

<h4>Geotext</h4>

<center><img src="images/geotext.gif"><h5>The Geotext tool</h5></center>

The geotext tool allows two simple text operations often required to solve
a geocache. Many geocaches ask you to calculate the letter sum of a certain
text or word. Just enter this word into geotext and the character sum
is being displayed while you type. Another common operation is the "shift"
letters. If you shift the letter "a" by one you get the next letter "b" (and
"z" becomes "a" again). If you shift by two "a" becomes "c" and so on. This
is the so-called cesar encryption. A special case is a shift by 13. This
encryption of shifting letters by 13 is named rot13 and is for example used
on the geocaching.com website to encrypt hints and spoilers.

<h4>Precise Position</h4>

<center><img src="images/precise_position.gif">
<h5>The Precise Position tool</h5></center>

The Precise Position is more for the hider than for the seeker. It is
supposed to be used when standing still. It allows you to average the
current position over some longer period of time. The tool will also
show you graphically how far all the positions received so far are
apart to give you an impression how precise the position really
is. The more coordinates you get and the smaller the radius of the
circle containing them all is the more precise is the resulting
coordinate.  You can then copy the resulting coordinate to the
clipboard for further processing in other applications.<p>

<h4><a name="geotoad">GeoToad</a></h4>

<a href="http://code.google.com/p/geotoad/">GeoToad</a> is not part of
GPXView itself but has to be installed seperately.  GeoToad is written
in the <a href="http://ruby-lang.org/">ruby language</a> and as of this writing has to be installed
together with the ruby interpreter from the <a
href="http://www.nokian900applications.com/repositories-extras-extras-devel-and-extras-testing-for-nokia-n900/">extras-devel
repository</a> when using Maemo5.<p>

<a href="http://code.google.com/p/geotoad/">GeoToad</a> allows you to
download geocache information directly from the <a
href="http://www.geocaching.com/">geocaching.com website</a>. In order
to comply with the terms of that site, GeoToad intentionally runs
rather slow (about one cache request per second) to prevent to
overload that site with automated requests.<p>

To use GeoToad you first have to enter your account information (you
don't need a premioum account!), the location you want to get geocache
information from and the size of the area you are interested
in. Please, start with an area of ~1km (0.6 mi) radius. Otherwise the
download may take rather long. You also have to select a place to
store the resulting file. You can choose any location, but it's
preferred to use a memory card to save precious root file system space
on a mobile device like the N900.<p>

<center>
<img src="images/geotoad_setup.gif">
<h5>Setup of GeoToad</h5>
</center>

GeoToad is then invoked using the parameters you just entered.<p>

<center>
<img src="images/geotoad_run_1.gif">
<h5>Running GeoToad</h5>
</center>

After a few seconds the first information should be returned and
GeoToad starts reporting what it receives from geocaching.com.<p>

<center>
<img src="images/geotoad_run_2.gif">
<h5>Search results are coming in</h5>
</center>

Once geotoad is done it reports some statistics about its work and
GPXView tells you that the GeoToad job is done.<p>

<center>
<img src="images/geotoad_run_3.gif">
<h5>GeoToad download is done</h5>
</center>

You can now close the window and return to the main screen. You'll find that
the download has been added to the list of GPX files.<p>

<center>
<img src="images/geotoad_result_1.gif">
<h5>The resulting file</h5>
</center>

You can now use this file like any other GPX file you might have downloaded
from geocaching.com or similar sites.<p>

<center>
<img src="images/geotoad_result_2.gif">
<h5>Caches downloaded by GeoToad</h5>
</center>

<h3><a name="map">The Map</a></h3>

GPXView comes with a built-in map. This map is downloaded on demand, but
all data being downloaded is caches locally. Once you've visited a certain
area on the map, the data will even be accessible without internet
connection.<p>

<center>
<img src="images/map_all_balloon.gif">
<h5>The map</h5>
</center>

The map is tightly integrated into GPXView and always displays all active
caches with little icons. You can click these icons and get detailed 
information of the cache in a "balloon". Clicking this balloon will cause
the main GPXView application to switch to that particular cache.<p>

The map data can be taken from several sources. Clicking the little arrow
on the right screen side will extent a menu allowing you to select a
different map source.<p>

<center>
<img src="images/map_source_sel.gif">
<h5>Selecting the map source</h5>
</center>

The map always displays your current GPS position using a blue marker
surrounded by a circular gray area. This area displays your current
GPS precision. In the example below the precision of ~5km is extremely
low indicating that the position is likely not derived from the GPS
signal but of location information derived from the cell network or a
wlan position. Furthermore a small blue arrow on the GPS indicator 
displays your current tracking.<p>

<center>
<img src="images/map_nav.gif">
<h5>Navigating to a cache</h5>
</center>

When there's a geocache selected in GPXViews main view, then all
caches except the selected one a displayed semi-transparent.
Furthermore a info display on the left side of the screen helps
navigating to the cache. Clicking on the coordinate in that info
display will center the map in that position.  Clicking the compass
will toggle between GPS mode (blue compass arrow) and map center mode
(black compass arrow).  In GPS mode, the distance and heading info is
displayed relative to the current GPS position. In map center mode the
distance and heading info is displayed relative to the map center.<p>

Finally, the current map position can be used as coordinate input
in the <a href="#coordinate_tool">coordinate tool</a>.<p>

</body>
</html>
