r.in.sentinel - Downloads and imports Sentinel-1 SAR and Sentinel-2 optical imagery using the cubo library via Microsoft Planetary Computer or Google Earth Engine.
Use Google Earth Engine instead of Planetary Computer
-c
Apply cloud masking using SCL band (Sentinel-2 L2A only)
-s
Apply spectral cloud index masking (uses B02, B04, B08/B8A; fallback for L1C or when SCL not available)
-l
List available dates/scenes and exit without downloading
-m
Apply cloud masking using i.sentinel.mask (requires B02,B03,B04,B08,B8A,B11,B12; auto-added)
-j
Write per-band metadata JSON to $MAPSET/cell_misc/
-p
Print region info and exit
-r
Create true-color RGB composite with r.composite after import (auto-adds B02, B03, B04 if not listed)
-d
Convert Sentinel-1 backscatter (vv/vh/hh/hv) from linear power to dB (10*log10); no effect on Sentinel-2 or the angle band
-o
Remove the Sentinel-2 L2A radiometric offset (DN - 1000 for processing baseline >= 04.00), harmonising with older products; no effect on SCL, Sentinel-1 or GEE
r.in.sentinel downloads Sentinel-2 imagery directly into the
current GRASS GIS mapset using the
cubo Python library.
Data is fetched from Microsoft Planetary Computer (default, no
credentials required) or Google Earth Engine (-g flag,
credentials required). Each acquisition date is imported as individual
raster maps and grouped with i.group.
The module reads the current computational region to determine the
centre coordinates (latitude/longitude) and the approximate download
extent. Both latlong and projected locations are supported.
Microsoft Planetary Computer (default)
Collection sentinel-2-l2a provides Sentinel-2 Level-2A surface
reflectance. No account is required. The stac option allows
pointing to any STAC-compliant endpoint.
Google Earth Engine
Use the -g flag and set collection to the GEE asset ID,
e.g. COPERNICUS/S2_SR_HARMONIZED. GEE credentials must be
configured beforehand (earthengine authenticate).
Two cloud removal methods are available and are mutually exclusive.
SCL-based masking (-c flag)
Recommended for Sentinel-2 L2A data. Uses the Scene Classification
Layer (SCL band) to keep only pixels classified as:
SCL value
Class
4
Vegetation
5
Not vegetated
6
Water
11
Snow / Ice
All other classes (clouds, shadows, saturated pixels, no-data) are set
to NULL. The SCL band is automatically added to the download list when
-c is requested.
Spectral Cloud Score Index (-s flag)
Fallback method suitable for L1C data or when the SCL band is
unavailable. Computes a Cloud Score Index (CSI) from the Blue, Red, and
NIR bands:
CSI = (B02 + B04) / (2 * B08 + eps)
Pixels are flagged as cloud when CSI > 0.35andB02 > 0.175 (scaled reflectance). Requires B02,
B04, and at least one of B08 or B8A.
The computational region centre is projected to WGS84 to serve as the
cubo cube centre. The download edge size is derived from the larger of
the NS or EW region extent. After download, each band slice is
imported with r.import using extent=region, which
reprojects and clips to the current computational region
automatically.
With the -j flag the module writes a description.json
file for each imported raster map to the standard GRASS location
$MAPSET/cell_misc/<map_name>/description.json.
Alternatively, the metadata option allows specifying a
directory where the files are saved
(<metadata_dir>/<map_name>/description.json). The
two options are mutually exclusive.
Each JSON file records:
Key
Description
collection
STAC collection name
band
Band identifier (e.g. B04)
date
Acquisition date (YYYYMMDD)
start_date / end_date
Query date range
epsg
EPSG code of the downloaded data
resolution_m
Spatial resolution in metres
stac_endpoint
STAC endpoint URL (null for GEE)
gee
true when downloaded from Google Earth Engine
cloud_cover_max
Maximum cloud cover filter applied
scl_masked
Whether SCL cloud masking was applied
spectral_masked
Whether spectral CSI masking was applied
boa_offset_removed
Whether the Sentinel-2 L2A offset was removed (o flag)
When the strds option is set, the module creates one STRDS per
downloaded band and registers all imported maps into it after the
import loop. The STRDS names follow the pattern
{strds}_{band}, e.g. s2_B04, s2_B08,
s2_SCL.
Temporal registration uses the acquisition timestamp already embedded
in each raster map by r.timestamp (format
DD Mon YYYY HH:MM:SS.ffffff), so no additional timestamp file
is required. The -i flag of t.register reads these
stored timestamps automatically.
This makes the imported data immediately usable with TGRASS tools such
as t.rast.series, t.rast.algebra, and
t.rast.list.
Cloud masking with i.sentinel.mask (-m flag)
The -m flag invokes i.sentinel.mask automatically for
each acquired date. The following bands are required by
i.sentinel.mask and are added to the download list
automatically if not already requested:
Role
Band
blue
B02
green
B03
red
B04
nir
B08
nir8a
B8A
swir11
B11
swir12
B12
Solar zenith and azimuth angles needed by i.sentinel.mask are
fetched automatically from the STAC item properties
(s2:mean_solar_zenith, s2:mean_solar_azimuth) and
written to cell_misc/<map>/description.json for each
imported band. i.sentinel.mask is then called with the
-s (rescale from DN to reflectance) and -c
(cloud-only, no shadow) flags.
After masking, cloudy pixels are set to NULL in every imported band
for that date using r.mapcalc. The resulting cloud mask
raster ({output}_{YYYYMMDD}_cloud_mask) is kept, included in
the i.group group, given a timestamp via r.timestamp,
and registered in the STRDS if the strds option is set.
If solar angle metadata is unavailable for a given date (GEE backend,
or STAC item without sun-angle properties), masking is skipped for
that date with a warning.
With the -l flag the module prints one date per line to stdout
and exits without importing anything. With the STAC backend the listing is
a metadata-only search over the same box the download would cover (the
clouds filter applies); no imagery is read. With g (GEE) the
cube is still built to list its dates.
Since processing baseline 04.00 (products from 25 January 2022),
Sentinel-2 L2A digital numbers include an offset
(BOA_ADD_OFFSET = -1000): surface reflectance is
(DN - 1000) / 10000. Planetary Computer serves the DNs
unchanged, so without correction normalised indices such as NDVI are biased
and older and newer products are not comparable. The o flag
subtracts 1000 from every reflectance band of the affected items (read from
the s2:processing_baseline item property, or from the
acquisition date if the property is missing) and clips at 0; the
SCL band is never modified. The correction is recorded in the map
history and, with j or metadata, as
boa_offset_removed in description.json. It has no
effect on Sentinel-1 or on GEE's already harmonised
COPERNICUS/S2_SR_HARMONIZED.
Acquisitions of the same date are mosaicked (first valid pixel wins) only
when they belong to the same satellite pass (within one hour of the first
acquisition of the day). Other passes of that day, e.g. the ascending
Sentinel-1 pass on a day that also has a descending one, are not used to
fill gaps, so each imported map has a single viewing geometry and its
timestamp matches its data.
This module writes UTM GeoTIFFs whose CRS is resolved from an EPSG
code via rasterio.crs.CRS.from_epsg(). That lookup hits the
proj.db SQLite authority database introduced in PROJ 6 and
fully stabilised in PROJ 7. With an older PROJ the database may be
absent, incomplete, or bundled inside GDAL under a different path,
causing r.import to fail with a CRS-related error or silently
create an unnamed / unknown projection in the temporary reprojection
location, which then produces incorrect or null output after
r.proj.
PROJ 9.x (the current generation, available in most distributions
since 2022) is recommended for best accuracy and datum-shift support.
Rasterio >= 1.3 and GDAL >= 3.5 are also recommended to ensure
they are linked against a PROJ 7+ library.
g.region n=47.73 s=47.68 e=-2.85 w=-2.93
r.in.sentinel collection=sentinel-2-l2a \
bands=B02,B04,B08 \
start=2023-07-01 end=2023-07-31 clouds=30 \
output=s2 flags=m
# B03, B8A, B11, B12 are added automatically; cloud_mask maps are created
# per date and cloudy pixels are nulled in all bands.
Montero, D. et al. (2023). A standardized catalogue of spectral
indices to advance the use of remote sensing in Earth system
research. Scientific Data.