Water Masking Plugin is a high-performance, scientific geospatial toolkit designed for QGIS to extract highly accurate water masks and generate clean, smoothed vector waterbody boundaries from multispectral satellite imagery (Sentinel-2, Landsat 8/9, PlanetScope, etc.).
Powered by algorithms developed for high-precision coastal and hydrological modeling, this plugin provides automated sensor radiometry profiling, seven specialized radiometric segmentation methods, speckle noise reduction, and geodesic ellipsoidal polygon filtering.
- Key Features
- Supported Sensors & Radiometric Profiling
- The 7 Water Masking Methods
- Parameters Reference
- Outputs & Data Products
- Polygon Selection & Dominance Modes
- Recommended Workflows
- Changelog
- Author & License
- 7 Advanced Masking Algorithms: Ranging from adaptive local Otsu thresholding to single-SWIR shadow-immune indices and multi-band spectral slope decision trees.
-
Intelligent Sensor Radiometry Profiling: Automatically detects data bit depth (8-bit DN, 16-bit scaled integers, Landsat C2 SR, Sentinel-2 L2A BOA, 32-bit float reflectance) and scales data to physical surface reflectance
$[0.0, 1.0]$ . -
True Geodesic/Ellipsoidal Geometry Engine: Polygon area and perimeter are computed using
QgsDistanceAreawith WGS-84 ellipsoidal geometry, eliminating projection distortions across both Projected (UTM) and Geographic (EPSG:4326) coordinate reference systems. - Vector Polygon Override: Seamlessly accepts custom vector regions of interest (ROI) to override or refine automated spectral extraction.
- Speckle & Sieve Noise Suppression: Eliminates salt-and-pepper noise and small isolated false-positive water pixels using spatial connectivity sieve filtering.
- Sub-Pixel Edge Smoothing: Applies iterative geometry smoothing (Hermite / Chaikin spline smoothing) to replace jagged raster stair-stepping with clean, natural shoreline contours.
The algorithm ingests multispectral rasters and dynamically profiles pixel value distributions to compute linear surface reflectance:
| Sensor / Format | Typical Input Range | Auto Scale Factor | Offset |
|---|---|---|---|
| Float Surface Reflectance |
0.0 – 1.0
|
1.0 |
0.0 |
| Sentinel-2 L2A (BOA) |
0 – 10,000
|
0.0001 ( |
0.0 |
| Landsat 8/9 Collection 2 SR |
7,273 – 43,636
|
0.0000275 |
-0.20 |
| 16-Bit Scaled Integer |
0 – 65,535
|
Dynamic |
0.0 |
| 8-Bit Digital Numbers (DN) |
0 – 255
|
0.0 |
-
Principle: Maximizes between-class variance (
$\sigma_B^2$ ) on the Normalized Difference Water Index (McFeeters, 1996):$$\text{NDWI} = \frac{\rho_{\text{Green}} - \rho_{\text{NIR}}}{\rho_{\text{Green}} + \rho_{\text{NIR}}}$$ -
Threshold Selection:
$$\tau = \text{clamp}(\tau_{\text{Otsu}} + \text{offset}, -0.05, 0.35)$$ -
Condition:
$(\text{NDWI} > \tau) \land (\rho_{\text{NIR}} < 0.18)$ - Best Used For: Standard open-water bodies (lakes, reservoirs, open ocean) with balanced land and water distribution.
- Principle: Allows direct user definition of the threshold value on the McFeeters NDWI raster.
- Condition: $(\text{NDWI} > \text{Threshold}{\text{manual}}) \land (\rho{\text{NIR}} < 0.18)$
- Best Used For: Precise calibration when matching known ground truth, historical gauge lines, or high-turbidity regions.
-
Principle: Multi-index logical intersection combining green-NIR, green-SWIR, and broad visible-IR contrasts with strict vegetation and reflectance cutoffs:
$$\text{MNDWI} = \frac{\rho_{\text{Green}} - \rho_{\text{SWIR}}}{\rho_{\text{Green}} + \rho_{\text{SWIR}}}$$ $$\text{NWI} = \frac{\overline{\rho}{\text{Visible}} - \overline{\rho}{\text{IR}}}{\overline{\rho}{\text{Visible}} + \overline{\rho}{\text{IR}}}$$$$\text{NDVI} = \frac{\rho_{\text{NIR}} - \rho_{\text{Red}}}{\rho_{\text{NIR}} + \rho_{\text{Red}}}$$ -
Condition:
$(\text{MNDWI} > 0.0) \land (\text{NWI} > 0.0) \land (\text{NDVI} < 0.12) \land (\rho_{\text{NIR}} < 0.18)$ - Best Used For: Coastal wetlands, estuaries, and inland lakes with heavy riparian or submerged vegetation.
-
Principle: Employs Valley-Emphasis Otsu thresholding coupled with 1D Gaussian histogram smoothing. If scene variance is unimodal or low (
$\sigma < 0.05$ ), it automatically defaults to a conservative multi-index equation to prevent threshold collapse. -
Condition (Bimodal):
$(\text{NDWI} > \tau_{\text{VE}}) \land (\text{MNDWI} > -0.08) \land (\rho_{\text{NIR}} < 0.18) \land (\text{NDVI} < 0.18)$ - Best Used For: Large satellite scenes where water constitutes a small fraction of the image (prevents global Otsu over-segmentation).
-
Principle: Spatially partitions the scene into
$512 \times 512$ pixel blocks. For each tile exhibiting mixed spectral variance ($\sigma > 0.04$ ), local Otsu thresholding is computed using tile-specific class weights:$$\sigma_{B,\text{tile}}^2 = \omega_{b,\text{tile}} \cdot \omega_{f,\text{tile}} \cdot (\mu_{b,\text{tile}} - \mu_{f,\text{tile}})^2$$ Tiles with pure water or pure land are anchored to extreme values, and the resulting threshold grid is interpolated back to full image resolution via bilinear interpolation. - Condition: $(\text{MNDWI} > \text{Grid}{\text{bilinear}}) \land (\text{MNDWI} > -0.10) \land (\rho{\text{NIR}} < 0.18)$
- Best Used For: Complex coastal scenes with large expanses of land and varied water depths or atmospheric haze variations across the scene.
-
Principle: Automated Water Extraction Index optimized for sensors with a single SWIR channel (Feyisa et al., 2014 adaptation):
$$\text{AWEI} = \rho_{\text{Blue}} + 2.5 \cdot \rho_{\text{Green}} - 1.5 \cdot \rho_{\text{NIR}} - 2.0 \cdot \rho_{\text{SWIR}}$$ -
Condition:
$(\text{AWEI} > 0.0) \land (\text{MNDWI} > -0.08) \land (\rho_{\text{NIR}} < 0.18) \land (\rho_{\text{SWIR}} < 0.12) \land (\text{NDVI} < 0.20)$ - Best Used For: Urban coastal zones, ports, and mountainous regions to eliminate terrain shadows, dark roofs, and asphalt roads.
- Principle: 6-band hierarchical spectral decision tree exploiting the rapid attenuation of infrared radiation in water relative to visible wavelengths: $$\text{Ratio}{\text{Vis/IR}} = \frac{\rho{\text{Coastal}} + \rho_{\text{Blue}} + \rho_{\text{Green}}}{\rho_{\text{NIR}} + \rho_{\text{SWIR}}}$$
- Condition: $(\text{Ratio}{\text{Vis/IR}} > 1.20) \land (\rho{\text{Green}} > \rho_{\text{SWIR}}) \land (\rho_{\text{NIR}} < 0.18) \land (\rho_{\text{SWIR}} < 0.12) \land (\text{MNDWI} > -0.08) \land (\text{NDVI} < 0.18)$
- Best Used For: Turbid shallow waters, intertidal mudflats, and coral reef environments.
| Parameter | Type | Default | Description |
|---|---|---|---|
| Input Multispectral Satellite Image | Raster Layer | Required | Input multi-band satellite raster (GeoTIFF, VRT, etc.). |
| Output Folder | Folder | Temp folder | Target directory where all result files and intermediate indices are saved. |
| Coastal / Aerosol Band | Band | 1 (Optional) |
Band index for Coastal Blue (~443 nm). Defaults to Band 2 if omitted. |
| Blue Band | Band | 2 |
Band index for Blue (~490 nm). |
| Green Band | Band | 3 |
Band index for Green (~560 nm). |
| Red Band | Band | 4 |
Band index for Red (~665 nm). |
| NIR Band | Band | 8 |
Band index for Near-Infrared (~842 nm). |
| SWIR Band | Band | 11 |
Band index for Shortwave Infrared (~1610 nm). Defaults to NIR if unavailable. |
| Input Water Polygon | Vector Layer | None | Optional polygon layer (ROI) that directly overrides automated spectral extraction. |
| Water Masking Method | Enum | Smart Hybrid |
Selection of one of the 7 masking algorithms described above. |
| Manual Threshold | Double | 0.0 |
Custom threshold value used only when "Manual NDWI Threshold" is selected. |
| Otsu Threshold Adjustment Offset | Double | 0.0 |
Additive offset applied to computed Otsu thresholds (+ stricter, - broader). |
| Raster Noise Removal (Speckle Filter) | Integer | 10 |
Minimum pixel cluster size for sieve filtering. Eliminates isolated noise pixels. |
| Vector Edge Smoothing Iterations | Integer | 3 |
Geometry smoothing passes (0 = raw stair-step pixels, 3 = natural coastal curves). |
| Polygon Selection & Filtering Mode | Enum | Adaptive |
Strategy for filtering extracted waterbody polygons. |
| Minimum Polygon Area Filter (ha) | Double | 1.0 |
Minimum physical area (in hectares) required to retain a polygon. |
| Maximum Major Waterbodies Count | Integer | 3 |
Maximum number of candidate waterbodies to retain in Top N or Adaptive mode. |
| Dissolve All Valid Water Polygons | Boolean | False |
Merges all retained polygons into a single MultiPolygon feature. |
| Save Intermediate Spectral Indices | Boolean | True |
Exports NDVI, MNDWI, NWI, AWEI, and log bands into a 1_Review_Indices/ folder. |
| Reproject Outputs to WGS84 | Boolean | False |
Reprojects output raster and GPKG to EPSG:4326 (Default keeps source CRS). |
All outputs are written to the directory specified in Output Folder:
📁 Your_Output_Folder/
├── 📄 01_Land_Water_Mask.tif # Binary Water Mask (1 = Water, 0 = Land, 255 = NoData)
├── 📄 01_Waterbody_Polygon.gpkg # OGC GeoPackage with smoothed waterbody boundaries
└── 📁 1_Review_Indices/ # (Optional) Spectral diagnostic index rasters
├── NDVI.tif
├── MNDWI.tif
├── NWI.tif
├── AWEI.tif
├── Log_Blue.tif
└── Log_Green.tif
| Attribute | Data Type | Description |
|---|---|---|
ID |
Integer | Unique identifier / rank of the waterbody polygon. |
Name |
String | Descriptive designation (e.g. Primary Coastal Sea / Ocean, Major Coastal Lagoon / Bay). |
Area_km2 |
Double | True geodesic area in square kilometers ( |
Area_ha |
Double | True geodesic area in hectares ( |
Perim_km |
Double | True geodesic perimeter in kilometers ( |
Dominance_% |
Double | Area relative to the primary dominant waterbody in the scene ( |
-
Adaptive Significance (Auto 1–3 Major Waterbodies) [Recommended]:
Calculates dominance ratios relative to the largest detected waterbody. Retains significant features (
$> 0.5%$ of primary or$> 10$ ha) up to$99.5%$ of cumulative water area. - Primary Waterbody Only (Strict 1 Polygon): Retains only the single largest contiguous waterbody (ideal for offshore bathymetric modeling).
-
Top N Major Waterbodies:
Retains the largest
$N$ polygons sorted strictly by physical area. -
All Polygons Exceeding Minimum Area:
Retains every polygon whose area exceeds
Minimum Polygon Area Filter (ha).
-
Open Coastlines & Clear Marine Waters:
Use Otsu (Automatic NDWI) or Smart Hybrid (Dynamic Auto) with Vector Smoothing
$= 3$ . - Inland Reservoirs & Agricultural Landscapes: Use 3 Indices Equation to prevent false positives over wet crops or dark soils.
- Large Satellite Granules with High Land-to-Water Ratio: Use Tiled / Local Adaptive Otsu to eliminate class imbalance artifacts.
- Coastal Cities, Ports, and Steep Topography: Use Modified AWEI (Single-SWIR) to suppress building shadows, asphalt, and cloud shadow contamination.
- Shallow Lagoons, Intertidal Reefs & Turbid Estuaries: Use Spectral Slope & Profile Tree.
- Fixed: Resolved critical class-weight bug in Tiled Local Adaptive Otsu variance calculation (
t_weight_b * t_weight_f). - Enhanced: Full geodesic/ellipsoidal area and perimeter measurement via
QgsDistanceArea, resolving geographic CRS (EPSG:4326) distortion. - Protected: Added division-by-zero guards in spectral slope and band ratio calculations.
- Optimized: Memory footprint reduction via on-demand computation and explicit garbage collection of large raster buffers.
- Enriched: Complete parameter tooltips and documentation inside the QGIS Processing dialog (
shortHelpString).
- Added Tiled Adaptive Otsu, Modified AWEI Single-SWIR, and Spectral Slope Tree.
- Implemented pure NumPy / Rasterio acceleration engine.
- Author: Mohamed Aly Nasef
- Email: Eng.m.nasef2017@gmail.com
- GitHub: https://github.com/Nasef2017/Water-Masking
- License: Apache License 2.0 (Apache-2.0) — see LICENSE for details.