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 (https://www.sentinel-hub.com/newsletters/20200407), 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

Evalscript

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