RivWidthCloud
RivWidthCloud, or RWC, is an open source software written to automate extracting river centerline and width from remotely sensed images. It was developed for the Google Earth Engine (GEE) platform and developed for both its JavaScript and Python APIs. A complete description of the method can be found in our publication RivWidthCloud: An Automated Google Earth Engine algorithm for river width extraction from remotely sensed imagery.
Usage guide
Note (update on December 31 2022)
USGS has discontinued the prodcution of collection 1 images, which RivWidthCloud was originally developed for. Use this script and the functions within to run RivWidthCloud on collection 2 images on Google Earth Engine. Original RivWidthCloud uses DSWE algorithm to identify water pixels, but since collection 2 has different reflectance values than collection 1, the original algorithm will need to be adapted before applied on collection 2 image. For now, the RivWidthCloud for collection 2 image uses the water classification from the Fmask algorithm, which is directly extracted from the quality band ‘QA_PIXEL’. Please note that there might be future versions of RivWidthCloud with DSWE algorithm adapted. Future updates will be released here.
The easiest and quickest way to use RWC is to run it from Google Earth Engine JavaScript code editor (https://developers.google.com/earth-engine/playground), where the functions in the RWC can be directly loaded and need no setup. The README file in the RivWidthCloud_JavaScript folder contains example script to run RWC for one Landsat image. If you need to run RWC over many Landsat images, then running the Python version might be more efficient.
JavaScript version quick example
The following example computes and exports river centerlines and widths for one Landsat image. It can be copy and paste into the GEE code editor (like this) and run directly from the webpage.
MAIN FUNCTION in rwc_landsat.js:
* parameterize riverwidth function
* @param {String} WATER_METHOD Water classification method ('Jones2019' or 'Zou2018'). Default: 'Zou2018'
* @param {integer} MAXDISTANCE Maximum distance (unit: meters) to check water pixel's connectivity to GRWL centerline. Default: 4000
* @param {integer} FILL_SIZE islands or bars smaller than this value (unit: pixels) will be removed before calculating centerline. Default: 333
* @param {integer} MAXDISTANCE_BRANCH_REMOVAL length of pruning. Spurious branch of the initial centerline will be removed by this length (unit: pixels). Default: 500
* @param {ee.Geometry.Polygon} AOI A polygon (or rectangle) geometry define the area of interest. Only widths and centerline from this area will be calculated. Default: null
* @return {Function} The river width function that takes SR image ID as input and outputs csv file of centerline and widths
rwGenSR(WATER_METHOD, MAXDISTANCE, FILL_SIZE, MAXDISTANCE_BRANCH_REMOVAL, AOI)
var fns = require('users/eeProject/RivWidthCloudPaper:rwc_landsat.js');
var imageId = "LC08_L1TP_022034_20130422_20170310_01_T1";
var aoi = ee.Geometry.Polygon(
[[[-88.47207053763748, 37.46382559855354],
[-88.47207053763748, 37.375480838211885],
[-88.2592104302156, 37.375480838211885],
[-88.2592104302156, 37.46382559855354]]], null, false);
var rwc = fns.rwGenSR('Jones2019', 4000, 333, 500, aoi);
var widths = rwc(imageId);
widths = widths.map(function(f) {return(f.setGeometry(null))});
Export.table.toDrive({
collection: widths,
description: imageId,
folder: "",
fileNamePrefix: imageId,
fileFormat: "CSV"});
Python version quick example
Running Python version requires setting up GEE Python environment beforehand. The tutorial for setting up the environment can be found at the official GEE user guide (https://developers.google.com/earth-engine/python_install).
Export widths for one image given the image ID
# show the help message
python rwc_landsat_one_image.py -h
# export widths for one image (LC08_L1TP_022034_20130422_20170310_01_T1) as shp file
python rwc_landsat_one_image.py LC08_L1TP_022034_20130422_20170310_01_T1 -f shp
Export widths for multiple images with IDs read from a CSV file
# show the help message
python rwc_landsat_batch.py -h
# running multiple tasks with each one extracting widths from one image
python rwc_landsat_batch.py example_batch_input/example_batch_input.csv
Files
The core algorithms responsible for calculating river centerlines and widths are identical in the JavaScript and the Python version. However, there is minor differences in how users might call these functions. Below is a description of the files that were common to both version. For files unique to different version please refer to the README.md file in its corresponding folder.
List of files that’s common to both the JavaScript and the Python version:
-
functions_Landsat578: contains files to process Landsat collection 1 tier 1 SR images
-
functions_Landsat578/functions_landsat: process Landsat image to (1) add classified water mask and (2) add bands of quality flags (cloud, cloud shadow, snow/ice, hill shadow)
-
functions_Landsat578/functions_waterClassification_Zou2018: contains water classification function based on Zou et al., 2018.
-
functions_Landsat578/functions_waterClassification_Jones2019: contains water classification function based on Dynamic Surface Water Extent (DSWE) based on Jones, 2019.
-
rwc_landsat: contains a wrapper function that sets the default parameter values for the RivWidthCloud software and outputs the main RivWidthCloud function.
-
functions_centerline_width: contains image processing functions that calculate 1px-wide centerline, crosssectional direction and widths sequentially.
-
functions_river: contains functions that calculate channel and river mask based on a given water mask.
Outputs
| Column name |
Description |
Unit |
| latitude |
Latitude of the centerline point |
Decimal degree |
| longitude |
Longitude of the centerline point |
Decimal degree |
| width |
Wetted river width measured at the centerline point |
Meter |
| orthogonalDirection |
Angle of the cross-sectional direction at the centerline point |
Radian |
| flag_elevation |
Mean elevation across the river surface (unit: meter) based on MERIT DEM |
Meter |
| image_id |
Image ID of the input Landsat image |
NA |
| crs |
the projection of the input image |
NA |
| flag_hillshadow |
indicate potential topographic shadow nearby that could affect the width accuracy |
NA |
| flag_snowIce |
indicate potential snow/ice nearby that could affect the width accuracy |
NA |
| flag_cloud |
indicate potential cloud nearby that could affect the width accuracy |
NA |
| flag_cldShadow |
indicate potential cloud shadow nearby that could affect the width accuracy |
NA |
| endsInWater |
indicate inaccurate width due to the insufficient length of the cross-sectional segment that was used to measure the river width |
NA |
| endsOverEdge |
indicate width too close to the edge of the image that the width can be inaccurate |
NA |
flag_snowIce, flag_cloud, flag_cldShadow, endsInWater, endsOverEdge, flag_hillshadow: all with values ranging from 0 to 1 with non-zero denoting that the corresponding conditions exist and the calculated width could be affected.
Cite
Yang, X., T.M. Pavelsky, G.H. Allen, and G. Donchyts (2019), RivWidthCloud: An Automated Google Earth Engine algorithm for river width extraction from remotely sensed imagery, IEEE Geoscience and Remote Sensing Letters. DOI: 10.1109/LGRS.2019.2920225
An early access of this article can be found at: https://ieeexplore.ieee.org/document/8752013
We welcome any feedback or suggestions for improvement. If you have any questions about the algorithm, please don’t hesitate to contact [email protected].
评论