Custom processing scripts

Sentinel Hub allows you to define custom JavaScript code for processing the layers before they are fetched via WMS, WMTS or other protocols.

Note: Examples of custom processing scripts can be found at https://custom-scripts.sentinel-hub.com/

Usage

Part of every WMS/WMTS/... request to our services are parameters instance id and layer. To obtain them, you need to log into WMS Configurator to create suitable configurations. Combination of instance id and layer determines the data source and the script (either predefined or custom). The layer's script can also be overriden via EVALSCRIPT URL parameter when doing a WMS/WMTS/... request.

Scripts are executed inside a JavaScript engine and can use standard JS functions. There are 2 styles of writing the scripts, basic and extended. The system determines the type of script automatically when executing it.

Note: EOCloud service supports basic scripts (and ES5) only. AWS services support both basic and extended scripts.

Basic scripts

Basic scripts are being run once for each pixel. They get the inputs through global variables and return an array of values.

Note: for more complex setup you should use extended scripts where supported, especially if you use Visualizers.

Inputs:

Available inputs depend on data source:

* SCL: https://www.sentinel-hub.com/faq/how-get-s2a-scene-classification-sentin...

** SNW and CLD bands are experimental and should not be used (they are subject to change without notice)

Please see data sources (and the corresponding EO products) for further information on the available input data.

Result:

Script must return an array of values. The length of the returned array is not prescribed by the system, but it must obey the following constraints:

• length of array must be the same on every invocation of script
• length of array must be supported by output format (1 or 3 for JPG and PNG, arbitrary for TIFF)

Often an array of a single value is returned (for example NDVI or some other indicator), or 3 values if one wants to visualize layer in RGB - but this depends on the use case and the client software.

Interpretation of returned values depends on output format:

• TIFF8, TIFF16, PNG, JPG: values are mapped so that range [0..1] maps to range [min..max] (0..65535 for TIFF16, 0..255 for other formats); values under 0.0 or over 1.0 are set to 0.0 and 1.0 respectively.
• TIFF32F: values are returned directly (as float32)

More info on output formats: https://www.sentinel-hub.com/develop/documentation/api/output-formats

Example script:

return [
    B04 * 2.5 + Math.max(0, B12 - 0.1),
    B03 * 2.5 + Math.max(0, B11 - 0.1),
    B02 * 2.5
];

Etna volcano eruption, dated 16. 3. 2017. Image combined from true colour image, overlaid with SWIR bands 11 and 12. (view on Sentinel Playground)

Extended scripts

Extended scripts consist of two parts, setup and evaluation:

• setup: defines the input (bands used) and output (resulting array size) components
• evaluation:
  • calculates the values of each pixel in the result and
  • (optionally) calls one of the predefined visualizers to convert the values to color space.

Example script:

function setup(dataSource) {
    setInputComponents([dataSource.B04, dataSource.B08]);
    setOutputComponentCount(1);
}

let viz = new HighlightCompressVisualizerSingle(-1.0, 1.0);

function evaluatePixel(samples) {
    let val = 1.5 * (samples[0].B08 - samples[0].B04) / (samples[0].B08 + samples[0].B04 + 0.5);
    return viz.process(val);
}

setup() function

Signature of the `setup` function is:

function setup(dataSource) {
    ...
}

Parameters:

• dataSource: an object with all the available bands for the selected datasource

Result:

Function should call 2 functions, each of them exactly once:

• setInputComponents(usedBands)
  • usedBands: an array of bands that will be made available to evaluatePixel
• setOutputComponentCount(n)
  • n: length of array that evaluatePixel will be returning

As with basic scripts, the length of the array returned by evaluatePixel is not prescribed by the system, but it must obey the following constraints:

• length of array must be the same on every invocation of script
• length of array must be supported by output format (1 or 3 for JPG and PNG, arbitrary for TIFF)

Often an array of a single value is returned (for example NDVI or some other indicator), or 3 values if one wants to visualize layer in RGB - but this depends on the use case and the client software.

evaluatePixel() function

Signature of the evaluatePixel function is:

function evaluatePixel(samples) {
    ...
}

Parameters:

• samples: an array of objects which contain the band values for the pixel being processed

Note: samples is an array because it allows processing of layers across time. In all other cases, samples always holds exactly one element (referenced by samples[0]).

Result:

Function should return an array of values, similar to how basic scripts do. The length of the returned array must match the length specified by setOutputComponentCount() call. Often evaluatePixel will use one of the Visualizers to transform calculated values to a suitable color space. As a performance measure, make sure Visualizer is instantiated outside of the function.

Debugging

If an exception is thrown from a script then request execution is stopped and response with the exception message will be returned (note that formatting of the message depends on the service endpoint), which can be used as a simple debugging tool.

Debugging basic scripts example:

let message = "Hello world";
throw new Error(message);

// response: "Failed to evaluate script! Error: Hello world"

Debugging extended scripts example:

function setup(dataSource) {
    let message = "Hello world";
    throw new Error(message);
}

function evaluatePixel(samples) {
    // ...
}

// response: "Failed to evaluate script! Error: Hello world"

Visualizers

Please see https://www.sentinel-hub.com/faq/how-configure-visualization-so-it-reflects-old-styles for more info on Visualizers.