GPXSee

• Home
• Screenshots
• Documentation
• Download

Paths

Several aspects of GPXSee are controlled by data/configuration files stored in either global(system) or user directories. The global paths to those directories are as follows:

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

User specific directories that - when present - override the global directory have the following paths:

Windows:	%APPDATA%\GPXSee\
Linux:	~/.local/share/gpxsee/
OS X:	~/Library/Application Support/GPXSee/
Android:	/storage/emulated/0/Android/data/org.gpxsee.gpxsee/files/

The expanded user specific paths, including the actual configuration directories, are also accesible from the GPXSee "Help" menu.

Data files

GPXSee opens GPX, TCX, FIT, KML, NMEA, IGC, CUP, SIGMA SLF, Suunto SML, LOC, GeoJSON, OziExplorer (PLT, RTE, WPT), Garmin GPI, Garmin CSV, TomTom OV2 & ITN, ONmove OMD/GHP, TwoNav (TRK, RTE, WPT) and geotagged JPEG files, however not all format features are supported for all formats. Generally, GPXSee supports four kinds of data objects:

• Tracks
• Routes
• Waypoints
• Areas (polygons)

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.

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)

Data filtering

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.

If you get unexpected results, try to disable the outlier elimination in the preferences.

Waypoint symbols

Waypoints that have a symbol name (GPX <sym> tag) defined can be shown with an icon corresponding to the name. The icons are searched in the global/user symbols directory and the icon is selected when the image basename (without extension) matches the symbol name.

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 maps directory. The map directory is recursively searched when loading the maps, so it may contain an arbitrary directory structure (which will be preserved in the map menu).

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 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.5" 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.5">
  <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 (MVT²), 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.5">
  <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>

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.

QuadTiles

QuadTiles (BING) maps - another variation of the OSM/Google tiles maps - are also supported by GPXSee. Use QuadTiles as the map type attribute and $quadkey as the quadkey placeholder in the URL.

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

Server access

If the map server requires HTTP authentication, you can use the authorization element to specify HTTP basic authorization credentials:

...
<authorization username="joe" password="123456"/>

Since version 13.3 you may also specify additional HTTP request headers using the header element:

...
<header name="Referer">https://referer.limited/</header>
<header name="User-Agent">Mozilla/5.0 (GNU Hurd)</header>

Offline maps

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, ENC charts, QCT maps, GEMF maps, Osmdroid SQLite maps, Orux maps and GeoTIFF and World-File georeferenced images are supported by GPXSee.

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

IMG maps

There is support for IMG maps overlay in GPXSee since version 7.30. If the map name is mapname.img and there is also a file named mapname.img.1 (.2, .3, ... for additional layers) in the same path, than it will be automatically loaded as an overlay of mapname.img.

JNX & KMZ maps

JNX & KMZ maps do not contain any info about the projection of their tile images, so it has to be provided externaly³. Generally, only two projections are used for JNX/KMZ maps - EPSG:4326 and EPSG:3857. If you see background color stripes in your JNX/KMZ map, you have to switch to the propper input projection in the preferences.

World Files

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 WKT1 format or by selecting the input projection in the preferences. If a PRJ file exists, it takes precedence.

Note, that the WKT datum entry must contain at least one of the TOWGS84 or AUTHORITY keys to provide a valid projection info (the AUTHORITY info overrides any parameter values). The WKT data must follow the OGC naming convention. Generally, the OGC WKT entries from epsg.io should work.

Map styles

MVT(PBF), Mapsforge and Garmin IMG maps can be styled with user defined styles. To apply a user defined style, place it to the style directory in one of the configuration paths. The style must be named style.typ (Garmin IMG), style.xml (Mapsforge) or style.json (MVT) for GPXSee to use it. If a Garmin IMG map contains a TYP file, it takes precedence over the user TYP file.

POI files

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.

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, SRTM1 and SRTM0.5). The DEM files must be put in the DEM directory in one of the configuration paths for GPXSee to use them.

The DEM files must have the expected filename format of NXXEYYY.hgt or NXXEYYY.hgt.zip for GPXSee to use them.

DEM downloads

Since GPXSee 9.6 you can download the required DEM files for the area covered by the loaded data from the GPXSee GUI. The URL is specified as a template where the NYY/SYY and EXXX/WXXX coordinates strings are replaced by $lat and $lon:

https://bailu.ch/dem3/$lat/$lat$lon.hgt.zip

The downloaded files are automatically renamed, if the file name is not in the required format.

Since version 10.2, there is a default DEM tiles download source hosted by the GPXSee project predefined in the preferences. The data is the DEM3 data originaly provided by Jonathan de Ferranti and repacked by the AAT project.

Positioning

Since version 10.0, GPXSee is able to show the real-time GPS position using the Qt positioning API. To make it work, you have to select and setup the positioning plugin used in the program preferences. See the Qt Positioning Plugins documentation for more info.

Windows & OS X

If your device/OS supports the platform positioning API (Core Location / Windows.Devices.Geolocation) you may try that first. If you have an external USB/serial GPS device connected, you can use the serialnmea plugin. In such case you have to provide the serial port id/device in the plugin parameters. Use something like COM3 on Windows and /dev/tty.SerialPort-3 on Mac.

Linux

On Linux, you can use Geoclue2 as the platform plugin, but Geoclue is "Gnome quality" software at its best and you will most probably not make it work.

Theoretically, you can also use the serialnmea plugin like on Windows/Mac, but practically almost all distributions fail to build the plugin... The only exception are distributions using Qt6 like ArchLinux. The NMEA plugin has been completely reworked in Qt6, is much more powerfull than in Qt5 and is compiled by default.

Known issues

Android file system

Due to the limited file system access on Android, all map formats that consist of multiple files (eg. OziExplorer maps or World-file georeferenced images) will not load properly when loaded from the application menu. You have to put such maps to the GPXSee map directory to make them work. The same applies to all SQLite-based map formats because of a Qt bug/limitation.

Even though all other maps will load from the application menu, it is strongly recommended for all offline maps to be also moved to the GPXSee map directory as the file access on Android is two orders of magnitude (100x!) slower when the file is located and opened from some "user folder" than if it is accessed/opened in the application folder. Especially IMG maps on new Android versions (>=11) are almost unusable when opened from the application menu.

OpenGL

There are numerous OpenGL issues in Qt that cause some kind of broken rendering or even an application crash. OpenGL is thus disabled by default even if it can significantly speed up rendering of big data sets. You may enable OpenGL in the preferences, but be prepared that "strange things" may happen...