.. image:: https://pytopo.readthedocs.io/en/latest/_images/pytopoicon.jpg
:align: right
:width: 218
:height: 290
:alt: PyTopo logo
==========================
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/
.. contents:: **Quick Links:**
:local:
Screenshots
-----------
+--------------------------------------------------------+------------------------------------------+
| |bandelier| | |landuse| |
+--------------------------------------------------------+------------------------------------------+
| Track logs and waypoints from hiking in Bandelier NP | Land use overlay for northern New Mexico |
+--------------------------------------------------------+------------------------------------------+
| |lexington| | |DOE| |
+--------------------------------------------------------+------------------------------------------+
| Trail above Lexington reservoir, using USGS/Topo! maps | Trails near White Rock, NM |
+--------------------------------------------------------+------------------------------------------+
| |frisco| | |ellie| |
+--------------------------------------------------------+------------------------------------------+
| San Francisco from the default view (OSM tiles) | Ellie track log statistics |
+--------------------------------------------------------+------------------------------------------+
.. _Using PyTopo:
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*.
You can change that by editing the MapCollection definitions in
*pytopo.sites*. See the
`PyTopo File Formats <https://shallowsky.com/software/topo/fileformats.html>`_
page for lots of gory 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.
*pytopo -h* prints 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 bindings
----------------------
============ ===========================================
Arrow keys Scroll the map in the indicated direction.
+/=, - Zoom in or out.
s Save the current map to a file under $HOME/Topo
Space Jump back to the pinned location.
m Switch to a different known site
q Quit
============ ===========================================
Dragging and mousewheel move and scroll the map, as you'd expect.
Right-clicking pops up a menu of other options.
Track Logs, Waypoints and Overlays
----------------------------------
PyTopo 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 Data
-----------------------
By 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 called *pytopo.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 of
`WMS <https://en.wikipedia.org/wiki/Web_Map_Service>`_
map data available, but many of them require that you register for
an API key. You'll find an example in *pytopo.sites*
of 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 on
`Creating Your Own Tiles <https://wiki.openstreetmap.org/wiki/Creating_your_own_tiles>`_
from 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 old
*National Geographic Topo!* CDROM sets.
The PyTopo classes that read tiles are called *MapCollections*. There are
several different types, but for most online WMS tile servers you'll
generally want an *OSMMapCollection*, and copying the examples in
*pytopo.sites* is the easiest way to make a new one. See the
`API documentation <https://pytopo.readthedocs.io/en/latest/#api-documentation>`_
for other types of MapCollections.
Installing and Dependencies
---------------------------
PyTopo is available on PyPI:
::
pip install pytopo
It 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 Github <https://github.com/akkana/pytopo>`_
if you want the latest and greatest.
You can pip install it from the source directory with:
::
pip install .
Dependencies include
- GTK3 (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 include
- numpy (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 Info
----------
*pytopo -h* gives usage examples.
If you need custom maps., edit *~/.config/pytopo/pytopo.sites* to add
new map Collections: see examples in that file or on the project home
page.
Code contributions appreciated!
Tests and Documentation
-----------------------
The official documentation is at
https://pytopo.readthedocs.io/en/latest/
To build the documentation locally:
::
python setup.py build_sphinx
or
::
cd sphinxdoc
make html
There are some unit tests in the test/ directory; run them with::
python -m unittest discover
from the top-level directory.
Happy mapping!
.. |bandelier| image:: https://pytopo.readthedocs.io/en/latest/_images/bandelier-ssT.jpg
:target: https://github.com/akkana/pytopo/blob/master/images/bandelier-ss.jpg
.. |landuse| image:: https://pytopo.readthedocs.io/en/latest/_images/ownership_overlay-ssT.jpg
:target: https://github.com/akkana/pytopo/blob/master/images/ownership_overlay-ss.jpg
.. |lexington| image:: https://pytopo.readthedocs.io/en/latest/_images/lexington-ssT.jpg
:target: https://github.com/akkana/pytopo/blob/master/images/lexington-ss.jpg
.. |DOE| image:: https://pytopo.readthedocs.io/en/latest/_images/doe-ssT.jpg
:target: https://github.com/akkana/pytopo/blob/master/images/doe-ss.jpg
.. |frisco| image:: https://pytopo.readthedocs.io/en/latest/_images/sf-ssT.jpg
:target: https://github.com/akkana/pytopo/blob/master/images/sf-ss.jpg
.. |ellie| image:: https://pytopo.readthedocs.io/en/latest/_images/ellieicon.jpg
:target: https://shallowsky.com/software/ellie/
Raw data
{
"_id": null,
"home_page": "http://shallowsky.com/software/topo/",
"name": "pytopo",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "maps, map viewer, track files, track logs, GPX, KML, GeoJSON",
"author": "Akkana Peck",
"author_email": "akkana@shallowsky.com",
"download_url": "https://files.pythonhosted.org/packages/1e/25/707c0fc524f477b786931ffdad81c3050600d582708302f62a6eb9b44fd2/pytopo-1.7.3.tar.gz",
"platform": null,
"description": ".. image:: https://pytopo.readthedocs.io/en/latest/_images/pytopoicon.jpg\n :align: right\n :width: 218\n :height: 290\n :alt: PyTopo logo\n\n==========================\nPyTopo: A Tiled Map Viewer\n==========================\n\n(and Track and Waypoint Editor)\n###############################\n\nPyTopo is a desktop tiled map viewer that can also show and edit\ntrack logs, waypoints and other simple geographic data.\n\nPyTopo can use tiles from a variety of sources, such as OpenStreetMap,\nand can read track or waypoint files in most common formats.\nIt can also make simple edits to track logs and waypoints, and\nsave the result in GPX format.\n\nDownloaded map tiles are cached locally, so you can use PyTopo offline\nif you\u2019ve already cached the tiles for an area.\n\nThe package also includes ellie, a simple script for reporting and\nplotting distance and elevation change statistics from a GPX track log.\n\nIt's developed on Linux, but should be able to run on any platform\nthat supports Python and GTK3.\n\nThe official documentation lives at:\nhttps://pytopo.readthedocs.io/en/latest/\n\n.. contents:: **Quick Links:**\n :local:\n\n\nScreenshots\n-----------\n\n+--------------------------------------------------------+------------------------------------------+\n| |bandelier| | |landuse| |\n+--------------------------------------------------------+------------------------------------------+\n| Track logs and waypoints from hiking in Bandelier NP | Land use overlay for northern New Mexico |\n+--------------------------------------------------------+------------------------------------------+\n| |lexington| | |DOE| |\n+--------------------------------------------------------+------------------------------------------+\n| Trail above Lexington reservoir, using USGS/Topo! maps | Trails near White Rock, NM |\n+--------------------------------------------------------+------------------------------------------+\n| |frisco| | |ellie| |\n+--------------------------------------------------------+------------------------------------------+\n| San Francisco from the default view (OSM tiles) | Ellie track log statistics |\n+--------------------------------------------------------+------------------------------------------+\n\n.. _Using PyTopo:\n\nUsing PyTopo\n------------\n\nThe first time you run pytopo, it will create a configuration file,\ntypically *~/.config/pytopo/pytopo.sites* (if it can't create that it\nwill fall back to *~/.pytopo* instead).\n\nYou might want to take a look at the file: this is where you can add\nadditional map collections or sites you visit frequently.\n\nBy default, pytopo will download OpenStreetMap tiles to *~/Maps*.\nYou can change that by editing the MapCollection definitions in\n*pytopo.sites*. See the\n`PyTopo File Formats <https://shallowsky.com/software/topo/fileformats.html>`_\npage for lots of gory details.\n\n*pytopo -p* will print out a list of known sites. With the initial\ndefault configuration you'll just have a few cities like\nsan-francisco, new-york, london, sydney; this is mostly to show you\nhow to add your own points of interest.\n\n*pytopo -h* prints help.\n\nUsage (command-line arguments)\n------------------------------\n\n::\n\n Usage: pytopo\n pytopo trackfile\n pytopo known_site\n pytopo [-t trackfile] [-c collection] [-o overlay] [-r] [site_name]\n pytopo [-t trackfile] start_lat start_lon [collection]\n pytopo -m : show a menu of known sites\n pytopo -p : list known sites, collections and tracks\n pytopo -r : re-download all map tiles that need to be shown\n pytopo -h : print this message\n\n Other flags:\n -k keys : comma-separated list of fields (keys) to look for\n when grouping polygonal regions.\n -g : follow a GPS if available\n -d[level] : debugging mode. Defaults to 1, level 2 shows a little more.\n\n With no arguments, will display a menu of known sites\n (defined in pytopo.sites).\n\n Map collections are defined in pytopo.sites.\n Overlays are also collections, drawn translucently on top of the base map,\n and there can be more than one.\n\n Track files may be in GPX, KML, KMZ or GeoJSON format, and may contain\n track points and/or waypoints; multiple track files are allowed.\n GeoJSON files may also contain polygons: use the -k option to specify\n which field in the GeoJSON feature should be used for coloring groups.\n\n Use decimal degrees for coordinates.\n\n Set up favorite site names in ~/.config/pytopo.sites,\n favorite track logs in ~/Tracks\n\n Move around by dragging and zoom with the mousewheel, or use the keyboard:\n Left/right/up/down: move in that direction\n +/=/-: zoom in/out\n spacebar: go back to last pinned location\n m: bring up the site selection dialog\n q: quit\n\n Right-click gives a context menu.\n Shift-click in the map to print the coordinates of the clicked location,\n as well as distance and bearing from the last shift-clicked point,\n to standard output.\n\n\nKey and Mouse bindings\n----------------------\n\n============ ===========================================\nArrow keys Scroll the map in the indicated direction.\n+/=, - Zoom in or out.\ns Save the current map to a file under $HOME/Topo\nSpace Jump back to the pinned location.\nm Switch to a different known site\nq Quit\n============ ===========================================\n\n\nDragging and mousewheel move and scroll the map, as you'd expect.\nRight-clicking pops up a menu of other options.\n\nTrack Logs, Waypoints and Overlays\n----------------------------------\n\nPyTopo can read track logs in GPX, KML, KMZ or geojson format, and\npolygon overlay files in geojson. It shows each\ntrack in a different color. You can toggle waypoint visibility with\nthe right-click context menu (for when there are too many waypoints\nand they get in the way of reading the map).\n\nYou can make simple edits to tracks, like splitting a track into parts\nor deleting to the beginning or end point, and can save the resulting\ntracks as a GPX file.\n\nSelect a track by left-clicking on it. The right-click context menu lets\nyou split a track or delete everything before or after the mouse\nposition, and save a track as GPX after you\u2019ve changed it.\n\nYou can also provide polygonal overlays from a GeoJSON file: for\nexample, to colorize areas according to land ownership or geology.\n\nPyTopo can also measure distances and bearing angles between points\n(shift-click and watch standard output). The right-click context menu\nreports the coordinates at the mouse position; if you want to\ncopy/paste, choose that menu item to print it to standard output.\n\nFor displaying or plotting distances and elevations, ellie is included\nas part of the PyTopo install.\n\nTiles: Getting Map Data\n-----------------------\n\nBy default, PyTopo sets up maps from OpenStreetMap and the USGS.\nThere are various sources of map tiles, but many of them require that\nyou register for an API key.\n\nOn startup, PyTopo will create a file called *pytopo.sites*: on Linux\nyou'll find it in *~/.config/pytopo*, but it may be elsewhere on other\nplatforms. You can edit that file to add new tile sources.\n\nThere are quite a few sources of\n`WMS <https://en.wikipedia.org/wiki/Web_Map_Service>`_\nmap data available, but many of them require that you register for\nan API key. You'll find an example in *pytopo.sites*\nof how to set up tiles from ThunderForest using an API key.\nSome tile providers, like Google, don\u2019t allow their tiles to be used\nby other programs, so please respect that and use sources that\ndon't have such restrictions.\n\nOr you can create your own tiles. OpenStreetMap has a page on\n`Creating Your Own Tiles <https://wiki.openstreetmap.org/wiki/Creating_your_own_tiles>`_\nfrom OpenStreetMap data, but the process is fairly elaborate and poorly\ndocumented. You can also use a large map and split it into tiles with\na program like ImageMagick, where you'd use a command like::\n\n convert source-map.jpg -rotate 90 -crop 300x300 -repage +0+0 out-map%02d.jpg\n\n(Don't use *-trim*; it will give you maps of inconsistent sizes, and\npytopo will have no way to tell where the origin of the map should be.)\n\nPyTopo can also use tiles from a few commercial programs like the old\n*National Geographic Topo!* CDROM sets.\n\nThe PyTopo classes that read tiles are called *MapCollections*. There are\nseveral different types, but for most online WMS tile servers you'll\ngenerally want an *OSMMapCollection*, and copying the examples in\n*pytopo.sites* is the easiest way to make a new one. See the\n`API documentation <https://pytopo.readthedocs.io/en/latest/#api-documentation>`_\nfor other types of MapCollections.\n\n\nInstalling and Dependencies\n---------------------------\n\nPyTopo is available on PyPI:\n::\n\n pip install pytopo\n\nIt installs two programs: pytopo, the map viewer, and ellie, which shows\ntrack log statistics. If you have matplotlib installed and your track log\nhas elevations, ellie can plot them, showing how much you climbed and\ndescended.\n\n`PyTopo's source is hosted on Github <https://github.com/akkana/pytopo>`_\nif you want the latest and greatest.\nYou can pip install it from the source directory with:\n::\n\n pip install .\n\nDependencies include\n\n- GTK3 (and its various dependencies, like pangocairo)\n- requests-futures (for downloading map tiles in the background)\n- simplejson (for reading XML-based formats like GPX and KML)\n\nOptional dependencies include\n\n- numpy (for analyzing track statistics like distance)\n- matplotlib ( for Ellie\u2019s track log visualizations)\n- shapely (used for polygonal overlays)\n- The programs gpsd and python-gps (to read from a GPS device)\n\nI've only tested PyTopo on Linux, but in theory it should run on any\nplatform. If not, let me know.\n\nOther Info\n----------\n\n*pytopo -h* gives usage examples.\n\nIf you need custom maps., edit *~/.config/pytopo/pytopo.sites* to add\nnew map Collections: see examples in that file or on the project home\npage.\n\nCode contributions appreciated!\n\nTests and Documentation\n-----------------------\n\nThe official documentation is at\nhttps://pytopo.readthedocs.io/en/latest/\n\nTo build the documentation locally:\n\n::\n\n python setup.py build_sphinx\n\nor\n\n::\n\n cd sphinxdoc\n make html\n\nThere are some unit tests in the test/ directory; run them with::\n\n python -m unittest discover\n\nfrom the top-level directory.\n\nHappy mapping!\n\n.. |bandelier| image:: https://pytopo.readthedocs.io/en/latest/_images/bandelier-ssT.jpg\n :target: https://github.com/akkana/pytopo/blob/master/images/bandelier-ss.jpg\n.. |landuse| image:: https://pytopo.readthedocs.io/en/latest/_images/ownership_overlay-ssT.jpg\n :target: https://github.com/akkana/pytopo/blob/master/images/ownership_overlay-ss.jpg\n.. |lexington| image:: https://pytopo.readthedocs.io/en/latest/_images/lexington-ssT.jpg\n :target: https://github.com/akkana/pytopo/blob/master/images/lexington-ss.jpg\n.. |DOE| image:: https://pytopo.readthedocs.io/en/latest/_images/doe-ssT.jpg\n :target: https://github.com/akkana/pytopo/blob/master/images/doe-ss.jpg\n.. |frisco| image:: https://pytopo.readthedocs.io/en/latest/_images/sf-ssT.jpg\n :target: https://github.com/akkana/pytopo/blob/master/images/sf-ss.jpg\n.. |ellie| image:: https://pytopo.readthedocs.io/en/latest/_images/ellieicon.jpg\n :target: https://shallowsky.com/software/ellie/\n",
"bugtrack_url": null,
"license": "GPLv2+",
"summary": "Tiled map viewer and track editor",
"version": "1.7.3",
"project_urls": {
"Bug Tracker": "https://github.com/akkana/pytopo/issues",
"Documentation": "https://pytopo.readthedocs.io/",
"Homepage": "http://shallowsky.com/software/topo/",
"Source Code": "https://github.com/akkana/pytopo/"
},
"split_keywords": [
"maps",
" map viewer",
" track files",
" track logs",
" gpx",
" kml",
" geojson"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e62441c3bb0374c1d5e8eb7d22cc683ba9c5c4dabca97147603873983c098a15",
"md5": "482e276d8efa89a8938a75ab5cfe6fe2",
"sha256": "cfde707117e9569c778742c661edaa551fcbe52d3bc476a5a1259520b642695f"
},
"downloads": -1,
"filename": "pytopo-1.7.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "482e276d8efa89a8938a75ab5cfe6fe2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 95313,
"upload_time": "2024-09-22T00:20:54",
"upload_time_iso_8601": "2024-09-22T00:20:54.423080Z",
"url": "https://files.pythonhosted.org/packages/e6/24/41c3bb0374c1d5e8eb7d22cc683ba9c5c4dabca97147603873983c098a15/pytopo-1.7.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1e25707c0fc524f477b786931ffdad81c3050600d582708302f62a6eb9b44fd2",
"md5": "485a4f169b8211f1b8b9ebc7f63a5202",
"sha256": "d3a7c12eec9f071e862404de1977b2e8006bde3e20c28bbaaaee81825dff4e9d"
},
"downloads": -1,
"filename": "pytopo-1.7.3.tar.gz",
"has_sig": false,
"md5_digest": "485a4f169b8211f1b8b9ebc7f63a5202",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 1216078,
"upload_time": "2024-09-22T00:21:08",
"upload_time_iso_8601": "2024-09-22T00:21:08.049549Z",
"url": "https://files.pythonhosted.org/packages/1e/25/707c0fc524f477b786931ffdad81c3050600d582708302f62a6eb9b44fd2/pytopo-1.7.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-22 00:21:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "akkana",
"github_project": "pytopo",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pytopo"
}
JSON
