<!DOCTYPE html>
<html lang="en">
<head>
<title>GPXSee - Documentation</title>
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
<link rel="icon" type="image/png" href="css/images/favicon.png"/>
<link rel="stylesheet" href="css/style.css" type="text/css" media="all" />
<!--[if IE 6]><link rel="stylesheet" href="css/ie6.css" type="text/css" media="all" /><![endif]-->
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-110140219-1"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-110140219-1');
</script>
</head>
<body>
<!-- START PAGE SOURCE -->
<div class="shell">
<div class="shell-b">
<div id="header">
<img src="css/images/gpxsee.png" alt="" class="logo"/><h1 class="logo"><a href="https://www.gpxsee.org">GPXSee</a></h1>
<div id="navigation">
<ul>
<li><a href="index.html">Home</a></li>
<li><a href="gallery.html">Screenshots</a></li>
<li><a href="doc.html" class="active">Documentation</a></li>
<li><a href="index.html#download">Download</a></li>
</ul>
</div>
<div class="cl"> </div>
</div>
<div id="main">
<div id="content">
<h2 id="data">Data files</h2>
<p>GPXSee opens GPX, TCX, FIT, KML, NMEA, IGC, CUP, SIGMA SLF, Suunto SML,
LOC, GeoJSON, OziExplorer (PLT, RTE, WPT), Garmin GPI,
<a href="http://www.poi-factory.com/garmin-csv-file-format">Garmin CSV</a>,
TomTom OV2 & ITN and geotagged JPEG files, however not all format features
are supported for all formats. Generally, GPXSee supports four kinds
of data objects:</p>
<ul>
<li>Tracks</li>
<li>Routes</li>
<li>Waypoints</li>
<li>Areas (polygons)</li>
</ul>
<p>Naturally, if a format supports only a subset of the objects, GPXSee also
supports only this subset. Some formats - especially KML - have support for
other data objects like 3D structures. Those are not supported by GPXSee.</p>
<p>In addition to GPS data, data from the following sensors is supported
by GPXSee:</p>
<ul>
<li>Heart rate</li>
<li>Cadence</li>
<li>Power</li>
<li>Temperature</li>
<li>Gear ratio/shifts (Shimano Di2, SRAM eTap)</li>
</ul>
<h3 id="filtering">Data filtering</h3>
<p>Outlier elimination and data smoothing is implemented and enabled by default.
In most cases this improves the representation of the recorded data but in some
special cases you may get much worse results than without it. A typical example
of such data are ski mountaineering tracks or in general tracks that are composed
of parts with very different speed profiles.</p>
<p>If you get unexpected results, try to disable the outlier elimination in
the preferences.</p>
<h2 id="maps">Maps</h2>
<p>Two kinds of maps are supported by GPXSee - online maps and offline maps.
You may either load them "ad hoc" from the GUI or they can be loaded
automatically at program startup from the following directory:</p>
<table class="config-files">
<tr>
<td class="os">Windows:</td>
<td class="file">C:\Program Files\GPXSee\maps</td>
</tr><tr>
<td class="os">Linux:</td>
<td class="file">/usr/share/gpxsee/maps</td>
</tr><tr>
<td class="os">OS X:</td>
<td class="file">/Applications/GPXSee.app/Contents/Resources/maps</td>
</tr>
</table>
<p>User specific map directories that - when present - override the global
map directory are also supported. The paths are as
follows<sup><a href="#legacyPaths">1</a></sup>:</p>
<table class="config-files">
<tr>
<td class="os">Windows:</td>
<td class="file">%APPDATA%\GPXSee\maps</td>
</tr><tr>
<td class="os">Linux:</td>
<td class="file">~/.local/share/gpxsee/maps</td>
</tr><tr>
<td class="os">OS X:</td>
<td class="file">~/Library/Application Support/GPXSee/maps</td>
</tr>
</table>
<p>The map directory is recursively searched when loading the maps, so it
may contain an arbitrary directory structure.</p>
<p>Supported map projections are Mercator (including Web Mercator),
Transverse Mercator (including UTM), Lambert Conformal Conic, Albers Equal Area,
Lambert Azimuthal Equal Area, Polar Stereographic, Oblique Stereographic, Křovák's,
Polyconic, and Latitude/Longitude (2D geographic). Additionally, the Swiss
and Hungarian Oblique Mercator projections are supported using LCC1 approximation.
For list of supported datums and projected coordinate systems see the
<a href="https://github.com/tumic0/GPXSee/blob/master/pkg/csv/gcs.csv">GCS.csv</a>
and <a href="https://github.com/tumic0/GPXSee/blob/master/pkg/csv/pcs.csv">PCS.csv</a>
configuration files (can be modified or overridden by user files like the map
directory).</p>
<h3 id="online">Online maps</h3>
<p>Online maps are represented by map source definition XML files. For the formal
map source file syntax see the <a href="map/1.4/map.xsd">map source
XSD file</a>. The paragraphs below are a "human-readable" summary of the XSD
syntax/semantics divided by map type.</p>
<h4 id="OSM">OSM/Google tiles</h4>
<p>The root <i>map</i> element contains two mandatory elements - <i>name</i>
and <i>url</i>, and two optional elements - <i>zoom</i> and <i>bounds</i>.
The tile X and Y coordinates are replaced with <code>$x</code> and
<code>$y</code> in the URL and the zoom level is replaced with
<code>$z</code>. An example map source definition file can look like:</p>
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.gpxsee.org/map/1.4" type="OSM">
<name>USGS Imagery</name>
<url>https://navigator.er.usgs.gov/tiles/aerial_Imagery.cgi/$z/$x/$y</url>
<zoom min="2" max="15"/>
<bounds bottom="0" top="74"/>
</map>
</pre>
<p>The bounds are WGS84 latitude/longitude values in degrees. If omitted, the
default zoom range is <0, 19> and the default bounds are
<-85.0511, 85.0511> and <-180, 180>.</p>
<p>GPXSee supports HiDPI map tiles. To specify that a map uses HiDPI tiles
use the pixelRatio attribute of the <i>tile</i> tag. For the most common
512x512px tiles (that shall be rendered as 256x256px tiles), set the value
to 2.</p>
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.gpxsee.org/map/1.4">
<name>OSM - HiDPI</name>
<url>https://a.osm.rrze.fau.de/osmhd/$z/$x/$y.png</url>
<tile pixelRatio="2">
</map>
</pre>
<p>In case of vector tile images (MVT<sup><a href="#pbf">2</a></sup>),
set the type attribute of the <i>tile</i> tag to "vector". This will
adjust the pixel ratio of the tile to the pixel ratio of the display
device.</p>
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.gpxsee.org/map/1.4">
<name>MapTiler</name>
<url>https://maps.tilehosting.com/data/v3/$z/$x/$y.pbf?key=apikey</url>
<tile type="vector" size="512"/>
<zoom max="14"/>
</map>
</pre>
<p>The map URL can be also a local file URL (<i>file:</i> scheme).</p>
<h4 id="TMS">TMS</h4>
<p>TMS maps with the global-mercator profile are supported by GPXSee in addition
to the OSM/Google tiles maps. The configuration is exactly the same as in the case
of OSM maps, the only difference is that TMS maps must have the <i>map</i>
<i>type</i> attribute set to <code>TMS</code>.</p>
<h4 id="QuadTiles">QuadTiles</h4>
<p>QuadTiles (BING) maps - another variation of the OSM/Google tiles maps - are also
supported by GPXSee. Use <code>QuadTiles</code> as the <i>map</i> <i>type</i>
attribute and <code>$quadkey</code> as the quadkey placeholder in the URL.</p>
<h4 id="WMTS">WMTS</h4>
<p>WMTS maps are distinguished by setting the <i>type</i> attribute of the
<i>map</i> element to <code>WMTS</code>. Both the KVP and REST access methods
are supported.</p>
<p>For KVP, the <i>url</i> element represents the WMTS base URL and two
additional elements are required - <i>layer</i> and <i>set</i>
(TileMatrixSet in WMTS). Optional <i>format</i> and <i>style</i> elements may
be specified defining the desired image format and layer style. If not set,
<code>image/png</code> is used for <i>format</i> and the default style for
<i>style</i>.</p>
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.gpxsee.org/map/1.4" type="WMTS">
<name>CUZK</name>
<url>http://geoportal.cuzk.cz/WMTS_ZM_900913/WMTService.aspx</url>
<layer>zm</layer>
<set axis="yx">ogc:1.0:globalcrs84pixel</set>
</map>
</pre>
<p>For REST access, the <i>url</i> element's <i>type</i> attribute must be set
to <code>REST</code>. The URL then represents the URL of the capabilities XML
document. Defining the format has no relevance for the REST access method.</p>
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.gpxsee.org/map/1.4" type="WMTS">
<name>Wien - Ortho</name>
<url type="REST">http://maps1.wien.gv.at/wmts/1.0.0/WMTSCapabilities.xml</url>
<layer>lb</layer>
<style>farbe</style>
<set>google3857</set>
</map>
</pre>
<p>There is one more important attribute - the <i>axis</i> attribute of the
<i>set</i> element. It specifies the axis order of the CRS used for the
tile matrix set. The default order is obtained from the CRS definition like
specified in the standard, but in praxis many servers use a wrong order. This
is why GPXSee enables overriding the default axis order using the <i>axis</i>
attribute. Possible values are <code>xy</code> and <code>yx</code>.</p>
<p>Finally, one can define additional dimensions like <code>Time</code> using
the <i>dimension</i> element. Use a separate entry for every additional dimension.</p>
<p>HiDPI WMTS tiles are supported too. Local (<i>file:</i> scheme) URLs are
supported in the map definition file as well as in the WMTS capabilities file.
This enables a fully local REST WMTS map configuration without the need of a web
server.</p>
<h4 id="WMS">WMS</h4>
<p>WMS maps are distinguished by setting the <i>type</i> attribute of the
<i>map</i> element to <code>WMS</code>. WMS map definitions are very similar to
WMTS map definitions, the main difference is that you must specify the map
CRS using the <i>crs</i> element instead of specifying the tile set. Like in the
case of the <i>set</i> element, you may specify the <i>axis</i> attribute to
override the default axis order.</p>
<p>It is possible to combine multiple WMS layers together in one map. To do so,
use a comma separated list of WMS layers as the <i>layer</i> element content and
a corresponding comma separated list as the <i>style</i> element content (can be
omitted if all styles are the default style).</p>
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.gpxsee.org/map/1.4" type="WMS">
<name>Katastr nemovitostí</name>
<url>http://services.cuzk.cz/wms/wms.asp</url>
<layer>polygony_parcel,polygony_budov,polygony_k_u</layer>
<crs axis="yx">EPSG:3034</crs>
</map>
</pre>
<h3 id="offline">Offline maps</h3>
<p>OziExplorer maps, TrekBuddy maps/atlases, Garmin JNX & IMG/GMAP maps,
TwoNav RMaps, MBTiles, KMZ maps, AlpineQuest AQM maps, Locus/OsmAnd/RMaps SQLite
maps, Mapsforge maps, BSB charts and GeoTIFF and World-File georeferenced images
are supported by GPXSee.</p>
<p>You may easily create offline atlases from online map services by using
<a href="http://mobac.sourceforge.net/">Mobile Atlas Creator (MOBAC)</a>.</p>
<h4 id="IMG">IMG maps</h4>
<p>There is support for IMG maps overlay in GPXSee since version 7.30. If the map
name is <i>mapname.img</i> and there is also a file named <i>mapname.img.1</i>
(.2, .3, ... for additional layers) in the same path, than it will be automatically
loaded as an overlay of <i>mapname.img</i>.</p>
<h4 id="JNXKML">JNX & KMZ maps</h4>
<p>JNX & KMZ maps do not contain any info about the projection of their
tile images, so it has to be provided externaly<sup><a href="#garmin">4</a></sup>.
Generally, only two projections are used for JNX/KMZ maps - EPSG:4326 and
EPSG:3857. If you see <a href="img/wrong_proj.png">background color stripes</a>
in your JNX/KMZ map, you have to switch to the propper input projection
in the preferences.</p>
<h4 id="worldfiles">World Files</h4>
<p>World-File georeferenced images require the projection info to be provided
additionaly to the world file. This can be done either using a separete PRJ
file in <a href="https://portal.ogc.org/files/?artifact_id=999">WKT1 format</a>
or by selecting the input projection in the preferences. If a PRJ file
exists, it takes precedence.</p>
<p>Note, that the WKT datum entry must contain at least one of the
<code>TOWGS84</code> or <code>AUTHORITY</code> keys to provide a valid projection
info (the <code>AUTHORITY</code> info overrides any parameter values). The
WKT data must follow the OGC naming convention. Generally, the OGC WKT entries
from <a href="https://epsg.io/">epsg.io</a> should work.</p>
<h3 id="styles">Map styles</h3>
<p>MVT(PBF), Mapsforge and Garmin IMG maps can be styled with user defined styles.
To apply a user defined style, place it to the <code>style</code> directory in
one of the configuration paths. The style must be named <i>style.typ</i> (Garmin
IMG), <i>style.xml</i> (Mapsforge) or <i>style.json</i> (MVT) for GPXSee to use it.
If a Garmin IMG map contains a TYP file, it takes precedence over the user TYP
file.</p>
<h2 id="poi">POI files</h2>
<p>All of the supported formats with waypoints capability - GPX, KML, TCX, NMEA,
CUP, WPT, LOC, GeoJSON and Garmin GPI & CSV - can be loaded either as data
files or as POI files. When a file is opened as a POI file, only waypoints reasonable
near the tracks/waypoints of the loaded data files are displayed.</p>
<p>To make GPXSee load a POI file automatically on startup, add the file to the
<code>POI</code> directory in one of the configuration paths.</p>
<h2 id="dem">DEM files</h2>
<p>Digital Elevation Model (DEM) files can be used as elevation source
instead of the recorded GPS data. The format of the DEM data is the SRTM HGT
file format (SRTM3 and SRTM1 are both supported). The DEM files must be
put<sup><a href="#unzip">3</a></sup> in the <code>DEM</code> directory in one
of the configuration paths for GPXSee to use them.</p>
<p>The DEM files must have the expected filename format of <code>NXXEYYY.hgt</code>
or <code>NXXEYYY.hgt.zip</code> for GPXSee to use them.</p>
<div id="footnote">
<p id="legacyPaths"><i>[1] The user paths have changed in GPXSee 7.</i></p>
<p id="pbf"><i>[2] To display PBF(MVT) tiles, <a href="https://github.com/tumic0/QtPBFImagePlugin">
QtPBFImagePlugin</a> is required (included in the Windows and OS X builds).</i></p>
<p id="unzip"><i>[3] For GPXSee versions older than 8.1, you have to unzip them
too.</i></p>
<p id="garmin"><i>[4] Some tools like Garmin software "solve" this by
rescaling the images, but this introduces a small, but still visible distortion
to the map.</i></p>
</div>
</div>
<div id="sidebar">
<div id="outline">
<div class="h4l"><a href="#data">Data files</a></div>
<div class="h5l"><a href="#filtering">Data filtering</a></div>
<div class="h4l"><a href="#maps">Maps</a></div>
<div class="h5l"><a href="#online">Online maps</a></div>
<div class="h6l"><a href="#OSM">OSM/Google tiles</a></div>
<div class="h6l"><a href="#TMS">TMS</a></div>
<div class="h6l"><a href="#QuadTiles">QuadTiles</a></div>
<div class="h6l"><a href="#WMTS">WMTS</a></div>
<div class="h6l"><a href="#WMS">WMS</a></div>
<div class="h5l"><a href="#offline">Offline maps</a></div>
<div class="h6l"><a href="#IMG">IMG maps</a></div>
<div class="h6l"><a href="#JNXKML">JNX & KMZ maps</a></div>
<div class="h6l"><a href="#worldfiles">World Files</a></div>
<div class="h5l"><a href="#styles">Map styles</a></div>
<div class="h4l"><a href="#poi">POI files</a></div>
<div class="h4l"><a href="#dem">DEM files</a></div>
</div>
</div>
<div class="cl"> </div>
</div>
</div>
</div>
<div class="footer">
<div class="shell">
<p class="lf">© 2017-2020 Martin Tůma, CC BY-ND 4.0</p>
<p class="rf">Design by <a href="http://www.websitecsstemplates.com/" target="_blank">WebsiteCSSTemplates</a></p>
<div style="clear:both;"></div>
</div>
</div>
<!-- END PAGE SOURCE -->
</body>
</html>