Skip to content

STACK service specifications


icon


Service Description

The Co-located Stacking (STACK) service computes the co-location of single-band assets having different map projections and spatial resolutions on a common grid. It performs resampling and warping of the secondary datasets and the stacking of each secondary with the reference. The upsampling or/and downsampling of spatially overlapping datasets is performed on a common area (intersection based on STAC asset geometry) and is based only on pixel coordinates. The service requires input geocoded products, which are a prerequisite for the stacking service. As an example, input single-band assets can be taken from multi-sensor Optical or SAR Calibrated Datasets, Results of other on-demand processing services, and Auxiliary Datasets. For more details find the section about inputs here. Co-location results depend on the level of accuracy of geopositioning of source images. The Co-located Stacking processor is built with the GDAL VRT method1. It can also generate new assets from the co-located stack using band arithmetic.

Workflow

The service implements the workflow depicted below.

graph TB b[(Datasets, Aux Datasets <br> or Results)] style b fill:#ffde86,stroke:#333,color:#282828,stroke-width:2px b --> a1[input n] b --> a2[input ...] b --> a3[input 2] b --> an[input 1] subgraph Input style Input fill:#e8e8e8,stroke:#818181,color:#282828 a1[/Dataset n/] style a1 fill:#acc8ff,stroke:#333,color:#282828,stroke-width:2px a2[/Dataset .../] style a2 fill:#acc8ff,stroke:#333,color:#282828,stroke-width:2px a3[/Dataset 2/] style a3 fill:#acc8ff,stroke:#333,color:#282828,stroke-width:2px an[/Dataset 1/] style an fill:#acc8ff,stroke:#333,color:#282828,stroke-width:2px alist[/List of comma separated <br> single band assets/] style alist fill:#acc8ff,stroke:#333,color:#282828,stroke-width:2px ba2[/AOI as WKT/] style ba2 fill:#acc8ff,stroke:#333,color:#282828,stroke-width:2px ba1[/S-expression/s/] style ba1 fill:#acc8ff,stroke:#333,color:#282828,stroke-width:2px end subgraph Co-located Stacking an --> stack[Co-located<br>stacking] a3 --> stack[Co-located<br>stacking] a2 --> stack[Co-located<br>stacking] a1 --> stack[Co-located<br>stacking] alist --> stack[Co-located<br>stacking] ba2 -.-> stack[Co-located<br>stacking] stack --> csn(Co-located<br>asset 1) style csn fill:#cfdfff,stroke:#333,color:#282828 stack --> cs3(Co-located<br>asset 2) style cs3 fill:#cfdfff,stroke:#333,color:#282828 stack --> cs2(Co-located<br>asset ...) style cs2 fill:#cfdfff,stroke:#333,color:#282828 stack --> cs1(Co-located<br>asset n) style cs1 fill:#cfdfff,stroke:#333,color:#282828 csn -.-> stack1[Band<br>arithmetic] cs3 -.-> stack1[Band<br>arithmetic] cs2 -.-> stack1[Band<br>arithmetic] cs1 -.-> stack1[Band<br>arithmetic] ba1 -.-> stack1[Band<br>arithmetic] end subgraph Output style Output fill:#e8e8e8,stroke:#818181,color:#282828 csn(Co-located<br>asset n) --> on[/Co-located<br>asset n/] style on fill:#acc8ff,stroke:#87afff,color:#282828,stroke-width:2px cs3(Co-located<br>asset ...) --> o3[/Co-located<br>asset .../] style o3 fill:#acc8ff,stroke:#87afff,color:#282828,stroke-width:2px cs2(Co-located<br>asset 2) --> o2[/Co-located<br>asset 2/] style o2 fill:#acc8ff,stroke:#87afff,color:#282828,stroke-width:2px cs1(Co-located<br>asset 1) --> o1[/Co-located<br>asset 1/] style o1 fill:#acc8ff,stroke:#87afff,color:#282828,stroke-width:2px stack1 -.-> oo[/New asset/s from <br> band arithmetic/] style oo fill:#acc8ff,stroke:#87afff,color:#282828,stroke-width:2px end

Inputs

Input of the STACK service can be geocoded images from supported SAR or optical sensors (e.g. reflectance or Sigma Nought single-band assets from Calibrated Datasets derived systematically in the calibration processing from supported Optical or SAR sensors). Co-location stacking is also possible if the input set of images is built by mixing single band assets from SAR and Optical Calibrated Datasets. Also, input single band assets in STACK can originates from Results of some on-demand processing services and from Auxiliary Datasets.

STACK supports single-band assets derived from the following services: PAN-Sharp, OPT-Index, BAS, IRIS, HOTSPOT, HASARD, and the two InSAR processors DInSAR, and SAR-COIN (for coherence asset only).

It also supports as input single band assets from the following Auxiliary Datasets: Copernicus DEM, and ESA World Cover.

Parameters

The STACK service requires a specified number of mandatory and optional parameters. All service parameters are listed in the below Table 1.

Parameter Description Required Default value
Input product reference(s) List of Datasets, Aux Dataset or Results from other processors including assets to be co-located YES
List(s) of comma-separated bands List of assets to be colocated as comma-separeted items YES
Area of Interest Area of interest expressed in WKT NO
S-expression/s S-expression/s to generate additional asset/s from the ones in the stack (e.g. average) NO

Table 1 - Service parameters for the STACK processor.

More information about the service parameters are given below.

Input-product-reference/s

This first mandatory parameter is the list of input products that are used to create the collocated stack.

The input products can be:

  • Optical calibrated products,
  • SAR calibrated products,
  • Auxiliary datasets,
  • Geophysical results of downstream processing service executions (e.g. SAR-COIN).

Warning

The specified input-product reference must include at least one single-band asset. In the co-location only single-band assets can be used (e.g. reflectance, backscatter, binary change mask or coherence) and not overview ones.

List-of-comma-separated-bands

This second mandatory parameter is a list of comma separated single band assets. It defines, for each input-reference product, the list of single band assets to extract. There's a one-to-one mapping between the input-reference and the assets parameters.

The list of single-band assets to be used for the co-location shall be given as a list of items specified with the following convention:

reference_dataset_number.single_band_asset

Example

To build a STACK using multiple reflectance single band assets (e.g. coastal, blue, green, red, and nir) from a single Calibrated Dataset (e.g. by specifying only one input product references 1) the users shall define the 5 input assets in STACK as following:

1.coastal,1.blue,1.green,1.red,1.nir

Example

To build a multitemporal STACK using multiple backscatter single band assets (e.g. s0_db_c_vv, and s0_db_c_vh) from multiple Calibrated Datasets (e.g. by specifying three different Optical Calibrated Datasets given as input product references 1, 2, and 3) the users shall define the 6 input assets in STACK as following:

1.s0_db_c_vv,1.s0_db_c_vh,2.s0_db_c_vv,2.s0_db_c_vh,3.s0_db_c_vv,3.s0_db_c_vh

Example

To build a co-located stack using a pair of two coherence single band assets (e.g. coh_c_vv_20220330_20220411,, and coh_c_vv_20220517_20220529) derived from two SAR-COIN Result, obtained by exploiting 4 Sentinel-1 SLC Datasets acquired on 20220330, 20220411, 20220517, and 20220529 the user shall specify two references to COIN Results given as input product references 1, and 2 and define the 2 input assets in STACK as following:

1.coh_c_vv_20220330_20220411, 2.coh_c_vv_20220517_20220529

Example

It is also possible to build a co-located stack by mixing different types of single-band assets derived from Results of other processing services. As an example to co-locate the flood-mask single band asset from HASARD, and the cva_change_detection one from CVA, the user must first specify references to HASARD and CVA Results as input product references 1, and 2 respectively. Later, the 2 input single-band assets can be defined in STACK as following:

1.flood-mask,2.cva_change_detection

Example

Co-located stacking also supports single-band assets from Auxiliary Datasets. As an example to co-locate the flood-mask asset from HASARD, and the worldcover one from ESA World Cover Auxiliary Dataset, the user must first specify references to an HASARD Result and the ESA World Cover Auxiliary Dataset as input product references 1, and 2 respectively. Later, the 2 input single-band assets can be defined in STACK as following:

1.flood-mask,2.worldcover

Warning

Use comma separated reference.bands and avoid inserting a space when specyfing the list of assets. Do not insert a space before/after the comma, e.g. asset1,asset2 and not asset1, asset2.

Tip

Always check the list of CBNs available in a Calibrated Dataset (or the name of single band assets included into an Auxiliary Dataset or a Result of a processing service) before defining list of single-band assets. A Worldview-2 MS Calibrated Dataset does not have a nir asset but a nir08 one. The ESA World Cover Auxiliary Dataset has only one single-band asset named worldcover. Results from similar on-demand change detection processing services may have multiple single-band assets with different STAC keys (e.g. flood-mask for HASARD and cva_change_detection for CVA).

Note

All CBNs available in the ESA Charter Mapper can be found here.

AOI (optional)

This third parameter (optional) may define the area of interest expressed as a Well-Known Text value.

Warning

If set, it overrides the automatic determination of the maximum common area between the input-reference products geometry.

Tip

In the definition of “Area of interest as Well Known Text” it is possible to apply as AOI the drawn polygon defined with the area filter. To do so, click on the Magic tool wizard button in the left side of the "Area of interest expressed as Well-known text" box and select the option AOI from the list. The platform will automatically fill the parameter value with the rectangular bounding box taken from the current search area in WKT format.

S-expression (optional)

This forth optional parameter allows generating a new single-band asset derived from the collocated image stack (e.g. average, normalized difference etc.).

A new band is defined with the name of the new output asset and it's associated s-expression separated by a colon : .

output_asset_name:(s-expression)

Warning

S-expressions can be made by using only the assets inserted in the list and not with all the ones in the source Dataset.

Warning

The s-expressions inserted by the user must be given within brackets.

As an example to derive a new asset as the average between red bands from a pair of input-reference products (1.red and 2.red):

average:(/ (+ 1.red 2.red) 2)

This will add a new asset called average in the co-located stack with average values derived from 1.red and 2.red.

Arithmetic/logical operators and functions

S-expressions in the ESA Charter Mapper supports arithmetic (* + / -) and logical (< <= == != >= > & |) operators plus some pre-defined functions.

More information about supported functions can be found in Table 2.

Function Description Syntax
asarray convert the input (list, tuples, etc.) to an array (asarray x)
interp returns the one-dimensional piecewise linear interpolant to a function with given discrete data points (xp, fp), evaluated at x (interp x xp fp)
mean returns the mean value (scalar) from the given input array x (mean x)
norm_diff returns the normalized difference between A and B as per ((x - y) / (x + y)) (norm_diff x y)
where return elements chosen from x or y depending on condition (where (condition) x y)

Table 2 - Supported functions that can be used in s-expressions.

Note

The current list of functions can be further expanded in the future based on the user needs.

Examples of s-expressions which can be used to generate new bands from the STACK are listed in the below sections.

Compute sum

The following s-expression:

sum:(+ 1.pan 2.pan)

can be used to generate a band as the sum of 1.pan and 2.pan.

Compute difference

The following s-expression:

difference:(- 1.pan 2.pan)

can be used to generate a band as the difference of 1.pan and 2.pan.

Compute average

The following s-expression:

average:(/ (+ 1.pan 2.pan) 2)

can be used to generate a band as the average between the values of 1.pan and 2.pan.

Compute difference from average

The following s-expression:

diff_from_avg:(- 1.pan (mean 1.pan))

can be used to estimate a band of difference from the average value of 1.pan.

Compute normalized difference

The following s-expression:

ndvi:(norm_diff 1.nir 1.red)

can be used to derive multiple spectral indexes defined as normalized difference (e.g. NDVI, NDWI, NDBI, etc.).

Interpolate or rescale

The following s-expression:

rescaled:(interp 1.red (asarray 0 10000) (asarray 0 1))

can be used to interpolate the rescaled TOA reflectance into its original [0,1] range. Here (asarray 0 10000) returns [0, 10000] and is used to specify input range to be used for the interpolation.

Binarization

The following s-expression:

opt_water_mask:(where (>= (norm_diff 1.green 1.nir) 0.3) 1 0)

can be used to derive a water mask from the binarization of a spectral index. Here (norm_diff 1.green 1.nir) is used to derive the NDWI index. The value 0.3 represents the threshold as TOA reflectance. Similar s-expressions can be made also for SAR such as:

sar_water_mask:(where (<= 1.s0_db_c_hh -23) 1 0)

in which 1.s0_db_c_hh is the asset and the value -23 represents the threshold as Sigma Nought in dB.

Combine Datasets, Results and Auxiliary Datasets

STACK can be used also to post-process an asset from a Result of another processor. For instance, this makes it possible to co-locate a binary flood map from the Result of the HASARD on-demand service with the Land Cover Auxiliary Dataset to extract flooded pixels over only a certain LC class. As an example the following s-expression:

flooded_cropland:(where (== 2.worldcover 40) 1.flood-mask 0)

can be used to derive a flood mask over only crop fields. In this case the s-expression (where (== 2.worldcover 40) 1.flood-mask 0)) is used to generate the flooded_cropland asset from the flood-mask one using the condition (== 2.worldcover 40). The value 40 represents the pixel value of the LC class cropland for the single-band asset worldcover offered in the ESA World Cover Auxiliary Dataset.

Figure

Figure 1 - Extraction of flooded cropland using the STACK service from a co-location of an HASARD`s binary flood map and the ESA world Cover.

Hint

Specifications of the worldcover single band asset can be found here.

Outputs

The output of STACK is a multi-mission and multitemporal co-located stack with N single band assets in COG format. The output STAC item includes as many assets as provided in input plus the ones generated with s-expressions.

STACK Product specifications can be found in the table below.

Attribute Value / description
Long Name Co-located stack from Optical or SAR EO data
Short Name source_reference_number.source_asset (e.g. 1.nir)
Description Multiband co-located stack of N images from optical and radar sensors
Processing level L1 / L2 (according to input)
Data Type Float32
Band N single-band
Format COG
Projection According to input
Fill Value According to input

  1. GDAL documentation, gdalbuildvrt, available at: https://gdal.org/programs/gdalbuildvrt.html