Impacts of the migration to Evalscript V3

Why we’re doing it (reasons and benefits)

Currently we have four different types of scripts. Simple, V1, V2, V3. It is confusing, hard to maintain, and for older scripts limits available features. V3 scripts do everything the previous versions can and add numerous useful functionalities. These include dataMask, units, data fusion, mosaicking selection ability, precisely defining the output, etc. After the change only V3 and simple scripts will remain; we are keeping simple scripts for the reason that for basic functionality and beginner users they are most easy to use.
An additional change is the removal of the TRANSPARENCY and BGCOLOR parameters in OGC requests. This is to remove the ambiguity of using these parameters alongside evalscipts. In any case their usage can be entirely replicated (and improved) by slightly modifying your evalscripts.
Sentinel Hub has for quite some time now outgrown the OGC standards and the goal is to consolidate new features in V3 evalscripts, while still supporting OGC standards.

When and how it will happen

As briefly summarized in the April’s newsletter (, we have already:

  • added V3 support to OGC services
  • added simple script support to process API
  • converted the scripts in the Custom Script repository
  • provided an API to convert v1 and v2 evalscripts to v3

In the near future, that is, at least the next few months, we will still support all versions. We will inform users at least 6 weeks prior to the end of the support. We would however recommend you start porting your scripts today.

Why some things can’t be done automagically

Complex evalscripts and parameter combinations (especially through OGC) limit automatic conversion to V3. For most simple-enough scripts (which can be quite complex actually) this can be done. Unfortunately, we can’t cover all the use-cases so if you fall into that category a small amount of work will be required.
The OGC FORMAT parameter influences the returned output even if the evalscript is the same. Since we cannot know what parameter value(s) you use this makes autoconversion unreliable.

The most important consequences of transition and how it impacts you

We realize change can be inconvenient, however we believe the simplification it brings is worth it. During the migration some additional work on your evalscripts might be necessary, as well as testing to make sure it runs correctly. We are doing our best to keep migration issues at a minimum, however due to the complexity of everything we would be surprised if no further issues pop up. Contact us if you find anything that isn’t working as expected.

What will happen when migration to evalscript V3 is finalised


Evalscripts V1 and V2 will stop working.
DataMask will become available in simple scripts via OGC.

impacts on OGC services

  • The depth= suffix of the format parameter won’t be supported anymore. If used, an error will be returned. The bit depth and the value of the response is fully under control of the evalscript. If the output of the evalscript can’t be “fitted” to the format of the OGC request (e.g., the evalscript defines sampleType: "FLOAT32" and the requested format is an 8bit integer) an error will also be returned.
  • The transparent parameter is deprecated. If used, it will be ignored. If the evalscript produces an output that has a transparency channel in the sense of four channel RGBA and the format supports it (for example PNG) an image with transparency will be returned. If the evalscript returns more channels that the format supports, the output is clipped to the number of channels (e.g. the evalscript returns 4 channels, JPG is requested, then only the first 3 returned channels will be placed in the JPG). This allows “transparent” scripts to be used with non-transparent formats, so you don’t need a separate script for each.
  • The bgColor parameter is deprecated. If used, it will be ignored. If your require a specific background color, modify the evalscript to do so. For how to do this, see here

A while ago we announced here that we are migrating data processing at Sentinel hub (SH) to evalscripts V3. We have prepared a converter and added support for evalscripts V3 to the EO Browser and to the Playground. We are now taking further steps towards the migration:

  • For each of the data products which used evalscripts V1 or V2 we added their corresponding V3 version. When creating new layers you can now select only data products which use either evalscripts V3 or simple script.
  • We converted all V1 and V2 evalscripts in our configuration templates.
  • We converted all V1 and V2 evalscripts in the custom scripts repository and in our documentation.
  • In the Dashboard:
    • layers which use evalscript V1 or V2 (or data products V1 or V2) are now underlined with red color and marked with a small icon (up arrow)
    • you can convert V1 and V2 evalscripts (and data products) with a click of the button
    • you can convert and revert the conversion of the data products if needed
  • We prepared a detailed tutorial for you to help you migrate to V3

All these changes have had no effect on your existing SH settings and configurations. Your SH requests still work as they have so far. This will remain so until the November 1st. This transition period is meant to give you enough time to fully migrate your SH configurations to V3.

Once the transition period is over we will disable support for evalscripts V1 and V2. At that point we will automatically:

  • convert all non-converted evalscripts to V3 using the converter API and
  • swap old data products (V1 and V2) with the corresponding V3 ones.
    Depending on how you request the data from SH, this automatic conversion might result in obtaining different values from SH with existing SH requests as explained in impacts on OGC services chapter here. We thus encourage you to take full control over the conversion and convert your scripts and data products before the end of the transition period.

In case of any further questions, feel free to contact us on our forum.

1 Like