Merge pull request #346 from azlinszkysinergise/sentinel2_magic_eyes

Sentinel2 magic eyes

Author: Guyon-Duifhuizen

sentinel-2/satellite_derived_bathymetry_mapping-sdbm/README.md

@@ -31,11 +31,11 @@ To detect water surface, simplified version of the existing custom script Water
 For detected water surfaces, Satellite Derived Bathymetry processing is done using band ratio calculation [1]. Procedure is based on ratio of two bands: blue/green or blue/red. Former ratio is better suited for depths between 5 to 18 meters and latter is better for depths lower than 5 meters. Ratio model uses a ratio of log-transformed water reflectance of bands.
 
 On the basis of bands ratio, pseudo Satellite Derived Bathymetry (pSDB) is calculated. In addition, with tunable constants scale and offset (m1 and m0), Satellite Derived Bathymetry can be calculated with equation:
-SDB = m1 * pSDB ñ m0
+SDB = m1 * pSDB - m0
 
 If m1 and m0 are known in advance (from articles etc.), pre-analysis and tuning of m1 and m0 is not needed. Result of the SDB equation are clamped with appropriate color mapping. Three different styles of bathymetry color mapping are available: blue ramp, blue blend and blue-black blend.
 
-Nevertheless, if m1 and m0 are unknown, pre-analysis is needed to appropriately tune m1 and m0. Pre-analysis includes depth data for at least 5 to 10 points and minor work ìoff the Sentinel Hub platformî to correlate depth data and calculated pSDB for mentioned points. Example of ìoff the Sentinel Hub platformî procedure is described in Supplementary material document.
+Nevertheless, if m1 and m0 are unknown, pre-analysis is needed to appropriately tune m1 and m0. Pre-analysis includes depth data for at least 5 to 10 points and minor work off the Sentinel Hub platform to correlate depth data and calculated pSDB for mentioned points. Example of off the Sentinel Hub platform procedure is described in Supplementary material document.
 
 If the goal of the mapping is only visual presentation of bathymetry variability, already known values of m1 and m0 for similar scenes or location could be enough without any pre-analysis procedure.
 
@@ -59,16 +59,15 @@ There could be false detection of water surface as urban, bare soil, clouds, sno
 For non-uniform scenes with low (black seaweed, dark bottom, shadow area) or high (high turbidity, shallow waters with bright bottom) reflectance of the bottom, script might not be applicable. That can result in over or under estimation of the depth.
 SDB method is usually effective up to 20 meters, sometimes even 25 meters.
 
-Script has simplified procedure for Satellite Derived Bathymetry method compared to usual research, as it does not include: water level difference between measured depths and water level at the time of satellite image acquisition (tide, storm surge, etc.), pre-processing of the scene (reflectance correction etc.) and validation procedure. Limitation of the script is also in case of unknown m1 and m0 as bathymetry data is needed and minor ìoff the platformî work.
+Script has simplified procedure for Satellite Derived Bathymetry method compared to usual research, as it does not include: water level difference between measured depths and water level at the time of satellite image acquisition (tide, storm surge, etc.), pre-processing of the scene (reflectance correction etc.) and validation procedure. Limitation of the script is also in case of unknown m1 and m0 as bathymetry data is needed and minor off the platform work.
 
-Nevertheless, script can serve perfectly as a tool for fast evaluation of shallow bathymetry.
+Nevertheless, the script can serve perfectly as a tool for fast evaluation of shallow bathymetry.
 
 In case of false or no detection of bathymetry depth, script could also serve to identify sediment transport, higher turbidity areas, white-water areas, bigger ships anchoring locations (illegal), or even ships movement direction by visible wake at the movement of the acquisition.
 
 **HOW THE SCRIPT WORKS:**
 
-1. In case of multi-temporal use, user has to select scenes dates:
-var scenes = ["2019-08-09",Ö];
+1. In case of multi-temporal use, user has to select scenes dates using the date selection tool in Copernicus Browser, or the time_interval parameter of the API request;
 
 2. In case default values of MNDWI and NDWI thresholds do not work as expected, values should be adjusted. 
 
@@ -77,19 +76,21 @@ var scenes = ["2019-08-09",Ö];
 4. SDB can be calculated on the basis of two different band ratios: blue/green or blue/red. Therefore, user must set SDBgreen=true for former and SDBgreen=false for latter.
 var SDBgreen=true;
 
-5. There is an option (cs) for different visualization schemes for final SDB: 0-blue ramp, 1-blue blend, 2-blue-black blend (legends in Supplementary material).
+5. There is an option (cs) for different visualization schemes for final SDB: 0-blue ramp, 1-blue blend, 2-blue-black blend (legends in Supplementary material - colour ramps are typically between 0 and 18 m).
 
 6. The most important step is to define, if m1 and m0 are already known. If they are, final calculation of SDB follows. If that is the case, user most set
 var preAnalysis=false;
 and known values of m1 and m0. In this case output of the script should already be appropriate.
 But if m1 and m0 are unknown, pre-analysis with tuning m1 and m0 is needed.  Therefore, user sets
 var preAnalysis=true;
 
-In this case user needs to have available depths for 5 to 10 points. It is recommended that this points are part of bathymetry cross section with variable depths (e.g. from 0 to 18 meters). For latter points calculated pSDB values are needed from pre-analysis. This can be obtained from green or red channel values of pre-analysis output. One has to be aware that red and green channels outputs adjusted pSDB values (multiplied or clamped). Therefore, that values must be first adjusted back to ìtrueî pSDB value. Then, latter values with known depths are used in linear regression to obtain m1 and m0. Finally, preAnalyis=false and obtained m1 and m0 are set for final SDB analysis.
+THIS SECTION IS KEPT FROM ORIGINAL SDBM CUSTOM SCRIPT README - BUT ESTIMATION RUNS DIFFERENTLY, SEE BELOW In this case user needs to have available depths for 5 to 10 points. It is recommended that this points are part of bathymetry cross section with variable depths (e.g. from 0 to 18 meters). For latter points calculated pSDB values are needed from pre-analysis. This can be obtained from green or red channel values of pre-analysis output. One has to be aware that red and green channels outputs adjusted pSDB values (multiplied or clamped). Therefore, that values must be first adjusted back to "true" pSDB value. Then, latter values with known depths are used in linear regression to obtain m1 and m0. Finally, preAnalyis=false and obtained m1 and m0 are set for final SDB analysis.
 
-In [supplementary material](supplementary_material.pdf), you can find detailed explanation of pre-analysis, tutorial on how to obtain multiplied pSDB values in green channel output and how to make linear regression. 
+Pre-analysis with the new version of the script: if the parameter preAnalysis is set to `true`, the algorithm outputs the pSDB - preliminary satellite derived bathymetry value. This is a product of the band ratio calculation, without the linear scaling parameters m0 and m1 applied. The user can then find locations where depth is known, create small area of interest polygons, calculate the histogram of pSDB within these, and set the linear scaling parameters m0 and m1 to output correct depth as sdbAvg.
 
-On the basis of the settings above, rest of the script gets executed. Firstly, values for setInputComponents is set on the basis of selected data source in EO Browser. As Band 12 does not exist for Landsat 8, script automatically knows which data source is it analysing (Sentinel-2 or Landsat 8). On this basis, appropriate bands for NIR, SWIR1 and SWIR2 are taken.
+THIS IS NOW OUTDATED: In [supplementary material](supplementary_material.pdf), you can find detailed explanation of pre-analysis, tutorial on how to obtain multiplied pSDB values in green channel output and how to make linear regression. 
+
+On the basis of the settings above, rest of the script gets executed. Firstly, values for setInputComponents is set on the basis of selected data source in Copernicus Browser. As Band 12 does not exist for Landsat 8, script automatically knows which data source is it analysing (Sentinel-2 or Landsat 8). On this basis, appropriate bands for NIR, SWIR1 and SWIR2 are taken.
 
 Scene(s) are analysed for water surface. According to settings, pixels are filtered or not for false detection of water surface. Both is done on the basis of thresholds for different indices. This part of the script is actually simplified version of Water Bodies` Mapping script.
 
@@ -99,6 +100,8 @@ Next, if m1 and m0 are known and pre-analysis is not needed, pSDB and SDB values
 
 Mohor Gartner
 
+The script has been adapted to Copernicus Browser multi-temporal scene handling and index, eoBrowserStats and dataMask variables added by András Zlinszky - aided by GitHub Copilot.
+
 ## Description of representative images
 
 1) The Gulf of Trieste, Northern Adriatic Sea, Sentinel-2 L1C, 2018-08-09