GRASS logo

NAME

r.in.ecostress - Downloads ECOSTRESS thermal imagery (land surface temperature, radiance, evapotranspiration and derived products) from NASA CMR/LP DAAC and optionally imports it, cropped to the current region.

KEYWORDS

raster, import, imagery, thermal, land surface temperature, evapotranspiration, ECOSTRESS, ISS, download, NASA, CMR, LP DAAC

SYNOPSIS

r.in.ecostress
r.in.ecostress --help
r.in.ecostress [-lpi] [product=string] [layers=string[,string,...]] start=string end=string [daynight=string] [version=string] [clouds=integer] [coverage=integer] [output=string] [output_dir=name] [token=string] [resample=string] [strds=string] [project=string] [dbase=string] [epsg=integer] [--help] [--verbose] [--quiet] [--ui]

Flags:

-l
List matching acquisitions and exit without downloading
-p
Print the search bounding box and exit
-i
Import downloaded layers as raster maps cropped to the current region
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

product=string
ECOSTRESS tiled product (70 m, MGRS tiles)
Options: lste, rad, jet, etaux, esi, wue, stars, sm, met, seb, et_alexi, esi_alexi
Default: lste
lste: L2T land surface temperature and emissivity (ECO_L2T_LSTE)
rad: L1CT top-of-atmosphere radiance, 5 thermal bands (ECO_L1CT_RAD)
jet: L3T evapotranspiration ensemble (ECO_L3T_JET)
etaux: L3T evapotranspiration auxiliary inputs, V003 only (ECO_L3T_ETAUX)
esi: L4T evaporative stress index (ECO_L4T_ESI)
wue: L4T water use efficiency (ECO_L4T_WUE)
stars: L2T daily ancillary NDVI and albedo (ECO_L2T_STARS)
sm: L3T downscaled soil moisture, V002 only (ECO_L3T_SM)
met: L3T downscaled meteorology, V002 only (ECO_L3T_MET)
seb: L3T surface energy balance, V002 only (ECO_L3T_SEB)
et_alexi: L3T disALEXI daily evapotranspiration, CONUS, V002 only (ECO_L3T_ET_ALEXI)
esi_alexi: L4T disALEXI daily evaporative stress index, CONUS, V002 only (ECO_L4T_ESI_ALEXI)
layers=string[,string,...]
Layers to download, as named in the granule files (e.g. LST,LST_err,QC,cloud for lste; radiance_1..radiance_5 for rad), or all (default: the main layers of the product)
start=string [required]
Start date (YYYY-MM-DD, UTC)
end=string [required]
End date (YYYY-MM-DD, UTC, inclusive)
daynight=string
Overpasses to keep (the ISS orbit samples every local time of day)
Options: day, night, both
Default: both
version=string
Collection version (default: the newest version available for each acquisition)
Options: 002, 003
clouds=integer
Maximum cloudy percentage of the observed part of the region (requires -i)
Options: 0-100
coverage=integer
Minimum percentage of the region observed by the swath (requires -i)
Options: 0-100
output=string
Prefix for the download directory and the imported raster map names
Default: eco
output_dir=name
Directory to save downloaded layers (default: $HOME/RSDATA/ECOSTRESS_<output>)
token=string
NASA Earthdata Bearer token (default: EARTHDATA_TOKEN env var, or a TOKEN file in output_dir)
resample=string
Resampling method when reprojecting to the region grid (quality and mask layers always use nearest)
Options: nearest, bilinear, bicubic, lanczos
Default: nearest
strds=string
Prefix for Space-Time Raster Datasets of imported maps, one per layer, e.g. <strds>_lst (requires -i)
project=string
Name of a new GRASS project to create for the imported data (default: the project this module was launched from)
dbase=string
GRASS database directory in which to create the new project (default: the current GISDBASE); only used with project=
epsg=integer
EPSG code of the new project's CRS (default: the UTM zone of the first tile, the CRS ECOSTRESS tiles are delivered in); only used with project=

Table of contents

DESCRIPTION

r.in.ecostress downloads NASA ECOSTRESS (ECOsystem Spaceborne Thermal Radiometer Experiment on Space Station) thermal imagery for the current region and a date range, and optionally imports it into the current GRASS project or a new one. ECOSTRESS flies on the International Space Station, like EMIT, and its products are distributed the same way: the module searches NASA's Common Metadata Repository (CMR) and downloads from LP DAAC, as r.in.emit does.

It reads the tiled ECOSTRESS products: 70 m Cloud-Optimized GeoTIFFs on the Sentinel-2 MGRS tiling grid (110 km tiles in their UTM zone), one file per layer. Only the requested layers are downloaded. The swath (L1B, L2) and gridded (L1CG, L2G) HDF5 products are not supported.

A free NASA Earthdata account and Bearer token are needed (Earthdata login, User Profile, Generate Token). The token is read from token=, from the EARTHDATA_TOKEN environment variable, or from a file named TOKEN in output_dir.

g.region n=5640000 s=5630000 e=580000 w=570000 res=70 -a

r.in.ecostress start=2025-07-01 end=2025-07-31 daynight=day \
  output=be clouds=50 coverage=10 strds=be -i

Products and layers

product= selects the collection; layers= the layers to fetch, named as in the granule files. The default layers are:

product collection default layers
lste ECO_L2T_LSTE LST, LST_err, QC, cloud
rad ECO_L1CT_RAD radiance_1 ... radiance_5
jet ECO_L3T_JET ETdaily
etaux ECO_L3T_ETAUX (V003) all
esi ECO_L4T_ESI ESI, PET
wue ECO_L4T_WUE WUE, GPP
stars ECO_L2T_STARS NDVI, albedo
sm ECO_L3T_SM (V002) SM
met ECO_L3T_MET (V002) Ta, RH
seb ECO_L3T_SEB (V002) Rn, Rg
et_alexi ECO_L3T_ET_ALEXI (V002, CONUS) ETdaily, ETdailyUncertainty
esi_alexi ECO_L4T_ESI_ALEXI (V002, CONUS) ESIdaily, ESIdailyUncertainty

layers=all fetches every layer of the granules. Use -l to see the layers available. A requested layer that no granule holds stops the module with an error, listing the available layers; a layer missing from some acquisitions only (for example because V002 and V003 differ) gives a warning.

The tiled layers hold physical values, with no scale factor: LST in kelvin, with NaN (null) under clouds and outside the swath; the cloud and water masks are 0/1. QC is the bit-packed quality word described in the ECOSTRESS L2 user guide.

Overpasses

The ISS orbit is not sun-synchronous: ECOSTRESS sees a place at varying times of day and night, often several times a day. daynight= keeps day or night overpasses only.

One overpass of the region is one ISS orbit. Its swath is cut into scenes of about 52 seconds, so a region can be covered by several tiles, and by two consecutive scenes on the same tile. All the granules of one orbit are therefore grouped: each layer is imported once per overpass, with the tiles and scenes mosaicked with r.patch.

Collection versions

ECOSTRESS Collection 2 (V002) covers the whole mission; V003 is being produced and covers part of it. By default the newest version of each tile and acquisition is kept, so a time series can mix versions (the module warns when it does). version= restricts the search to one version. Duplicate granules of the same tile and time (other scene numbers or builds of the same data) are dropped the same way.

Search area

The search box is the current region, reprojected to WGS84 with g.region -b. CMR matches each tile on its bounding box; tiles that straddle the antimeridian get a box covering every longitude and would match any search, so their longitudes are checked against their UTM zone instead.

Import (-i)

With -i, each layer is imported with r.import using extent=region and resolution=region: the maps are reprojected onto the current region grid, so every map of a time series is aligned. resample= sets the method for continuous layers; QC, masks and flags always use nearest neighbour.

Map names are {output}_{layer}_{acquisition time}, with the layer in lower case, e.g. be_lst_20250725T164442 and be_lst_err_20250725T164442. Maps that already exist are kept unless --overwrite is given.

Each map gets its acquisition time (UTC, the start of the first scene of the overpass) with r.timestamp, its units (K for LST), and the granule titles and day/night flag in its metadata (r.info).

With strds=, a space-time raster dataset is created per layer, named {strds}_{layer}, e.g. be_lst, and the maps are registered with their timestamps.

Cloud and coverage filter

CMR has no cloud cover for ECOSTRESS. With -i, clouds= and coverage= measure each overpass over the region instead: the cloud mask and the first requested data layer are imported first. A cell is observed if it is flagged cloudy or the data layer has a value there (outside the swath, the cloud mask reads 0 and the data is null).

An overpass that fails is removed and its other layers are not downloaded. The cloud mask is removed afterwards unless it was among the requested layers.

Downloads

Layers are saved under output_dir (default $HOME/RSDATA/ECOSTRESS_{output}), in one directory per year, with the LP DAAC file names. Files already present are not downloaded again unless --overwrite is given. A layer tile is a few MB.

New project

project= creates (or reuses) a project under dbase= and imports there. Its CRS is the UTM zone of the first tile unless epsg= is given, and its region is set to the search area at 70 m. The search area always comes from the calling session's region.

EXAMPLES

List the night overpasses of a month, with their tiles and layers:

r.in.ecostress start=2025-07-01 end=2025-07-31 daynight=night -l

Import day-time LST with its error and quality layers, keeping overpasses that see at least half of the region with at most 20% cloud, into a time series:

r.in.ecostress start=2025-06-01 end=2025-08-31 daynight=day \
  layers=LST,LST_err,QC,cloud coverage=50 clouds=20 output=be strds=be -i
t.rast.list be_lst

Daily evapotranspiration of the same overpasses:

r.in.ecostress product=jet start=2025-06-01 end=2025-08-31 \
  coverage=50 clouds=20 output=be strds=be_et -i

Top-of-atmosphere radiance of the five thermal bands, V002 only:

r.in.ecostress product=rad version=002 start=2025-07-25 end=2025-07-25 -i

SEE ALSO

g.region, r.import, r.in.emit, r.in.landsat, r.in.sentinel, r.patch, r.timestamp, t.create, t.register

REFERENCES

AUTHORS

Yann Chemin

SOURCE CODE

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

Accessed: Sunday Nov 15 11:07:38 2026


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

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