Units Improvements

News
1

Hi Users,

The concept of units on Sentinel Hub has been revamped and improved. The units for each band are now well defined in the docs. As a reminder, by specifying the units parameter in your evalscript, you can choose the physical quantity and corresponding units of measurement for the values of each band. The changes as specified in the docs will be available on Sentinel Hub shortly.

Starting Monday, November 1, 2021, November 29, 2021, Sentinel Hub will validate the units parameter in your evalscripts. This means that requests for bands in unsupported units will be rejected. This should only impact requests which are already producing wrong results, so you should not be too worried about it. We will also use the upcoming month to monitor active requests, to see if there are some problematic use-cases.
This validation is temporarily disabled until then, so you have some time to correct any potential problematic evalscripts which have worked in the past.

For more information, and a list of supported units for each band of each data collection, see our docs. Here is a direct link to the units chapter for Sentinel-2 L2A, for example: https://docs.sentinel-hub.com/api/latest/data/sentinel-2-l2a/#units

In case of trouble, you usually only need to replace the problematic units parameters with the default values given in the documentation for the corresponding bands. Note that for nearly all bands there is only one supported unit so it is just a matter of updating the name; correcting the “units” value will therefore not have any effect on the values in the script. Alternatively, removing “units” from your evalscript will return the default units for each band.

Here is an example error message returned by the service for incorrect requests once validation starts: “Band ‘B10’ of collection ‘LOTL1’ requested in unsupported units ‘REFLECTANCE’! Supported units for this band: [BRIGHTNESS_TEMPERATURE].”

In this example you would need to change the units parameter from REFLECTANCE to BRIGHTNESS_TEMPERATURE. Note in this case there is only one supported unit (BRIGHTNESS_TEMPERATURE). Correcting this will not change any values in the evalscript as brightness temperature values are already returned now. So clearly REFLECTANCE is not the right value and needs to be updated.

Note also that the S2 L2A band AOT had its normalization corrected to 1000 from 10000. This change will also be in effect shortly.

2

Hi All,

Following feedback we decided to update the units values for various auxiliary bands to be more in line with units logic. The documentation has been updated with these changes, don’t forget to refresh the page to ensure you see the correct version. Sentinel-2 L2A docs, for example: https://docs.sentinel-hub.com/api/latest/data/sentinel-2-l2a/#units

Please note that we have analyzed the logs over the last month and identified all that might be affected. That said, as there is a small chance we missed some, or some of you have simply not been active over the last period, it would be good if you double check.

Keep in mind that units validation will start Monday, November 1, 2021, November 29, 2021. This only affects evalscripts where units are explicitly set. If you are using evalscripts with explicitly set units, please check that the correct units values are being requested.

In addition to this, the SR_ATMOS_OPACITY band (Landsat 7 ETM+ Collection 2 Level 2 and Landsat 4-5 TM Collection 2 Level 2) currently does not have the correct scaling applied. We noticed that incorrect values are being returned with values being 1000 times too large. This will also be corrected starting November 1 November 29.

3

A note for eolearn users:

Using older versions of the software may produce autogenerated evalscipts which will fail validation. To fix this, please update to the latest version.

4

In general, I noticed if you do not update in time, then there is some kind of mess!

5

Yes, sorry for the inconvenience. Without units validation you could have scripts which do not make sense (see the example in the first post). Units validation is also a prerequisite for offering various bands in different units, something we plan to do in the future.

6

Due to the breaking nature of the change, we’ve decided to postpone the validation of the units parameter until Monday, November 29, 2021. This extension is meant solely to prevent service interruptions once the changes go live, so we urge you to update your code as soon as possible.

7

Is there any way to check my requests before they get rejected? So I can be sure that my modifications are correct and units validation will not break my code.

8

As of this writing unfortunately no, there is no automated way of doing this. We are, however, working on something which will help, but we can’t promise any timeline.

Note that we are contacting users which we know are using incorrect scripts, so if you didn’t receive any emails from us most likely your requests are OK.

9

Hi All,

Thank you for the updates regarding the concept of units.

Actually using the eo-learn package, I was doing as follows to get my S2 data :

input_task = SentinelHubInputTask(
    data_collection=DataCollection.SENTINEL2_L2A,
    bands=['B01', 'B02', 'B03', 'B04', 'B05', 'B06', 'B07', 'B08', 'B8A', 'B09', 'B11', 'B12'],
    bands_feature=(FeatureType.DATA, 'BANDS-S2-L2A'),
    additional_data=[(FeatureType.MASK, 'dataMask', 'IS_DATA'),
                     (FeatureType.MASK, 'SCL'),
                     (FeatureType.DATA, 'viewZenithMean'),
                     (FeatureType.DATA, 'sunZenithAngles'),
                     (FeatureType.DATA, 'viewAzimuthMean'),
                     (FeatureType.DATA, 'sunAzimuthAngles')],
    resolution=10,
    maxcc=coverage_predicate,
    time_difference=time_difference,
    config=config,
    max_threads=n_threads
)

However, I get now the following error when I am doing the request :

Server response: “{“error”:{“status”:400,“reason”:“Bad Request”,“message”:“Invalid script! Band ‘SCL’ of collection ‘S2L2A’ requested in unsupported units ‘PERCENT’! Supported units for this band: [DN]. See Units Improvements for more information.”,“code”:“RENDERER_EXCEPTION”}}”

I tried to look at the source code of SentinelHubInputTask but I did not manage to find how to update my function in order to specify the data type Unit.DN for my additional data. “SCL”.

May I ask you if anyone could help me ? If you have any suggestions regarding this function, feel free to recommend :).

Have a great day,
Johann

10

Hi @johann.desloires,

It seems that we have a bug here in sentinelhub-py package where we define units for each band. SCL should use Unit.DN while CLD should use Unit.PERCENT. We’ll try to fix this and release a new version as soon as possible.

In the mean time you can use this temporary solution to make your code work. Basically, you define a new DataCollection enum that correctly defines units for SCL and CLD bands:

import numpy as np
from sentinelhub import DataCollection, Band, Unit

fixed_metabands = []
for metaband in DataCollection.SENTINEL2_L2A.metabands:
    if metaband.name == 'SCL':
        fixed_metaband = Band('SCL', (Unit.DN,), (np.uint8,))
        fixed_metabands.append(fixed_metaband)
    elif metaband.name == 'CLD':
        fixed_metaband = Band('CLD', (Unit.PERCENT,), (np.uint8,))
        fixed_metabands.append(fixed_metaband)
    else:
        fixed_metabands.append(metaband)

fixed_collection = DataCollection.SENTINEL2_L2A.define_from(
    'SENTINEL2_L2A_FIXED',
    metabands=fixed_metabands
)

# Now use the fixed collection in the eo-learn task
input_task = SentinelHubInputTask(
    data_collection=fixed_collection,
    bands=['B01', 'B02', 'B03', 'B04', 'B05', 'B06', 'B07', 'B08', 'B8A', 'B09', 'B11', 'B12'],
    bands_feature=(FeatureType.DATA, 'BANDS-S2-L2A'),
    additional_data=[(FeatureType.MASK, 'dataMask', 'IS_DATA'),
                     (FeatureType.MASK, 'SCL'),
                     (FeatureType.DATA, 'viewZenithMean'),
                     (FeatureType.DATA, 'sunZenithAngles'),
                     (FeatureType.DATA, 'viewAzimuthMean'),
                     (FeatureType.DATA, 'sunAzimuthAngles')],
    resolution=10,
    maxcc=coverage_predicate,
    time_difference=time_difference,
    config=config,
    max_threads=n_threads
)
11

The issue with SCL band in DataCollection.SENTINEL2_L2A has now been fixed in the newly released version 3.4.2 of sentinelhub package.