This repository is an homage to the programming language
R, open-source geographic data and the art of map making. It provides code and examples to render customizable stylized city maps using data from OpenStreetMap. Take a look at the tutorial for a quick guide on how to get started.
Every three hours this repository creates and tweets a view of a random city. You can find all city views created so far at the twitter handle
@rcityviews. Please do not hesitate to share your own creations using the hashtag
The functionality in this repository is implemented in the
rcityviews. This package is not available on CRAN but can be obtained via GitHub by running the command below in
# install.packages("remotes") # Uncomment if you do not have the 'remotes' package installed remotes::install_github("koenderks/rcityviews", dependencies = TRUE)
After installation, you can load the package into the
R session using the following command.
First, you can search for a city name in the package database using the
list_cities() function. This function looks in the internal database and finds any city name that contains the expression in
list_cities(match = "Ams") #> name country lat long #> 1356 Amstelveen The Netherlands 52.32 4.86 #> 1357 Amsterdam The Netherlands 52.37 4.89 #> 1358 Amstetten Austria 48.13 14.86 #> 25857 New Amsterdam Guyana 6.25 -57.53 #> 26031 Nieuw Amsterdam Suriname 5.91 -55.07
If you cannot find your preferred city in the internal package database, you can use the
new_city() function to manually specify a location using its latitude and longitude coordinates.
city <- new_city(name = "Lagos", country = "Portugal", lat = 37.10, long = -8.68) #> Discovered the city of Lagos, Portugal at 37.1° / -8.68°!
Second, once you have obtained the name of the city you want to view or have specified a location of a city, you can use the
cityview() function to create a
ggplot2 object. Use the
zoom argument to zoom in on your city (e.g.,
zoom > 1, decreases computation time) or zoom out of your city (e.g.,
zoom < 0.5, increases computation time).
p <- cityview(name = "Amsterdam", zoom = 1) # or cityview(name = city) # see ?cityview for more input parameters of this function
Finally, render times in
R or RStudio can be very long for crowded spatial images. It is therefore recommended to directly save the image in a
500mm x 500mm format. Typically, the ideal way to do this given a
ggplot2 object named
p is to execute the command below.
ggplot2::ggsave(filename = "Amsterdam.png", plot = p, height = 500, width = 500, units = "mm", dpi = 100)
However, you can also do this instantly by providing a filename directly to the
cityview() function via its
filename argument. To save rendering time, the image is exported in an appropriate size and the function does not return a
cityview(name = "Amsterdam", filename = "Amsterdam.png")
For personal (non-commercial) printing it is advised to use the option
license = FALSE and save the image to a
.svg file. Afterwards, the image is best printed in a
500mm x 500mm format.
There are ten pre-specified themes that can be used to style the image. The image above is created using
theme = "vintage" (the default), but other options for the
theme argument include
modern (top left),
bright (top middle),
delftware (top right),
comic (middle left),
rouge (middle middle),
original (middle right),
midearth (bottom left),
batik (bottom middle) and
vice (bottom right).
In addition to the ten pre-specified themes, the package provides full flexibility to customize the theme by providing a named list. This is demonstrated in the code block below.
# For example: black, beige and white theme, streets only myTheme <- list( colors = list( background = "#232323", water = NA, landuse = NA, contours = NA, streets = "#d7b174", rails = c("#d7b174", "#232323"), buildings = NA, text = "#ffffff", waterlines = NA ), font = list( family = "serif", face = "bold", scale = 1, append = "\u2014" ), size = list( borders = list( contours = 0.15, water = 0.4, canal = 0.5, river = 0.6 ), streets = list( path = 0.2, residential = 0.3, structure = 0.35, tertiary = 0.4, secondary = 0.5, primary = 0.6, motorway = 0.8, rails = 0.65, runway = 3 ) ) ) cityview(name = "Rio de Janeiro", zoom = 0.5, theme = myTheme, border = "square", filename = "Rio.png")
There are several types of borders that can be used to enclose the city. The image above is created using
border = "square", but other options for the
border argument include
none (the default),
There are three other arguments to the
cityview() function that can be used to tailor the image to your liking. First, the argument
halftone allows you to add a colored dotted dither to the image (e.g.,
halftone = "#ffffff", left). Second, setting
legend = TRUE adds a distance measurer and a compass to the image (middle). Third, the argument
places takes an integer and adds that amount of names of towns, villages, suburbs, quarters and neighbourhoods to the image (e.g.,
places = 10, right).
You can make your own images without having to code using an
R Shiny implementation of the package. A live version of the application can be found here but it is also easily accessible from within
R by calling the function
The data is available under the Open Database License.