STACK service specifications
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 calibrated datasets from different sensors, optical and SAR. 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.
Inputs
Input of the Co-located Stacking service are geocoded images from supported SAR or optical sensors (e.g. geophysical single-band assets in Datasets derived systematically in the calibration processing from supported SAR and Optical sensors). Co-location stacking is also possible if the input set of images is built by mixing assets from SAR and Optical EO data.
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 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
- Geophysical results of downstream processing service executions
Warning
The specified input-product reference must include at least one geophysical single-band asset. In the co-registration only single-band geophysical assets can be used.
List-of-comma-separated-bands
This second mandatory parameter is a list of bands expressed as a comma separated list of common band names. It defines, for each input-reference product, the list of common band names to extract. There's a one-to-one mapping between the input-reference and the bands parameters. The list of single-band geophysical assets to be used for the co-location shall be given as a list of comma separated items following the following convention:
reference_dataset_number.single_band_asset
Example
To build a STACK using multiple geophysical 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 geophysical 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
Warning
Use comma separated reference.bands
and avoid spaces between assets.
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 maximium 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 :fontawesome-solid-magic: 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 current search area in WKT format.
S-expression (optional)
This forth optional parameter allows generating a new band derived from the collocated stack result product (e.g. average, index etc.).
A new band is defined with a key and it's associated s-expression separated by a colon : .
output_band_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
.
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 mormalized 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-expresions which can be used to generate new bands from the STACK are listed in the below sections.
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
.
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
.
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
.
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
.
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 resclaed 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 water mask from binarization. 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.
Outputs
The output of this service is a multi-mission and multitemporal co-located stack with N assets as single band GeoTIFF in COG format. The output is a STAC item with as many assets as provided in input. All assets of this co-located stack are COG and have the same shape.
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 |
-
GDAL documentation, gdalbuildvrt, available at: https://gdal.org/programs/gdalbuildvrt.html. ↩