You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
``InfeRes`` is a python package that is designed to help automatic extraction of reservoir characteristics (water surface area, level, and storage-volume) time-series by taking leverage
7
+
``InfeRes`` is a python package that is designed to help automatic extraction of reservoir characteristics (water surface area, level, and storagevolume) time-series by taking leverage
8
8
of the Google Earth Engine data collection (`Landsat series <https://developers.google.com/earth-engine/datasets/catalog/landsat/>`_, `Sentinel-2 <https://developers.google.com/earth-engine/datasets/catalog/sentinel-2/>`_), and high resolution `DEM (30m) <https://www.usgs.gov/centers/eros/science/usgs-eros-archive-digital-elevation-shuttle-radar-topography-mission-srtm-1/>`_.
9
9
It built on top of `GDAL <https://gdal.org/>`_, `Scikit-Learn <https://scikit-learn.org/>`_, `NumPy <https://numpy.org/>`_ and `Matplotlib <https://matplotlib.org/>`_,
10
10
and other popular python packages. ``InfeRes`` is developed with a novel algorithm which helps inferring reservoir characteristics even from the partially cloudy images.
11
11
``InfeRes`` can be applied to monitor water surface area in any reservoir or waterbody; whereas, storage-volume can be obtained for the large reservoirs (storage >= 0.1m:sup:`3`) listed in the `GRanD <https://www.globaldamwatch.org/directory/>`_ database.
12
12
13
-
Components of InfeRes
14
-
---------------------
13
+
The InfeRes workflow is fully modularized, with scripts organized by function:
15
14
16
-
1. Data download
15
+
1- main.py: Central orchestration script for running the full InfeRes pipeline over multiple reservoirs.
17
16
18
-
- Using standalone python environment (``DataDownload_GEE.py``)
19
-
- Using web browser-based python environment (``DataDownload_GEE_GoogleColab.py``)
17
+
2- utils.py: Generic helper functions for raster operations, coordinate transformations, and basic math.
20
18
21
-
2. Data processing
19
+
3- metadata_builder.py: Generates geospatial metadata from the GRanD database for input preparation.
22
20
23
-
- Main python module (``main.py``)
24
-
- Python module to create reservoir's Area-Elevation-Storage curves (``CURVE.py``)
25
-
- Python module for pre-processing of satellite images (``PREPROCESSING.py``)
26
-
- Python module to estimate reservoir's area and storage time-series (``WSA.py``)
21
+
4- download_baselayers.py: Downloads foundational datasets (e.g., DEM, GSW frequency, and maximum extent layers) from Google Earth Engine.
27
22
28
-
Folder structure
29
-
---------------------
23
+
5- reservoir_delineation.py: Identifies reservoir extents based on DEMs and frequency maps.
24
+
25
+
6- reservoir_curve.py: Builds hypsometric curves from DEM data and reference curves (e.g., GRDL dataset).
30
26
31
-
Download **InfeRes package** from GitHub (`link <https://github.com/Critical-Infrastructure-Systems-Lab/InfeRes/>`_) and unzip it inside any directory. For instance, after unzip InfeRes path should be *D:/My Drive/code/*. Another folder 'Reservoirs' (path *D:/My Drive/Reservoirs/*), where your satellite data will be downloaded. We have provided the example data for AyunHa reservoir for a quick setup and testing InfeRes as a case study.
27
+
7- satellite_composite.py: Constructs Landsat and Sentinel-based NDWI composites over specified periods and regions.
32
28
33
-
**NOTE**: Please unzip all compressed folders before running InfeRes. The folder directories and their paths should be as follows after the unzip:
29
+
8- ndwi_processing.py: Preprocesses Landsat and Sentinel imagery, including NDWI calculation and cloud masking.
30
+
31
+
9- satellite_water_area.py: Extracts water surface area from satellite NDWI using filtering and clustering methods.
32
+
33
+
10- area_to_storage.py: Converts surface water area estimates into elevation and storage (volume) using reservoir hypsometric curve.
- Open spyder and load all the InfeRes modules (i.e. ``DataDownload_GEE.py``, ``main.py``, ``CURVE.py``, ``PREPROCESSING.py``, and ``WSA.py``)
71
-
72
-
Usage Instructions
73
-
---------------------
74
-
75
-
1. **DataDownload_GEE.py**
76
-
77
-
``DataDownload_GEE.py`` is the first step towards running **InfeRes**. ``DataDownload_GEE.py`` will download the satellite images and store them in the Google Drive. Therefore, make sure you have sufficient space in your cloud storage (Google Drive in this case) before running ``DataDownload_GEE.py``. Please also note that the downloading will take time to finish, which depends on the size of satellite image, downloading speed, and the number of images ordered. Therefore, one should first run ``DataDownload_GEE.py`` standalone, and wait until all the orders are successfully downloaded before running the other modules of InfeRes.
78
-
79
-
Inputs required (variable name):
80
-
81
-
- Name of the reservoir (res_name) = AyunHa
82
-
- Year of commission (res_built_year) = 1997
83
-
- Bounding box (boundary) = [108.155, 13.700, 108.300, 13.575]. Where, (108.155, 13.700) and (108.300, 13.575) are the (longitude, latitude) of top-left and bottom-right points of the bounding box.
84
-
85
-
The data will be downloaded inside *D:/My Drive/Reservoirs/AyunHa/* in two different folders.
86
-
87
-
- Raw satellite data (Normalized Difference Water Index or NDWI in this case) will be at *D:/My Drive/Reservoirs/AyunHa/AyunHa_RawData/*.
88
-
- Supplementary data (DEM, Water frequency, Maximum reservoir extent in this case) will be at *D:/My Drive/Reservoirs/AyunHa/AyunHa_Supporting/*.
89
-
90
-
2. **DataDownload_GEE_GoogleColab.py**
91
-
92
-
``DataDownload_GEE_GoogleColab.py`` is an alternative of ``DataDownload_GEE.py``, which runs of web browser-based python environment such as Google Colab. It also takes the same set of inputs (i.e. Name of the reservoir, Year of commission, and Bounding box). However, in this case the data will be downloaded in next in your Google Drive, so the downloading path will be *D:/My Drive/AyunHa_RawData/* and *D:/My Drive/AyunHa_Supporting/* for raw satellite data and supplementary data, respectively.
93
-
94
-
Please note that you need to maintain the folder structure as *D:/My Drive/Reservoirs/AyunHa/AyunHa_RawData/* and *D:/My Drive/Reservoirs/AyunHa/AyunHa_Supporting/* before running the InfeRes modules. Therefore, you need to move the data to the correct folder arrangement once the downloading is completed.
95
-
96
-
3. **PREPROCESSING.py**
97
-
98
-
``PREPROCESSING.py`` performs the following tasks:
99
-
100
-
- Creating the reservoir isolation raster (binary map of reservoir maximum extent).
101
-
- Creating reservoir isolation for DEM (masked DEM)
102
-
- Reprojecting and resizing (or clipping) the satellite images including DEM, water extent, and frequency raster.
103
-
- Creating a collection of relatively good quality (less cloud cover) satellite images.
104
-
105
-
Inputs required (variable name):
106
-
107
-
- Name of the reservoir (res_name) = AyunHa
108
-
- Year of commission (res_built_year) = 1997
109
-
- Maximum water level in meter (max_wl) = 211
110
-
- A point coordinates on the reservoir (point) = [108.232, 13.638]
- Reservoir's design capacity (i.e. maximum capacity) = 253 (this value can be extracted from the GRanD database)
127
-
128
-
b. If reservoir has built after the acquisition of DEM (i.e. year 2000, as we are using SRTM DEM):
129
-
130
-
- Name of the reservoir (res_name) = AyunHa
131
-
- Maximum water level in meter (max_wl) = 211
132
-
133
-
5. **WSA.py**
134
-
135
-
``WSA.py`` estimates the area and storage time-series from the pre-processed time satellite images, which only takes input as the name of the reservoir.
136
-
137
-
Inputs required (variable name):
138
-
139
-
- Name of the reservoir (res_name) = AyunHa
140
-
141
-
How to Run?
142
-
---------------------
143
-
144
-
**Step 1.** Run either **DataDownload_GEE_GoogleColab.py** or **DataDownload_GEE.py** standalone, and let the data download finish (i.e. Satellite NDWI images, Maximum water extent, Water frequency, and DEM).
145
-
146
-
**Step 2.** (Assuming you already have all the required datasets) Open Spyder and locate the directory to the code, and load the modules ``main.py``, ``PREPROCESSING.py``, ``CURVE.py``, and ``WSA.py``.
147
-
148
-
**Step 3.** Configure ``main.py``
149
-
150
-
- Modify the path of InfeRes directory (i.e. **parent_directory**)
151
-
- Prepare the input file (i.e. **inputs_InfeRes.csv**)
152
-
153
-
**inputs_InfeRes.csv** contains:
154
-
155
-
* Name of the reservoir (res_name) = AyunHa
156
-
* Year of commission (res_built_year) = 1997
157
-
* Maximum water level in meter (max_wl) = 211
158
-
* GRanD ID = 7153 (if GRanD ID is not available, assign 0)
159
-
* A point coordinates on the reservoir (point) = [108.232, 13.638]
* Reservoir's design capacity = 253 (assign 0, if reservoir has built after 2000)
162
-
* Run the ``main.py``
163
-
164
-
NOTE: ``main.py`` calls other modules in a sequential order (``PREPROCESSING.py`` -> ``CURVE.py`` -> ``WSA.py``) to get the desired outputs (i.e. reservoir's area, level, and storage in this case).
165
-
166
-
Outputs
167
-
---------------------
168
-
169
-
The outputs will be saved in a folder called *'Outputs'* in the same directory where your input data are kept.
- List of images used for estiamtion of storage (**Image_List.csv**)
175
-
- Table containing the scene-based (landsat and Sentinel) reservoir area and storage (**WSA.csv**)
176
-
- Updated table containing scene-based reservoir area in km:sup:`2`, water level in m, and storage in million m:sup:`3` (**WSA_updated.csv**)
177
-
- Intermediate raster images
178
-
- Intermediate figures (inside a seperate folder called *JPG_files*)
179
43
180
44
References
181
45
---------------------
182
46
183
47
- Vu, T.D., Dang, T.D., Galelli, S., Hossain, F. (2022) `Satellite observations reveal 13 years of reservoir filling strategies, operating rules, and hydrological alterations in the Upper Mekong River basin. <https://hess.copernicus.org/articles/26/2345/2022/>` Hydrol. Earth Syst. Sci., 26, 2345–2364.
184
48
185
-
- Mahto, S., Fatichi, S., Galelli, S. (2024) `A 1985–2023 time series dataset of absolute reservoir storage in Mainland Southeast Asia (MSEA-Res). <https://essd.copernicus.org/preprints/essd-2024-441/>` Earth Syst. Sci. Data Discuss, in review.
49
+
- Mahto, S., Fatichi, S., Galelli, S. (2025) `A 1985–2023 time series dataset of absolute reservoir storage in Mainland Southeast Asia (MSEA-Res). <https://doi.org/10.5194/essd-17-2693-2025>` Earth Syst. Sci. Data, 17, 2693–2712.
0 commit comments