Block capabilities

Introduction

When adding blocks to a workflow, the combination is limited, which means that a block can only be connected to certain other blocks. These constraints are called block capabilities. Block capabilities define the order of the blocks added to a workflow and dictate which blocks match by specifying the parameter values necessary to allow the combination of blocks: spectral or spatial resolution, file format, bit depth etc. Block capabilities are divided into input and output capabilities.

The blocks connect with each other if their input and output capabilities match. For example, a block that outputs a GeoTIFF is compatible with the next block that accepts GeoTIFF as input. Another example is when a processing block based on a machine learning model divides the image into smaller tiles, in order to parallelize the computation and save memory. If you want to make the tiling process a mandatory step of the workflow, you need to specify it in the manifest. For instance, the processing block Ship Detection exclusively accepts input data as image tiles of 768 x 768 pixels.

Block capabilities differ between data and processing blocks. The data block is the first block in a workflow and it only has an output capability. The processing block always follows a data block, so it has both an input and an output capability.

In this guide, we will delve into how to specify capabilities and view more examples below.

Specification

Block capabilities are specified in the block manifest, a JSON file that contains the block metadata.

Input capabilities define what data types are accepted as inputs.

Output capabilities define what kind of data types are generated by a block.

Block capabilities are validated during the job configuration of a workflow. For a given sequence of blocks in a workflow, the output capabilities of the first block must match the input capabilities of the next block. The capabilities can be left empty under the following conditions:

Input capabilities are empty for the first block of a workflow.
Output capabilities are empty for the last block of a workflow.

In the workflow below, block A1 has no input capabilities and block A2 has no output capabilities:

Block A1 -> Block A2

This means that block A2 cannot be added after block A1:

Block A0 -> Block A1 -> Block A2

This means that block A0 cannot be added before block A1:

Block A0 -> Block A1

Here is an example manifest for block A1.

{
  "_up42_specification_version": 2,
  "name": "A1",
  "type": "data",
  "display_name": "My custom A1 block",
  "description": "Provides data from the foo satellite.",
  "parameters": {
    "ids": {
      "type": "array",
      "default": null
    },
    "bbox": {
      "type": "array",
      "default": null
    },
    "intersects": {
      "type": "geometry"
    },
    "contains": {
      "type": "geometry"
    },
    "time": {
      "type": "dateRange",
      "default": "2018-01-01T00:00:00+00:00/2020-12-31T23:59:59+00:00"
    },
    "time_series": {
      "type": "array",
      "default": null
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "default": 1
    },
    "acquisition_mode": {
      "type": "string",
      "default": null
    },
    "orbit_direction": {
      "type": "string",
      "default": null
    }
  },
  "machine": {
    "type": "small"
  },
  "optional_features": {
    "quicklook_supported": true,
    "dry_run_supported": true
  },
  "input_capabilities": {}, // empty input capabilities: block is first in a workflow
  "output_capabilities": {
    "raster": {
      "up42_standard": {
        "format": "SAFE",
        "sensor": "Sentinel1GRD",
        "dtype": "uint16",
        "resolution": 10,
        "bands": {
          "or": [
            ["HH", "HV", "alpha"],
            ["VV", "VH", "alpha"],
            ["HH", "alpha"],
            ["VV", "alpha"]
          ]
        },
        "processing_level": "l1"
      }
    }
  }
}

Here is an example manifest for block A2.

{
  "_up42_specification_version": 2,
  "name": "A2",
  "type": "processing",
  "display_name": "My custom A2 block",
  "description": "Computes the number of quux in a foo satellite image.",
  "parameters": {
    "minutes": {
      "type": "number",
      "default": 25
    },
    "max_features": {
      "type": "number",
      "default": 1000
    }
  },
  "machine": {
    "type": "medium"
  },
  "input_capabilities": {
    "vector": {
      "up42_standard": {
        "format": "GeoJSON",
        "geometry_type": "Polygon"
      },
      "custom": {
        "object_type": "ship"
      }
    }
  },
  "output_capabilities": {} // empty output capabilities: block is last in a workflow
}

Operators

A capability is specified as a nested JSON object. The capabilities are defined with specific keys or operators. The table below shows examples of operators.

Operator	Description	Example
`>`	The propagation operator, used when the value of an output capability key is propagated to the output capabilities of the following block.	Pansharpening
`or`	The boolean OR operator. Given an array of values for a key, the key has to match at least one of the values.	SNAP Polarimetric Processing Sentinel-1
`${parameter}`	Injects the value(s) of parameters from the job configuration into the capabilities. This operator is to be used when a value specified in the job parameters is to be injected at execution time into the capabilities.	Raster Tiling

The propagation operator > can only be used in output capabilities. Trying to use it in input capabilities will result in it being treated as a string and consequently the resulting behaviour of the block will be unpredictable.

Meta capabilities

Meta capabilities are always at the root of the block capability definition and they precede all other keys in the tree representing the JSON object for a capability.

Meta capabilities correspond to the possible types of data that can be created and/or consumed inside a given workflow.

The supported meta capabilities are presented in the table below.

Meta capability	Description
`raster`	An image file format.
`vector`	A vector file format.
`misc`	A miscellaneous file format: CSV, XML, or JSON.

A meta capability needs to contain at least one of the following fields to be valid:

Meta capability	Description
`up42_standard`	A capability definition that conforms to the UP42 standard.
`custom`	A custom capability that is not included in the UP42 standard.

UP42 standard meta capabilities

Raster capabilities

Parameter	Definition	Example
`format`	File input/output format.	GTiff (GeoTIFF) SAFE DIMAP NetCDF
`dtype`	Data type according to the C99 language specification. Fixed width integers and floats.	uint8 uint16 float
`sensor`	Name of the sensor (satellite, aircraft, drone etc.) and product type (for satellite images). The possible values are constantly updated, according to the newest data sources being added.	Pleiades SPOT Sentinel1GRD (Sentinel 1 GRD) Sentinel1SLC (Sentinel 1 SLC) Sentinel2 Sentinel3 Sentinel 5P Landsat8 MODIS Meteomatics Hexagon
`resolution`	The spatial resolution of the image (in meters). For blocks providing multiple spectral bands, the value corresponds to the highest resolution possible. This value can be either an unsigned integer or a float.	10 0.5
`bands`	Array of bands (for optical images) or polarizations (for radar images) provided by the block.	red green blue nir (near infrared) nir2 (additional near infrared band) pan (panchromatic) ndvi (NDVI output band) dem (digital elevation model) alpha (image transparency band) coastal rededge (red edge band) rededge2 (additional red edge band) watervapour (water vapour band) swir (short wave infrared band) swir2 (additional short wave infrared band) swir3 (another additional short wave infrared band) HH (horizontal-horizontal polarization) VV (vertical-vertical polarization) HV (horizontal-vertical polarization) VH (vertical-horizontal polarization)
`processing_level`	The processing level of the image product.	l1 (encompasses Levels 1A, 1B and 1C) l2 (encompasses Levels 2A and 2B) l3 (encompasses Levels 3A and 3B)
`tile_width`	The tile width (in pixels) for a block that requires tiling (input capability) or provides tiling (output capability).	768
`tile_height`	The tile height (in pixels) for a block that requires tiling (input capability) or provides tiling (output capability).	1032

For more information, please refer to the full raster specification and raster types.

Vector capabilities

Parameter	Definition	Example
`format`	File input/output format.	GeoJSON Shapefile KML KMZ
`geometry_type`	Possible vector types for GeoJSON.	Point Line Polygon MultiPoint MultiLine MultiPolygon

For more information, please refer to the full vector specification and vector types.

Misc capabilities

Parameter	Definition	Example
`format`	File input/output format.	csv (Comma Separated Values) xml (XML) json (JSON)

For more information, please refer to the full misc specification and types.

The full list of built-in capabilities is available as part of the block manifest JSON schema.

Custom meta capabilities

You may specify your own capability keys. This might be needed in the case of:

Adding extra keys to better constrain the workflow construction.
The built-in keys do not contemplate your use case.

Examples

Pansharpening block manifest

{
  "_up42_specification_version": 2,
  "name": "pansharpen",
  "type": "processing",
  "tags": ["imagery", "processing", "preprocessing"],
  "display_name": "Pansharpening SPOT/Pléiades",
  "description": "Pansharpens images from Pléiades or SPOT.",
  "parameters": {
    "method": {
      "type": "string",
      "default": "SFIM"
    },
    "include_pan": {
      "type": "boolean",
      "default": false
    }
  },
  "machine": {
    "type": "large"
  },
  "input_capabilities": {
    "raster": {
      "up42_standard": {
        "format": "DIMAP",
        "sensor": {
          "or": ["Pleiades", "SPOT"]
        },
        "bands": ["red", "green", "blue", "nir", "pan"]
      }
    }
  },
  "output_capabilities": {
    "raster": {
      "up42_standard": {
        "format": "GTiff",
        "bands": {
          "or": [
            ["red", "green", "blue", "nir"],
            ["red", "green", "blue", "nir", "pan"]
          ]
        },
        "sensor": ">", // propagate from input capabilities
        "resolution": ">",
        "processing_level": ">",
        "dtype": ">"
      }
    }
  }
}

Sentinel-1 L1 GRD (SAFE) block manifest

{
  "_up42_specification_version": 2,
  "name": "sentinel-1-grd-fullscene",
  "type": "data",
  "tags": ["Airbus", "Sobloo", "Sentinel", "C-band", "SAR", "Copernicus", "global", "high resolution", "environment"],
  "display_name": "Sentinel-1 L1C GRD Full Scenes",
  "description": "Provides Sentinel-1 L1C GRD Full Scenes data in SAFE format.",
  "parameters": {
    "ids": {
      "type": "array",
      "default": null
    },
    "bbox": {
      "type": "array",
      "default": null
    },
    "intersects": {
      "type": "geometry"
    },
    "contains": {
      "type": "geometry"
    },
    "time": {
      "type": "dateRange",
      "default": "2018-01-01T00:00:00+00:00/2020-12-31T23:59:59+00:00"
    },
    "time_series": {
      "type": "array",
      "default": null
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "default": 1
    },
    "acquisition_mode": {
      "type": "string",
      "default": null
    },
    "orbit_direction": {
      "type": "string",
      "default": null
    }
  },
  "machine": {
    "type": "small"
  },
  "optional_features": {
    "quicklook_supported": true,
    "dry_run_supported": true
  },
  "input_capabilities": {},
  "output_capabilities": {
    "raster": {
      "up42_standard": {
        "format": "SAFE",
        "sensor": "Sentinel1GRD",
        "dtype": "uint16",
        "resolution": 10,
        "bands": {
          "or": [ // or operator, all the possible band/polarization combinations
            ["HH", "HV", "alpha"],
            ["VV", "VH", "alpha"],
            ["HH", "alpha"],
            ["VV", "alpha"]
          ]
        },
        "processing_level": "l1"
      }
    }
  }
}

Raster Tiling block manifest

{
  "_up42_specification_version": 2,
  "name": "tiling",
  "type": "processing",
  "tags": ["imagery", "preprocessing", "machine learning"],
  "display_name": "Raster Tiling",
  "description": "Clips rasters into tiles for machine learning algorithms.",
  "parameters": {
    "tile_width": {
      "type": "number",
      "required": true,
      "description": "Width of a tile in pixels",
      "default": 768
    },
    "tile_height": {
      "type": "number",
      "required": true,
      "description": "Height of a tile in pixels",
      "default": 768
    },
    "match_extents": {
      "type": "boolean",
      "required": false,
      "description": "If set to true, tile extents of all input layers will match (default false)",
      "default": false
    },
    "augmentation_factor": {
      "type": "number",
      "required": false,
      "description": "Factor used to create additional tiles by applying a pixel offset (default 1)",
      "default": 1
    },
    "output_prefix": {
      "type": "string",
      "required": false,
      "description": "Prefix of tile names, default is to use input filename",
      "default": ""
    },
    "discard_empty_tiles": {
      "type": "boolean",
      "required": false,
      "description": "If set to True, tiles that only consist of nodata (as defined by an alpha band or a set nodata value) will not be returned.",
      "default": true
    },
    "nodata": {
      "type": "number",
      "required": false,
      "description": "Value representing nodata within each raster band. If not set, defaults to the nodata value of the input raster.",
      "default": null
    }
  },
  "machine": {
    "type": "medium"
  },
  "input_capabilities": {
    "raster": {
      "up42_standard": {
        "format": "GTiff"
      }
    }
  },
  "output_capabilities": {
    "raster": {
      "up42_standard": {
        "format": "GTiff",
        "bands": ">",
        "resolution": ">",
        "sensor": ">",
        "dtype": ">",
        "processing_level": ">",
        "tile_width": "${tile_width}", // inject values from job parameters
        "tile_height": "${tile_height}"
      },
      "custom": {
        "match_extents": "${match_extents}"
      }
    }
  }
}

SNAP Polarimetric Processing Sentinel-1 block manifest

{
  "_up42_specification_version": 2,
  "name": "snap-polarimetric",
  "type": "processing",
  "tags": ["snap", "polarimetric", "preprocessing"],
  "display_name": "SNAP Polarimetric Processing",
  "description": "This block provides a common polarimetric processing workflow with SNAP that operates ESA SAFE format scenes.",
  "parameters": {
    "bbox": {
      "type": "array",
      "default": null
    },
    "intersects": {
      "type": "geometry",
      "default": null
    },
    "contains": {
      "type": "geometry",
      "default": null
    },
    "polarisations": {
      "type": "array",
      "required": false,
      "description": "Requested polarisations for the output",
      "default": ["VV"],
      "items": {
        "type": "string",
        "enum": ["VV", "VH"]
      }
    },
    "mask": {
      "type": "array",
      "default": null,
      "items": {
        "type": "string",
        "enum": ["land", "sea"]
      }
    },
    "tcorrection": {
      "type": "boolean",
      "default": true
    },
    "clip_to_aoi": {
      "type": "boolean",
      "default": false
    }
  },
  "machine": {
    "type": "xlarge"
  },
  "input_capabilities": {
    "raster": {
      "up42_standard": {
        "format": "SAFE", // it only accepts SAFE files as input format
        "sensor": "Sentinel1GRD",
        "dtype": "uint16",
        "resolution": 10,
        "bands": {
          "or": [
            ["HH", "HV", "alpha"],
            ["VV", "VH", "alpha"],
            ["HH", "alpha"],
            ["VV", "alpha"]
          ]
        },
        "processing_level": "l1"
      }
    }
  },
  "output_capabilities": {
    "raster": {
      "up42_standard": {
        "format": "GTiff",
        "sensor": ">",
        "dtype": ">",
        "resolution": ">",
        "bands": ">",
        "processing_level": ">"
      }
    }
  }
}

Ship Detection block manifest

{
  "_up42_specification_version": 2,
  "name": "ship-detection",
  "display_name": "Ship Detection",
  "type": "processing",
  "tags": ["analytics", "detection", "machine learning", "object"],
  "description": "Detects ships on SPOT and Pleiades imagery (with SPOT imagery resolution).",
  "machine": {
    "type": "gpu_nvidia_tesla_k80"
  },
  "parameters": {},
  "input_capabilities": {
    "raster": {
      "up42_standard": {
        "format": "GTiff",
        "dtype": "uint8",
        "resolution": 1.5,
        "tile_width": 768, // input image sliced in 76x768 tiles required
        "tile_height": 768
      }
    }
  },
  "output_capabilities": {
    "vector": {
      "up42_standard": {
        "format": "GeoJSON",
        "geometry_type": "Polygon"
      },
      "custom": {
        "object_type": "ships"
      }
    }
  }
}

Custom block manifest: KML output

{
  "_up42_specification_version": 2,
  "name": "My KML output block",
  "display_name": "Tree counting",
  "type": "processing",
  "description": "Counts trees from a VHR resolution image.",
  "machine": {
    "type": "gpu_nvidia_tesla_k80"
  },
  "parameters": {},
  "input_capabilities": {
    "raster": {
      "up42_standard": {
        "format": "GTiff",
        "dtype": "uint8",
        "resolution": 0.5,
        "tile_width": 768, // input image sliced in 76x768 tiles required
        "tile_height": 768
      }
    }
  },
  "output_capabilities": {
    "vector": {
      "up42_standard":{
        "format": "KML"
      },
      "custom": {
        "object_type": "tree"
      }
    }
  }
}

Custom block manifest: PNG output

{
  "_up42_specification_version": 2,
  "name": "My display format block",
  "display_name": "PNG converter",
  "type": "processing",
  "description": "Converts a GeoTIFF to PNG.",
  "machine": {
    "type": "large"
  },
  "parameters": {},
  "input_capabilities": {
    "raster": {
      "up42_standard": {
        "format": "GTiff",
        "dtype": "uint8",
      }
    }
  },
  "output_capabilities": {
    "raster": {
      "custom": {
        "format": "PNG",
        "depth": 8,
        "has_alpha": true,
        "dtype": uint8
      }
    }
  }
}