-
Notifications
You must be signed in to change notification settings - Fork 16
/
README.Rmd
235 lines (175 loc) · 9.7 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
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include=FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
out.width = "100%"
)
library(tibble)
```
# rstac <img src="inst/extdata/img/logo.png" align="right" width="120"/>
R Client Library for SpatioTemporal Asset Catalog (rstac)
<!-- badges: start -->
[](https://github.com/brazil-data-cube/rstac/blob/master/LICENSE)
<!-- [](https://drone.dpi.inpe.br/brazil-data-cube/rstac) -->
[](https://github.com/brazil-data-cube/rstac/actions/workflows/R-CMD-check.yaml)
[](https://ci.appveyor.com/project/OldLipe/rstac)
[](https://app.codecov.io/gh/brazil-data-cube/rstac)
[](https://lifecycle.r-lib.org/articles/stages.html)
[](https://cran.r-project.org/package=rstac)
[](https://github.com/radiantearth/stac-api-spec)
[](https://discord.com/channels/689541907621085198#)
<!-- badges: end -->
STAC is a specification of files and web services used to describe geospatial
information assets. The specification can be consulted in [https://stacspec.org/](https://stacspec.org/).
R client library for STAC (`rstac`) was designed to fully support STAC API v1.0.0.
It also supports earlier versions (>= v0.8.0).
## Installation
```{R install, eval=FALSE}
# install via CRAN
install.packages("rstac")
```
### Development version
To install the development version of `rstac`, run the following commands
```{R install-dev, eval=FALSE}
remotes::install_github("brazil-data-cube/rstac")
```
Importing `rstac` package:
```{r load, echo=TRUE, message=FALSE, warning=FALSE}
library(rstac)
```
## Usage
`rstac` implements the following STAC endpoints:
```{R endpoints, echo=FALSE}
tibble::tribble(
~"**STAC** endpoints", ~"`rstac` functions", ~"API version",
"`/`", "`stac()`", ">= 0.9.0",
"`/stac`", "`stac()`", "< 0.9.0",
"`/collections`", "`collections()`", ">= 0.9.0",
"`/collections/{collectionId}`", "`collections(collection_id)`", ">= 0.9.0",
"`/collections/{collectionId}/items`", "`items()`", ">= 0.9.0",
"`/collections/{collectionId}/items/{itemId}`", "`items(feature_id)`", ">= 0.9.0",
"`/search`", "`stac_search()`", ">= 0.9.0",
"`/stac/search`", "`stac_search()`", "< 0.9.0",
"`/conformance`", "`conformance()`", ">= 0.9.0",
"`/collections/{collectionId}/queryables`", "`queryables()`", ">= 1.0.0"
) %>% as.data.frame() %>% knitr::kable(format = "markdown")
```
These functions can be used to retrieve information from a STAC API service.
The code below creates a `stac` object and list the available collections of
the STAC API of the [Brazil Data Cube](http://www.brazildatacube.org/en/home-page-2/) project of
the Brazilian National Space Research Institute (INPE).
```{R stac-obj, echo=TRUE}
s_obj <- stac("https://brazildatacube.dpi.inpe.br/stac/")
get_request(s_obj)
```
The variable `s_obj` stores information to connect to the Brazil Data
Cube STAC web service. The `get_request` method makes a HTTP GET connection
to it and retrieves a STAC Catalog document from the server. Each `links`
entry is an available collection that can be accessed via STAC API.
In the code below, we get some STAC items of `CB4-16D-2` collection that
intersects the bounding box passed to the `bbox` parameter. To do this, we
call the `stac_search` function that implements the STAC `/search`
endpoint. The returned document is a STAC Item Collection (a geojson
containing a feature collection).
```{R bdc-items1, echo=TRUE}
it_obj <- s_obj %>%
stac_search(collections = "CB4-16D-2",
bbox = c(-47.02148, -17.35063, -42.53906, -12.98314),
limit = 100) %>%
get_request()
it_obj
```
The `rstac` uses the [httr](https://github.com/r-lib/httr) package to manage
HTTP requests, allowing the use of tokens from the authorization protocols OAuth
1.0 or 2.0 as well as other configuration options. In the code below, we present
an example of how to pass a parameter token on a HTTP request.
```{R bdc-items2, eval=FALSE}
it_obj <- s_obj %>%
stac_search(collections = "CB4-16D-2",
bbox = c(-47.02148, -17.35063, -42.53906, -12.98314)) %>%
get_request(add_headers("x-api-key" = "MY-TOKEN"))
```
In addition to the functions mentioned above, the `rstac` package provides some
extra functions for handling items and to bulk download the assets.
### Items functions
`rstac` provides some functions that facilitates the interaction with STAC data.
In the example below, we get how many items matched the search criteria:
```{R bdc-items3, echo=TRUE}
# it_obj variable from the last code example
it_obj %>%
items_matched()
```
However, if we count how many items there are in `it_obj` variable, we get `10`,
meaning that more items could be fetched from the STAC service:
```{R bdc-items4, echo=TRUE}
it_obj %>%
items_length()
```
```{R bdc-items5, echo=TRUE}
# fetch all items from server
# (but don't stored them back in it_obj)
it_obj <- it_obj %>%
items_fetch(progress = FALSE)
it_obj %>%
items_length()
```
### Download assets
All we've got in previous example was metadata to STAC Items, including
links to geospatial data called `assets`. To download all `assets` in a
STAC Item Collection we can use `assets_download()` function, that returns
an update STAC Item Collection referring to the downloaded assets. The code
below downloads the `thumbnail` assets (.png files) of `10` items stored in
`it_obj` variable.
```{R download, eval=FALSE}
download_items <- it_obj %>%
assets_download(assets_name = "thumbnail", items_max = 10)
```
### CQL2 query filter
`rstac` also supports advanced query filter using common query language (CQL2).
Users can write complex filter expressions using R code in an easy and
natural way. For a complete
```{R cql2, echo=TRUE}
s_obj <- stac("https://planetarycomputer.microsoft.com/api/stac/v1")
it_obj <- s_obj %>%
ext_filter(
collection == "sentinel-2-l2a" && `s2:vegetation_percentage` >= 50 &&
`eo:cloud_cover` <= 10 && `s2:mgrs_tile` == "20LKP" &&
anyinteracts(datetime, interval("2020-06-01", "2020-09-30"))
) %>%
post_request()
```
## Getting help
You can get a full explanation about each STAC (v1.0.0) endpoint at [STAC API spec](https://github.com/radiantearth/stac-api-spec/tree/master/ogcapi-features). A detailed
documentation with examples on how to use each endpoint and other functions
available in the `rstac` package can be obtained by typing `?rstac` in R
console.
## Citation
To cite rstac in publications use:
R. Simoes, F. C. de Souza, M. Zaglia, G. R. de Queiroz, R. D. C. dos Santos
and K. R. Ferreira, "Rstac: An R Package to Access Spatiotemporal Asset
Catalog Satellite Imagery," 2021 IEEE International Geoscience and Remote
Sensing Symposium IGARSS, 2021, pp. 7674-7677, doi:
10.1109/IGARSS47720.2021.9553518.
## Acknowledgements for financial support
We acknowledge and thank the project funders that provided financial and material support:
- Amazon Fund, established by the Brazilian government with financial contribution from Norway, through the project contract between the Brazilian Development Bank (BNDES) and the Foundation for Science, Technology and Space Applications (FUNCATE), for the establishment of the Brazil Data Cube, process 17.2.0536.1.
- Radiant Earth Foundation and STAC Project Steering Committee for the advance of STAC ecosystem programme.
- OpenGeoHub Foundation and the European Commission (EC) through the project Open-Earth-Monitor Cyberinfrastructure: Environmental information to support EU’s Green Deal (1 Jun. 2022 – 31 May 2026 - 101059548)
## How to contribute?
The `rstac` package was implemented based on an extensible architecture, so
feel free to contribute by implementing new STAC API
[extensions/fragments](https://github.com/radiantearth/stac-api-spec/tree/master/fragments)
based on the STAC API specifications.
1. Make a project
[fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo).
2. Create a file inside the `R/` directory called `ext_{extension_name}.R`.
3. In the code, you need to specify a subclass name (e.g.`my_subclass`) for
your extension and use it when calling [`rstac_query()`](https://github.com/brazil-data-cube/rstac/blob/master/R/query-funs.R) function. You also need to implement for your subclass the following S3 generic functions: [`before_request()`](https://github.com/brazil-data-cube/rstac/blob/master/R/extensions.R), [`after_response()`](https://github.com/brazil-data-cube/rstac/blob/master/R/extensions.R), and [`parse_params()`](https://github.com/brazil-data-cube/rstac/blob/master/R/extensions.R). With these S3 generics methods you
can define how parameters should be submitted to the HTTP request and the types
of the returned documents. See the implemented [ext_filter](https://github.com/brazil-data-cube/rstac/blob/master/R/ext_filter.R)
API extension as an example.
4. Make a [Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) on the most recent [development branch](https://github.com/brazil-data-cube/rstac/).