---
title: "Installation"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Installation}
  %\VignetteEngine{knitr::knitr}
  %\usepackage[UTF-8]{inputenc}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

## Installing <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>

Instruction are provided separately for each OS:

- [Install on Linux systems](#on-linux-systems)
- [Install on Windows](#on-windows)
- [Install on MacOS](#on-macos)

Alternatively, <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> can be used [in a Docker container](docker.html).


### <i class="fa fa-linux" aria-hidden="true"></i> On Linux systems

#### Installing dependencies

Before installing <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>, it is recommended to check [R](https://cran.r-project.org/bin/linux/) (v. 3.4.4 or higher) and the following libraries to be present:

- [GDAL](https://gdal.org/), [PROJ](https://proj4.org/) and [GEOS](https://trac.osgeo.org/geos/)
    (required by [rgdal](https://r-forge.r-project.org/projects/rgdal/)
    and [rgeos](https://r-forge.r-project.org/projects/rgeos/));
- [jq](https://stedolan.github.io/jq/)
    (required by [jqr](https://github.com/ropensci/jqr/));
- [protobuf](https://github.com/protocolbuffers/protobuf/)
    (required by [protolite](https://github.com/jeroen/protolite/));
- [V8](https://v8.dev/)
    (required by [geojsonio](https://github.com/ropensci/geojsonio/));
- [openssl](https://www.openssl.org/)
    (required by [openssl](https://github.com/jeroen/openssl/));
- [cairo](https://www.cairographics.org/)
    (required by [gdtools](https://github.com/davidgohel/gdtools/));
- [libcurl](https://curl.se/libcurl/)
    (required by [curl](https://github.com/jeroen/curl/));
- [NetCDF](https://www.unidata.ucar.edu/software/netcdf/)
    (required by [ncdf4](https://github.com/mdsumner/ncdf4/));
- [libxml2](http://xmlsoft.org/)
    (required by [XML](https://CRAN.R-project.org/package=XML/)).
    
Some external dependencies are required to run specific
<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>
features:

* [**Sen2Cor**](http://step.esa.int/main/snap-supported-plugins/sen2cor/)
    is used to perform atmospheric correction of Sentinel-2 Level-1C products:
    it is required by the package, unless you choose not to correct products locally
    (using only Level-1C – TOA products or downloading directly Level-2A products);
* [**GDAL**](https://gdal.org/)
    is required to smooth/bufferise a cloud mask, and can be optionally used
    to compute spectral indices, RGB images and thumbnails;
* [**aria2**](https://aria2.github.io/) is an alternative downloader which
    can be used to faster the download of SAFE archives; it can be optionally
    installed and used.

To install both package dependencies and runtime binaries (excepting **Sen2Cor**, which is installed by <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>):

- On Ubuntu:
    - Ubuntu 20.04 LTS Focal and newer:
        ```{bash, eval = FALSE}
        sudo apt install -y r-base gdal-bin aria2 libpython2-dev libudunits2-dev libgdal-dev libjq-dev libprotobuf-dev protobuf-compiler libv8-dev libssl-dev libcairo2-dev
        ```
    - Older distros:
        ```{bash, eval = FALSE}
        sudo apt-get install -y r-base gdal-bin python-gdal aria2 libpython-dev libudunits2-dev libgdal-dev libjq-dev libprotobuf-dev protobuf-compiler libv8-dev libssl-dev libcairo2-dev
        ```
    On Ubuntu 16.04 LTS Xenial, the repositories [ubuntugis](https://launchpad.net/~ubuntugis) and [opencpu](https://launchpad.net/~opencpu) must be added before installing the packages:
        ```{bash, eval = FALSE}
        sudo add-apt-repository -y ppa:opencpu/jq
        sudo add-apt-repository -y ppa:ubuntugis/ubuntugis-unstable
        sudo apt-get update -q
        ```
        
    Installation was tested over Ubuntu 20.04 LTS focal and 18.04 LTS Bionic; non-LTS versions > 18.04 and Ubuntu 16.04 LTS Xenial should work. Other releases (Ubuntu non-LTS < 18.04; Ubuntu LTS &#8804; 14.04) are not supported.
- On Debian:
    ```{bash, eval = FALSE}
    sudo apt-get install -y r-base gdal-bin python-gdal aria2 libpython-dev libudunits2-dev libgdal-dev libjq-dev libprotobuf-dev protobuf-compiler libnode-dev libssl-dev libcairo2-dev proj-epsg
    ```
    Installation was tested over Debian 9 Stretch; older releases are not supported.
- On Fedora:
    ```{bash, eval = FALSE}
    sudo yum install R gdal gdal-python aria2 python-devels gdal-devel proj-devel geos-devel udunits2-devel jq-devel protobuf-devel v8-devel openssl-devel cairo-devel libcurl-devel netcdf-devel libxml2-devel
    ```
    Installation was tested over Fedora 29.
- On ArchLinux:
    ```{bash, eval = FALSE}
    sudo pacman -S --noconfirm r base-devel gcc-fortran python-gdal wget aria2 jq protobuf git
    cd /tmp; git clone https://aur.archlinux.org/gyp-git.git
    cd gyp-git; makepkg -si --noconfirm
    cd /tmp; git clone https://aur.archlinux.org/v8-3.14.git
    cd v8-3.14; makepkg -si --noconfirm
    cd /tmp; git clone https://aur.archlinux.org/udunits.git
    cd udunits; makepkg -si --noconfirm
    ```
    Installation was tested on date 2018-11-21.

#### Installing <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>

Before proceeding, it is suggested to update the existing R packages:
```{r, eval = FALSE}
update.packages(ask = FALSE)
```
Doing that, the following warning could appear:
```
Warning in install.packages(update[instlib == l, "Package"], l, contriburl = contriburl,  :
  'lib = "/usr/lib/R/library"' is not writable
Would you like to use a personal library instead?  (y/n)
```
If so, press `y` and continue.
Moreover, if no personal libraries already exist, it is asked to create a new one: ask `y` and continue.

After that, the package can be installed from CRAN:
```{r, eval = FALSE}
install.packages("sen2r")
```

Alternatively, the development version can be installed from GitHub with the R package **remotes**.
To do it:

1. install the package **remotes**, if missing:
    ```{r, eval = FALSE}
    install.packages("remotes")
    ```
2. load it and install
    <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>:
    ```{r, eval = FALSE}
    library(remotes)
    install_github("ranghetti/sen2r")
    ```

This will install the R package along with its package dependencies,
containing all the functions necessary to preprocess data.

Finally, **Sen2Cor** can be installed from R:
```{r, eval = FALSE}
library(sen2r)
install_sen2cor()
```

### <i class="fa fa-windows" aria-hidden="true"></i> On Windows

[R](https://cran.r-project.org/bin/windows/base/) must be installed before proceeding.

In the case it was already installed, it is suggested to update the existing R packages:
```{r, eval = FALSE}
update.packages(ask = FALSE)
```

<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> can be installed from CRAN:
```{r, eval = FALSE}
install.packages("sen2r")
```

Alternatively, the development version can be installed from GitHub with the R package **remotes**.
To do it:

1. install the package **remotes**, if missing:
    ```{r, eval = FALSE}
    install.packages("remotes")
    ```
2. load it and install
    <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>:
    ```{r, eval = FALSE}
    library(remotes)
    install_github("ranghetti/sen2r")
    ```

This will install the R package along with its package dependencies,
containing all the functions necessary to preprocess data.


### <i class="fa fa-apple" aria-hidden="true"></i> On MacOS

[R](https://cran.r-project.org/bin/windows/base/) must be installed before proceeding.

In the case it was already installed, it is suggested to update the existing R packages:
```{r, eval = FALSE}
update.packages(ask = FALSE)
```

Packages can be installed using the compiled binaries, except from **sp**, **sf**, **rgdal** and **rgeos**,
which are recommended to be compiled. To do it, use the command
```{r, eval = FALSE}
install.packages(c("sp", "sf", "rgdal", "rgeos"), type = "source")
```
__after__ having installed GDAL as described above.

<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> can be installed from CRAN:
```{r, eval = FALSE}
install.packages("sen2r")
```

Alternatively, the development version can be installed from GitHub with the R package **remotes**.
To do it:

1. install the package **remotes**, if missing:
    ```{r, eval = FALSE}
    install.packages("remotes")
    ```
2. load it and install
    <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>:
    ```{r, eval = FALSE}
    library(remotes)
    install_github("ranghetti/sen2r")
    ```

This will install the R package along with its package dependencies,
containing all the functions necessary to preprocess data.



### Installing Sen2Cor

[**Sen2Cor**](http://step.esa.int/main/snap-supported-plugins/sen2cor/)
is used to perform atmospheric correction of Sentinel-2 Level-1C products,
so its installation can be skipped in case this function is not required
by the user (using only Level-1C – TOA products 
or downloading directly Level-2A products).

It can be graphically checked / installed launching the function
```{r, eval = FALSE}
library(sen2r)
check_sen2r_deps()
```
This function opens a GUI which help to check if this and other dependencies
are satisfied;
from this GUI a new Sen2Cor installation can be performed,
or an existing environment can be linked to Sen2Cor.

Alternatively, it can be installed from the command line with the
following function:
```{r, eval = FALSE}
install_sen2cor()
```


### Installing other dependencies (generally unrequired and discouraged)

Other dependencies can be configure to run specific
<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>
features; their installation is generally unrequired (they do not add relevant
improvements to the package) and discouraged (errors could occur).

* [**GDAL**](https://gdal.org/)
    is no more required, being used only to smooth/bufferise a cloud mask
    (and _optionally_ to compute spectral indices, RGB images and thumbnails).
    On Windows, to avoid incompatibilities, it is _strictly mandatory_ 
    to use a GDAL installation provided with the 
    [OSGeo4W installer](https://qgis.org/it/site/forusers/download.html):
    if this requirement is not satisfied, it is possible to install GDAL
    with OSGeo4W directly from R (see below).
    **Note**: configuring a runtime **GDAL** environment could fail for different reasons
    (e.g. problems related to GDAL environment like missing libraries,
    or custom environment variables which could conflict).
    <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>
    maintainers are not responsible in case of GDAL-related issues
    (no assistance is provided in this case).
* [**aria2**](https://aria2.github.io/) is an alternative downloader which
    can be used to faster the download of SAFE archives; it can be optionally
    installed and used.
    Since the number of concurrent downloads from ESA SciHub is limited to 2,
    the use of **aria2** is generally not faster than the default downloader;
    for this reason, its use is recommended only in case of problems with
    the default downloader.

These dependences can be graphically checked launching the function
```{r, eval = FALSE}
library(sen2r)
check_sen2r_deps()
```

Alternatively, they can be installed individually from the command line with the
following functions (see their respective references for further details):
```{r, eval = FALSE}
check_gdal()
install_aria2()
```


#### Note on GDAL installation on MacOS
In order to avoid incompatibilities with GDAL, it is _strictly mandatory_ to use
a GDAL installation provided with the
[OSGeo Homebrew repository](https://github.com/OSGeo/homebrew-osgeo4mac).
To do it:

1. if Homebrew is missing on your system, install it opening a terminal and typing:
    ```{bash, eval = FALSE}
    /usr/bin/ruby -e "$(curl -fsSL https://github.com/Homebrew/install/raw/master/install)"
    ```
    (see [the Homebrew webpage](https://brew.sh/) for details);
2. install GDAL by typing:
    ```{bash, eval = FALSE}
    brew tap osgeo/osgeo4mac
    brew install osgeo-gdal-python
    ```
    (see [the OSGeo Homebrew webpage](https://github.com/OSGeo/homebrew-osgeo4mac) for details).
    At this step, an error could be returned in case another GDAL installation was already present;
    in this case, follow the instruction returned in the terminal to solve it
    (probably some packages must be unlinked with the instructions `brew unlink <package>`).
