Package: pytopo
PyTopo: A Tiled Map Viewer(and Track and Waypoint Editor)PyTopo is a desktop tiled map viewer that can also show and edit
track logs, waypoints and other simple geographic data.PyTopo can use tiles from a variety of sources, such as OpenStreetMap,
and can read track or waypoint files in most common formats.
It can also make simple edits to track logs and waypoints, and
save the result in GPX format.Downloaded map tiles are cached locally, so you can use PyTopo offline
if you’ve already cached the tiles for an area.The package also includes ellie, a simple script for reporting and
plotting distance and elevation change statistics from a GPX track log.It’s developed on Linux, but should be able to run on any platform
that supports Python and GTK3.The official documentation lives at:https://pytopo.readthedocs.io/en/latest/Quick Links:ScreenshotsUsing PyTopoUsage (command-line arguments)Key and Mouse bindingsTrack Logs, Waypoints and OverlaysTiles: Getting Map DataInstalling and DependenciesOther InfoTests and DocumentationScreenshotsTrack logs and waypoints from hiking in Bandelier NPLand use overlay for northern New MexicoTrail above Lexington reservoir, using USGS/Topo! mapsTrails in near White Rock, NMSan Francisco from the default view (OSM tiles)Ellie track log statisticsUsing PyTopoThe first time you run pytopo, it will create a configuration file,
typically~/.config/pytopo/pytopo.sites(if it can’t create that it
will fall back to~/.pytopoinstead).You might want to take a look at the file: this is where you can add
additional map collections or sites you visit frequently.By default, pytopo will download OpenStreetMap tiles to~/Maps.
You can change that by editing the MapCollection definitions inpytopo.sites. See thePyTopo File Formatspage for lots of gory details.pytopo -pwill print out a list of known sites. With the initial
default configuration you’ll just have a few cities like
san-francisco, new-york, london, sydney; this is mostly to show you
how to add your own points of interest.pytopo -hprints help.Usage (command-line arguments)Usage: pytopo
       pytopo trackfile
       pytopo known_site
       pytopo [-t trackfile] [-c collection] [-o overlay] [-r] [site_name]
       pytopo [-t trackfile] start_lat start_lon [collection]
       pytopo -m :  show a menu of known sites
       pytopo -p :  list known sites, collections and tracks
       pytopo -r :  re-download all map tiles that need to be shown
       pytopo -h :  print this message

Other flags:
       -k keys   : comma-separated list of fields (keys) to look for
                   when grouping polygonal regions.
       -g        : follow a GPS if available
       -d[level] : debugging mode. Defaults to 1, level 2 shows a little more.

With no arguments, will display a menu of known sites
(defined in pytopo.sites).

Map collections are defined in pytopo.sites.
Overlays are also collections, drawn translucently on top of the base map,
 and there can be more than one.

Track files may be in GPX, KML, KMZ or GeoJSON format, and may contain
track points and/or waypoints; multiple track files are allowed.
GeoJSON files may also contain polygons: use the -k option to specify
which field in the GeoJSON feature should be used for coloring groups.

Use decimal degrees for coordinates.

Set up favorite site names in ~/.config/pytopo.sites,
favorite track logs in ~/Tracks

Move around by dragging and zoom with the mousewheel, or use the keyboard:
  Left/right/up/down:  move in that direction
               +/=/-:  zoom in/out
            spacebar:  go back to last pinned location
                   m:  bring up the site selection dialog
                   q:  quit

Right-click gives a context menu.
Shift-click in the map to print the coordinates of the clicked location,
as well as distance and bearing from the last shift-clicked point,
to standard output.Key and Mouse bindingsArrow keysScroll the map in the indicated direction.+/=, -Zoom in or out.sSave the current map to a file under $HOME/TopoSpaceJump back to the pinned location.mSwitch to a different known siteqQuitDragging and mousewheel move and scroll the map, as you’d expect.
Right-clicking pops up a menu of other options.Track Logs, Waypoints and OverlaysPyTopo can read track logs in GPX, KML, KMZ or geojson format, and
polygon overlay files in geojson. It shows each
track in a different color. You can toggle waypoint visibility with
the right-click context menu (for when there are too many waypoints
and they get in the way of reading the map).You can make simple edits to tracks, like splitting a track into parts
or deleting to the beginning or end point, and can save the resulting
tracks as a GPX file.Select a track by left-clicking on it. The right-click context menu lets
you split a track or delete everything before or after the mouse
position, and save a track as GPX after you’ve changed it.You can also provide polygonal overlays from a GeoJSON file: for
example, to colorize areas according to land ownership or geology.PyTopo can also measure distances and bearing angles between points
(shift-click and watch standard output). The right-click context menu
reports the coordinates at the mouse position; if you want to
copy/paste, choose that menu item to print it to standard output.For displaying or plotting distances and elevations, ellie is included
as part of the PyTopo install.Tiles: Getting Map DataBy default, PyTopo sets up maps from OpenStreetMap and the USGS.
There are various sources of map tiles, but many of them require that
you register for an API key.On startup, PyTopo will create a file calledpytopo.sites: on Linux
you’ll find it in~/.config/pytopo, but it may be elsewhere on other
platforms. You can edit that file to add new tile sources.There are quite a few sources ofWMSmap data available, but many of them require that you register for
an API key. You’ll find an example inpytopo.sitesof how to set up tiles from ThunderForest using an API key.
Some tile providers, like Google, don’t allow their tiles to be used
by other programs, so please respect that and use sources that
don’t have such restrictions.Or you can create your own tiles. OpenStreetMap has a page onCreating Your Own Tilesfrom OpenStreetMap data, but the process is fairly elaborate and poorly
documented. You can also use a large map and split it into tiles with
a program like ImageMagick, where you’d use a command like:convert source-map.jpg -rotate 90 -crop 300x300 -repage +0+0 out-map%02d.jpg(Don’t use-trim; it will give you maps of inconsistent sizes, and
pytopo will have no way to tell where the origin of the map should be.)PyTopo can also use tiles from a few commercial programs like the oldNational Geographic Topo!CDROM sets.The PyTopo classes that read tiles are calledMapCollections. There are
several different types, but for most online WMS tile servers you’ll
generally want anOSMMapCollection, and copying the examples inpytopo.sitesis the easiest way to make a new one. See theAPI documentationfor other types of MapCollections.Installing and DependenciesPyTopo is available on PyPI:pip install pytopoIt installs two programs: pytopo, the map viewer, and ellie, which shows
track log statistics. If you have matplotlib installed and your track log
has elevations, ellie can plot them, showing how much you climbed and
descended.PyTopo’s source is hosted on Githubif you want the latest and greatest.Dependencies includeGTK3 (and its various dependencies, like pangocairo)requests-futures (for downloading map tiles in the background)simplejson (for reading XML-based formats like GPX and KML)Optional dependencies includenumpy (for analyzing track statistics like distance)matplotlib ( for Ellie’s track log visualizations)shapely (used for polygonal overlays)The programs gpsd and python-gps (to read from a GPS device)I’ve only tested PyTopo on Linux, but in theory it should run on any
platform. If not, let me know.Other Infopytopo -hgives usage examples.If you need custom maps., edit~/.config/pytopo/pytopo.sitesto add
new map Collections: see examples in that file or on the project home
page.Code contributions appreciated!Tests and DocumentationThe official documentation is athttps://pytopo.readthedocs.io/en/latest/To build the documentation locally:python setup.py build_sphinxorcd sphinxdoc
make htmlThere are some unit tests in the test/ directory; run them with:python -m unittest discoverfrom the top-level directory.Happy mapping!