WaterQuality

Screenshot

Synopsis

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.

Dependencies

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

Instalation

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 .

Inversion Functions

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'
    }
}

Usage:

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.

Institutions

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)

License

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.

References

[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.

cordmaur / WaterQuality

readme