Package: coastseg
CoastSegNewsWe are thrilled to announce the official release of CoastSeg version 1.0.0! Please see therelease notes. If you are an existing CoastSeg user, to upgrade to this latest version of CoastSeg:git pull origin mainthen:pip install coastseg==1.0.0What is CoastSeg?Coastseg stands for Coastal Segmentation, it is an interactive jupyter notebook for downloading satellite imagery withCoastSatand applying Doodleverse/Zooimage 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 forCoastSatusingSegmentation Zoomodels.... 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 imageryIn 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 onlineA pip-installable package for CoastSat workflowsUse of concurrency for image downloads from Google Earth EngineA faster and more convenient API-based methodology for tidal height estimation, using pyTMDAn initial implementation of an alternative shoreline mapping workflow using Zoo models from the DoodleverseA conda environment that can work on secure networksScript-based data wrangling utilitiesHyperparameter experimentation and tracking using an organizational workflow idea called ‘Sessions’Supporting databases for transects, reference shorelines, beach slopes, and other useful metadata variablesA 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.Table of ContentsInstallation InstructionsGetting StartedUseful LinksWikiDiscussionContribution GuideInstallation InstructionsWe recommend that you use Windows 10, Windows 11, or Ubuntu Linux. Mac users, please seehereIn order to use Coastseg you need to install Python packages in an environment. We recommend you useAnacondaorMinicondato 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 thecdcommand (change directory) to go the folder where you have downloaded the Coastseg repository.Install from conda-forgeCreate an miniconda/Anaconda environment and Activate itThis command creates an anaconda environment namedcoastsegand installspython 3.10in it.condacreate--namecoastsegpython=3.10-y
condaactivatecoastsegInstall coastsegcondainstall-cconda-forgecoastseg==1.1.41(Optional) Install Optional DependenciesOnly install these dependencies if you plan to use CoastSeg's zoo workflow notebook.pipinstalltensorflow
pipinstalltransformersInstall from PypiCreate an miniconda/Anaconda environmentThis command creates an anaconda environment namedcoastsegand installspython 3.10in it.condacreate--namecoastsegpython=3.10-yActivate your conda environmentcondaactivatecoastsegIf you have successfully activated coastseg you should see that your terminal's command line prompt should now start with(coastseg).Install Conda DependenciesCoastSeg requiresjupyterlabandgeopandasto function properly so they will be installed in thecoastsegenvironment.GeopandashasGDALas a dependency so its best to install it with conda.Make sure to install geopandas from theconda-forgechannel to ensure you get the latest version.Make sure to install both jupyterlab and geopandas from the conda forge channel to avoid dependency conflictscondainstall-cconda-forgegeopandasjupyterlab-yInstall the CoastSeg from PyPipipinstallcoastsegUninstall the h5py installed by pip and reinstall with conda-forgepip install jsonschema==4.19.0is a temporary command you have to run until issuehttps://github.com/stac-utils/pystac/issues/1214is resolvedpipinstalljsonschema==4.19.0--userpipuninstallh5py-y
condainstall-cconda-forgeh5py-yCoastSeg Update GuideThis 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.Step 1: Install CoastSeg from PyPiOption 1:  Update to the latest versionInstall CoastSeg from PyPiTo ensure you have the latest features and fixes, use this command:pipinstallcoastseg--upgradeDon'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 jsonschemaThis is necessary to run coastseg in a jupyter notebook.pipinstalljsonschema==4.19.0--userOption 2:  Update to a Specific VersionInstall CoastSeg from PyPiIf you need a specific version of CoastSeg, use this command:Replace  with the desired version number (e.g., 1.1.26).pipinstallcoastseg==<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 jsonschemaThis is necessary to run coastseg in a jupyter notebook.pipinstalljsonschema==4.19.0--userStep 2: Update Code and Notebooks from GitHub(Optional) Follow these steps if you want the latest notebooks or code updates from the CoastSeg GitHub repository.Click to expand instructionsStep 1: Open CoastSeg in AnacondaOpen Anaconda PromptActivate the coastseg environmentcondaactivatecoastsegGo to your coastseg locationcd<coastseglocation>Step 2: Check for a Remote Connection to CoastSeg Repository-Run the command below. In the output of this command you should seeorigin  https://github.com/Doodleverse/CoastSeg.git (fetch)git remote -vIf you don't see this output, then run the following commandgitremoteaddoriginhttps://github.com/Doodleverse/CoastSeg.gitgitpulloriginmainStep 3: Pull the Latest ChangesRun the command belowgit pull origin mainIf you recieve an error message like the one shown below then proceed to 3, otherwise go toGo to Step 4: Verify Update SuccessPlease commit your changes or stash them before you merge
    AbortingRun the command below:WARNINGThis will clear out anything you have written to thecertifications.jsonmake sure to save that file to a new location then move it back when you're done upgradinggit fetch origin
       git reset --hard origin/main
       git pull origin mainStep 4: Verify Update Successgit statusThis command should return the following messageOn branch main
Your branch is up to date with 'origin/main'.Having Installation Errors?Use the commandconda clean --allto clean old packages from your anaconda base environment. Ensure you are not in your coastseg environment or any other environment by runningconda deactivate, to deactivate any environment you're in before runningconda clean --all. It is recommended that you have Anaconda prompt (terminal for Mac and Linux) open as an administrator before you attempt to installcoastsegagain.Conda Clean Stepscondadeactivate
condaclean--allGetting StartedSign up to use Google Earth Engine Python APIFirst, you need to request access to Google Earth Engine athttps://signup.earthengine.google.com/. It takes about 1 day for Google to approve requests.Activate your conda environmentcondaactivatecoastsegIf you have successfully activated coastseg you should see that your terminal's command line prompt should now start with(coastseg).Download CoastSeg from GitHubOnce you’ve created the coastseg environment you’ll need to rungit clonethe coastseg code onto your computer. Follow the guideHow to Clone CoastSegin the wiki for how to perform a git clone to download the coastseg code onto your computer.Launch Jupyter LabRun this command in the coastseg directory to launch the notebookSDS_coastsat_classifierjupyterlabSDS_coastsat_classifier.ipynbUse theSDS_coastsat_classifierto Download ImageryCheck out the wiki guideHow to Download Imageryfor comprehensive guides for how to use coastseg to download imagery and apply image segmentation models to the imagery you download.Use theadd_new_transects_notebookto Download ImageryAuthorsPackage maintainers:@dbuscombe-usgsContracted 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@edlazarusBeta 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 impossibleCitationsThank you to all the amazing research who contributed their transects to coastseg.Hawaii small islandshttps://pubs.usgs.gov/of/2011/1009/data.htmlBarter Island, Alaskahttps://www.sciencebase.gov/catalog/item/5fa1f10ad34e198cb793cee4Pacific Northwest, Gulf, and SE USA: Dr Sean Vitousek, USGS-PCMSC, based on DSAS transectsAtlantic barrier islands:https://www.sciencebase.gov/catalog/item/5d5ece47e4b01d82ce961e36Mexico, New Zealand, Japan, Chile, Peru all from:https://zenodo.org/record/7758183#.ZCXZMcrMJPYSnyder, 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 athttps://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.7758183Vos, 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.7272538Gibbs, 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.