Instructions

PyGPSClient offers the facility for users to import their own custom offline imagery for use as background maps in the Map View and GPX Track View panels. The custom map configuration is saved in the usermaps_l setting in PyGPSClient's json configuration file. To create custom geo-referenced imagery, we use and recommend the free, open-source QGIS software, which is available for most platforms including Windows, MacOS and Linux.

ⓘ This illustration uses OpenStreetMap (OSM) as a basemap, but any other geo-referenceable map layer could be used instead, including your own imagery. Note that OpenStreetMap is open data, licensed under the Open Data Commons Open Database License (ODbL) by the OpenStreetMap Foundation (OSMF). Please acknowledge this license if you distribute any map images based on an OSM source.

1. Download and install QGIS. The latest LTR version at time of writing is 3.44. It's a relatively large package (≈ 3 GB) and the install may take a couple of minutes or so.

   ⚠ If you're installing on MacOS Sequoia or newer, note the "Tips for first launch".

2. Navigate to the left hand browser and select XYZ Tiles..OpenStreetMap (OpenStreetMap is available as standard in recent versions of QGIS - previously it was available as an optional plugin).

3. Shift and zoom into the area of interest. Toggle the 'Coordinate/Extents' display in the bottommost status bar to show the current map extent.

   

4. Note that the Coordinate Reference System (CRS) used by Open Street Map is EPSG:3857, which will display coordinates and extents in meters by default. To see coordinates in lat/lon format, select from the top menu bar Project..Properties..General and change the "Display coordinates using" setting to "Map Geographic (degrees)".

   

   Alternatively, you can select an different CRS EPSG:4326, which uses lat/lon coordinates by default, but the map projection will appear a little "stretched" along the x-axis (it will still render OK in PyGPSClient).

   

5. When you reach the desired extent, select from the top menu bar Project..Import/Export..Export Map to Image....

6. Accept all the defaults in the "Save Map as Image" pop-up box. Ensure the "Append Georeference Information" option is ticked. If necessary, make a note of the map extent (if using EPSG:3857, the extents will be in meters; if using EPSG:4326, the extents will be in lat/lon format). If you have a high resolution screen, you can adjust the default Resolution setting (dpi or Output height/width) to match your screen resolution, at the expense of a larger file size. Note that the maximum image size that PyGPSClient can accommodate is roughly 150 million pixels, or around 430 MB.

   

7. Save the map as a geoTIFF (*.tif) file.

8. You can now import the saved image into PyGPSClient using Options..Import Custom Map. If the Python rasterio library is installed, the map extents will be extracted automatically - otherwise, it must be entered manually in lat/lon format.

   

   The "First?" checkbox determines whether the map file is imported as the first or last item in the usermaps_l list.

9. Provided at least one custom map is imported, the user may select a Map Type of "custom". PyGPSClient will then search the available custom maps (in the order they appear in the usermaps_l list) and automatically display the first imported map whose extents encompass the current location. If no suitable imported map is found, it will display an error message No custom map available for location.

   

10. Note that the PyGPSClient map widget can only display a single map image at a time (it cannot 'tile' multiple images to cover the visible canvas extents). Typically, a user may wish to import a series of small, high resolution maps covering the individual areas of interest, followed by a larger 'catch-all' map at lower resolution. NB: The minimum and maximum viable 'zoom' levels depend on the resolution and extents of the imported image - if the zoom bounds exceed the image extents, the Zoom spinbox will be highlighted.