A repository of custom scripts that can be used with Sentinel-Hub services.

Ulyssys Water Quality Viewer (UWQV)

Water quality visualization script for Sentinel-2 and Sentinel-3 imagery data

Show minified, optimized script (recommended for usage).

Show unminified script (for debugging purposes).

Timelapse (2019) of Lake Balaton with Sentinel-2 and Sentinel-3 imagery side by side
'Timelapse of 2019'

Evaluate and visualize

  1. Visit one of the following example sites or find your own area of interest:
  2. Interpret what you see
  3. Modify the values in the PARAMS object according to your needs (for possible values see Understanding and fine tuning PARAMS)
  4. Hit Refresh after modifying any of the properties 'Refresh'

Description of the script

Ulyssys Water Quality Viewer (UWQV) is a custom script for the Sentinel-hub EO-Browser or the Sentinel-hub Playground to dynamically visualize the chlorophyll and sediment conditions of water bodies on both Sentinel-2 and Sentinel-3 images.

The visualization you see is a product of two masking operations and two water quality parameter visualizations:


By default, all pixels identified as “not water” (cloud, snow or land) are shown in true colour. All pixels identifed as water are coloured with an algorithm that evaluates chlorophyll and suspended sediment concentration together. This visualization can be compared to a GIS map with two raster layers, sediment on top and chlorophyll below. The sediment “layer” is semi-transparent and can cover the chlorophyll “layer”. Just like clouds in the atmosphere, sediment in the water reduces transparency and obscures chlorophyll. Therefore water pixels with high sediment concentrations are coloured dark brown regardless of their chlorophyll concentration. Medium sediment concentrations are coloured wheat (light brown) with increasing transparency towards lower sediment concentrations. At low sediment concentrations the sediment “layer” is completely transparent. Below the semi-transparent sediment “layer”, the chlorophyll concentration is visualized. High chlorophyll concentrations are marked in red, medium concentrations green, and low concentrations dark blue (see palette image below).

By changing input parameters of the script it is also possible to:

Understanding and fine tuning PARAMS

The visual output is controlled by the PARAMS object defined at the beginning of the script. It has three logical parts: Indices, Limits and Graphics. You may control the visualization by fine tuning the properties, setting them to predefined values (e.g. changing the selected chlorophyll index from 'default' to 'rlh') or modifying numeric values (e.g. chlorophyll maximum value from 0.05 to 0.03). Some of the properties are nullable (e.g. if you only wish to see sediment without chlorophyll just set chlIndex to null without quotation marks). You may see unwanted results if the properties are incorrectly set.

Structure and default values:

const PARAMS = {
  // Indices
  chlIndex: "default",
  tssIndex: "default",
  watermaskIndices: ["ndwi", "hol"],
  // Limits
  chlMin: -0.005,
  chlMax: 0.05,
  tssMin: 0.075,
  tssMax: 0.185,
  waterMax: 0,
  cloudMax: 0.02,
  // Graphics
  foreground: "default",
  foregroundOpacity: 1.0,
  background: "default",
  backgroundOpacity: 1.0

Possible values:

Details of the script

Scientific background

From an ecological perspective, the term “water quality” refers to the status of the most important abiotic and biotic properties of the water column in a given time and location. The most important water quality parameters from a habitat management perspective are chlorophyll concentration and suspended sediment concentration, and these are also strongly linked to bathing and drinking water quality for human use (see supplementary for further details). Chlorophyll concentration is a proxy for the amount of algae and therefore of energy and biomass input into the aquatic food web via photosynthesis. Since algae growth is often limited by the availability of nutrients, high chlorophyll concentrations are frequently a result of pollution from communal sewage or agricultural runoff. Suspended sediment can originate from currents or waves moving the sediment up from the bottom of the water (called resuspension), or from tributary rivers that carry sediment as they flow. The amount of sediment in the water column also depends strongly on grain size: fine-grained sediment can be picked up by slow currents and takes long to settle down again, while larger grained sediment is only moved by very strong currents and settles very quickly.

Technical background

The script uses pre-existing and relatively widely tested algorithms for masking and visualization. Water surfaces are masked by NDWI thresholding, (McFeeters 1996), and two existing cloud mask scripts in the Sentinel Hub repository are integrated, hol and bcy (Hollstein 2015; Cohen, Braaten and Young 2016). For suspended sediment, we use simple intensities of a single band near 700 nm or 620 nm (Nechad 2010, Sentinel 3 user guide). For chlorophyll concentration, various indices area available, all based on the reflectance line height (RLH) algorithm. RLH involves calculating the difference (“height”) of reflectance in one spectral band compared to a baseline calculated by linear interpolation between the values of two other bands (Yacobi 1995). Two specific spectral bands have been identified where chlorophyll flourescence produces a peak, at 685 nm and at 709 nm, and by calculating a RLH compared to the neighbouring bands defines two spectral indices, named Fluorescence Line Height (FLH) (Gitelson 1994) and Maximum Chlorophyll Index (MCI) respectively for studies with the MERIS satellite sensor (Gower 2005). Both of these indices can be calculated for Sentinel-3 data, and it has been shown that flh is more suitable for low chlorophyll concentrations while mci performs better for high chlorophyll concentrations. However, Sentinel-2 does not have a spectral band at 700 nm, so FLH cannot be used, but Band 05 at 705 nm is suitable for calculating mci. Additionally, for the sake of continuity we provide two RLH-based indices that were part of the functionality of Global Lake Watch (Zlinszky Supan Koma 2017), under the name rlh. These are both modified versions of the MCI with different baseline bands that we believe could be less sensitive to chlorophyll (Schalles 1998). Please see the References section for full citations and the supplementary material for full discussion of the methods selected.

Limitations and typical problems

UWQV is just a visualization, not a quantitative map. The colours produced by the script are a function of the satellite image pixel values which in turn are mainly, but not exclusively determined by the chlorophyll and sediment concentrations in the water column. The indices we use are tested to be positively correlated to the water quality parameter values they represent, but the exact correlation functions can vary considerably between different locations and different atmospheric and water conditions. Nevertheless, we believe that UWQV can help to understand the properties and dynamics of aquatic ecosystems in a new way by providing high spatial or temporal resolution from the Sentinel 2 and 3 satellites.

We are aware of some typical cases where the algorithm produces errors:

Why minified

The dist/script.min.js file is a minified version of the script which means it is much smaller (~3.5x), runs faster but is less human readable. You can find the original, unminified source file with useful comments and meaningful variable names at src/script.js. The source file is too large to copy its contents to the script window (exceeds the maximum URL length). We recommend using the minified version in the script window, but you can also enter the URL of the unminified source file into the input field below the script window (in this case you won’t be able to modify the parameters).

Modify the script

If you want to include another water quality algorithm or make other major changes and you wish to alter the script itself, you have to (1) modify the unminified source file (2) re-create the minified version of the script. We recommend doing it the following way:

  1. Copy the contents of this folder on your machine (maybe the easiest way is to download the whole repository and unzip it somewhere on your machine).
  2. Install Node.js if you don’t have it yet.
  3. From the script root folder (where the package.json file can be found), run npm install in a terminal. This will install all necessary dependencies that are needed for the minifying locally.
  4. Modify the src/script.js file from a text editor.
  5. Also from the script root folder, run npm run minify. This will overwrite the dist/script.min.js file.
  6. You can also run npm run watch. In this case the minifying happens automatically whenever you alter the src/script.js file until you shut the command down. This is how we alter the code as well.

Authors of the script

András Zlinszky PhD (@azlinszky) and Gergely Padányi-Gulyás (@fegyi001) at Ulyssys Ltd, Budapest, Hungary, 2020.

How to cite

In order to make this script fully citeable, we obtained a doi via and uploaded the supplementary document as a technical note, available under this link.

In a document bibliography, please use the following citation:

Zlinszky, A.; Padányi-Gulyás, G. Ulyssys Water Quality Viewer Technical Description Supplementary. Preprints 2020, 2020010386 (doi: 10.20944/preprints202001.0386.v1).

Description of representative images

Understanding the visualization

We illustrate the visualization of different chlorophyll concentrations on the example of an algae bloom on Lake Balaton, Hungary. The lake shows a clear gradient from the Southwest (high chlorophyll - up to 400 µg/l) to the Northeast (lower chlorophyll - about 20 µg/l). The red arrow marks a location where chlorophyll concentration was so high that the NDWI water masking mistook the water for land. The white arrow shows a location where chlorophyll concentration is high but also suspended sediment is present, here the transparent grey of the sediment is overlain on the colouring of the chlorophyll. The orange arrow shows a location where suspended sediment is locally relatively high but chlorophyll is low, while the blue arrow points to a place where both chlorophyll and suspended sediment are relatively low.

Lake Balaton, Sentinel-2A, 2019-09-05, True Colour. The true colour image shows the intensity of the algae bloom in the western part of the lake and also the relatively bright colour of the suspended sediment.


Lake Balaton, Sentinel-2A, 2019-09-05, UWQV Default settings. The chlorophyll visualization shows the extremely high concentrations in the western basin of the lake. The Sentinel-2 algorithm we use is less sensitive to suspended sediment concentration, with only the small area marked by the orange arrow coloured for sediment.


Lake Balaton, Sentinel-3, 2019-09-05, UWQV Default settings. While Sentinel-3 has lower spatial resolution than Sentinel-2, the chlorophyll and suspended sediment algorithms are more selective than for Sentinel-2, therefore they discern chlorophyll and sediment more successfully. The Western basin of the lake is coloured transparent grey (with the chlorophyll visualization “underneath”), the small patch of sediment in the central part of the lake is well identified and the lower concentrations in the eastern basin are not mistaken for chlorophyll.


Tuning the parameters

We show an example of selecting appropriate algorithms and limits in order to enhance the visualization to show more details on the example of an algae bloom on Lake Pontchartrain, Louisiana, United States. Optimum settings for visualizing this situation would suggest minimum and maximum limits defined by the minimum and maximum values observed in the scene. Water masking also has to be adjusted: similar to the previous example, chlorophyll and sediment concentrations are high enough in some small areas to cause problems.

Lake Pontchartrain, Sentinel-2A, 2020-01-06, True Colour. In the first step, the true colour image is visualized, in order to take a look at the general situation. High suspended sediment concentrations are evident in the Mississippi River, the bright green streak of a severe algae bloom along the southern third of the lake is also clear - these represent the maximum values while clear waters at the northern corner of the lake seem to hold the minimum.


Lake Pontchartrain, Sentinel-2A, 2020-01-06, UWQV Default settings. Using the default settings of UWQV, many more streaks of high chlorophlyll become visible, but the most affected area of the bloom is masked as non-water. Fluorescence Line Height is apparently sensitive to small amounts of chlorophyll but saturates at very high amounts, without reaching the values represented by the red colour. Along the southern shore of the lake, suspended sediment also has a strong influence on water colour, as marked by the grey transparent visualization. The Mississippi River is also visualized with a combination of greens and greys, as expected from water with relatively high sediment and chlorophyll content.


Lake Pontchartrain, Sentinel-2A, 2020-01-06, Modified water masking. Cloud masking is not necessary at all in this cloud-free scene, so the Hollstein cloud masking algorithm used as default is disabled by deleting 'hol' from watermaskIndices. However, NDWI-based water masking is problematic: within part of the area affected by the bloom, high chlorophyll and sediment content causes high reflectivity in near-infrared atypical for water, and therefore with the default waterMax value of 0, a masking error is caused. waterMax has to be lowered all the way to -0.62 if all pixels in the affected area are to be kept as water. To study the effect of changing the masking threshold, the parameter background was set to 'black'; this made all pixels labelled as non-water to appear black. The image shows that with such a low NDWI threshold most of the scene is mistaken as water. Note that Hollstein cloud masking could also have been used to identify water areas, but in our implementation the parameters of this algorithm are not tuneable.


Lake Pontchartrain, Sentinel-2A, 2020-01-06, Enhanced visualization. The next step is to optimize chlorophyll and sediment visualization. Accepting the compromise that some water pixels will be lost, but also false positives will be created, Hollstein cloud masking has been disabled, but waterMax was left at the default value. Instead of Fluorescence Line Height, the Reflectance Line Height algorithm was selected by setting the chlIndex parameter to 'rlh'. Reflectance Line Height seems to perform better for the high chlorophyll concentrations observed here, and is apparently less influenced by suspended sediment in the Mississippi river. In order to stretch the colouring scheme to the pixel values occurring within the image, chlMin was increased to 0.006 and chlMax was reduced slightly to 0.045. Suspended sediment visualization was left at the default values. Finally, in order to emphasize the water quality patterns further, the non-water pixels were slightly darkened by setting the background parameter to 'black' and the backgroundOpacity to 0.3.



Special thanks to


Creative Commons License

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License