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 ⭐️

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

• 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

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 activate coastsat

mamba clean --all
mamba update conda

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

An example of how to run the software in a Jupyter Notebook is provided in example_jupyter.ipynb.

If you prefer to use Spyder or other integrated development environments (IDEs), a Python script named example.py is also included in the repository. If using Spyder, make sure that the Graphics Backend is set to Automatic and not Inline (as this mode doesn't allow to interact with the figures). To change this setting go under Preferences>IPython console>Graphics.

To retrieve from the GEE server the available satellite images cropped around the user-defined region of coastline for the particular time period of interest, the following variables are required:

• polygon: the coordinates of the region of interest (longitude/latitude pairs in WGS84), do not exceed 100 sqkm or GEE will return memory error (for long beaches split in smaller polygons).
• dates: dates over which the images will be retrieved (e.g., dates = ['2017-12-01', '2018-01-01'])
• sat_list: satellite missions to consider (e.g., sat_list = ['L5', 'L7', 'L8', 'L9', 'S2'] for Landsat 5, 7, 8, 9 and Sentinel-2 collections)
• sitename: name of the site (this is the name of the subfolder where the images and other accompanying files will be stored)
• filepath: filepath to the directory where the data will be stored
• (optional) S2tile: for Sentinel-2, this parameter let's you specify the tile from which you'd like to crop your ROI, this avoids having many duplicates in the Sentinel-2 collection. For example inputs['S2tile'] = '56HLH' is the S2 tile for Sydney, check this website to view all tiles and find the one covering your ROI.
• (optional) LandsatWRS: for Landsat, this parameter let's you specify the tile from which you'd like to crop your ROI, this avoids having many duplicates from overlapping tiles. For example inputs['LandsatWRS'] = '089083' is the Landsat tile for Sydney, check this link to find the tile covering your ROI.

The call metadata = SDS_download.retrieve_images(inputs) will launch the retrieval of the images and store them as .TIF files (under /filepath/sitename). The metadata contains the exact time of acquisition (in UTC time) of each image, its projection and its geometric accuracy. If the images have already been downloaded previously and the user only wants to run the shoreline detection, the metadata can be loaded directly by running metadata = SDS_download.get_metadata(inputs).

The inputs below will download all the images of Narrabeen acquired by since the start of 2024 by Landsat and Sentinel-2.

# region of interest (longitude, latitude)
polygon = [[[151.2957545, -33.7012561],
            [151.297557, -33.7388075],
            [151.312234, -33.7390216],
            [151.311204, -33.701399],
            [151.2957545, -33.7012561]]]
# date range
dates = ['2024-01-01', '2025-01-01']
# satellite missions ['L5','L7','L8','L9','S2']
sat_list = ['L8','L9','S2']
# name of the site
sitename = 'NARRA'
# directory where the data will be stored
filepath = os.path.join(os.getcwd(), 'data')
# put all the inputs into a dictionnary
inputs = {'polygon': polygon, 'dates': dates, 'sat_list': sat_list,
          'sitename': sitename, 'filepath':filepath}
# download images
metadata = SDS_download.retrieve_images(inputs)

Once the images have been downloaded, the shorelines can be mapped. The following user-defined settings are needed:

• cloud_thresh: threshold on maximum cloud cover that is acceptable on the images (value between 0 and 1 - this may require some initial experimentation).
• dist_clouds: buffer around cloud pixels where shoreline is not mapped (in metres)
• output_epsg: epsg code defining the spatial reference system of the shoreline coordinates. It has to be a cartesian coordinate system (i.e. projected) and not a geographical coordinate system (in latitude and longitude angles). See http://spatialreference.org/ to find the EPSG number corresponding to your local coordinate system. If you do not use a local projection your results will not be accurate.
• check_detection: if set to True the user can quality control each shoreline detection interactively (recommended when mapping shorelines for the first time) and accept/reject each shoreline.
• adjust_detection: in case users wants more control over the detected shorelines, they can set this parameter to True, then they will be able to manually adjust the threshold used to map the shoreline on each image.
• save_figure: if set to True a figure of each mapped shoreline is saved under /filepath/sitename/jpg_files/detection, even if the two previous parameters are set to False. Note that this may slow down the process.

There are additional parameters (min_beach_size, min_length_sl, cloud_mask_issue, sand_color, pan_off, s2cloudless_prob) that can be fine-tuned to optimise the detection (for Advanced users). For the moment leave these parameters on their default values, we will see later how they can be edited and what they do.

An example of settings for Narrabeen beach is provided below.

settings = {
    # general parameters:
    'cloud_thresh': 0.5,        # threshold on maximum cloud cover
    'dist_clouds': 300,         # ditance around clouds where shoreline is not mapped
    'output_epsg': 28356,       # epsg code of spatial reference system for the output
    # quality control:
    'check_detection': True,    # if True, shows each shoreline detection to the user for validation
    'adjust_detection': False,  # if True, allows user to adjust the postion of each shoreline by changing the threhold
    'save_figure': True,        # if True, saves a figure showing the mapped shoreline for each image
    # [ONLY FOR ADVANCED USERS] advanced detection parameters:
    'min_beach_area': 1000,     # minimum area (in metres^2) for an object to be labelled as a beach
    'min_length_sl': 500,       # minimum length (in metres) of shoreline perimeter to be valid
    'cloud_mask_issue': False,  # switch this parameter to True if sand pixels are masked as clouds
    'sand_color': 'default',    # 'default', 'latest', 'dark' (for grey/black sand beaches) or 'bright' (for white beaches)
    'pan_off': False,           # True to switch pansharpening off for Landsat 7/8/9 imagery
    's2cloudless_prob': 60,     # probability to mask cloudy pixels in s2cloudless

    'inputs': inputs, # add the inputs defined previously
}

Before mapping the shorelines, it is HIGHLY RECOMMENDED to digitize a reference shoreline in order to improve the detection. This can be done by calling settings['reference_shoreline'] = SDS_preprocess.get_reference_sl_manual(metadata, settings), which allows the user to manually digitize the reference shoreline on a cloud-free image. Then you can set the maximum distance from the reference shoreline where shoreline points can be detection using settings['max_dist_ref']. This reference shoreline helps to reject outliers and false detections when mapping shorelines. See below how to accurately add this reference shoreline.

settings['reference_shoreline'] = SDS_preprocess.get_reference_sl_manual(metadata, settings)
settings['max_dist_ref'] = 100 # max distance (in meters) allowed from the reference shoreline

Additionally, there is the option to visualise the images and create a timelapse (MP4) using the code below:

# preprocess images and save as jpg
SDS_preprocess.save_jpg(metadata, settings, use_matplotlib=True)
# create MP4 timelapse animation
fn_animation = os.path.join(inputs['filepath'],inputs['sitename'], '%s_animation_RGB.mp4'%inputs['sitename'])
fp_images = os.path.join(inputs['filepath'], inputs['sitename'], 'jpg_files', 'preprocessed')
fps = 4 # frames per second in animation
SDS_tools.make_animation_mp4(fp_images, fps, fn_animation)

Once all the settings have been defined, the batch shoreline detection can be launched by calling:

output = SDS_shoreline.extract_shorelines(metadata, settings)

To quality-control the detections manually, set check_detection to True, and a figure like the one below will pop up and let the user manually accept/reject each detection by pressing on the keyboard the right arrow (⇨) to keep the shoreline or left arrow (⇦) to skip the mapped shoreline. The user can break the loop at any time by pressing escape (nothing will be saved though).

For further control on the detections (especially in meso/macrotidal coastal environments), the user can set adjust_detection to True. In that case, the threshold used to define the shoreline can be manually adjusted on each image. See the animation below that shows how the shoreline position can be adjusted in a gentle-sloping macrotidal beach in France (Truc Vert).

Once all the shorelines have been mapped, the output is saved in two different formats (under /filepath/data/SITENAME):

• SITENAME_output.pkl: contains a list with the shoreline coordinates, the exact timestamp at which the image was captured (UTC time), the geometric accuracy and the cloud cover of each individual image. This list can be manipulated with Python, a snippet of code to plot the results is provided in the example script.
• SITENAME_output.geojson: this output can be visualised in a GIS software (e.g., QGIS, ArcGIS).

The GeoJSON shorelines can be opened in a GIS software (QGIS) as shown below.

While the default settings work in most cases, there are instances where you will need to adjust the Advanced Parameters described below.

Finally, the provided classifiers may not be able to detect sand accurately at certain beaches so you have the option to re-train your own classifier in a separate notebook.

This section shows how to process the satellite-derived shoreline to obtain time-series along shore-normal transects.

3 options are provided to define the coordinates of the transects:

1. Interactively draw shore-normal transects along the mapped shorelines:

transects = SDS_transects.draw_transects(output, settings)

2. Load the transect coordinates from a .geojson file:

transects = SDS_tools.transects_from_geojson(path_to_geojson_file)

3. Create the transects by manually providing the coordinates of two points:

transects = dict([])
transects['Transect 1'] = np.array([[342836, ,6269215], [343315, 6269071]])
transects['Transect 2'] = np.array([[342482, 6268466], [342958, 6268310]])
transects['Transect 3'] = np.array([[342185, 6267650], [342685, 6267641]])

⚠️ each transect is defined by two points, its origin and a second point that defines its length and orientation. The origin is always defined first and located landwards, the second point is located seawards.

⚠️ if you choose options 2 or 3, make sure that the points that you are providing are in the spatial reference system defined by settings['output_epsg'], otherwise they won't match the shorelines.

An example of how to draw the transects is shown below.

To calculate the intersections between the shorelines and the transects, there are 2 modes: simple and quality-controlled.

settings['along_dist'] = 25
cross_distance = SDS_transects.compute_intersection(output, transects, settings)

settings_transects = { # parameters for computing intersections
                      'along_dist':          25,        # along-shore distance to use for computing the intersection
                      'min_points':          3,         # minimum number of shoreline points to calculate an intersection
                      'max_std':             15,        # max std for points around transect
                      'max_range':           30,        # max range for points around transect
                      'min_chainage':        -100,      # largest negative value along transect (landwards of transect origin)
                      'multiple_inter':      'auto',    # mode for removing outliers ('auto', 'nan', 'max')
                      'auto_prc':            0.1,       # percentage of the time that multiple intersects are present to use the max
                     }
cross_distance = SDS_transects.compute_intersection_QC(output, transects, settings_transects)

Each satellite image is captured at a different stage of the tide, therefore a tidal correction is necessary to remove the apparent shoreline changes cause by tidal fluctuations.

In order to tidally-correct the time-series of shoreline change, two inputs are needed: 1) tide level time-series and 2) an estimate of the beach slope.

In the notebook, the user has two options for the tide level time-series:

• Option 1: use a CSV file with the time-series of water levels (at least 15/30 min timestep). Note that this file should be formatted as the one provided in /examples NARRA_tides.csv. Dates should be in UTC time and tides in metres above mean sea level.
• Option 2: use the FES2022 global tide model to predict tide levels at your beach. This requires you to have FES2022 setup, follow the instructions in this document. Once installed, you can predict tides for any dates at any location in the world!

Once you have the tide levels, you need an estimate of the beach slope. You can provide this manually (e.g., 0.1 for all transects) or you can also estimate it using the satellite-derived shorelines and tide levels inside the notebook, see the Beach Slope estimation scetion. This parts uses the CoastSat.slope repository, for more details on the methodology see Vos et al. 2020 (preprint available here).

The tidally-corrected time-series can be post-processed to remove outliers with a despiking algorithm SDS_transects.reject_outliers(). This function was developed to remove obvious outliers in the time-series by removing the points that do not make physical sense in a shoreline change setting. For example, the shoreline can experience rapid erosion after a large storm, but it will then take time to recover and return to its previous state. Therefore, if the shoreline erodes/accretes suddenly of a significant amount (max_cross_change) and then immediately returns to its previous state, this spike does not make any physical sense and can be considered an outlier.

settings_outliers = {'max_cross_change':   40,             # maximum cross-shore change observable between consecutive timesteps
                     'otsu_threshold':     [-.5,0],        # min and max intensity threshold use for contouring the shoreline
                     'plot_fig':           True,           # whether to plot the intermediate steps
                    }
cross_distance = SDS_transects.reject_outliers(cross_distance,output,settings_outliers)

Additionally, this function also checks that the Otsu thresholds used to map the shoreline are within the typical range defined by otsu_threshold, with values outside this range (typically -0.5 to 0) identified as outliers.

Additionally, a set of functions to compute seasonal averages, monthly averages and linear trends on the shoreline time-series are provided.

SDS_transects.seasonal_averages()

SDS_transects.monthly_averages()

⚠️ given that the shoreline time-series are not uniformly sampled and there is more density of datapoints towards the end of the record (more satellite in orbit), it is best to estimate the long-term trends on the seasonally-averaged shoreline time-series as the trend estimated on the raw time-series may be biased towards the end of the record.

This section provides code to compare the satellite-derived shorelines against the survey data for Narrabeen, available at http://narrabeen.wrl.unsw.edu.au/.

Having a problem? Post an issue in the Issues page (please do not email).

If you are willing to contribute, check out our todo list in the Projects page.

1. Fork the repository (https://github.com/kvos/coastsat/fork). A fork is a copy on which you can make your changes.
2. Create a new branch on your fork
3. Commit your changes and push them to your branch
4. When the branch is ready to be merged, create a Pull Request (how to make a clean pull request explained here)

This section provides a list of references that use the CoastSat toolbox as well as existing shoreline datasets extracted with CoastSat.

• Vos K., Splinter K.D., Harley M.D., Simmons J.A., Turner I.L. (2019). CoastSat: a Google Earth Engine-enabled Python toolkit to extract shorelines from publicly available satellite imagery. Environmental Modelling and Software. 122, 104528. https://doi.org/10.1016/j.envsoft.2019.104528 (Open Access)

• Vos K., Harley M.D., Splinter K.D., Simmons J.A., Turner I.L. (2019). Sub-annual to multi-decadal shoreline variability from publicly available satellite imagery. Coastal Engineering. 150, 160–174. https://doi.org/10.1016/j.coastaleng.2019.04.004

• Vos K., Harley M.D., Splinter K.D., Walker A., Turner I.L. (2020). Beach slopes from satellite-derived shorelines. Geophysical Research Letters. 47(14). https://doi.org/10.1029/2020GL088365 (Open Access preprint here)

• Vos, K. and Deng, W. and Harley, M. D. and Turner, I. L. and Splinter, K. D. M. (2022). Beach-face slope dataset for Australia. Earth System Science Data. volume 14, 3, p. 1345--1357. https://doi.org/10.5194/essd-14-1345-2022

• Vos, K., Harley, M.D., Turner, I.L. et al. Pacific shoreline erosion and accretion patterns controlled by El Niño/Southern Oscillation. Nature Geosciences. 16, 140–146 (2023). https://doi.org/10.1038/s41561-022-01117-8

• Castelle B., Masselink G., Scott T., Stokes C., Konstantinou A., Marieu V., Bujan S. (2021). Satellite-derived shoreline detection at a high-energy meso-macrotidal beach. Geomorphology. volume 383, 107707. https://doi.org/10.1016/j.geomorph.2021.107707

• Castelle, B., Ritz, A., Marieu, V., Lerma, A. N., & Vandenhove, M. (2022). Primary drivers of multidecadal spatial and temporal patterns of shoreline change derived from optical satellite imagery. Geomorphology, 413, 108360. https://doi.org/10.1016/j.geomorph.2022.10836

• Konstantinou, A., Scott, T., Masselink, G., Stokes, K., Conley, D., & Castelle, B. (2023). Satellite-based shoreline detection along high-energy macrotidal coasts and influence of beach state. Marine Geology, 107082. https://doi.org/10.1016/j.margeo.2023.107082

• Time-series of shoreline change along the Pacific Rim (v1.4) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.7758183

• Time-series of shoreline change along the U.S. Atlantic coast: U.S. Geological Survey data release, https://doi.org/10.5066/P9BQQTCI.

• Time-series of shoreline change for the Klamath River Littoral Cell (California) (1.0) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.7641757

• Beach-face slope dataset for Australia (Version 2) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.7272538

• Training dataset used for pixel-wise classification in CoastSat (initial version): https://doi.org/10.5281/zenodo.3334147