forked from ranghetti/sen2r
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
184 lines (149 loc) · 10.4 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
---
output:
github_document:
toc: yes
toc_depth: 2
fig_caption: no
---
<!-- IMPORTANT: do NOT edit README.Rmd! Edit index.Rmd instead, -->
<!-- and generate README.Rmd using utils/code/create_README.sh -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
[](https://travis-ci.org/ranghetti/sen2r)
[](https://doi.org/10.5281/zenodo.1240384)
[](https://cran.r-project.org/package=sen2r)
[](http://www.gnu.org/licenses/gpl-3.0)
[](http://sen2r.ranghetti.info/CONDUCT.html)
<img src="man/figures/sen2r_logo_200px.png" width="200" height="113" align="right" />
# sen2r: Find, Download and Process Sentinel-2 Data
<span style="color:#5793dd;vertical-align:top;font-size:90%;font-weight:normal;">sen</span><span style="color:#6a7077;vertical-align:baseline;font-size:115%;font-weight:bolder;">2</span><span style="color:#2f66d5;vertical-align:baseline;font-size:90%;font-weight:bold;">r</span>
is an R library which helps to download and preprocess Sentinel-2 optical images.
The purpose of the functions contained in the library is to provide the instruments
required to easily perform (and eventually automate) all the steps necessary
to build a complete Sentinel-2 processing chain, without the need of any manual
intervention nor the needing to manually integrate any external tool.
In particular,
<span style="color:#5793dd;vertical-align:top;font-size:90%;font-weight:normal;">sen</span><span style="color:#6a7077;vertical-align:baseline;font-size:115%;font-weight:bolder;">2</span><span style="color:#2f66d5;vertical-align:baseline;font-size:90%;font-weight:bold;">r</span>
allows to:
* retrieve the list of available products on a selected area
(which can be provided by specifying a bounding box, by loading a vector file
or by drawing it on a map) in a given time window;
* download the required SAFE Level-1C products, or
retrieve the required SAFE Level-2A products by downloading them (if available)
or downloading the corresponding Level-1C and correcting them with **Sen2Cor**;
* obtain the required products (Top of Atmosphere radiances, Bottom of Atmosphere
reflectances, Surface Classification Maps, True Colour Images) clipped on the
specified area (adjacent tiles belonging to the same frame are merged);
* mask cloudy pixels (using the Surface Classification Map as masking layer);
* computing spectral indices and RGB images.
Setting the execution of this processing chain is particularly easy using the
<span style="color:#5793dd;vertical-align:top;font-size:90%;font-weight:normal;">sen</span><span style="color:#6a7077;vertical-align:baseline;font-size:115%;font-weight:bolder;">2</span><span style="color:#2f66d5;vertical-align:baseline;font-size:90%;font-weight:bold;">r</span>
GUI, which allows to set the parameters, to directly launch the main function
or to save them in a JSON file which can be used to launch the processing at a later stage.
The possibility to launch the processing with a set of parameters saved in a JSON file
(or directly passed as function arguments) makes easy to build scripts to
automatically update an archive of Sentinel-2 products.
Specific processing operations (i.e. applying **Sen2Cor** on Level-1c SAFE products,
merging adjacent tiles, computing spectral indices from existing products)
can also be performed using intermediate functions (see [usage](#usage)).
## Installation
### Install locally
The package can be installed from GitHub with the R package **remotes**:
```{r, eval = FALSE}
remotes::install_github("ranghetti/sen2r")
```
For detailed instructions about installing the package (including dependencies),
see the [Installation](http://sen2r.ranghetti.info/articles/installation.html) page.
### Run as Docker image
A dockerised version of <span style="color:#5793dd;vertical-align:top;font-size:90%;font-weight:normal;">sen</span><span style="color:#6a7077;vertical-align:baseline;font-size:115%;font-weight:bolder;">2</span><span style="color:#2f66d5;vertical-align:baseline;font-size:90%;font-weight:bold;">r</span> is available [here](https://hub.docker.com/r/ranghetti/sen2r).
For detailed instructions about using it, see the page ["Run in a Docker container"](http://sen2r.ranghetti.info/articles/docker.html) page.
## Usage
The simplest way to use
<span style="color:#5793dd;vertical-align:top;font-size:90%;font-weight:normal;">sen</span><span style="color:#6a7077;vertical-align:baseline;font-size:115%;font-weight:bolder;">2</span><span style="color:#2f66d5;vertical-align:baseline;font-size:90%;font-weight:bold;">r</span>
is to execute it in interactive mode:
```{r, eval = FALSE}
library(sen2r)
sen2r()
```
this opens a GUI which allows to set the required processing parameters,
and then launches the main function.
<p style="text-align:center;">
<a href="https://raw.githubusercontent.com/ranghetti/sen2r/devel/man/figures/sen2r_gui_sheet1.png" target="_blank">
<img src="man/figures/sen2r_gui_sheet1_small.png">
</a>
<a href="https://raw.githubusercontent.com/ranghetti/sen2r/devel/man/figures/sen2r_gui_sheet2.png" target="_blank">
<img src="man/figures/sen2r_gui_sheet2_small.png">
</a>
<br/>
<a href="https://raw.githubusercontent.com/ranghetti/sen2r/devel/man/figures/sen2r_gui_sheet3.png" target="_blank">
<img src="man/figures/sen2r_gui_sheet3_small.png">
</a>
<a href="https://raw.githubusercontent.com/ranghetti/sen2r/devel/man/figures/sen2r_gui_sheet4.png" target="_blank">
<img src="man/figures/sen2r_gui_sheet4_small.png">
</a>
<a href="https://raw.githubusercontent.com/ranghetti/sen2r/devel/man/figures/sen2r_gui_sheet5.png" target="_blank">
<img src="man/figures/sen2r_gui_sheet5_small.png">
</a>
</p>
Alternatively,
[`sen2r()`](http://sen2r.ranghetti.info/reference/sen2r.html)
can be launched with a list of parameters (created with
[`s2_gui()`](http://sen2r.ranghetti.info/reference/s2_gui.html))
or passing manually the parameters as arguments of the function
(see [the documentation of the function](http://sen2r.ranghetti.info/reference/sen2r.html) for further details).
Other specific functions can be used to run single steps separately:
* [`s2_list()`](http://sen2r.ranghetti.info/reference/s2_list.html)
to retrieve the list of available Sentinel-2 products based on input parameters;
* [`s2_download()`](http://sen2r.ranghetti.info/reference/s2_download.html)
to download Sentinel-2 products;
* [`sen2cor()`](reference/sen2cor.html)
to correct level-1C products using [Sen2Cor](http://step.esa.int/main/third-party-plugins-2/sen2cor);
* [`s2_translate()`](http://sen2r.ranghetti.info/reference/s2_translate.html)
to convert Sentinel-2 products from SAFE format to a format managed by GDAL;
* [`s2_merge()`](http://sen2r.ranghetti.info/reference/s2_merge.html)
to merge Sentinel-2 tiles which have the same date and orbit;
* [`gdal_warp()`](http://sen2r.ranghetti.info/reference/gdal_warp.html)
to clip, reproject and warp raster files (this is a wrapper to call
[gdal_translate](http://www.gdal.org/gdal_translate.html) or
[gdalwarp](http://www.gdal.org/gdalwarp.html) based on input parameters);
* [`s2_mask()`](http://sen2r.ranghetti.info/reference/s2_mask.html)
to apply a cloud mask to Sentinel-2 products;
* [`s2_rgb()`](http://sen2r.ranghetti.info/reference/s2_rgb.html)
to generate RGB images from Sentinel-2 Surface Reflectance multiband raster files;
* [`s2_calcindices()`](http://sen2r.ranghetti.info/reference/s2_calcindices.html)
to compute maps of spectral indices from Sentinel-2 Surface Reflectance multiband raster files;
* [`s2_thumbnails()`](http://sen2r.ranghetti.info/reference/s2_thumbnails.html)
to generate RGB thumbnails (JPEG or PNG) of the products.
## Credits
<a href="http://www.irea.cnr.it" target="_blank"> <img src="man/figures/irea_logo_200px.png" height="100" align="left" style="padding-right: 100px;"/></a>
<span style="color:#5793dd;vertical-align:top;font-size:90%;font-weight:normal;">sen</span><span style="color:#6a7077;vertical-align:baseline;font-size:115%;font-weight:bolder;">2</span><span style="color:#2f66d5;vertical-align:baseline;font-size:90%;font-weight:bold;">r</span>
is being developed by Luigi Ranghetti and Lorenzo Busetto
([IREA-CNR](http://www.irea.cnr.it)),
and it is released under the [GNU General Public License version 3](https://www.gnu.org/licenses/gpl-3.0.html) (GPL‑3).
The [<span style="color:#5793dd;vertical-align:top;font-size:90%;font-weight:normal;">sen</span><span style="color:#6a7077;vertical-align:baseline;font-size:115%;font-weight:bolder;">2</span><span style="color:#2f66d5;vertical-align:baseline;font-size:90%;font-weight:bold;">r</span> logo](https://raw.githubusercontent.com/ranghetti/sen2r/devel/man/figures/sen2r_logo_200px.png),
partially derived from the [R logo](https://www.r-project.org/logo),
is released under the [Creative Commons Attribution-ShareAlike 4.0 International license](https://creativecommons.org/licenses/by-sa/4.0) (CC-BY-SA 4.0).
To cite this library, please use the following entry:
Ranghetti, L.\ and Busetto, L.\ (`r strftime(Sys.Date(),"%Y")`). *sen2r: Find, Download and Process Sentinel-2 Data*. R package version `r packageVersion("sen2r")`. DOI: [10.5281/zenodo.1240384](https://dx.doi.org/10.5281/zenodo.1240384). URL: [http://sen2r.ranghetti.info](http://sen2r.ranghetti.info).
```bibtex
@Manual{sen2r,
title = {sen2r: Find, Download and Process Sentinel-2 Data},
author = {Luigi Ranghetti and Lorenzo Busetto},
year = {`r strftime(Sys.Date(),"%Y")`},
note = {R package version `r packageVersion("sen2r")`},
doi = {10.5281/zenodo.1240384},
url = {http://sen2r.ranghetti.info},
}
```
## Contributing
This project is released with a [Contributor Code of Conduct](http://sen2r.ranghetti.info/CONDUCT.html).
By participating in this project you agree to abide by its terms.
Users are encouraged to use GitHub issues in case of errors with the package.
Before opening a new issue, please read
<a href="https://github.com/ranghetti/sen2r/issues/186" target="_blank">these notes</a>.