---
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/dis-organization/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", dependencies = TRUE)
```
The parameter `dependencies = TRUE` is used to install also suggested dependencies, 
which includes Shiny packages required to run the Graphical User Interface.
Anyway, it could be omitted as Shiny packages can be installed later, before running the GUI.

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", dependencies = TRUE)
    ```

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>`).
