Coastseg stands for Coastal Segmentation, it is an interactive jupyter notebook for downloading satellite imagery with CoastSat and applying Doodleverse/Zoo image segmentation models to satellite imagery. CoastSeg provides an interactive interface for drawing Regions of Interest (ROIs) on a map, downloading satellite imagery, loading geojson files, extracting shorelines from satellite imagery, and much more. In a nutshell, it is ...
- ... an easy way to download time-series of cloud-masked and post-processed satellite imagery anywhere in the world
- ... a mapping extension for CoastSat using Segmentation Zoo models.
- ... an interactive interface to download satellite imagery using CoastSat from Google Earth Engine
- ... an interactive interface for extracting shorelines from satellite imagery
- ... an interactive interface to apply segmentation models to satellite imagery
In more detail, CoastSeg represents the following advances in satellite-derived shoreline workflows:
- An emulation of the CoastSat methodology for defining a shoreline extraction project, image downloading, shoreline extraction, shoreline filtering, and tide correction, all within a single jupyter notebook that can be accessed online
- A pip-installable package for CoastSat workflows
- Use of concurrency for image downloads from Google Earth Engine
- A faster and more convenient API-based methodology for tidal height estimation, using pyTMD
- An initial implementation of an alternative shoreline mapping workflow using Zoo models from the Doodleverse
- A conda environment that can work on secure networks
- Script-based data wrangling utilities
- Hyperparameter experimentation and tracking using an organizational workflow idea called ‘Sessions’
- Supporting databases for transects, reference shorelines, beach slopes, and other useful metadata variables
- A deep-learning based shoreline extraction workflow (still in development)
Version 1 is now stable, and we have a lot of planned new features for version 2.
- Create ROIs(regions of interest) along the coast and automatically load shorelines on the map.
- Use Google Earth Engine to automatically download satellite imagery for each ROI clicked on the map.
- Coastseg can automatically extract shorelines from downloaded satellite imagery.
We recommend that you use Windows 10, Windows 11, or Ubuntu Linux. Mac users, please see here
In order to use Coastseg you need to install Python packages in an environment. We recommend you use Anaconda or Miniconda to install the python packages in an environment for Coastseg.
After you install miniconda/Anaconda on your PC, open the Anaconda prompt or Terminal in Mac and Linux and use the cd
command (change directory) to go the folder where you have downloaded the Coastseg repository.
We highly recommend you install CoastSeg using conda
following the instructions in Install from conda-forge.
- Create an miniconda/Anaconda environment and Activate it
- This command creates an anaconda environment named
coastseg
and installspython 3.10
in it.conda create --name coastseg python=3.10 -y conda activate coastseg
-
Install coastseg
conda install -c conda-forge coastseg
-
(Optional) Install Optional Dependencies
- Only install these dependencies if you plan to use CoastSeg's Zoo workflow notebook.
pip install tensorflow pip install transformers
- Create an miniconda/Anaconda environment
- This command creates an anaconda environment named
coastseg
and installspython 3.10
in it.conda create --name coastseg python=3.10 -y
-
Activate your conda environment
conda activate coastseg
- If you have successfully activated coastseg you should see that your terminal's command line prompt should now start with
(coastseg)
.
- Install Conda Dependencies
- CoastSeg requires
jupyterlab
andgeopandas
to function properly so they will be installed in thecoastseg
environment. - Geopandas has GDAL as a dependency so its best to install it with conda.
- Make sure to install geopandas from the
conda-forge
channel to ensure you get the latest version. - Make sure to install both jupyterlab and geopandas from the conda forge channel to avoid dependency conflicts
conda install -c conda-forge geopandas -y
- CoastSeg requires
- Install the CoastSeg from PyPi
pip install coastseg
- Uninstall the h5py installed by pip and reinstall with conda-forge
pip install jsonschema==4.19.0
is a temporary command you have to run until issue stac-utils/pystac#1214 is resolved
pip install jsonschema==4.19.0 --user pip uninstall h5py -y conda install -c conda-forge h5py -y
Use the command conda clean --all
to clean old packages from your anaconda base environment. Ensure you are not in your coastseg environment or any other environment by running conda deactivate
, to deactivate any environment you're in before running conda clean --all
. It is recommended that you have Anaconda prompt (terminal for Mac and Linux) open as an administrator before you attempt to install coastseg
again.
conda deactivate
conda clean --all
1.Sign up to use Google Earth Engine Python API
-
Request access to Google Earth Engine at https://signup.earthengine.google.com/
-
It takes about 1 day for Google to approve requests.
1.Activate the coastseg conda environment
conda activate coastseg
- If you have successfully activated coastseg you should see that your terminal's command line prompt should now start with
(coastseg)
.
2.Download CoastSeg from GitHub
git clone coastseg --depth 1 https://github.com/Doodleverse/CoastSeg.git
1.Launch Jupyter Lab
- Run this command in the coastseg directory to launch the notebook
SDS_coastsat_classifier
conda activate coastseg
jupyter lab SDS_coastsat_classifier.ipynb
2.Authenticate with Google Earth Engine
- Run the cell located under 'Authenticate with Google Earth Engine (GEE)'
3.Draw an Bounding Box
- Draw a bounding box along the coast in this box is where ROIs will be created
Option 1: Draw a Bounding Box with the box tool
Option 2: Draw a Bounding Box with the polygon tool
- This is useful if you have back - barrier shorelines that you don't want to include
4.Generate ROI (Region of Interest)
-
ROIs can only be generated along a shoreline
-
If no shoreline is found then an error message will appear telling you no ROIs can be created. If this happens create your own reference shoreline following the guide here How to Create Reference Shoreline
5.Load Transects
-
Make sure there are transects inside the ROI you have selected otherwise you won't be able to extract shorelines
-
If there isn't a reference shoreline or any transects available for your site check out the guide on how to upload your own here
6.Modify the Settings
-
Change the satellites to L8 and L9
-
Change the dates to 12/01/2023 - 03/01/2024
-
Change the size of the reference shoreline buffer
-
Click
Save Settings
7.Name the Session
-
Let's call this 'demo_session'
-
This is the name of the folder that will be saved in
CoastSeg/sessions
-
It will contain a subdirectory for each ROI that shorelines will be extracted for
8.Preview the available Imagery
- Preview the amount of available imagery for the selected ROI between the dates
9.Download the ROIs
-
Click the ROIs you want to download on the map ( they will turn blue when selected)
-
If no transects or reference shorelines are available for the region you have uploaded follow the guide here
-
NEVER rename your ROIs this is because CoastSeg keeps track of the filename in the 'config.json' and you won't be able to load it into CoastSeg again if you do. The ROI's ID is the filename so that information will be lost if you rename it.
-
Extracting shorelines works by finding the land water interface in the image and drawing a line along it
-
A time series of shoreline position along each transect is generated as well
1.Download the tide model
-
Before tidal correction can be applied the tide model must be downloaded
-
Follow the tutorial: How to Download Tide Model
2.Load the Session with Extracted Shorelines
-
Re-open the jupyter notebook
-
Under the 'Kernel' menu Click 'restart and clear outputs of all cells'
- Click 'Load Session' and load 'sample_session'
3.Click Correct Tides
-
Click the ROI ID from the dropdown
-- You should see some extracted shorelines on the map if you don't then the ROI ID won't appear in the dropdown
-
Enter Beach Slope
-
Enter Beach Elevation relative to Mean Sea Level
This guide is designed to help you easily update CoastSeg, whether you're updating to a specific version, the latest version, applying a patch, or updating code and notebooks from GitHub.
- Install CoastSeg from PyPi
- To ensure you have the latest features and fixes, use this command:
pip install coastseg --upgrade
- Don't worry if you see the warning message below. This is normal
"ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts."
- Install jsonschema
- This is necessary to run coastseg in a jupyter notebook.
pip install jsonschema==4.19.0 --user
- Install CoastSeg from PyPi
- If you need a specific version of CoastSeg, use this command:
- Replace with the desired version number (e.g., 1.1.26).
pip install coastseg==<version>
- Don't worry if you see the warning message below. This is normal
"ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts."
- Install jsonschema
- This is necessary to run coastseg in a jupyter notebook.
pip install jsonschema==4.19.0 --user
(Optional) Follow these steps if you want the latest notebooks or code updates from the CoastSeg GitHub repository.
Click to expand instructions
- Open Anaconda Prompt
- Activate the coastseg environment
conda activate coastseg
- Go to your coastseg location
cd <coastseg location>
-Run the command below. In the output of this command you should see origin https://github.com/Doodleverse/CoastSeg.git (fetch)
git remote -v
- If you don't see this output, then run the following command
git remote add origin https://github.com/Doodleverse/CoastSeg.git git pull origin main
-
Run the command below
git pull origin main
-
If you recieve an error message like the one shown below then proceed to 3, otherwise go to Go to Step 4: Verify Update Success
Please commit your changes or stash them before you merge Aborting
-
Run the command below:
- WARNING This will clear out anything you have written to the
certifications.json
make sure to save that file to a new location then move it back when you're done upgrading
git fetch origin
git reset --hard origin/main
git pull origin main
git status
- This command should return the following message
-
On branch main Your branch is up to date with 'origin/main'.
Package maintainers:
- @dbuscombe-usgs Contracted to USGS Pacific Coastal and Marine Science Center.
- @2320sharon : Lead Software Developer / Contracted to USGS Pacific Coastal and Marine Science Center.
Contributions:
- @ebgoldstein
- @venuswku
- @robbibt
- @edlazarus
- Beta testers: Catherine Janda, Ann Gibbs, Jon Warrick, Andrea O’Neill, Kathryn Weber, Julia Heslin (USGS)
- We would like to express our gratitude to all the contributors who made this release possible. Thank you to everyone who tested the beta versions of coastseg and provided us with the feedback we needed to improve coastseg. Thanks also to the developers and maintainers of pyTMD, DEA-tools, xarray, and GDAL, without which this project would be impossible
Thank you to all the amazing research who contributed their transects to coastseg.
- Hawaii small islands https://pubs.usgs.gov/of/2011/1009/data.html
- Barter Island, Alaska https://www.sciencebase.gov/catalog/item/5fa1f10ad34e198cb793cee4
- Pacific Northwest, Gulf, and SE USA: Dr Sean Vitousek, USGS-PCMSC, based on DSAS transects
- Atlantic barrier islands: https://www.sciencebase.gov/catalog/item/5d5ece47e4b01d82ce961e36
- Mexico, New Zealand, Japan, Chile, Peru all from: https://zenodo.org/record/7758183#.ZCXZMcrMJPY
- Snyder, A.G., and Gibbs, A.E., 2019, National assessment of shoreline change: A GIS compilation of updated vector shorelines and associated shoreline change data for the north coast of Alaska, Icy Cape to Cape Prince of Wales: U.S. Geological Survey data release, https://doi.org/10.5066/P9H1S1PV.
- Gibbs, A.E., Ohman, K.A., Coppersmith, R., and Richmond, B.M., 2017, National Assessment of Shoreline Change: A GIS compilation of updated vector shorelines and associated shoreline change data for the north coast of Alaska, U.S. Canadian border to Icy Cape: U.S. Geological Survey data release, https://doi.org/10.5066/F72Z13N1.
- Himmelstoss, E.A., Kratzmann, M., Hapke, C., Thieler, E.R., and List, J., 2010, The National Assessment of Shoreline Change: A GIS Compilation of Vector Shorelines and Associated Shoreline Change Data for the New England and Mid-Atlantic Coasts: U.S. Geological Survey Open-File Report 2010-1119, available at https://pubs.usgs.gov/of/2010/1119/.
- Kilian Vos. (2023). Time-series of shoreline change along the Pacific Rim (v1.4) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.7758183
- Vos, Kilian, Wen, Deng, Harley, Mitchell D., Turner, Ian L., & Splinter, Kristen D. (2022). Beach-face slope dataset for Australia (Version 2) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.7272538
- Gibbs, A.E., Jones, B.M., and Richmond, B.M., 2020, A GIS compilation of vector shorelines and coastal bluff edge positions, and associated rate-of-change data for Barter Island, Alaska: U.S. Geological Survey data release, https://doi.org/10.5066/P9CRBC5I.
To compile into a pdf use
pandoc paper.md -o paper.pdf --bibliography paper.bib