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. I use PyTopo at home for reviewing logs from where I've hiked and exploring track and waypoint data for places I plan to go.
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 open tile sources. (Not Google Maps, since Google's terms of service doesn't permit other programs to use their tiles.)
Download: PyTopo hosted on Github.
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.
|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.|
Dragging and mousewheel move and scroll the map, as you'd expect. Right-clicking in the map pops up a menu of various other options.
Click on a track or waypoint to select it and see what's known about it.
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 PyTopo can handle track files in GPX, KML, KMZ or GeoJSON formats. They may contain track points and/or waypoints, and you can multiple track files.
|San Francisco from the default setup (OpenStreetMap tiles).||Trails and a waypoint in the DOE-owned lands near White Rock, NM, using OpenCycleMap tiles.||Tacklogs and waypoints from a Garmin GPS above Lexington reservoir near Los Gatos, CA, using USGS/Topo! topographic maps.|
Aside from OpenStreetMap data, pytopo can use local map data on disk or CD.
PyTopo can also use tiled map data from sources like the Topo! local area and specific park map packages sold in camping/hiking stores (sometimes under the aegis of National Geographic). Caution: the Topo! Back Roads Explorer and the statewide explorer collections are not in this friendly tiled 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.)
For some areas, you can download USGS topo maps free. For instance, for California you can get maps in TIFF format from the California Spatial Information Library. You also may need to use specialized maps, such as geologic or land-use maps.
To use this sort of map, you have to split the large map into tiles. One way is to use ImageMagick, with 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 will have no way to tell where the origin of the map should be.
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
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.)
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:
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.
(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.)