-
Notifications
You must be signed in to change notification settings - Fork 11
/
Copy pathREADME.Rmd
147 lines (115 loc) · 5.27 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
knitr::knit_hooks$set(margin = function(before, options, envir) {
if (before) {
par(mar = c(0, 0, 0, 0))
}
})
```
# maptiles <img src="man/figures/logo.png" align="right" width="140"/>
<!-- badges: start -->
[](https://github.com/riatelab/maptiles/actions/workflows/check-standard.yaml)
[](https://app.codecov.io/gh/riatelab/maptiles?branch=main)
[](https://CRAN.R-project.org/package=maptiles)
[](https://www.repostatus.org/#active)
<!-- badges: end -->
To create maps from tiles, `maptiles` downloads, composes and displays tiles
from a large number of providers (e.g. OpenStreetMap, Stadia, Esri, CARTO, or
Thunderforest).
## Installation
You can install the released version of `maptiles` from [CRAN](https://CRAN.R-project.org/package=maptiles) with:
``` r
install.packages("maptiles")
```
You can install the development version of `maptiles` from GitHub with:
``` r
# install.packages("remotes")
remotes::install_github("riatelab/maptiles")
```
## Demo
This is a basic example which shows you how to dowload and display OpenStreetMap
tiles over North Carolina:
```{r example, fig.ext="png", margin = TRUE, fig.width=808/96, fig.height = 303/96, dpi = 96, fig.show='hide'}
library(sf)
library(maptiles)
# import North Carolina counties
nc_raw <- st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
# Project to EPSG:3857
nc <- st_transform(nc_raw, "EPSG:3857")
# dowload tiles and compose raster (SpatRaster)
nc_osm <- get_tiles(nc, crop = TRUE)
# display map
plot_tiles(nc_osm)
# add Norh Carolina counties
plot(st_geometry(nc), col = NA, add = TRUE)
# add credit
mtext(text = get_credit("OpenStreetMap"), side = 1, line = -1, adj = .99)
```
`maptiles` gives access to a lot of tiles servers, but it is possible to
add others. The following example demonstrates the setting of a map tiles server
and how to cache the original tiles for future use:
```{r example2,fig.ext="png", margin = TRUE, fig.width=1615/96, fig.height = 605/96, fig.show='hide', dpi = 96}
# define the tile server parameters
osmpos <- create_provider(
name = "CARTO.POSITRON",
url = "https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png",
sub = c("a", "b", "c", "d"),
citation = "© OpenStreetMap contributors © CARTO "
)
# dowload tiles and compose raster (SpatRaster)
nc_osmpos <- get_tiles(
x = nc, provider = osmpos, crop = TRUE,
cachedir = tempdir(), verbose = TRUE, retina = TRUE
)
# display map
plot_tiles(nc_osmpos)
# display credits
mtext(text = get_credit(osmpos), side = 1, line = -1, adj = .99)
```
The following figure shows mini maps for most of the tiles providers available:
## Projection
Original tiles use a projection known as "Web Mercator",
"WGS84 / Pseudo Mercator", "Google Mercator", "EPSG:3857" or "EPSG:900913".
In most cases `get_tiles()` uses the projection of its `x` argument to
reproject the tiles. If you wish to avoid any deformation induced by the
reprojection process, use "EPSG:3857" for `x` projection.
## Attribution of map tiles
All maps available through `maptiles` are offered freely by various providers.
The only counterpart from the user is to properly display an attribution text
on the maps.
`get_credit()` displays a short attribution text to add on each map
using the downloaded tiles.
## Alternatives
There are many alternative packages that pursue the same objective as
`maptiles`. Some focus on a specific map tiles provider (e.g. Mapbox, Google,
OpenStreetMap) or on a specific graphics device (`ggplot2`). The goal of `maptiles`
is to be flexible enough to allow the use of different providers and to have a
minimal number of robust and modern dependencies.
However, depending on the use case, one of following packages may better
suit your needs:
* [`ceramic`](https://github.com/hypertidy/ceramic)
* [`ggmap`](https://github.com/dkahle/ggmap) (`ggplot2` focused)
* [`ggspatial`](https://github.com/paleolimbot/ggspatial) (`ggplot2` focused, based on `rosm`)
* [`mapboxapi`](https://github.com/walkerke/mapboxapi) (mapbox)
* [`mapsapi`](https://github.com/michaeldorman/mapsapi/) (google, based on `RgoogleMaps`)
* [`OpenStreetMap`](https://github.com/ifellows/ROSM) (requires Java)
* [`RgoogleMaps`](https://github.com/markusloecher/rgooglemaps) (google)
* [`rosm`](https://github.com/paleolimbot/rosm)
* ...
## Note
Not to be confused with [`tilemaps`](https://github.com/kaerosen/tilemaps), that "implements an algorithm for generating maps, known as tile maps, in which each region is represented by a single tile of the same shape and size."