CoastSat

CoastSat is an open-source software toolkit written in Python that enables users to obtain time-series of shoreline position at any coastline worldwide from 40 years (and growing) of publicly available satellite imagery (Landsat and Sentinel-2).

Finding CoastSat useful? Show your support with a Github star — it’s a simple click that helps others discover it ⭐️

:point_right: Visit the CoastSat website to explore and download existing satellite-derived shoreline datasets generated with CoastSat in the Pacific and Atlantic basins.

<details> <summary><strong>Project description</strong></summary>

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 field measurements are available. CoastSat enables the non-expert user to extract shorelines from Landsat 5, Landsat 7, Landsat 8, Landsat 9 and Sentinel-2 images. The shoreline detection algorithm implemented in CoastSat is optimised for sandy beach coastlines. It 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.

The toolbox has the following functionalities:

1. easy retrieval of satellite imagery spanning the user-defined region of interest and time period from Google Earth Engine, including state-of-the-art pre-processing steps (re-projecting the different bands, pansharpening, advanced cloud masking).
2. automated extraction of shorelines from all the selected images using a sub-pixel resolution technique and options for quality-control.
3. intersection of the 2D shorelines with user-defined shore-normal transects to create time-series of shoreline change.
4. tidal correction of shoreline time-series and extraction of tidal levels at the time of image acquisition from a global tide model (FES2022)
5. post-processing of the shoreline time-series, despiking and seasonal averaging.
6. Beach slope estimation using satellite-derived shorelines and predicted tides

</details> <details> <summary><strong>Latest updates</strong></summary>

:arrow_forward: (2024/10/02) CoastSat v3.0: integration with FES2022 global tide model to perform tidal correction and beach slope estimation within CoastSat.

:arrow_forward: (2024/08/29) CoastSat v2.7: reverse compatibility for file downloads (pre v2.6) and removed Collection 1 (deprecated, throws an error)

:arrow_forward: (2024/05/07) CoastSat v2.6: added the tilename at the end of each image filename when downloading so that images can be separated by tiles if needed. Also a number of bug fixes on matplotlib and numpy from @2320sharon and @thekester.

:arrow_forward: (2024/04/26) CoastSat v2.5: contributions from @2320sharon and @DanieTheron to improve the download updates and cloud masking for Landsat.

</details> <details> <summary><strong>Additional toolkits and documentation</strong></summary>

:point_right: Other open-source repositories and extensions related to CoastSat:

• CoastSat.slope: estimates the beach-face slope from the satellite-derived shorelines obtained with CoastSat (integrated in CoastSat since v3.0).
• CoastSat.PlanetScope: shoreline extraction for PlanetScope Dove imagery (near-daily since 2017 at 3m resolution).
• SDS_Benchmark: testbed for satellite-derived shorelines mapping algorithms and validation against benchmark datasets.
• CoastSat.islands: 2D planform measurements for small reef islands.
• CoastSat.Maxar: shoreline extraction on Maxar World-View images (in progress)
• InletTracker: monitoring of intermittent open/close estuary entrances.
• VedgeSat: monitoring vegetation lines.
• CoastSeg: an interactive toolbox for downloading satellite imagery, applying image segmentation models, mapping shoreline positions and more.

:point_right: Publications describing the CoastSat satellite-derived shorelines data and methods:

• Shoreline detection algorithm: https://doi.org/10.1016/j.envsoft.2019.104528 (Open Access)
• Accuracy assessment: https://doi.org/10.1016/j.coastaleng.2019.04.004
• Challenges in meso-macrotidal environments: https://doi.org/10.1016/j.geomorph.2021.107707
• Basin-scale shoreline mapping (Paficic): https://www.nature.com/articles/s41561-022-01117-8 (The Conversation article here)
• Beach slope estimation: https://doi.org/10.1029/2020GL088365 (preprint here)
• Beach slope dataset for Australia: https://doi.org/10.5194/essd-14-1345-2022

</details>

Table of Contents

• Installation
• Usage
  • Retrieval of the satellite images in GEE
  • Shoreline detection
  • Shoreline intersections with transects
  • Tidal correction and beach slope estimation
  • Post-processing (seasonal averages and linear trends)
  • Validation against survey data at Narrabeen-Collaroy
• Contributing and Issues
• References and Datasets

1. Installation<a name="introduction"></a>

<details> <summary><strong>1.1 Create an environment with Mamba/Anaconda:</strong></summary>

To run the toolbox you first need to install the required Python packages in an environment.You can do this with Anaconda or with Mamba. It is highly recommended to use Mamba. Go to https://github.com/conda-forge/miniforge and download Miniforge for your operating system.

Once you have it installed on your PC, open the Miniforge Prompt (in Mac and Linux, open a terminal window) and run the following commands to install the coastsat environment:

mamba create -n coastsat
mamba activate coastsat
mamba install python=3.11 geopandas gdal -y
mamba install earthengine-api scikit-image matplotlib astropy notebook -y
pip install pyqt5 imageio-ffmpeg
mamba install pyfes -y
mamba install pyyaml -y

All the required packages have now been installed and are self-contained in an environment called coastsat. Always make sure that the environment is activated with:

mamba activate coastsat

To confirm that you have successfully activated CoastSat, your terminal command line prompt should now start with (coastsat).

:warning: In case errors are raised :warning:: clean things up with the following command before attempting to install coastsat again:

mamba clean --all
mamba update conda

If you are more used to Anaconda you can run the same commands in the Anaconda Prompt by replacing mamba with conda.

If any problems with the installation, raise an issue.

</details> <details> <summary><strong>1.2 Activate Google Earth Engine Python API:</strong></summary>

1. Create a Google Earth Engine project at https://signup.earthengine.google.com/.
2. Go to https://cloud.google.com/sdk/docs/install and install the gcloud CLI. For Windows, download the Google Cloud CLI installer.
3. Once installation is completed, it will automatically let you configure your project and authenticate with your GEE account. If it doesn't, run gcloud init on the terminal.
4. Finally, you need to store your GEE project name. If it is not displayed during configuration, run gcloud config get-value project to print in in the terminal. For example, mine is ee-voskilian. This project name needs to be added in the Python scripts/notebooks to authenticate GEE:

   project_name = 'ee-voskilian'
   SDS_download.authenticate_and_initialize(project_name)
   

:warning: if you're having issues with GEE authentication, open the gloud CLI and run this command: gcloud components update. :warning: if you're finding that you're always asked to authenticate, open the gloud CLI and run this command: gcloud auth application-default login to set a default authentication on your machine.

</details>

:white_check_mark: If you completed those two steps you are ready to start using CoastSat!

2. Usage<a name="usage"></a>

An example of how to run the software in a Jupyter Notebook is provided in example_jupyter.ipynb. You can also run the Jupyter Notebook in VS Code directly.

If you prefer to use a Python script, for example in Spyder or other integrated development environments (IDEs), use example.py. If using Spyder, make sure that the Graphics Backend is set to **Automat