Skip to content

seanyx/RivWidthCloudPaper

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

49 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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)

// Goal: calculate river centerlines and widths for one Landsat SR image (LC08_L1TP_022034_20130422_20170310_01_T1)

// load in RivWidthCloud
var fns = require('users/eeProject/RivWidthCloudPaper:rwc_landsat.js');

// assign the image id of the image from which the widths and centerline will be extracted
var imageId = "LC08_L1TP_022034_20130422_20170310_01_T1";

// setting the parameters for the rivwidthcloud (rwc) function
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);

// apply the rwc function to the image
var widths = rwc(imageId);

// remove the geometry before exporting the width as CSV file
widths = widths.map(function(f) {return(f.setGeometry(null))});

// export the result as a CSV file into Google drive
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

Contact

We welcome any feedback or suggestions for improvement. If you have any questions about the algorithm, please don't hesitate to contact yangxiao@live.unc.edu.

About

A Google Earth Engine based algorithm that extracts river centerlines and widths from satellite images

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published