t.rast.import.netcdf

Import netCDF files that adhere to the CF convention as STRDS.

t.rast.import.netcdf [-arlfeo] input=Input file(s) ("-" = stdin) [semantic_labels=Input file with configuration for semantic labels ("-" = stdin)] [output=name] [end_time=string] [start_time=string] [temporal_relations=string [,string,...]] [resample=string] [print=string] [color=style] [memory=memory in MB] [nprocs=Number of cores] [separator=character] [nodata=Source nodata [,Source nodata,...]] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

t.rast.import.netcdf input=Input file(s) ("-" = stdin) print=string

grass.script.run_command("t.rast.import.netcdf", input, semantic_labels=None, output=None, end_time=None, start_time=None, temporal_relations="equal,during,contains,overlaps,overlapped,starts,started,finishes,finished", resample="nearest", print=None, color="viridis", memory=300, nprocs=1, separator="pipe", nodata=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("t.rast.import.netcdf", input="Input file(s) ("-" = stdin)", print="string")

Parameters

Command linePython (grass.script)

input=Input file(s) ("-" = stdin) [required]
    URL or name of input netcdf-file ("-" = stdin)
semantic_labels=Input file with configuration for semantic labels ("-" = stdin)
    File with mapping of variables or subdatasets to semantic labels
output=name
    Name of the output space time raster dataset
end_time=string
    Latest timestamp of temporal extent to include in the output
    Timestamp of format "YYYY-MM-DD HH:MM:SS"
start_time=string
    Earliest timestamp of temporal extent to include in the output
    Timestamp of format "YYYY-MM-DD HH:MM:SS"
temporal_relations=string [,string,...]
    Allowed temporal relation for temporal filtering
    Allowed temporal relation between time dimension in the netCDF file and temporal window defined by start_time and end_time
    Allowed values: equal, during, contains, overlaps, overlapped, starts, started, finishes, finished
    Default: equal,during,contains,overlaps,overlapped,starts,started,finishes,finished
resample=string
    Resampling method when data is reprojected
    Allowed values: nearest, bilinear, bicubic, cubicspline, lanczos, average, mode, max, min, med, Q1, Q3
    Default: nearest
print=string
    Print metadata and exit
    Allowed values: extended, grass
color=style
    Color table to assign to imported datasets
    Allowed values: aspect, aspectcolr, bcyr, bgyr, blues, byg, byr, celsius, corine, curvature, differences, elevation, etopo2, evi, fahrenheit, forest_cover, gdd, grass, greens, grey, grey.eq, grey.log, grey1.0, grey255, gyr, haxby, inferno, kelvin, magma, ndvi, ndwi, nlcd, oranges, plasma, population, population_dens, precipitation, precipitation_daily, precipitation_monthly, rainbow, ramp, random, reds, roygbiv, rstcurv, ryb, ryg, sepia, slope, soilmoisture, srtm, srtm_percent, srtm_plus, terrain, viridis, water, wave
    Default: viridis
             aspect: aspect oriented grey colors [range: map values]
             aspectcolr: aspect oriented rainbow colors [range: 0 to 360]
             bcyr: blue through cyan through yellow to red [range: map values]
             bgyr: blue through green through yellow to red [range: map values]
             blues: white to blue [range: map values]
             byg: blue through yellow to green [range: map values]
             byr: blue through yellow to red [range: map values]
             celsius: blue to red for degree Celsius temperature [range: -80 to 80]
             corine: EU Corine land cover colors [range: 111 to 995]
             curvature: for terrain curvatures (from v.surf.rst and r.slope.aspect) [range: map values]
             differences: differences oriented colors [range: map values]
             elevation: maps relative ranges of raster values to elevation color ramp [range: map values]
             etopo2: colors for ETOPO2 worldwide bathymetry/topography [range: -11000 to 8850]
             evi: enhanced vegetative index colors [range: -1 to 1]
             fahrenheit: blue to red for Fahrenheit temperature [range: -112 to 176]
             forest_cover: percentage of forest cover [range: 0 to 100]
             gdd: accumulated growing degree days [range: 0 to 6000]
             grass: GRASS GIS green (perceptually uniform) [range: map values]
             greens: white to green [range: map values]
             grey: grey scale [range: map values]
             grey.eq: histogram-equalized grey scale [range: map values]
             grey.log: histogram logarithmic transformed grey scale [range: map values]
             grey1.0: grey scale for raster values between 0.0-1.0 [range: 0 to 1]
             grey255: grey scale for raster values between 0-255 [range: 0 to 255]
             gyr: green through yellow to red [range: map values]
             haxby: relative colors for bathymetry or topography [range: map values]
             inferno: perceptually uniform sequential color table inferno [range: map values]
             kelvin: blue to red for temperature in Kelvin scale [range: 193.15 to 353.15]
             magma: perceptually uniform sequential color table magma [range: map values]
             ndvi: Normalized Difference Vegetation Index colors [range: -1 to 1]
             ndwi: Normalized Difference Water Index colors [range: -200 to 200]
             nlcd: US National Land Cover Dataset colors [range: 0 to 95]
             oranges: white to orange [range: map values]
             plasma: perceptually uniform sequential color table plasma [range: map values]
             population: color table covering human population classification breaks [range: 0 to 2e+09]
             population_dens: color table covering human population density classification breaks [range: 0 to 1e+09]
             precipitation: precipitation color table (0..2000mm) [range: 0 to 7000]
             precipitation_daily: precipitation color table (0..1000mm) [range: 0 to 10000]
             precipitation_monthly: precipitation color table (0..1000mm) [range: 0 to 1000]
             rainbow: rainbow color table [range: map values]
             ramp: color ramp [range: map values]
             random: random color table [range: map values]
             reds: white to red [range: map values]
             roygbiv: [range: map values]
             rstcurv: terrain curvature (from r.resamp.rst) [range: map values]
             ryb: red through yellow to blue [range: map values]
             ryg: red through yellow to green [range: map values]
             sepia: yellowish-brown through to white [range: map values]
             slope: r.slope.aspect-type slope colors for raster values 0-90 [range: 0 to 90]
             soilmoisture: soilmoisture color table (0.0-1.0) [range: 0 to 1]
             srtm: color palette for Shuttle Radar Topography Mission elevation [range: -11000 to 8850]
             srtm_percent: color palette for Shuttle Radar Topography Mission using relative elevation [range: map values]
             srtm_plus: color palette for Shuttle Radar Topography Mission elevation (with seafloor colors) [range: -11000 to 8850]
             terrain: global elevation color table covering -11000 to +8850m [range: -11000 to 8850]
             viridis: perceptually uniform sequential color table viridis [range: map values]
             water: water depth [range: map values]
             wave: color wave [range: map values]
memory=memory in MB
    Maximum memory to be used (in MB)
    Cache size for raster rows
    Default: 300
nprocs=Number of cores
    Number of cores to use during import
    Default: 1
separator=character
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Default: pipe
nodata=Source nodata [,Source nodata,...]
    Comma separated list of values representing nodata in the input dataset
-a
    Append to STRDS
-r
    Import only within current region
-l
    Link the raster files using r.external
-f
    Link the raster files in a fast way, without reading metadata using r.external
-e
    Extend location extents based on new dataset
-o
    Override projection check (use current location's projection)
    Assume that the dataset has same projection as the current location
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

input : str, required
    URL or name of input netcdf-file ("-" = stdin)
    Used as: input, file, Input file(s) ("-" = stdin)
semantic_labels : str, optional
    File with mapping of variables or subdatasets to semantic labels
    Used as: input, file, Input file with configuration for semantic labels ("-" = stdin)
output : str, optional
    Name of the output space time raster dataset
    Used as: output, strds, name
end_time : str, optional
    Latest timestamp of temporal extent to include in the output
    Timestamp of format "YYYY-MM-DD HH:MM:SS"
start_time : str, optional
    Earliest timestamp of temporal extent to include in the output
    Timestamp of format "YYYY-MM-DD HH:MM:SS"
temporal_relations : str | list[str], optional
    Allowed temporal relation for temporal filtering
    Allowed temporal relation between time dimension in the netCDF file and temporal window defined by start_time and end_time
    Allowed values: equal, during, contains, overlaps, overlapped, starts, started, finishes, finished
    Default: equal,during,contains,overlaps,overlapped,starts,started,finishes,finished
resample : str, optional
    Resampling method when data is reprojected
    Allowed values: nearest, bilinear, bicubic, cubicspline, lanczos, average, mode, max, min, med, Q1, Q3
    Default: nearest
print : str, optional
    Print metadata and exit
    Allowed values: extended, grass
color : str, optional
    Color table to assign to imported datasets
    Used as: input, colortable, style
    Allowed values: aspect, aspectcolr, bcyr, bgyr, blues, byg, byr, celsius, corine, curvature, differences, elevation, etopo2, evi, fahrenheit, forest_cover, gdd, grass, greens, grey, grey.eq, grey.log, grey1.0, grey255, gyr, haxby, inferno, kelvin, magma, ndvi, ndwi, nlcd, oranges, plasma, population, population_dens, precipitation, precipitation_daily, precipitation_monthly, rainbow, ramp, random, reds, roygbiv, rstcurv, ryb, ryg, sepia, slope, soilmoisture, srtm, srtm_percent, srtm_plus, terrain, viridis, water, wave
             aspect: aspect oriented grey colors [range: map values]
             aspectcolr: aspect oriented rainbow colors [range: 0 to 360]
             bcyr: blue through cyan through yellow to red [range: map values]
             bgyr: blue through green through yellow to red [range: map values]
             blues: white to blue [range: map values]
             byg: blue through yellow to green [range: map values]
             byr: blue through yellow to red [range: map values]
             celsius: blue to red for degree Celsius temperature [range: -80 to 80]
             corine: EU Corine land cover colors [range: 111 to 995]
             curvature: for terrain curvatures (from v.surf.rst and r.slope.aspect) [range: map values]
             differences: differences oriented colors [range: map values]
             elevation: maps relative ranges of raster values to elevation color ramp [range: map values]
             etopo2: colors for ETOPO2 worldwide bathymetry/topography [range: -11000 to 8850]
             evi: enhanced vegetative index colors [range: -1 to 1]
             fahrenheit: blue to red for Fahrenheit temperature [range: -112 to 176]
             forest_cover: percentage of forest cover [range: 0 to 100]
             gdd: accumulated growing degree days [range: 0 to 6000]
             grass: GRASS GIS green (perceptually uniform) [range: map values]
             greens: white to green [range: map values]
             grey: grey scale [range: map values]
             grey.eq: histogram-equalized grey scale [range: map values]
             grey.log: histogram logarithmic transformed grey scale [range: map values]
             grey1.0: grey scale for raster values between 0.0-1.0 [range: 0 to 1]
             grey255: grey scale for raster values between 0-255 [range: 0 to 255]
             gyr: green through yellow to red [range: map values]
             haxby: relative colors for bathymetry or topography [range: map values]
             inferno: perceptually uniform sequential color table inferno [range: map values]
             kelvin: blue to red for temperature in Kelvin scale [range: 193.15 to 353.15]
             magma: perceptually uniform sequential color table magma [range: map values]
             ndvi: Normalized Difference Vegetation Index colors [range: -1 to 1]
             ndwi: Normalized Difference Water Index colors [range: -200 to 200]
             nlcd: US National Land Cover Dataset colors [range: 0 to 95]
             oranges: white to orange [range: map values]
             plasma: perceptually uniform sequential color table plasma [range: map values]
             population: color table covering human population classification breaks [range: 0 to 2e+09]
             population_dens: color table covering human population density classification breaks [range: 0 to 1e+09]
             precipitation: precipitation color table (0..2000mm) [range: 0 to 7000]
             precipitation_daily: precipitation color table (0..1000mm) [range: 0 to 10000]
             precipitation_monthly: precipitation color table (0..1000mm) [range: 0 to 1000]
             rainbow: rainbow color table [range: map values]
             ramp: color ramp [range: map values]
             random: random color table [range: map values]
             reds: white to red [range: map values]
             roygbiv: [range: map values]
             rstcurv: terrain curvature (from r.resamp.rst) [range: map values]
             ryb: red through yellow to blue [range: map values]
             ryg: red through yellow to green [range: map values]
             sepia: yellowish-brown through to white [range: map values]
             slope: r.slope.aspect-type slope colors for raster values 0-90 [range: 0 to 90]
             soilmoisture: soilmoisture color table (0.0-1.0) [range: 0 to 1]
             srtm: color palette for Shuttle Radar Topography Mission elevation [range: -11000 to 8850]
             srtm_percent: color palette for Shuttle Radar Topography Mission using relative elevation [range: map values]
             srtm_plus: color palette for Shuttle Radar Topography Mission elevation (with seafloor colors) [range: -11000 to 8850]
             terrain: global elevation color table covering -11000 to +8850m [range: -11000 to 8850]
             viridis: perceptually uniform sequential color table viridis [range: map values]
             water: water depth [range: map values]
             wave: color wave [range: map values]
    Default: viridis
memory : int, optional
    Maximum memory to be used (in MB)
    Cache size for raster rows
    Used as: memory in MB
    Default: 300
nprocs : int, optional
    Number of cores to use during import
    Used as: Number of cores
    Default: 1
separator : str, optional
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
    Default: pipe
nodata : str | list[str], optional
    Comma separated list of values representing nodata in the input dataset
    Used as: Source nodata
flags : str, optional
    Allowed values: a, r, l, f, e, o
    a
        Append to STRDS
    r
        Import only within current region
    l
        Link the raster files using r.external
    f
        Link the raster files in a fast way, without reading metadata using r.external
    e
        Extend location extents based on new dataset
    o
        Override projection check (use current location's projection)
        Assume that the dataset has same projection as the current location
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

t.rast.import.netcdf imports content of one or more NetCDF files into a GRASS GIS Space Time Raster Dataset (STRDS). NetCDF files are expected to follow the CF-convention. Files not adhering to those standards may fail to import.

Input URL(s) to NetCDF files can be provided in the input option as either a file, with one URL to a dataset per line, a comma-separated list of URLs or a single URL. "-" causes input to be taken from stdin.

The module works for both local and remote data (e.g. on a Thredds Server). Data can be imported via r.in.gdal or linked with r.external.

t.rast.import.netcdf uses GDALs Virtual Raster format (VRT) if data's Coordinate Reference system differs from the one of the current location where they are supposed to be imported.

Reprojection on import is done using GDAL warp if necessary. In that case, users should be aware of the extent and resolution of the data to import and the current computational region. Import is limited to and aligned with the current computational region, if the r-flag is set. Otherwise, extent and resolution in the target CRS is guessed by GDAL. Import of global data to coordinate systems that do not support that extent will thus fail.

Starting with GRASS GIS version 8.0, different variables or subdatasets in a NetCDF file can be imported as "semantic_label" into one STRDS. To achieve this, a configuration file has to be provided in the semantic_labels option. That configuration file maps subdatasets in the NetCDF file to GRASS GIS semantic_labels. Each line in that file must have the following format: input_netcdf_subdataset=grass_gis_semantic_label The equal sign = is required. If a semantic_labels configuration file is provided, the import of subdatasets is limited to those subdatasets listed in the file. Hence, it can be used to filter variables of interest.

KNOWN ISSUES

The VRT format is also used when linking NetCDF data that contains subdatasets, as subdatasets are currently not supported in r.external.

Reading NetCDF files directly via HTTP protocol (like in the examples below) is currently not supported on MS Windows.

GDAL versions prior to 3.4.1 do not support reading NetCDF files directly via HTTP protocol on newer Linux kernels either. Please make sure to have at least GDAL version 3.4.1 on recent Linux systems. See posts on the GDAL-dev mailing list. for reference.

REQUIREMENTS

Support of semantic_labels is only available with GRASS GIS 8.0 or later. t.rast.import.netcdf uses the following non-standard Python modules:

numpy
GDAL (preferably version >= 3.4.1)
cf-units

EXAMPLES

Link Sentinel-2 scenes from the Norwegian Ground Segment

# Choose Scenes to import (see also m.crawl.thredds module)
echo "https://nbstds.met.no/thredds/fileServer/NBS/S2A/2021/02/28/S2A_MSIL1C_20210228T103021_N0202_R108_T35WPU_20210228T201033_DTERRENGDATA.nc
https://nbstds.met.no/thredds/fileServer/NBS/S2A/2021/02/28/S2A_MSIL1C_20210228T103021_N0202_R108_T32VNL_20210228T201033_DTERRENGDATA.nc" > nc.txt

# Create a semantic_label configuration file
echo "B1=S2_1
B2=S2_2" > semantic_labels.conf

# Import data (link NetCDF files without downloading them)
t.rast.import.netcdf -l input=nc.txt output=S2A semantic_labels=semantic_labels.conf \
memory=2048 nprocs=2 nodata="-1"

Import Norwegian Climate data

# Create a semantic_label configuration file
echo "tg=temperature_avg
tn=temperature_min" > semantic_labels.conf

# Import data within a selected time window
t.rast.import.netcdf output=SeNorge semantic_labels=semantic_labels.conf \
memory=2048 nprocs=2 start_time="2020-08-01" end_time="2021-08-01" \
input=https://thredds.met.no/thredds/fileServer/senorge/seNorge_2018/Archive/seNorge2018_2020.nc

Append to STRDS from previous imports

# Choose dataset to import (see also m.crawl.thredds module)

# Create a semantic_label configuration file
echo "tg=temperature_avg
tn=temperature_min" > semantic_labels.conf

# Import data within a selected time window
t.rast.import.netcdf output=SeNorge semantic_labels=semantic_labels.conf \
memory=2048 nprocs=2 -a start_time="2020-08-01" end_time="2021-08-01" \
input=https://thredds.met.no/thredds/fileServer/senorge/seNorge_2018/Archive/seNorge2018_2021.nc

TODO

Capture and store extended metadata in a way that allows for filtering of relevant maps.
Improve printing of metadata and file structure
Support more options of Virtual Raster files (data type, ...)

AUTHORS

Stefan Blumentrath, Norwegian Institute for Nature Research (NINA), Oslo

SOURCE CODE

Available at: t.rast.import.netcdf source code (history)
Latest change: Friday Feb 21 10:10:05 2025 in commit 7d78fe3