#+title: osm.el - OpenStreetMap viewer for Emacs
#+author: Daniel Mendler
#+language: en
#+export_file_name: osm.texi
#+texinfo_dir_category: Emacs
#+texinfo_dir_title: OpenStreetMap: (osm).
#+texinfo_dir_desc: OpenStreetMap viewer for Emacs

#+html: <a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true"/></a>
#+html: <a href="http://elpa.gnu.org/packages/osm.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/osm.svg"/></a>
#+html: <a href="http://elpa.gnu.org/devel/osm.html"><img alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/osm.svg"/></a>
#+html: <a href="https://melpa.org/#/osm"><img alt="MELPA" src="https://melpa.org/packages/osm-badge.svg"/></a>
#+html: <a href="https://stable.melpa.org/#/osm"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/osm-badge.svg"/></a>

[[https://github.com/minad/osm/blob/screenshots/osm.png?raw=true]]
(Map tiles © https://opentopomap.org,  https://openstreetmap.org)

* Features

- Parallel fetching of tiles with curl
- Scrolling in large and small steps
- Zooming
- Mouse support (dragging, clicking)
- Map scale indicator
- Jump to coordinate
- Search for location by name
- Org link support
- Bookmarked positions with pins
- Multiple preconfigured servers

* Configuration

#+begin_src emacs-lisp
  (use-package osm
    :bind (("C-c m h" . osm-home)
           ("C-c m s" . osm-search)
           ("C-c m t" . osm-server)
           ("C-c m g" . osm-goto)
           ("C-c m b" . osm-bookmark-jump))
    :init
    ;; Load Org link support
    (with-eval-after-load 'org
      (require 'osm-ol)))
#+end_src

* Bookmarks and Org links

To store a bookmark press the key ~b~, to store Org links press the key ~l~. You can
also use a custom binding, e.g., ~C-c l~. Then the link can be inserted into an Org
buffer with ~C-c C-l~. Bookmarks and Org links can be created at point with the
mouse, see ~osm-bookmark-set-click~ and ~osm-org-link-click~.

Examples:

- [[osm:opentopomap:41.869560826994544,12.45849609375,6][Italia, 41.87° 12.46° OpenTopoMap]]
- [[osm:51.48950698022105,-0.144195556640625,11][London, England, 51.49° -0.14°]]
- [[osm:cyclosm:55.686875255964424,12.569732666015625,12][København, Danmark, 55.69° 12.57° CyclOSM]]
- [[osm:stamen-watercolor:40.72956780913898,-73.97918701171875,12][New York, United States, 40.73° -73.98° Stamen Watercolor]]
- [[osm:opentopomap:27.961656050984658,86.89224243164062,13][Mount Everest, 27.96° 86.89° OpenTopoMap]]

* Commands and Key Bindings

Top-level commands:
- =osm-home=: Open new map at home coordinates
- =osm-search=: Search and jump to location
- =osm-goto=: Go to coordinates
- =osm-server=: Select server
- =osm-bookmark-jump=: Jump to bookmark

Key bindings in =osm-mode= buffer:
- ~<arrow>~: Small step scrolling
- ~C-<arrow>~, ~M-<arrow>~: Large step scrolling
- ~+~, ~SPC~: =osm-zoom-in= - Zoom in
- ~-~, ~S-SPC~: =osm-zoom-out= - Zoom out
- ~<mouse-1>~: =osm-zoom-click= - Zoom to point
- ~<mouse-2>~: =osm-org-link-click= - Store point as Org link
- ~<mouse-3>~: =osm-bookmark-set-click= - Store point as bookmark
- ~<S-mouse-3>~: =osm-bookmark-delete-click= - Delete bookmark at point
- ~<down-mouse-*>~: =osm-drag= - Drag the map with the mouse
- ~g~: =osm-goto= - Go to location
- ~h~: =osm-home= - Go to home location
- ~s~: =osm-search= - Search for location
- ~t~: =osm-server= - Select tile server
- ~l~: =org-store-link= - Store org link
- ~b~: =osm-bookmark-set= - Set bookmark
- ~B~: =osm-bookmark-jump= - Jump to bookmark
- ~q~: =quit-window= - Close buffer and window
- ~c~: =clone-buffer= - Clone buffer

* Related projects

There have been other attempts at map viewers in Emacs before.

- https://github.com/ruediger/osm-mode
- https://github.com/svenssonjoel/Emacs-OSM
- https://github.com/jd/google-maps.el

* Contributions

Since this package is part of [[http://elpa.gnu.org/packages/osm.html][GNU ELPA]] contributions require a copyright
assignment to the FSF.
