The WaterQuality package extends the functionalities of the WaterDetect[1] package (https://github.com/cordmaur/WaterDetect) to calculate continental water quality parameters from satellite reflectances. The inversion algorithms are not implemented, as they depend on the region or specifics calibration and can be found in the literature. Once the inversion function is defined, the water quality parameter is calculated just where there exist water, according to the waterdetect mask and the reports are generated.
As an example, an inversion algorithms for total suspended matter (TSM), proposed by Nechad et al. (2010)[2] has been implemented. Refer to the notebook 01_Example.ipynb under the nbs/ folder for more information
The Medium article Creating water quality maps from remote sensed images with Python has the first steps on the package.
The required libraries are:
GDAL>=3.0.2
matplotlib>=3.1.2
PyPDF2>=1.26.0
scipy>=1.3.2
scikit-learn>=0.22
skimage>=0.16.2
numpy>=1.17
waterdetect>=1.5
Alternatively:
conda env create -f environment.yml
conda activate waterquality
The easiest way to install waterquality package is with pip command, directly from the git repository, like so:
pip install git+https://github.com/cordmaur/WaterQuality.git@main
Alternatively, you can clone the repository and install from its root throught the following commands:
git clone https://github.com/cordmaur/WaterQuality.git
cd WaterQuality
pip install -e .
If the waterquality is being used from a Jupyter Notebook, refer to the medium story for more information on how to create new functions and pass them to the algorithm.
If it is being called from the console, the functions need to be informed in the file inversion_functions.py.
The new fuction should be defined with the name of the band (as used in WaterDetect) as argument (e.g., Red, Green, Nir, Mir, etc.).
Once created, the functions that will be used should appear in the functions dictionary.
These examples are available inside the inversion_functions.py file:
# Bellow is an example extracted from Nechad et al. (2010)
def nechad(Red):
a = 610.94
c = 0.2324
spm = 610.94 * Red / (1 - (Red/c))
return spm
functions = {
'SPM_Nechad3': {
'function': nechad,
'units': 'mg/l'
}
}
Make sure waterdetect is already installed, following the instructions in https://github.com/cordmaur/WaterDetect.
Once installed, a waterquality entry point is created in the path of the environment.
One can check the installation and options by running waterquality --help. Check also the waterdetect instalation. GDAL will be necessary for waterquality package.
usage: waterquality [-h] [-GC] [-i INPUT] [-o OUT] [-s SHP] [-sm] [-p PRODUCT] [-cwd CONFIG_WD] [-cwq CONFIG_WQ]
The waterquality adds a post-processing function to waterdetect package to calc water quality parameters. Waterdetect
should be installed in the environment.
optional arguments:
-h, --help show this help message and exit
-GC, --GetConfig Copy the inversion_functions.py, WaterQuality.ini and the WaterDetect.ini into the current
directory and skips the processing. Once copied you can edit the .ini file and launch the
waterquality without -c option.
-i INPUT, --input INPUT
The products input folder. Required.
-o OUT, --out OUT Output directory. Required.
-s SHP, --shp SHP SHP file. Optional.
-sm, --single Run WaterDetect over only one image instead of a directory of images. Optional.
-p PRODUCT, --product PRODUCT
The product to be processed (S2_THEIA, L8_USGS, S2_L1C or S2_S2COR)
-cwd CONFIG_WD, --config_wd CONFIG_WD
WaterDetect configuration file (.ini). Only needed if running WD.If not passed,
WaterDetect.ini from current dir is used as default.
-cwq CONFIG_WQ, --config_wq CONFIG_WQ
WaterQuality configuration file (.ini). If not passed, WaterQuality.ini from current dir is
used as default.
The waterquality uses the WaterQuality.ini configuration file as well as WaterDetect.ini from waterdetect package.To
copy the package's default .ini files into the current directory, type: `waterquality -GC .` without other arguments
and it will copy WaterDetect.ini and WaterQuality.ini into the current directory.The file inversion_functions.py
should be updated with the necessary inversion functions.
WaterQuality can be run from the console or through a notebook. For notebook usage, refer to the notebook 01_Example.ipynb under nbs/ folder.
The basic usage for the waterquality from the console is:
waterquality -i c:/input_folder -i -c:/output_folder -p S2_S2COR [-s any_shape.shp]
The input directory should contain the uncompressed folders for the images. The script will loop through all folders in the input directory and save the water masks, graphs and reports to the output folder. The output folder must be created beforehand.
If the config file is not specified, the script will search for WaterDetect.ini and WaterQuality.ini in the current folder.
- ANA - Agência Nacional de Águas (https://www.gov.br/ana/en/)
- GET - Géosciences Environnement Toulouse (https://www.get.omp.eu/)
- IRD - Institut de Recherche pour le Développement (https://en.ird.fr/)
- CNES - Centre National d'Études Spatiales (https://cnes.fr/fr)
This code is licensed under the GNU General Public License v3.0 license. Please, refer to GNU's webpage (https://www.gnu.org/licenses/gpl-3.0.en.html) for details.
[1] Cordeiro, Maurício C. R., Jean-Michel Martinez, and Santiago Peña-Luque. 2021. “Automatic Water Detection from Multidimensional Hierarchical Clustering for Sentinel-2 Images and a Comparison with Level 2A Processors.” Remote Sensing of Environment 253 (February): 112209. https://doi.org/10.1016/j.rse.2020.112209.
[2] Nechad, B., K. G. Ruddick, and Y. Park. 2010. “Calibration and Validation of a Generic Multisensor Algorithm for Mapping of Total Suspended Matter in Turbid Waters.” Remote Sensing of Environment 114 (4): 854–66. https://doi.org/10.1016/j.rse.2009.11.022.