i.pytorch.predict - GRASS manual

NAME

i.pytorch.predict - Apply Deep Learning model to imagery group using pytorch

KEYWORDS

raster, imagery, deep learning, pytorch, unet, GPU, predict

SYNOPSIS

i.pytorch.predict

i.pytorch.predict --help

i.pytorch.predict [-cl] input=name [auxillary_group=name] [reference_group=name] model=name model_code=name [vector_tiles=name] [tile_size=integer[,integer,...]] [overlap=integer] [mask_json=name] configuration=name [nprocs=integer] output=name [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-c: Use CPU as device for prediction, default is use cuda (GPU) if detected
-l: Limit output to valid range (data outside the valid range is set to valid min/max)
--overwrite: Allow output files to overwrite existing files
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

input=name [required]: Input imagery group
auxillary_group=name: Input imagery group with auxillary data
reference_group=name: Reference imagery group (usually a complementary to the input group but from a different point in time)
model=name [required]: Path to input deep learning model file (.pt)
model_code=name [required]: Path to input deep learning model code (.py)
vector_tiles=name: Name of input vector map; Vector map with tiles to process (will be extended by "overlap")
tile_size=integer[,integer,...]: Number of rows and columns in tiles
overlap=integer: Number of rows and columns of overlap in tiles
mask_json=name: JSON file with one or more mask band or map name(s) and reclass rules for masking, e.g. {"mask_band": "1 thru 12 36 = 1", "mask_map": "0"}
configuration=name [required]: Path to JSON file with band configuration in the input deep learning model
nprocs=integer: Number of threads for parallel computing; 0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs; Default: 0
output=name [required]: Name for output raster map

DESCRIPTION
CONFIGURATION
NOTES
EXAMPLES
REQUIREMENTS
AUTHOR

DESCRIPTION

i.pytorch.predict applies a pre-trained, saved deep learning model developed with pytorch to an imagery group.

Typically, application of deep learning models requires both the model file and associated code. The directory from wich the associated code can be loaded has to be given in the model_code option.

This module requires in addition meta-information in JSON format, in the configuration option describing the model together with it`s input and output.

The imagery group provided in the input option has to contain raster maps for all bands required by the deep learning model. Raster maps are matched to the input bands using semantic labels and based on the meta information provided in the configuration option. In addition, an auxillary_group and a reference_group can be provided. Those options can be useful if e.g. input data from different points in time, with the same, semantic labels are supposed to be fed to model. Often, collecting all input bands in the input group can be sufficient.

CONFIGURATION

The configuration is a JSON file that contains relevant information for initialisation of the model and describes all relevant input variables, potentially together with auxillary or reference data, that are needed for applying the given deep learning model. The JSON file also describes the output bands accordingly. It is excpected to be structure as follows:

  {"model":  # Dictinary matching the parameters of the signature of the UNet model code
  {
   "model_backbone": "backbones.UNetV1",  # Name of the module and class representing the UNet model in the model code directory
   "model_name": "NVECOP2-CNN",
   "model_version": "v1.0",
   "model_dimensions": {"input_dimensions": "NCHW", "output_dimensions": "NCHW"}, # string representation of the dimensions of expected model input and output
       # N: Number of images in batch
       # H: Height of the images
       # W: Width of the images
       # C: Number of channels / bands of the images
   # Keys below depend on the UNet model code, which should consequently use keyword arguments with defined data type and defaults for all parameters
   "n_classes": 2,
   "depth": 5,
   "start_filts": 32,
   "up_mode": "bilinear",
   "merge_mode": "concat",
   "partial_conv": True,
   "use_bn": True,
   "activation_func": "lrelu"
   },
"input_bands": {  # dictionary describing the input bands expected by the model
   'S1_reflectance_an':  {  # input band name / key (to be matched to semantic labels)
       "order": 1,  # position in the input data cube to the DL model
       "offset": 0,  # Offset to be applied to the values in the input band, (0 means no offset)
       "scale": 1,  # Scale to be applied to the values in the input band, after offset (1 means no scaling)
       "valid_range": [None, 2],  # Tuple with valid range (min, max) of the input data with scale and offset applied, (None means inf for max and -inf for min)
       "fill_value": 0,  # Value to replace NoData value with
       "description": "Sentinel-3 SLSTR band S1 scaled to reflectance values",  # Human readable description of the band that is expected as input
       },
   'S2_reflectance_an':  {"order": 2, "offset": 0, "scale": 1, "valid_range": [None, 2], "fill_value": 0, "description": "Sentine-3 SLSTR band S1 in reflectance values"},
   'S3_reflectance_an':  {"order": 3, "offset": 0, "scale": 1, "valid_range": [None, 2], "fill_value": 0, "description": "Sentine-3 SLSTR band S1 in reflectance values"},
   'S5_reflectance_an':  {"order": 4, "offset": 0, "scale": 1, "valid_range": [None, 2], "fill_value": 0, "description": "Sentine-3 SLSTR band S1 in reflectance values"},
   'S6_reflectance_an':  {"order": 5, "offset": 0, "scale": 1, "valid_range": [None, 2], "fill_value": 0, "description": "Sentine-3 SLSTR band S1 in reflectance values"},
   'S8_BT_in':  {"order": 6, "offset": -200, "scale": 100, "valid_range": None, "fill_value": 0, "description": "Sentine-3 SLSTR band S1 in reflectance values"},
   'S9_BT_in':  {"order": 7, "offset": -200, "scale": 100, "valid_range": None, "fill_value": 0, "description": "Sentine-3 SLSTR band S1 in reflectance values"},
   },
"output_bands":  # This section contains meta information about output bands from the DL model, each output band should have a description
   {
       "fsc": {
           "title": "Fractional Snow Cover (FSC)",
           "standard_name": "surface_snow_area_fraction",  # https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html
           "description": ("The NVECOP2-CNN FSC algorithm is developed by NR in
               "the AI4Arctic project based on a CNN."
               "A modified version of the UNet has been applied and trained with"
               "selected and quality-controlled 10-m resolution snow maps based"
               "on Sentinel-2."
               "The FSC product provides regular information on snow "
               "cover fraction (0-100 %) per grid cell for the given "
               "land area except for land ice areas. The product is "
               "based on reflectance values from Sentinel-3 SLSTR RBT product,"
               "bands 1,2,3,5, and 6 at 500m resolution"),
           "units": "percent",  # ideally CF-compliant name or symbol: https://ncics.org/portfolio/other-resources/udunits2/
           "valid_output_range": [0,100],
           "dtype": "uint8",  # string representing the numpy dtype ("uint8", "int8", "uint16", "int16", "uint32", "int32", "float32", "float64")
           "fill_value": 255  # Value representing NoData
           "offset": 0,  # Offset to be applied to the values in the output band, (0 means no offset)
           "scale": 1,  # Scale to be applied to the values in the output band, after offset (1 means no scaling)
           "classes": None,  # class values and names if output band contains classes, e.g. {0: "bare land", 1: "snow cover", 2: "waterbody", 3: "cloud"}
           },
   },
}

NOTES

All raster maps in the input groups are expected to have semantic_labels assigned to them, because the semantic_labels are used to match the bands to the model. Processing on GPU may require a smaller tile_size setting in order to fit data to available GPU memory. Smaller tile sizes however lead to an increased number of temporary data. Users may encounter "Too many open files" error in such cases, esp. when results are patched in parallel as well. See the r.patch manual for ways to circumvent those issues. In general, processing on GPU is significantly faster, and lager tile sizes are processed faster than smaller ones. However, the tile_size setting can be optimized to match closer to the height and width ratio of the current region.

EXAMPLES

i.pytorch.predict input="Sentinel_3_2023_11_13" model="./fsc.pt" \
  nodel_code=./unet configuration="./fsc_config.json" \
  nprocs=8 tile_size="1024,1024" output="S3_SLSTR_2023_11_13"

REQUIREMENTS

i.pytorch.predict uses the following non-standard Python libraries:

The pytorch Python library
The numpy Python library
An internal "pytorchlib" library

AUTHOR

Stefan Blumentrath, NVE

SOURCE CODE

Available at: i.pytorch.predict source code (history)

Accessed: Monday Jul 27 12:22:31 2026