GRASS logo

NAME

r.in.landcover - Downloads and imports land cover / land use rasters from Microsoft Planetary Computer or Google Earth Engine using the cubo library.

KEYWORDS

Import, imagery, land cover, land use, LULC, STAC, Planetary Computer, ESA WorldCover, temporal, metadata

SYNOPSIS

r.in.landcover
r.in.landcover --help
r.in.landcover [-gcjlp] collection=string start=string end=string [bands=string[,string,...]] [resolution=integer] [output=string] [stac=string] [strds=string] [metadata=string] [--help] [--verbose] [--quiet] [--ui]

Flags:

-g
Use Google Earth Engine instead of Planetary Computer
-c
Apply collection-specific color table and category labels after import
-j
Write per-map metadata JSON to $MAPSET/cell_misc//description.json
-l
List available years/dates and exit without downloading
-p
Print region info and exit
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

collection=string [required]
Land cover collection to download
Options: esa-worldcover, io-lulc-annual-v02, io-lulc-9-class, io-lulc, nrcan-landcover, drcog-lulc, cop-lc, modis-mcd12q1-061, dynamicworld
Default: esa-worldcover
esa-worldcover: ESA WorldCover 10 m (2020-2021)
io-lulc-annual-v02: Esri 10 m Annual LULC 9-class V2 (2017-2023)
io-lulc-9-class: Esri 10 m Annual LULC 9-class V1 (2017-2022)
io-lulc: Esri 10 m Land Cover 10-class (2017-2021)
nrcan-landcover: Land Cover of Canada 30 m (2015-2020)
drcog-lulc: Denver Regional LULC 1 m (2018-2020)
cop-lc: Copernicus Global Land Cover 100 m (2015-2019)
modis-mcd12q1-061: MODIS MCD12Q1 Land Cover Type 500 m (2001-present)
dynamicworld: Google Dynamic World 10 m near-real-time (2015-present, GEE only)
start=string [required]
Start of requested period (YYYY or YYYY-MM-DD)
end=string [required]
End of requested period (YYYY or YYYY-MM-DD)
bands=string[,string,...]
Asset/band names to download (default: auto-detected per collection)
resolution=integer
Spatial resolution in metres (0 = use collection default)
Default: 0
output=string
Prefix for output raster map names
Default: landcover
stac=string
STAC endpoint URL
Default: https://planetarycomputer.microsoft.com/api/stac/v1
strds=string
Name of the Space-Time Raster Dataset to create/extend (one STRDS per band)
metadata=string
Directory for per-map metadata JSON files (alternative to -j)

Table of contents

DESCRIPTION

r.in.landcover downloads and imports land cover / land use raster products 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).

The module reads the current computational region to determine the centre coordinates and download extent. Both latlong and projected locations are supported. Each year or date is imported as an individual raster map; optional STRDS creation and collection-specific color tables are supported.

Output naming

Raster maps are named {output}_{date}_{band}, where {date} is YYYY for annual products or YYYYMMDD for sub-annual products, and {band} is the asset name (e.g. map, data, landcover).

Example: landcover_2021_map for ESA WorldCover 2021.

Supported collections

Collection IDProductResolutionPeriodBackend
esa-worldcoverESA WorldCover10 m2020-2021Planetary Computer
io-lulc-annual-v02Esri Annual LULC 9-class V210 m2017-2023Planetary Computer
io-lulc-9-classEsri Annual LULC 9-class V110 m2017-2022Planetary Computer
io-lulcEsri Land Cover 10-class10 m2017-2021Planetary Computer
nrcan-landcoverLand Cover of Canada30 m2015-2020Planetary Computer
drcog-lulcDenver Regional LULC1 m2018-2020Planetary Computer
cop-lcCopernicus Global Land Cover (CGLS-LC100)100 m2015-2019Planetary Computer
modis-mcd12q1-061MODIS MCD12Q1 Land Cover Type500 m2001-presentPlanetary Computer
dynamicworldGoogle Dynamic World10 m2015-presentGEE only (-g)

NOTES

Year-based temporal handling

Most land cover products are annual composites. Their STAC items do not carry a point datetime, only a start_datetime / end_datetime interval (e.g. 2021-01-01 / 2021-12-31). The module uses start_datetime to derive the year string used in map names, and registers maps in the STRDS with their full year interval so that temporal tools such as t.rast.series treat them correctly.

The r.timestamp metadata on each map is set to the year start (01 Jan YYYY 00:00:00).

Mosaicking

When the requested region spans multiple STAC tiles for the same year, the module downloads all overlapping tiles and mosaics them by priority overlay (first tile's valid pixels win; later tiles only fill in gaps the earlier ones left as nodata) -- not a pixel-wise average. Land cover class codes are categorical (e.g. ESA WorldCover's 10 = tree cover, 40 = cropland): averaging two class codes produces a class that doesn't exist (mean of 10 and 40 is 25, not a real category), so overlapping tiles are combined by which one actually has data at each pixel, never by arithmetic mean.

Latitude-corrected sizing and resolution

A degree of longitude covers less ground distance than a degree of latitude away from the equator (by a factor of cos(latitude)). The module accounts for this both when sizing the downloaded cube (so the requested area actually covers the current region's east-west extent, not less) and when setting the region's resolution for latlong projects (so resolution, given in metres, converts to the correct east-west degree step, not the same step used for north-south).

Color tables and category labels

With the -c flag the module applies a collection-specific color table (r.colors) and class label table (r.category) after each import. The color schemes follow the official product legend for each dataset.

ESA WorldCover classes

ValueClass
10Tree cover
20Shrubland
30Grassland
40Cropland
50Built-up
60Bare / sparse vegetation
70Snow and ice
80Permanent water bodies
90Herbaceous wetland
95Mangroves
100Moss and lichen

Copernicus Global Land Cover (cop-lc) -- discrete_classification

ValueClass
0Unknown
20Shrubs
30Herbaceous vegetation
40Cultivated / agriculture
50Urban / built up
60Bare / sparse vegetation
70Snow and ice
80Permanent water bodies
90Herbaceous wetland
100Moss and lichen
111-116Closed forest (subtypes)
121-126Open forest (subtypes)
200Open sea

Note: unlike every other supported collection, class 0 ("Unknown") is a real, meaningful category here -- the module uses a nodata sentinel that can't collide with any supported collection's own category values (rather than 0) so these pixels round-trip correctly instead of being masked out as missing data.

Additional Copernicus LC bands (specify with bands=): forest_type, bare-coverfraction, urban-coverfraction, crops-coverfraction, grass-coverfraction, shrubs-coverfraction, water-permanent-coverfraction, water-seasonal-coverfraction, snow-coverfraction, moss-coverfraction, discrete_classification-proba.

MODIS MCD12Q1 (modis-mcd12q1-061) -- LC_Type1 (IGBP)

ValueClass
1Evergreen needleleaf forests
2Evergreen broadleaf forests
3Deciduous needleleaf forests
4Deciduous broadleaf forests
5Mixed forests
6Closed shrublands
7Open shrublands
8Woody savannas
9Savannas
10Grasslands
11Permanent wetlands
12Croplands
13Urban and built-up lands
14Cropland / natural vegetation mosaics
15Snow and ice
16Barren
17Water bodies
255Unclassified

Other MODIS MCD12Q1 classification schemes available via bands=: LC_Type2 (UMD), LC_Type3 (LAI/FPAR), LC_Type4 (BGC), LC_Type5 (Plant Functional Types), LW (land/water mask).

Dynamic World (dynamicworld) -- label (GEE only)

ValueClass
0Water
1Trees
2Grass
3Flooded vegetation
4Crops
5Shrub and scrub
6Built
7Bare
8Snow and ice

Dynamic World also provides per-class probability bands (0-1 float): water, trees, grass, flooded_vegetation, crops, shrub_and_scrub, built, bare, snow_and_ice.

Esri LULC 9-class (io-lulc-annual-v02 / io-lulc-9-class)

ValueClass
1Water
2Trees
4Flooded vegetation
5Crops
7Built area
8Bare ground
9Snow / ice
10Clouds
11Rangeland

Space-Time Raster Dataset (STRDS)

When the strds option is provided the module creates one STRDS per downloaded band and registers all maps as year intervals using a t.register file (mapname|start|end). This makes annual land cover maps directly usable with TGRASS tools for change analysis: 
t.rast.list input=lc_ts_map
t.rast.series input=lc_ts_map output=lc_mode method=mode

Listing available years

With -l the module prints available year(s) within the requested period and exits without downloading or importing anything.

REQUIREMENTS

pip install cubo rasterio rioxarray
For GEE support: 
pip install earthengine-api
earthengine authenticate

PROJ version warning

PROJ >= 7.0 is required. This module writes GeoTIFFs whose CRS is resolved from an EPSG code via rasterio.crs.CRS.from_epsg(), which requires the proj.db SQLite authority database introduced in PROJ 6 and stabilised in PROJ 7. PROJ 9.x (current) is recommended, together with Rasterio >= 1.3 and GDAL >= 3.5. 
proj --version
python3 -c "import pyproj; print(pyproj.proj_version_str)"

EXAMPLES

Download ESA WorldCover for both available years

g.region n=47.73 s=47.68 e=-2.85 w=-2.93
r.in.landcover collection=esa-worldcover \
    start=2020 end=2021 \
    output=lc flags=c
# Creates: lc_2020_map, lc_2021_map with official color table

Download all Esri Annual LULC into a STRDS

r.in.landcover collection=io-lulc-annual-v02 \
    start=2017 end=2023 \
    output=lc_esri strds=lc_esri_ts flags=c
t.rast.list input=lc_esri_ts_data

List available years without downloading

r.in.landcover collection=io-lulc-annual-v02 \
    start=2017 end=2023 output=dummy flags=l

Land Cover of Canada at 30 m

g.region n=51.1 s=50.9 e=-114.0 w=-114.2
r.in.landcover collection=nrcan-landcover \
    start=2015 end=2020 resolution=30 \
    output=lc_canada flags=c

Write metadata JSON and create STRDS

r.in.landcover collection=esa-worldcover \
    start=2020 end=2021 \
    output=lc_meta strds=lc_meta_ts flags=cj

Copernicus Global Land Cover (100 m, 2015-2019)

g.region n=47.73 s=47.68 e=-2.85 w=-2.93
r.in.landcover collection=cop-lc \
    start=2015 end=2019 \
    output=lc_cop strds=lc_cop_ts flags=c
# Also download fractional cover layers
r.in.landcover collection=cop-lc \
    start=2019 end=2019 \
    bands=bare-coverfraction,urban-coverfraction,crops-coverfraction \
    output=lc_cop_frac

MODIS MCD12Q1 land cover time series (500 m, 2001-present)

r.in.landcover collection=modis-mcd12q1-061 \
    start=2001 end=2023 \
    output=lc_modis strds=lc_modis_ts flags=c
# UMD classification instead of default IGBP (LC_Type1)
r.in.landcover collection=modis-mcd12q1-061 \
    start=2020 end=2020 \
    bands=LC_Type2 output=lc_modis_umd

Dynamic World near-real-time (GEE, 10 m)

# Requires: earthengine authenticate
r.in.landcover collection=dynamicworld \
    start=2023-06-01 end=2023-08-31 \
    output=lc_dw strds=lc_dw_ts flags=gc
# Download probability bands
r.in.landcover collection=dynamicworld \
    start=2023-07-01 end=2023-07-31 \
    bands=trees,crops,built \
    output=lc_dw_proba flags=g

Use Google Earth Engine backend

r.in.landcover collection=ESA/WorldCover/v200 \
    start=2021 end=2021 output=lc_gee flags=g

SEE ALSO

r.import, r.colors, r.category, r.in.sentinel, t.create, t.register, t.rast.series, t.rast.algebra

REFERENCES

AUTHOR

Yann Chemin

SOURCE CODE

Available at: r.in.landcover source code (history)

Accessed: Monday Jul 27 12:29:35 2026

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual