OSM maps in Emacs and Org mode

osm-maps.el provides functionality to work with GPS data and produce SVG images with PNG map tiles (OSM or Google) as backgrounds and draw your tracks on top of them.

org-osm-link.el provides a special link type for org-mode, that uses a series of choords as URL.

org-gpx-link.el provides a special link type for org-mode that links to a GPX file.

Implemented features

• Download and caching of background tiles. Sources are OSM (default) or google maps.
• Optionally use online resources as background tiles.
• Maps are saved as SVG files and thus may share cached background tiles.
• Working Org links. The link type is track:. Clicking a track: link pops up a map of the track. The map is created if it does not exist yet.
• Interactive creation of Org track: links.
• HTML export of links and maps. Maps will be modified to work in the publishing directory and are referenced through hyperlinks (customizable).
• LaTeX export of links. Maps will be referenced by a hyperlink.
• Import org track links from GPX files semi-interactively.
• Export org track links to GPX. Either the next link or all links in a region. Each track is added only once, provided track-filename and choords match.
• org-track-extract.pl extracts tracks from your org file again and prints statistics or a GPX file. The export may be restricted to a subtre and/or a certain number of tracks. Here is an example:

  org-track-extract.pl --max 2 --format gpx \
         --subtree 4.1.1 ~/training.org 2>debug.log
      

• SVGs may be published along with your Org-files. See Publishing Setup below.

Setup

Just make sure osm-maps.el and org-osm-link.el are in your load-path, and add this line to your setup (.emacs probably):

(require 'org-osm-link)

After restarting Emacs (or evalutating the code above) you may customize the new OSM features:

M-x customize-group RET osm-maps RET

The most important feature is to adjust ist the caching behaviour. This is controlled by the variable osm-do-cache. If this variable is non-nil, the background tiles are downloaded and stored to disc for local use.

Downloading tiles might take some time for bigger areas. The tiles needed to cover my training area use 26 MB disc space (zoom-level 15).

Producing the images without caching is a bit faster, but you will need to be online when browsing the results.

What do the links look like?

A link to a track looks like this:

[[track:((9.707032442092896 52.37033874553582)(9.711474180221558 52.375238282987))FILENAME.svg][DESCRIPTION]]
               ^^^               ^^^
            longitude          latitude

…or this (filename first):

[[track:FILENAME.svg((9.707032442092896 52.37033874553582)(9.711474180221558 52.375238282987))][DESCRIPTION]]

Negative latitudes are on the southern hemisphere.

Once you click the link, an image is created for you and shown in a new buffer by default. You may provide a custom funciton to show the images. See the docs for the custom variable `osm-org-image-viewer-function’ in org-osm-link.el (C-h v osm-org-i TAB RET). The docstring provides several proposals, one of which you might find useful.

How to insert track links easily

There are two ways to insert links appart from adding them by hand.

1. M-x osm-org-compose-link asks for the list of coords, the filename and the link description and inserts the link at point.
2. M-x osm-org-gpx-to-links asks for a gpx file to read and inserts all the tracks found in that file interactively as seperate links.

Can I export osm-org track: links to GPX?

Yes. From within Emacs use

M-X osm-org-track-links-to-gpx

which works on the track: link at point or the next link found. If a region is active, export all track: links found in there to a single GPX file.

From the command line, use org-track-extract.pl like this:

perl org-track-extract.pl -f gpx path-to-file.org

Will extract all track: links in path-to-file.org and write a complete GPX file to stdout.

For more information try

perl org-track-extract.pl -h

Can I publish the maps with HTML?

Yes. See the docs for `osm-publish-map-for-html’ in org-osm-link.el (C-h f osm-pu TAB RET).

This is my publishing setup. Well - the short version :)

(setq org-publish-project-alist
      '(
        ;; Publishes the HTML pages.
        ;; ... and generate missing SVG images for all track: links found
        ;; and download missing background tiles to your cache directory.
        ("org-notes"
         :base-directory "~/org/notes/"
         :recursive t
         :base-extension "org"
         :publishing-directory "~/public_html/org-notes/"
         :publishing-function org-html-publish-to-html
         :exclude "OSM"
         )

        ;; Publish the tracks.
        ("org-osm-maps"
         :base-directory "~/org/notes/tracks/"
         :publishing-directory "~/public_html/tracks/"
         :recursive t
         :base-extension "svg"
         :osm-cache-directory "~/org/notes/img/OSM/"
         ;; Use `osm-publish-map-for-html':
         :publishing-function osm-publish-map-for-html
         )

        ;; More componets ...

        ("org" :components ("org-notes" "org-osm-maps" "... more components"))))

Caveats

Crashes caused by looong lines in tooltips

Did not see this bug for long time now. But Emacs used to crash every now and so often when I moved the mouse over a track link. This was caused by those very long lines in tooltips when hovering a track: link. You can avoid tooltips per file by adding these lines to the end of your training diaries:

# Local Variables:
# eval: (tooltip-mode -1)
# End: