osmplotr

Data visualisation using OpenStreetMap objects

https://github.com/ropensci/osmplotr

Keywords

Keywords from Contributors

Repository

Data visualisation using OpenStreetMap objects

README.Rmd

---
title: "osmplotr, an R package for making maps with OpenStreetMap data"
keywords: "open street map, openstreetmap, OSM, map, visualisation, visualization"
output:
  rmarkdown::html_vignette:
    self_contained: no

  md_document:
    variant: markdown_github
---



```{r opts, echo = FALSE}
knitr::opts_chunk$set (
    collapse = TRUE,
    warning = TRUE,
    message = TRUE,
    width = 120,
    comment = "#>",
    fig.retina = 2,
    fig.path = "README-"
)
```

[![R build
status](https://github.com/ropensci/osmplotr/workflows/R-CMD-check/badge.svg)](https://github.com/ropensci/osmplotr/actions?query=workflow%3AR-CMD-check)
[![codecov](https://app.codecov.io/gh/ropensci/osmplotr/branch/master/graph/badge.svg)](https://app.codecov.io/gh/ropensci/osmplotr)
[![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/)

![](man/figures/map1.png)

[![CRAN Downloads](https://cranlogs.r-pkg.org/badges/grand-total/osmplotr?color=orange)](https://cran.r-project.org/package=osmplotr/)
[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/osmplotr)](https://cran.r-project.org/package=osmplotr/)
[![](https://badges.ropensci.org/27_status.svg)](https://github.com/ropensci/software-review/issues/27)

R package to produce visually impressive customisable images of OpenStreetMap
(OSM) data downloaded internally from the 
[overpass api](http://overpass-api.de/). The above map was produced directly
from `osmplotr` with no further modification. This `README` briefly demonstrates
the following functionality:

[1. Quick Introduction](#1 intro)

[2. Installation](#2 installation)

[3. A Simple Map](#3 simple map)

[4. Highlighting Selected Areas](#4 highlighting areas)

[5. Highlighting Clusters](#5 highlighting clusters)

[6. Highlighting Areas Bounded by Named Highways](#6 highlighting with highways)

[7. Data Surfaces](#7 data surfaces)

[8. Gallery](#8 gallery)

---------------

## 1. Quick Introduction

But first the easy steps to map making:
```{r, echo = FALSE, message = FALSE, eval = TRUE}
library (osmplotr)
```


1. Specify the bounding box for the desired region
    ```{r}
    bbox <- get_bbox (c (-0.15, 51.5, -0.10, 51.52))
    ```
2. Download the desired data---in this case, all building perimeters.
    ```{r, eval = FALSE}
    dat_B <- extract_osm_objects (key = "building", bbox = bbox)
    ```
3. Initiate an `osm_basemap` with desired background (`bg`) colour
    ```{r map1, eval = FALSE}
    map <- osm_basemap (bbox = bbox, bg = "gray20")
    ```
4. Overlay objects on plot in the desired colour.
    ```{r, eval = FALSE}
    map <- add_osm_objects (map, dat_B, col = "gray40")
    ```
5. Print the map to graphics device of choice
    ```{r, eval = FALSE}
    print_osm_map (map)
    ```

```{r london2, echo = FALSE, eval = FALSE}
library (osmdata)
bbox <- get_bbox (c (-0.15, 51.5, -0.10, 51.52))
q0 <- opq (bbox)
q1 <- add_osm_feature (q0, key = "building")
dat_B <- osmdata_sf (q1, quiet = FALSE)$osm_polygons
q1 <- add_osm_feature (q0, key = "highway")
dat_H <- osmdata_sf (q1, quiet = FALSE)$osm_lines
q1 <- add_osm_feature (q0, key = "leisure", value = "park")
dat_P <- osmdata_sf (q1, quiet = FALSE)$osm_polygons
q1 <- add_osm_feature (q0, key = "landuse", value = "grass")
dat_G <- osmdata_sf (q1, quiet = FALSE)$osm_polygons
london2 <- list (dat_B = dat_B, dat_H = dat_H, dat_P = dat_P, dat_G = dat_G)
save (london2, file = "london2.rda")
```

---------------

## 2. Installation

First install the package
```{r, eval = FALSE}
install.packages ("osmplotr")
```
or the development version
```{r, eval = FALSE}
devtools::install_github ("ropensci/osmplotr")
```
And then load it in the usual way
```{r, eval = FALSE}
library (osmplotr)
```

---------------

## 3. A Simple Map

Simple maps can be made by overlaying different kinds of OSM data in different
colours:
```{r, eval = FALSE}
dat_H <- extract_osm_objects (key = "highway", bbox = bbox)
dat_P <- extract_osm_objects (key = "park", bbox = bbox)
dat_G <- extract_osm_objects (key = "landuse", value = "grass", bbox = bbox)
```
```{r, echo = FALSE, eval = FALSE}
load ("london2.rda")
dat_B <- london2$dat_B
dat_H <- london2$dat_H
dat_G <- london2$dat_G
dat_P <- london2$dat_P
```
```{r map2, eval = FALSE}
map <- osm_basemap (bbox = bbox, bg = "gray20")
map <- add_osm_objects (map, dat_B, col = "gray40")
map <- add_osm_objects (map, dat_H, col = "gray80")
map <- add_osm_objects (map, dat_P, col = "darkseagreen")
map <- add_osm_objects (map, dat_G, col = "darkseagreen1")
print_osm_map (map)
```
```{r map2-print, eval = FALSE, echo = FALSE}
print_osm_map (map, file = "map2.png", width = 600, units = "px", dpi = 72)
```




---------------

## 4. Highlighting Selected Areas

`osmplotr` is primarily intended as a data visualisation tool, particularly
through enabling selected regions to be highlighted. Regions can be defined
according to simple point boundaries:

```{r}
pts <- sp::SpatialPoints (cbind (
    c (-0.115, -0.13, -0.13, -0.115),
    c (51.505, 51.505, 51.515, 51.515)
))
```
OSM objects within the defined regions can then be highlighted with different
colour schemes. `cols` defines colours for each group (with only one here),
while `bg` defines the colour of the remaining, background area.
```{r map3, eval = FALSE}
map <- osm_basemap (bbox = bbox, bg = "gray20")
map <- add_osm_groups (map, dat_B, groups = pts, cols = "orange", bg = "gray40")
map <- add_osm_objects (map, london$dat_P, col = "darkseagreen1")
map <- add_osm_groups (
    map,
    london$dat_P,
    groups = pts,
    cols = "darkseagreen1",
    bg = "darkseagreen",
    boundary = 0
)
print_osm_map (map)
```
```{r map3-print, eval = FALSE, echo = FALSE}
print_osm_map (map, filename = "map3.png", width = 600, units = "px", dpi = 72)
```



Note the `border = 0` argument on the last call divides the park polygons
precisely along the border. The same map highlighted in dark-on-light:
```{r map4, eval = FALSE}
map <- osm_basemap (bbox = bbox, bg = "gray95")
map <- add_osm_groups (map, dat_B, groups = pts, cols = "gray40", bg = "gray85")
map <- add_osm_groups (map, dat_H, groups = pts, cols = "gray20", bg = "gray70")
print_osm_map (map)
```
```{r map4-print, eval = FALSE, echo = FALSE}
print_osm_map (map, filename = "map4.png", width = 600, units = "px", dpi = 72)
```



---------------

## 5. Highlighting Clusters

`add_osm_groups` also enables plotting an entire region as a group of
spatially distinct clusters of defined colours. Groups can be defined by simple
spatial points denoting their centres:

```{r, echo = TRUE}
set.seed (2)
ngroups <- 12
x <- bbox [1, 1] + runif (ngroups) * diff (bbox [1, ])
y <- bbox [2, 1] + runif (ngroups) * diff (bbox [2, ])
groups <- cbind (x, y)
groups <- apply (groups, 1, function (i) {
    sp::SpatialPoints (matrix (i, nrow = 1, ncol = 2))
})
```
Calling `add_osm_groups` with no `bg` argument forces all points lying outside
those defined groups to be allocated to the nearest groups, and thus produces an
inclusive grouping extending across an entire region.

```{r map5, eval = FALSE}
map <- osm_basemap (bbox = bbox, bg = "gray20")
map <- add_osm_groups (
    map,
    dat_B,
    groups = groups,
    cols = rainbow (length (groups)),
    border_width = 2
)
print_osm_map (map)
```
```{r map5-print, eval = FALSE, echo = FALSE}
print_osm_map (map, filename = "map5.png", width = 600, units = "px", dpi = 72)
```



---------------

## 6. Highlighting Areas Bounded by Named Highways

An alternative way of defining highlighted groups is by naming the highways
encircling desired regions.
```{r, eval = FALSE}
# These highways extend beyond the previous, smaller bbox
bbox_big <- get_bbox (c (-0.15, 51.5, -0.10, 51.52))
highways <- c (
    "Davies.St", "Berkeley.Sq", "Berkeley.St", "Piccadilly",
    "Regent.St", "Oxford.St"
)
highways1 <- connect_highways (highways = highways, bbox = bbox_big)
highways <- c ("Regent.St", "Oxford.St", "Shaftesbury")
highways2 <- connect_highways (highways = highways, bbox = bbox_big)
highways <- c (
    "Piccadilly", "Shaftesbury.Ave", "Charing.Cross.R",
    "Saint.Martin", "Trafalgar.Sq", "Cockspur.St",
    "Pall.Mall", "St.James"
)
highways3 <- connect_highways (highways = highways, bbox = bbox_big)
highways <- c (
    "Charing.Cross", "Duncannon.St", "Strand", "Aldwych",
    "Kingsway", "High.Holborn", "Shaftesbury.Ave"
)
highways4 <- connect_highways (highways = highways, bbox = bbox_big)
highways <- c (
    "Kingsway", "Holborn", "Farringdon.St", "Strand",
    "Fleet.St", "Aldwych"
)
highways5 <- connect_highways (highways = highways, bbox = bbox_big)
groups <- list (highways1, highways2, highways3, highways4, highways5)
```
And then passing these lists of groups returned by `connect_highways` to
`add_osm_groups`, this time with some Wes Anderson flair.
```{r map 6, eval = FALSE}
map <- osm_basemap (bbox = bbox, bg = "gray20")
library (wesanderson)
cols <- wes_palette ("Darjeeling", 5)
map <- add_osm_groups (
    map,
    dat_B,
    groups = groups,
    boundary = 1,
    cols = cols,
    bg = "gray40",
    colmat = FALSE
)
map <- add_osm_groups (
    map,
    dat_H,
    groups = groups,
    boundary = 0,
    cols = cols,
    bg = "gray70",
    colmat = FALSE
)
print_osm_map (map)
```
```{r map6-print, eval = FALSE, echo = FALSE}
print_osm_map (map, filename = "map6.png", width = 600, units = "px", dpi = 72)
```




---------------

## 7. Data Surfaces

Finally, `osmplotr` contains a function `add_osm_surface` that spatially
interpolates a given set of spatial data points and colours OSM objects
according to a specified colour gradient. This is illustrated here with the
`volcano` data projected onto the `bbox`.
```{r}
x <- seq (bbox [1, 1], bbox [1, 2], length.out = dim (volcano) [1])
y <- seq (bbox [2, 1], bbox [2, 2], length.out = dim (volcano) [2])
xy <- cbind (rep (x, dim (volcano) [2]), rep (y, each = dim (volcano) [1]))
z <- as.numeric (volcano)
dat <- data.frame (x = xy [, 1], y = xy [, 2], z = z)
```
```{r map7, eval = FALSE}
map <- osm_basemap (bbox = bbox, bg = "gray20")
cols <- gray (0:50 / 50)
map <- add_osm_surface (map, dat_B, dat = dat, cols = cols)
# Darken cols by ~20%
map <- add_osm_surface (
    map,
    dat_H,
    dat = dat,
    cols = adjust_colours (cols, -0.2)
)
map <- add_colourbar (map, cols = cols, zlims = range (volcano))
map <- add_axes (map)
print_osm_map (map)
```
```{r map7-print, eval = FALSE, echo = FALSE}
print_osm_map (map, filename = "map7.png", width = 600, units = "px", dpi = 72)
```

```{r map1-print, eval = FALSE, echo = FALSE}
# This is map1 used as the title
# extrafont::loadfonts ()
lab_dat <- data.frame (
    x = mean (bbox [1, ]), y = mean (bbox [2, ]),
    lab = "osmplotr"
)
aes <- ggplot2::aes (x, y, label = lab)

bbox <- get_bbox (c (-0.15, 51.5, -0.10, 51.52))
map <- osm_basemap (bbox = bbox, bg = "gray20")
cols <- gray (0:50 / 50)
map <- add_osm_surface (map, dat_B, dat = dat, cols = cols)
map <- add_osm_surface (
    map,
    dat_H,
    dat = dat,
    cols = adjust_colours (cols, -0.2)
)

# map2 <- map + ggplot2::geom_text (dat = dat, mapping = aes, size = 60,
#                                  colour = "white",
#                                 family = "Lato Light", nudge_y = 0.0015)
map2 <- map + ggplot2::geom_text (
    dat = lab_dat, mapping = aes, size = 45,
    colour = "black",
    family = "Purisa", fontface = 2,
    nudge_y = 0.0005, nudge_x = 0.0005
)
map2 <- map2 + ggplot2::geom_text (
    dat = lab_dat, mapping = aes, size = 45,
    colour = "white", family = "Purisa",
    nudge_y = 0.001, fontface = 2
)
print_osm_map (map2,
    filename = "map1.png", width = 800, units = "px",
    dpi = 72
)
```



---------------

## 8. Gallery

Got a nice `osmplotr` map? Please contribute in one of the following ways:

1. Fork repo, add link to `README.md/.Rmd`, and send pull request; or

2. Open issue with details; or

3. Send email to address in
   [`DESCRIPTION`](https://github.com/ropensci/osmplotr/blob/master/DESCRIPTION).

---------------

See package vignettes 
([basic maps](https://docs.ropensci.org/osmplotr/articles/basic-maps.html) and
[data maps](https://docs.ropensci.org/osmplotr/articles/data-maps.html)) for a
lot more detail and further capabilities of `osmplotr`.  Please note that this
project is released with a [Contributor Code of
Conduct](https://ropensci.org/code-of-conduct/). By participating in this
project you agree to abide by its terms.

--------------

[![ropensci\_footer](https://ropensci.org//public_images/github_footer.png)](https://ropensci.org/)

Owner

CodeMeta (codemeta.json)

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "osmplotr",
  "description": "Bespoke images of 'OpenStreetMap' ('OSM') data and data visualisation using 'OSM' objects.",
  "name": "osmplotr: Bespoke Images of 'OpenStreetMap' Data",
  "relatedLink": "https://docs.ropensci.org/osmplotr/",
  "codeRepository": "https://github.com/ropensci/osmplotr",
  "issueTracker": "https://github.com/ropensci/osmplotr/issues",
  "license": "https://spdx.org/licenses/GPL-3.0",
  "version": "0.3.5.032",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.5.1 (2025-06-13)",
  "author": [
    {
      "@type": "Person",
      "givenName": "Mark",
      "familyName": "Padgham",
      "email": "mark.padgham@email.com"
    },
    {
      "@type": "Person",
      "givenName": "Richard",
      "familyName": "Beare"
    }
  ],
  "contributor": [
    {
      "@type": "Person",
      "givenName": "Finkelstein",
      "familyName": "Noam"
    },
    {
      "@type": "Person",
      "givenName": "Bartnik",
      "familyName": "Lukasz"
    }
  ],
  "copyrightHolder": [
    {
      "@type": "Person",
      "givenName": "Finkelstein",
      "familyName": "Noam"
    },
    {
      "@type": "Person",
      "givenName": "Bartnik",
      "familyName": "Lukasz"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Mark",
      "familyName": "Padgham",
      "email": "mark.padgham@email.com"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "curl",
      "name": "curl",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=curl"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "geodist",
      "name": "geodist",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=geodist"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "magrittr",
      "name": "magrittr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=magrittr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "markdown",
      "name": "markdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=markdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "R",
      "name": "R",
      "version": ">= 3.2.3"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "e1071",
      "name": "e1071",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=e1071"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "ggm",
      "name": "ggm",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ggm"
    },
    "4": {
      "@type": "SoftwareApplication",
      "identifier": "ggplot2",
      "name": "ggplot2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ggplot2"
    },
    "5": {
      "@type": "SoftwareApplication",
      "identifier": "mapproj",
      "name": "mapproj",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=mapproj"
    },
    "6": {
      "@type": "SoftwareApplication",
      "identifier": "methods",
      "name": "methods"
    },
    "7": {
      "@type": "SoftwareApplication",
      "identifier": "osmdata",
      "name": "osmdata",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=osmdata"
    },
    "8": {
      "@type": "SoftwareApplication",
      "identifier": "sf",
      "name": "sf",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=sf"
    },
    "9": {
      "@type": "SoftwareApplication",
      "identifier": "sfheaders",
      "name": "sfheaders",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=sfheaders"
    },
    "10": {
      "@type": "SoftwareApplication",
      "identifier": "sp",
      "name": "sp",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=sp"
    },
    "11": {
      "@type": "SoftwareApplication",
      "identifier": "spatstat",
      "name": "spatstat",
      "version": ">= 2.0-0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=spatstat"
    },
    "12": {
      "@type": "SoftwareApplication",
      "identifier": "spatstat.explore",
      "name": "spatstat.explore",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=spatstat.explore"
    },
    "13": {
      "@type": "SoftwareApplication",
      "identifier": "spatstat.geom",
      "name": "spatstat.geom",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=spatstat.geom"
    },
    "SystemRequirements": {}
  },
  "fileSize": "3214.001KB",
  "releaseNotes": "https://github.com/ropensci/osmplotr/blob/main/NEWS.md",
  "readme": "https://github.com/ropensci/osmplotr/blob/main/README.md",
  "contIntegration": [
    "https://github.com/ropensci/osmplotr/actions?query=workflow%3AR-CMD-check",
    "https://app.codecov.io/gh/ropensci/osmplotr"
  ],
  "developmentStatus": "https://www.repostatus.org/",
  "review": {
    "@type": "Review",
    "url": "https://github.com/ropensci/software-review/issues/27",
    "provider": "https://ropensci.org"
  },
  "keywords": [
    "osm",
    "openstreetmap",
    "overpass-api",
    "overpass",
    "data-visualisation",
    "highlighting-clusters",
    "r",
    "rstats",
    "r-package",
    "peer-reviewed"
  ]
}

GitHub Events

Committers

Last synced: about 2 years ago

Issues and Pull Requests

Last synced: 6 months ago

Packages