GPXSee - Documentation

Data files

GPXSee opens GPX, TCX, FIT, KML, IGC, NMEA, SLF, LOC, GeoJSON, OziExplorer (PLT, RTE, WPT) and Garmin CSV files, however not all format features are supported for all formats. Generally, GPXSee supports three kinds of data objects:

Tracks
Routes
Waypoints

Naturally, if a format supports only a subset of the objects, GPXSee also supports only this subset. Some formats - especially KML - have support for a plenty of other data objects like surfaces or even 3D structures. Those are not supported by GPXSee.

In addition to GPS data, data from the following sensors is supported by GPXSee:

Heart rate
Cadence
Power
Temperature
Gear ratio/shifts (Shimano Di2, SRAM eTap)

Maps

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:

Windows:	C:\Program Files\GPXSee\maps
Linux:	/usr/share/gpxsee/maps
OS X:	/Applications/GPXSee.app/Contents/Resources/maps

User specific map directories that - when present - override the global map directory are also supported. The paths are as follows¹:

Windows:	%APPDATA%\GPXSee\maps
Linux:	~/.local/share/gpxsee/maps
OS X:	~/Library/Application Support/GPXSee/maps

The map directory is recursively searched when loading the maps, so it may contain an arbitrary directory structure.

Supported map projections are Mercator (including Web Mercator), Transverse Mercator (including UTM), Lambert Conformal Conic, Albers Equal Area, Lambert Azimuthal Equal Area, Polar Stereographic, Křovák's and Latitude/Longitude (2D geographic). Additionally, the Swiss and Hungarian Oblique Mercator projections are aupported using LCC1 approximation. For list of supported datums and projected coordinate systems see the GCS.csv and PCS.csv configuration files (can be modified or overridden by user files like the map directory).

Online maps

Online maps are represented by map source definition XML files. For the formal map source file syntax see the map source XSD file. The paragraphs below are a "human-readable" summary of the XSD syntax/semantics divided by map type.

OSM/Google tiles

The root map element contains two mandatory elements - name and url, and two optional elements - zoom and bounds. The tile X and Y coordinates are replaced with $x and $y in the URL and the zoom level is replaced with $z. An example map source definition file can look like:

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.gpxsee.org/map/1.3" 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>

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>.

GPXSee supports HiDPI map tiles. To specify that a map uses HiDPI tiles use the pixelRatio attribute of the tile tag. For the most common 512x512px tiles (that shall be rendered as 256x256px tiles), set the value to 2.

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.gpxsee.org/map/1.3">
  <name>OSM - HiDPI</name>
  <url>https://a.osm.rrze.fau.de/osmhd/$z/$x/$y.png</url>
  <tile pixelRatio="2">
</map>

In case of vector tile images (PBF²), set the type attribute of the tile tag to "vector". This will adjust the pixel ratio of the tile to the pixel ratio of the display device.

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.gpxsee.org/map/1.3">
  <name>MapTiler</name>
  <url>https://maps.tilehosting.com/data/v3/$z/$x/$y.pbf?key=apikey</url>
  <tile type="vector"/>
  <zoom max="14"/>
</map>

The map URL can be also a local file URL (file: scheme).

TMS

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 map type attribute set to TMS.

WMTS

WMTS maps are distinguished by setting the type attribute of the map element to WMTS. Both the KVP and REST access methods are supported.

For KVP, the url element represents the WMTS base URL and two additional elements are required - layer and set (TileMatrixSet in WMTS). Optional format and style elements may be specified defining the desired image format and layer style. If not set, image/png is used for format and the default style for style.

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.gpxsee.org/map/1.3" 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>

For REST access, the url element's type attribute must be set to REST. The URL then represents the URL of the capabilities XML document. Defining the format has no relevance for the REST access method.

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.gpxsee.org/map/1.3" 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>

There is one more important attribute - the axis attribute of the set 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 axis attribute. Possible values are xy and yx.

Finally, one can define additional dimensions like Time using the dimension element. Use a separate entry for every additional dimension.

HiDPI WMTS tiles are supported too. Local (file: 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.

WMS

WMS maps are distinguished by setting the type attribute of the map element to WMS. WMS map definitions are very similar to WMTS map definitions, the main difference is that you must specify the map CRS using the crs element instead of specifying the tile set. Like in the case of the set element, you may specify the axis attribute to override the default axis order.

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 layer element content and a corresponding comma separated list as the style element content (can be omitted if all styles are the default style).

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.gpxsee.org/map/1.3" 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>

Offline maps

OziExplorer maps, TrekBuddy maps/atlases, Garmin JNX maps, MBTiles and GeoTIFF images are supported by GPXSee.

You may easily create offline atlases from online map services by using Mobile Atlas Creator (MOBAC).

POI files

All of the supported formats with waypoints capability - GPX, KML, TCX, NMEA, WPT and Garmin 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.

To make GPXSee load a POI file automatically on startup, add the file to the POI directory in one of the configuration paths.

DEM files

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 extracted in the DEM directory in one of the configuration paths for GPXSee to use them.

The SRTM data is provided for example by the USGS.

[1] The user paths have changed in GPXSee 7.

[2] To display PBF(MVT) tiles/MBTiles, QtPBFImagePlugin is required (part of the official Windows & OS X builds).