The TheiaR package provides an efficient and clean interface to search, download and manage products from Theia website.
The basic functionalities are:
.meta4
file) obtained from Theia website.RasterStack
objects (with the raster
library)gdalcubes
objects (with the gdalcubes
library)NOTE: To search and download data from Theia, you will need to register to their website.
NOTE: In order to use Landsat or SpotWorldHeritage products, you’ll need to make a first manual download to agree to the license and validate your account.
You can install the latest stable version from Github with:
::install_github('norival/theiaR')
devtools
# or, to install the development version
::install_github('norival/theiaR', 'devel') devtools
Or, you can install it from CRAN:
isntall.packages('theiaR')
A workflow to search and download tiles would be something like:
library(theiaR)
# create a list containing the query
<- list(collection = "SENTINEL2",
myquery town = "Grenoble",
start.date = "2018-07-01",
end.date = "2018-07-06")
# create a collection from the query
<- TheiaCollection$new(query = myquery, dir.path = ".", check = TRUE)
mycollection
# check available tiles fro the query
$status
mycollection
# download the tiles into 'dir.path'
$download(auth = "path/to/auth/file.txt") mycollection
First, load the package.
library(theiaR)
To search and download data from Theia, you will need to register to their website.
NOTE: In order to use Landsat or SpotWorldHeritage products, you’ll need to make a first manual download to agree to the license and validate your account.
The first step is to create a collection of tile(s). This can be done either from a query or from a cart file.
A query is simply a named list
of search terms. For example:
<- list(collection = "SENTINEL2",
myquery town = "Grenoble",
start.date = "2018-07-01",
end.date = "2018-07-06")
will create a query to Theia database, looking for tiles from Sentinel2 satellite around Grenoble, between 2018-07-01 and 2018-07-06.
It accepts the following terms.
collection: The collection to look for. Accepted values are: SENTINEL2
, LANDSAT
, SpotWorldHeritage
, Snow
. Defaults to SENTINEL2
.
platform: The platform to look for. Accepted values are: LANDSAT5
, LANDSAT7
, LANDSAT8
, SPOT1
, SPOT2
, SPOT3
, SPOT4
, SPOT5
, SENTINEL2A
, SENTINEL2B
.
level: Processing level of products. Accepted values are: LEVEL1C
, LEVEL2A
and LEVEL3A
. Defaults to 'LEVEL2A
.
To specify the location of the tiles, several alternatives are available. You can specify the town around which you want your data with:
You can specify directly the tile ID if you know it:
You can specify a point by giving its x/y coordinates:
latitude: The x coordinate of a point.
longitude: The y coordinate of a point.
Or you can specify a rectangle by giving its min/max coordinates:
latmin: The minimum latitude to search.
latmax: The maximum latitude to search.
lonmin: The minimum longitude to search.
lonmax: The maximum longitude to search.
You can also look for a specific orbit number or relative orbit number:
orbit.number: The orbit number
rel.orbit.number: The relative orbit number
Finally, you can filter results by giving the date range and the maximum cloud cover:
max.clouds: The maximum of cloud cover wanted (0-100).
start.date: The first date to look for (format: YYYY-MM-DD
).
end.date: The last date to look for (format: YYYY-MM-DD
).
You can then create your collection with:
<- TheiaCollection$new(query = myquery, dir.path = ".", check = TRUE) mycollection
where dir.path
is the path you want your tiles to be further downloaded (This only queries Theia’s catalog for available tiles, nothing is downloaded). If tiles are already present in dir.path
, they will be checked by computing a checksum and comparing it to the hash provided by Theia (only available for Sentinel2 data, no hash is provided for other collections, and files are then assumed to be correct). This ensures that the files have been correctly downloaded. Set check = FALSE
to skip file’s check.
print(mycollection)
#> An collection of tiles from Theia
#>
#> Number of tiles: 11
#> Directory path : './'
#>
#> Obtained from query
Alternatively, you can download a cart from Theia. To create a cart, login to Theia website, make a search for tiles, and add wanted tiles to your cart. Then, download your cart and save the resulting .meta4
file to your disk.
You can then create your collection using this file:
<- system.file("extdata", "cart.meta4", package = "theiaR")
cart.path
<- TheiaCollection$new(cart.path = cart.path,
mycollection dir.path = ".",
check = TRUE)
print(mycollection)
#> An collection of tiles from Theia
#>
#> Number of tiles: 2
#> Directory path : './'
#>
#> Obtained from cart file
As above, it will check the hash of files if they are already present in dir.path
.
The next step is to download your collection. You can get the status of your collection by running:
$status
mycollection#> tile exists checked correct extracted
#> 1 SENTINEL2B_20190128-104831-308_L2A_T31TGK_D FALSE FALSE FALSE FALSE
#> 2 SENTINEL2A_20190113-104826-809_L2A_T31TGK_D FALSE FALSE FALSE FALSE
To download all tiles in a collection, simply run:
$download(auth = myauth) mycollection
where myauth is the path to file storing your Theia credentials. If it does not exist yet, you will be securely prompted for your login and password, and the file will be created.
This will check if files are present, check their hashes, and download them if needed (if files do not exist or checksums are wrong). To overwrite existing files, run:
$download(auth = myauth, overwrite = TRUE) mycollection
Alternatively, you can read bands directly from the zip archives (by using the vsizip
interface provided by GDAL). Use:
$bands mytile
to get a list of available bands. Then:
<- mytile$read(bands = c("B5", "B6")) mybands
to load the bands into memory (returns a RasterStack
object). It performs the necessary corrections on the values.
You can also read bands from a collection by running:
<- mycollection$read(bands = c("B5", "B6")) mybands
which returns a list
of RasterStack
objects.
NOTE: loading several tiles needs a lot of memory (~900MB/tile)
gdalcubes
collectionAlternatively, you can use the great gdalcubes package to create a three dimensional representation of the tiles. Simply run:
library(gdalcubes)
<- mycollection$as_gdalcube("path/to/gdalcubes.sqlite") gdalcubes
where path/to/gdalcubes.sqlite
is the path to store the gdalcubes object data.
If you want to extract the archives, you can run:
<- mycollection$extract() file.path
which will extract tiles into the same directory as the archives.
This is not recommended, as this will take a large amount of disk space
Thanks to Olivier Hagolle for his work on theia_download.py
(github), which has inspired this package.