# CoastSat

Python code to extract shorelines at sub-pixel resolution from publicly available satellite imagery. The shoreline detection algorithm is described in *Vos K., Harley M.D., Splinter K.D., Simmons J.A., Turner I.L. (in review). Capturing intra-annual to multi-decadal shoreline variability from publicly available satellite imagery, Coastal Engineering*. Google Earth Engine's Python API is used to access the archive of publicly available satellite imagery (Landsat series and Sentinel-2).

Written by *Kilian Vos*.

## Description

Satellite remote sensing can provide low-cost long-term shoreline data capable of resolving the temporal scales of interest to coastal scientists and engineers at sites where no in-situ measurements are available. Satellite imagery spannig the last 30 years with constant revisit periods is publicly available and suitable to extract repeated measurements of the shoreline positon.
*coastsat* is an open-source Python module that allows to extract shorelines from Landsat 5, Landsat 7, Landsat 8 and Sentinel-2 images.
The shoreline detection algorithm proposed here combines a sub-pixel border segmentation and an image classification component, which refines the segmentation into four distinct categories such that the shoreline detection is specific to the sand/water interface.

## Requirements

In this section instructions on how to install all the necessary Python packages using *Anaconda* are provided.
Best practice is to create a new environment that will contain all the packages. To do this open the *Anaconda prompt* and run the following command: 
- *conda create -n coastsat python=3.6* (it will create a new Python 3.6 environment called *coastsat*)

Then activate the new environment run:
- *conda activate coastsat*

Now you need to install **Google Earth Engine's Python API** module.
Follow these steps to install the *earthengine-api* package:
- go to https://earthengine.google.com and go to signup
Go back to the *Anaconda prompt* where the *coastsat* environment is active and run the following commands:
- *conda install -c conda-forge earthengine-api*
- *earthengine authenticate* (this will open a web browser where you will have login with your Google Earth Engine credentials)

Once you have installed the *earthengine-api*, you need to install the other Python packages that are used in this toolbox (*scikit-image*, *scikit-learn* etc...). 

If on *win-64*, use the *Anaconda prompt* to navigate to the directory where you downloaded the repository and run:
- *conda install --name coastsat --file environment.txt* (this will install all the necessary packages)

Now you are ready to start using the toolbox!

If on *linux* or *osx*, you can create the *coastsat* environment with the following command:
- *conda env create -f environment.yml*

Then, follow the instructions above to install *earthengine-api* in your environment.

## Use 

A demonstration of the use of *coastsat* is provided in the Jupyter Notebook *shoreline_extraction.ipynb*. The code can also be run in Spyder with *main_spyder.py*.

The first step is to retrieve the satellite images of the region of interest from Google Earth Engine servers by calling *SDS_download.get_images(sitename, polygon, dates, sat_list)*:
- *sitename* is a string which will define the name of the folder where the files will be stored
- *polygon* contains the coordinates of the region of interest (longitude/latitude pairs)
- *dates* defines the dates over which the images will be retrieved (e.g., *dates = ['2017-12-01', '2018-01-01']*)  
- *sat_list* indicates which satellite missions to consider (e.g., *sat_list = ['L5', 'L7', 'L8', 'S2']* will download images from Landsat 5, 7, 8 and Sentinel-2 collections).

The images are cropped on the Google Earth Engine servers and only the region of interest is downloaded resulting in low memory allocation (~ 1 megabyte/image for a 5km-long beach). The relevant image metadata (time of acquisition, geometric accuracy...etc) is stored in a file named *sitename_metadata.pkl*.

Once the images have been downloaded, the shorelines are extracted from the multispectral images using the sub-pixel resolution technique described in *Vos K., Harley M.D., Splinter K.D., Simmons J.A., Turner I.L. (in review). Capturing intra-annual to multi-decadal shoreline variability from publicly available satellite imagery, Coastal Engineering*.
The shoreline extraction is performed by the function SDS_shoreline.extract_shorelines(metadata, settings). The user must define the settings in a Python dictionary. To ensure maximum robustness of the algorithm the user can optionally digitize a reference shoreline (byc calling *SDS_preprocess.get_reference_sl(metadata, settings)*) that will then be used to identify obvious outliers and minimize false detections. Since the cloud mask is not perfect (especially in Sentinel-2 images) the user has the option to manually validate each detection by setting the *'check_detection'* parameter to *True*.
The shoreline coordinates (in the coordinate system defined by the user in *'output_epsg'* are stored in a file named *sitename_out.pkl*.

## Issues and Contributions

Looking to contribute to the code? Please see the [Issues page](https://github.com/kvos/coastsat/issues).