search

ydoherty / CoastSat.PlanetScope

Batch shoreline extraction toolkit for PlanetScope Dove satellite imagery
GNU General Public License v3.0
46 stars 12 forks source link

readme

CoastSat.PlanetScope

Yarran Doherty, UNSW Water Research Laboratory, 01/2021

Description

CoastSat.PlanetScope is an open-source extension to the CoastSat python toolkit enabling users to extract time-series of shoreline position from PlanetScope Dove satellite imagery. Similar to CoastSat, the CoastSat.PlanetScope extension utilises a machine-learning shoreline detection algorithm to classify images into sand, water, whitewater and other pixel classes prior to a sub-pixel shoreline extraction process. An additional co-registration step is implemented to minimise the impact of geo-location errors. Transect intersection and a tidal correction based on a generic beach slope is then applied to provide a timeseries of shoreline position.

Output files include:

Installation

For users of Coastsat, the CoastSat.PlanetScope toolkit may be run in the original CoastSat environment once the following packages are installed:

For first time users or where rasterio/arosics installation issues arise, a coastsat_ps environment may be installed using the provided environment.yml file. The easiest method of installation is using Anaconda which can be downloaded here. Once Anaconda is installed, open Anaconda Prompt and navigate to the local downloaded CoastSat.PlanetScope repo folder by entering "cd C:\add\filepath\here\to\CoastSat.PlanetScope". Once this has been done, enter the following commands one by one to install the planetscope environment from the provided .yml file:

conda env create -f environment.yml -n coastsat_ps

conda activate coastsat_ps

spyder

Once spyder is open, navigate to the CoastSat.PlanetScope folder to set the working direcctory (top right hand box in spyder) and open the CoastSat_PS.py file to begin the example run through. Note that every time you want to run the code, you will need to activate the coastsat_ps environnment and open spyder using the last two lines of code above.

Data Requirements

PlanetScope images must be manually downloaded by the user.

All user input files (area of interest polygon, transects & tide data) should be saved in the folder "...CoastSat.PlanetScope/user_inputs"

Beach slopes for the tidal correction (step 5) can be extracted using the CoastSat.Slope toolkit

Usage

It is recommended the toolkit be run in spyder. Ensure spyder graphics backend is set to 'automatic' for proper interactive plot rendering.

CoastSat.PlanetScope is run from the CoastSat_PS.py file.

Settings and interactive steps are based on the CoastSat workflow and will be familiar to users of CoastSat.

Interactive popup window steps include:

Results and plots are saved in '...CoastSat.PlanetScope/outputs/site_name/shoreline outputs'.

Training Neural-Network Classifier

Due to the preliminary stage of testing, validation was primarily completed at Narrabeen-Collaroy beach in Sydney, Australia. As such, the NN classifier is optimised for this site and may perform poorly at alternate sites with differing sediment composition. It is recommended a new classifier be trained for such regions.

Steps are provided in "...CoastSat.PlanetScope/coastsat_ps/classifier/train_new_classifier.py".

Validation Results

Detailed results and methodology outlined in:

Doherty Y., Harley M.D., Splinter K.D., Vos K. (2022). A Python Toolkit to Monitor Sandy Shoreline Change Using High- Resolution PlanetScope Cubesats. Environmental Modelling & Software. https://doi.org/10.1016/j.envsoft.2022.105512

As a starting point for user validation studies, an example jupyter notebook comparing CoastSat (Landsat/Sentinel-2) shorelines against in-situ survey data can be found on the main CoastSat repo for Narrabeen-Collaroy beach. Note that CoastSat.PlanetScope results will require re-structuring to match the CoastSat validation input format.

Development Opportunities

Known Issues & Workarounds

The following issues have been identified by users and workarounds are presented below. My availability to maintain and update this repo is limited so user feedback, bug fixes and devlopments are encouraged!