[PyTopo for Linux]

pytopo: A Map Viewer for Linux

PyTopo is a Python-gtk map viewer which interprets local tiled map data and displays it in an interactive viewer, where you can scroll to adjacent maps, switch between resolutions, or produce a map image for printing or editing.

Why does PyTopo exist? I needed a local, offline mapping program that worked on Linux.

I like to travel to remote locations with no network access, and of course I want maps once I'm there. When I first started PyTopo, smartphones didn't exist yet, and even in the smartphone age I often want a larger map than I can show on a phone screen, with a user interface that's easier to use for showing things like track logs.

Originally PyTopo was written to use data from National Geographic's commercial Topo! data CDs. Since then, it has expanded to use OpenStreetMap tiles as well as several other tile open sources. (Not Google Maps, since Google's terms of service doesn't permit other programs to use their tiles.)

Download: The current released version is PyTopo 1.1, but I strongly recommend that you use the latest git version instead: PyTopo hosted on Github. It has a lot more features.

The latest and greatest is always in the current git version: PyTopo hosted on Github.

There's an older experimental MeeGo package for anyone interested in trying it, and I'd be interested to know if it works on other RPM platforms as well: PyTopo-1.0-1-beta1.noarch.rpm.

Using PyTopo

The 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 ~/.pytopo instead).

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. Of course, you can change that. See the PyTopo File Formats page for more details.

pytopo -p will 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.

Key bindings

Left, Right,
Up, Down
Scroll the map in the indicated direction.
+/=, - Zoom in or out.
s Save the current map to a file under $HOME/Topo
Space Print (to standard output) the current coordinates of map center.
q Quit

Clicking in the map displays the coordinates of where you clicked, as well as the distance and bearing from the last clicked point.

Dragging and mousewheel move and scroll the map, as you'd expect.

Click on a track or waypoint to select it and see what's known about it.

Right mouse click will bring up a menu offering other options.

Usage (commandline arguments)

Usage: pytopo site_name
       pytopo trackfile...
       pytopo [trackfile...] start_lat start_long collection
       pytopo -p
Use degrees.decimal_minutes format for coordinates.
Set up site names in ~/.pytopo
Print list of known sites with pytopo -p

Track files are GPX files which may contain track points and/or waypoints;
multiple track files are allowed.


(Click to see larger image)
[San Francisco/OpenStreetMap screenshot] [White Rock DOE/OpenCycleMap screenshot] [Trails above Lexington reservoir/USGS screenshot]
San Francisco from the default setup. Several tracklogs and waypoints hiking in the DOE-owned lands near White Rock, NM. Tacklogs and waypoints above Lexington reservoir near Los Gatos, using USGS/Topo! dara

Preloaded Map Data

Aside from OpenStreetMap data, pytopo can use local map data on disk or CD.

The Topo! local area and specific park map packages sold in camping/hiking stores (sometimes under the aegis of National Geographic) are reasonably priced as a source of map data. They come with Windows software, but Linux users can ignore the software and use the data files, which are standard GIF, named in a fairly straightforward way. They're a good source of US map data.

Caution: the Topo! Back Roads Explorer and the statewide explorer collections are not in this friendly format. They use large data files in a proprietary ".tpq" format. Tom Trebisky has analyzed the format and has written an extractor, and he also has a C GTK viewer for this format. (Eventually I hope to integrate direct support for them into pytopo as well.)

Making Your Own Map Collections

You can buy map bits directly from the USGS, but they have a hefty setup fee so it's not cost effective unless you're buying quite a lot.

For some areas, you can download topo maps; for instance, for California you can get maps in TIFF format from the California Spatial Information Library. You still have to split up the maps into maplets, though; if you have ImageMagick, you can use a command like

convert in-map.jpg -rotate 90 -crop 300x300 -repage +0+0 out-map%02d.jpg

Note: previously I included -trim as part of that line, and a lot of pages you'll find googling for image splitting will tell you to use -trim. Don't: it will give you maps of inconsistent sizes, and pytopo has no way to tell where the origin of the map should be.

A map split this way can be read with PyTopo 0.5 or later. Maps downloaded as PDF (such as USGS geologic maps) might work in imagemagick, but if not, try converting them to a raster format before splitting, using a program like GIMP or a command like

gs -sDEVICE=jpeg -r300 -sOutputFile=output-map.jpg input-map.pdf

API Documentation

If you want to contribute to PyTopo, or use the code for something else, you'll probably want to know more about the classes it uses, in the PyTopo API Documentation. (This is generated with epydoc --no-frames pytopo and is not guaranteed to be up to date.)

Non-interactive mapping scripts

I wrote some older commandline helper scripts, but honestly, I don't use them myself and don't vouch for them. I list them here merely on the chance that someone might find one of them a useful building block:

Is it Only For Linux?

PyTopo should run fine on any system which has Python, gtk, gdk-pixbuf, and PyGTK. I've tried to make the code as portable as I can, but I've only tested it on Linux. If it doesn't work for you, please let me know.

Bugs / Wishlist

(Stuff that would be nifty, but is either difficult, or requires additional map data that I'd have to pay for. If you want something on this list, bribing me with interesting map data would be an excellent approach.)

Change Log

Coming in 1.2 (late 2015/early 2016):
Move by dragging, zoom with the mousewheel. Switch between different background maps. Much better track log and waypoint handling, with multiple colors and selection. Accept KML as well as GPX track logs. Pin and remember specific locations. Probably lots of other things I've forgotten.
1.1, November 16 2011
Fix a lot of minor bugs and some usability problems with features introduced in 1.0.
1.0, May 7 2011
Lots of UI additions to make pytopo work well on MeeGo and other tablets. Now there's a "pin", you can save sites, go to saved track logs and lots of other goodies, including some great contributions from Ville JyrkkÀ.
0.9, October 30, 2010
New format! OSMMapCollection handles OpenStreetMap tiles, including (optionally) downloading them for you.
Figure out trackpoint files from context -- no need to use -t any more. So now you can run pytopo *.gpx site
If there's no config file initially, create a default one using tiles from the default OSM website and a few major cities.
More flexible handling of initial window width.
0.8, June 20, 2009
Support track/waypoint files;
support worldwide coordinates by using negative longitudes when west of the prime meridian;
complete codebase refactor -- cleaner, more generalizable, more OO code;
base class for implementing new tiled map collections;
some associated MapCollection file format changes;
accept config file in .config/pytopo as well as ~/.pytopo
; introduce new (still buggy and undocumented) OSMMapCollection.
0.7, September 10, 2008
Add -c to find the center of a collection;
fix a bug when latitude or longitude is less than 10°.
0.6, October 12, 2007
Fix bad memory leak (will run much better on small-memory machines now).
Integrate Tom Trebisky's Topo2 format.
0.5, August 21, 2006
Formal 0.5 release: Fix a bug when specifying long/lat on the command line.
0.5b2, June 2, 2006
Fix "save as". Fix latitude reported when clicking.
0.5b1, April 16, 2006
Read more general map formats. Display to arbitrarily sized windows. Bug fixes. Code refactoring.
0.4, April 17, 2005
Calculate distance and bearing between clicks; assorted bug fixes.
0.3, April 13, 2005
Add 's' binding to save current map to a file (using montage from ImageMagick).
Better fix for expose handling.
0.2, April 8, 2005 Temporary fix for spurious expose problem (excessive CPU usage).
0.1, April 5, 2005
Coordinate handling routines mostly working. Store coordinates of center, not edge, so zoom works.

Ellie: Plot GPS elevation profiles
More Software
Shallowsky Home
mail me