path: root/README.org

#+title: osm.el - OpenStreetMap viewer for Emacs
#+author: Daniel Mendler
#+language: en
#+export_file_name: osm.texi
#+texinfo_dir_category: Emacs misc features
#+texinfo_dir_title: Osm: (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="https://elpa.gnu.org/packages/osm.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/osm.svg"/></a>
#+html: <a href="https://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>
#+html: <img src="https://github.com/minad/osm/blob/screenshots/osm.png?raw=true"/><p><i>The map data is © <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors, licensed under the <a href="https://opendatacommons.org/licenses/odbl/">ODbL</a></i></p>

Osm.el is a tile-based map viewer, with a responsive movable and zoomable
display. The map can be controlled with the keyboard or with the mouse. The
viewer fetches the map tiles in parallel from tile servers via the =curl= program.
The package comes with a list of multiple preconfigured tile servers. You can
bookmark your favorite locations using regular Emacs bookmarks or create links
from Org files to locations. Furthermore the package provides commands to search
for locations by name and to open and display GPX tracks.

#+toc: headlines 8

* Features

- Responsive, zoomable and movable map display
- Display of tracks and POIs from GPX file
- Parallel fetching of tiles with curl
- Moving in large and small steps
- Mouse support (dragging, clicking, menu)
- Map scale indicator
- Distance measurement
- Go to coordinate
- Search for location by name
- Save Geo URL, Org link or Elisp link
- Open Geo, Google Maps or OpenStreetMap URLs
- Bookmarked positions with pins
- Multiple preconfigured tile servers

* Configuration

The package is available on GNU ELPA and can be installed with =package-install=.
Note that Osm.el requires Emacs 29 and depends on the external =curl= program.
Emacs must be built with =libxml=, =librsvg=, =libjpeg=, =libpng= and =libwebp= support.
Emacs 30 comes with a native JSON parser, while on Emacs 29, =libjansson= is
needed. The following is an example configuration which relies on =use-package=.
Please take a look at the [[https://github.com/minad/osm/wiki][wiki]] for additional tile server configurations, e.g.,
Google Maps for satellite and aerial maps.

#+begin_src emacs-lisp
(use-package osm
  :bind ("C-c m" . osm-prefix-map) ;; Alternatives: `osm-home' or `osm'

  :custom
  ;; Take a look at the customization group `osm' for more options.
  (osm-server 'default) ;; Configure the tile server
  (osm-copyright t)     ;; Display the copyright information

  :config

  ;; Add custom servers, see also https://github.com/minad/osm/wiki
  ;; (osm-add-server 'myserver
  ;;   :name "My tile server"
  ;;   :group "Custom"
  ;;   :description "Tiles based on aerial images"
  ;;   :url "https://myserver/tiles/%z/%x/%y.png?apikey=%k")
)
#+end_src

* Bookmarks, Org links, Geo urls and Elisp links

There exist multiple methods to store a location, such that you can return there
afterwards.

- ~b~: Create a bookmark of the current location. The bookmark is stored as an
  Emacs bookmark in =bookmark-alist=. You can jump to the bookmark via the
  completion commands =osm-bookmark-jump= or =bookmark-jump=.
- ~l~: Store an Org link to the current location. The link can be inserted
  subsequently into an Org buffer with ~C-c C-l~.
- ~u~: Save the geo url of the current location in the kill ring. The url can be
  inserted in another buffer via ~C-y~. A geo url has the form
  ~geo:27.96,86.89;z=13~.
- ~C-u u~: Save an Elisp link to the current location in the kill ring. An Elisp
  link has the form ~(osm 51.49 -0.14 11)~.

Bookmarks and Org links can be created at point by clicking with the mouse. See
the docstrings of the commands ~osm-bookmark-set~ and ~org-link-store~.

**** Org link examples

Click on a link or press ~RET~ to jump to the location. These links work in Org
buffers in Emacs. Furthermore you can open Org links in arbitrary buffers with
~org-open-at-point-global~. I recommend binding the command to a convenient key,
e.g., ~C-c o~. The format of the links complies with the [[https://en.wikipedia.org/wiki/Geo_URI_scheme][geo URI scheme]] defined by
[[https://datatracker.ietf.org/doc/html/rfc5870][RFC 5870]].

#+begin_example
  [[geo:41.869560826994544,12.45849609375;z=6][Italia, 41.87° 12.46°]]
  [[geo:51.48950698022105,-0.144195556640625;z=11][London, England, 51.49° -0.14°]]
  [[geo:55.686875255964424,12.569732666015625;z=12;s=cyclosm][København, Danmark, 55.69° 12.57° CyclOSM]]
  [[geo:27.961656050984658,86.89224243164062;z=13][Mount Everest, 27.96° 86.89°]]
#+end_example

**** Elisp link examples

Place the point behind the closing parenthesis and press ~C-x C-e~ to jump to the
location. The Elisp links can be used in arbitrary text files. Since they are
Elisp s-expressions they can be easily manipulated programatically.

#+begin_src emacs-lisp
  (osm 41.869561 12.458496 6 "Lazio, Italia")
  (osm 51.489507 -0.144196 11 "London, Greater London, England, SW1A 2DX, United Kingdom")
  (osm 55.686875 12.569733 12 'cyclosm "København, Københavns Kommune, Region Hovedstaden, 1357, Danmark")
  (osm 27.961656 86.892242 13 "Khumjung, Khumbupasanglahmu, सोलुखुम्बु, Province #1, Nepal")
  (osm "Tour Eiffel, Av. Gustave Eiffel, Paris") ;; Address link
#+end_src

* Distance measurement

Osm provides a simple distance measurement utility. In order to measure a
distance, place or select a pin by clicking with the left mouse button. Then
create one or more additional way points by pressing shift and clicking the left
mouse button. The length of the track will be shown in the echo area. You can
select the way points of the track and delete them with ~d~ or ~DEL~.

* Commands and Key Bindings

Top-level commands in =osm-prefix-map=. These bindings are available globally if
you bind =osm-prefix-map= to a key like =C-c m=. For example, to search for a
location press the key sequence =C-c m s=. Furthermore the key bindings are
available in Osm buffers. There it is sufficient to press the key =s= only to
initiate a search.

- ~h~: =osm-home= - Open new map at home coordinates
- ~s~: =osm-search= - Search and jump to location
- ~r~: =osm-route= - Search for a route between two locations
- ~t~: =osm-goto= - Go to coordinates
- ~u~: =osm-url= - Go to Geo URL, OpenStreetMap.org or Google Maps URL.
- ~v~: =osm-server= - Select server
- ~j~: =osm-jump= - Jump to pin (bookmark or POI)
- ~f~: =osm-open= - Open GPX file in map viewer

Some additional key bindings are available in Osm buffers:

- ~<arrow>~: Small step scrolling
- ~C-<arrow>~, ~M-<arrow>~, ~S-<arrow>~: Large step scrolling
- ~+~, ~SPC~: =osm-zoom-in= - Zoom in
- ~-~, ~S-SPC~: =osm-zoom-out= - Zoom out
- ~<mouse-1>~: =osm-mouse-pin= - Place pin at point
- ~<mouse-2>~: =org-link-store= - Store point as Org link
- ~<mouse-3>~: =osm-bookmark-set= - Store point as bookmark
- ~S-<mouse-1>~: =osm-mouse-track= - Create track pin to measure distance
- ~<down-mouse-*>~: =osm-mouse-drag= - Drag the map with the mouse
- ~d~, ~DEL~: =osm-delete= - Delete selected pin (bookmark or way point)
- ~n~: =osm-rename= - Rename selected pin
- ~c~: =osm-center= - Center to currently selected pin
- ~F~, ~R~: =osm-hide= - Hide GPX file or route
- ~l~: =org-store-link= - Store Org link
- ~u~: =osm-save-url= - Save geo url in the kill ring
- ~b~: =osm-bookmark-set= - Set bookmark
- ~q~: =quit-window= - Close buffer and window
- ~o~: =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
- https://github.com/emacsattic/org-osm-link

* Contributions

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