PyTopo: Setting Up Your .pytopo File

In order to use pytopo, you need to create a configuration file -- either .config/pytopo/pytopo.sites or .pytopo in your home directory -- to tell pytopo where you keep your maps and what format they're in. There are also some other variables you can customize in that file.

Collections

A Collection is a set of maps from one source, all in the same format. For instance, if I load the Topo! Death Valley CD into a directory, that would represent one collection.

You must have at least one collection in order to use pytopo (otherwise it won't know where to look for your map data).

Define your collections like this:

Collections = [
    OSMMapCollection( "openstreetmap", "~/Maps/openstreetmap",
                      ".png", 256, 256, 10,
                      "http://a.tile.openstreetmap.org" ),
    Topo1MapCollection( "deathvalley", "/home/yourname/Maps/dvl_data",
                        7.5, 266, 328 ),
    Topo2MapCollection( "kingscyn", "/home/yourname/Maps/kingscyn", "topo",
                        410, 256 ),
    GenericMapCollection( "pa-geo", "/home/yourname/Maps/pa-geo-300",
                          "pa-geo-300-", ".jpg",
                          -122.497, 37.498, 300, 400, 10746, 13124,
                          2, True, False )
]

This defines four collections. The first is the default OpenStreetMap file set. If you specify a URL, as in this example, pytopo will download any tiles it needs. If you already have tiles and want to work offline, you can disable downloading by making this URL blank. OpenStreetMap has several different tile sets, so you can change the URL to use a different one if you prefer. For instance, http://b.tile.opencyclemap.org/cycle will get you the topographic OpenCycleMap tiles. To find out where your favorite OSM tile set is coming from, just view the map on openstreetmap.org, right click in the map and "View image" and note the URL.

The second one is called "deathvalley", stored in the directory named /home/yourname/Maps/dvl_data, and uses the format Topo1MapCollection -- the simple format used in Topo! regional CD sets. The filenames already have latitude and longitude encoded into them, but you do need to specify the size.

The third collection is a different sort of Topo! format, one with filenames beginning with "topo" and much wider and shorter jpeg images.

The last collection, called "pa-geo" and stored in /home/yourname/Maps/pa-geo, is more complicated. GenericMapCollection is a much more general format suitable for map collections you create yourself. Suppose a sample map in the collection might have a filename like pa-map-03-17.png. Then the pieces of the GenericMapCollection are:

Field	Value	Description
Name	pa-geo	Name of the collection
Directory	/home/yourname/Maps/pa-geo	Directory where the files live
Prefix	pa-map-	Prefix prepended to every filename
Suffix	.png	Suffix (extension) appended to every filename
Longitude	123	Longitude of upper left corner
Latitude	37.5	Latitude of upper left corner
Width	Width of each maplet
Height	Height of each maplet
X scale	10742	X scale (pixels per degree)
Y scale	13120	Y scale (pixels per degree)
Num digits	2	Number of digits for each grid point in the filenames
Use dash?	True	Use a dash between X and Y grid point numbers in the file name? (E.g. pa-map-03-17.png vs. pa-map-0317.png.)
Latitude first?	True	Is the latitude the first grid point (e.g. 03) in the filename?

Map Collections are simply Python classes. If you have a weird type of map collection and you know some Python programming, you can define your own map collection type inside your .pytopo file. If you write a collection class that might be useful to someone else, please send it to me and I'll include it in the next version of pytopo.

I'm working on a new format, using tiles downloaded from the OpenStreetMap project. Stay tuned for PyTopo 0.9!

Named Sites

Once you have one or more collections defined, you can start defining named sites which you can use as starting points when you run pytopo.

The format is:

[ sitename, longitude, latitude, collection_name ]

Example:

 KnownSites = [
     # San Francisco Bay Area
     [ "saratogagap", 122.0725, 37.155, "sfr" ],
     [ "lexington", 121.594, 37.12, "sfr" ],
     # Death Valley
     [ "zabriskie", 116.475, 36.245, "deathvalley" ],
     # From the Big Sur map:
     [ "pinnacles", 121.0865, 36.3247, "bigsur" ],
     ]

Other Useful Variables

You can customize pytopo by changing the values of these variables:

If you don't like the default window size, you can specify a different one:

init_width = 1200
init_height = 800

It's possible to tell pytopo to save the map you're currently viewing, for instance, so you could edit it or print it out. But this code doesn't get tested much and may be broken. If it does work, you can control where it saves:

# Where to save generated maps. The default is fine for most people.
MapSaveDir = os.environ["HOME"] + "/Topo/"
Note: Saving maps may be buggy. I haven't tested it in
quite a long time.