geetools_VH/shoreline_extraction.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Shoreline extraction from satellite images"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook shows how to download satellite images (Landsat 5,7,8 and Sentinel-2) from Google Earth Engine and apply the shoreline detection algorithm 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*.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initial settings"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Python packages required to run this notebook can be installed by running the following anaconda command:\n",
    "*\"conda env create -f environment.yml\"*. This will create a new enviroment with all the relevant packages installed. You will also need to sign up for Google Earth Engine (https://earthengine.google.com and go to signup) and authenticate on the computer so that python can access via your login."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import pickle\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "import warnings\n",
    "warnings.filterwarnings(\"ignore\")\n",
    "# load modules from directory\n",
    "import SDS_download, SDS_preprocess, SDS_tools, SDS_shoreline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Download images"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Define the region of interest, the dates and the satellite missions from which you want to download images. The image will be cropped on the Google Earth Engine server and only the region of interest will be downloaded resulting in low memory allocation (~ 1 megabyte/image for 5 km of beach)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# define the area of interest (longitude, latitude)\n",
    "polygon = [[[151.301454, -33.700754],\n",
    "            [151.311453, -33.702075], \n",
    "            [151.307237, -33.739761],\n",
    "            [151.294220, -33.736329],\n",
    "            [151.301454, -33.700754]]]\n",
    "             \n",
    "# define dates of interest\n",
    "dates = ['2017-12-01','2018-01-01']\n",
    "\n",
    "# define satellite missions ('L5' --> landsat 5 , 'S2' --> Sentinel-2)\n",
    "sat_list = ['L5', 'L7', 'L8', 'S2']\n",
    "\n",
    "# give a name to the site\n",
    "sitename = 'NARRA'\n",
    "\n",
    "# download satellite images. The cropped images are saved in a '/data' subfolder. The image information is stored\n",
    "# into 'metadata.pkl'.\n",
    "# SDS_download.get_images(sitename, polygon, dates, sat_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Shoreline extraction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Performs a sub-pixel resolution shoreline detection method integrating a supervised classification component that allows to map the boundary between water and sand."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# parameters and settings\n",
    "%matplotlib qt\n",
    "settings = {    \n",
    "    'sitename': sitename,\n",
    "       \n",
    "    # general parameters:\n",
    "    'cloud_thresh': 0.5,        # threshold on maximum cloud cover\n",
    "    'output_epsg': 28356,       # epsg code of the desired output spatial reference system\n",
    "       \n",
    "    # shoreline detection parameters:\n",
    "    'min_beach_size': 20,       # minimum number of connected pixels for a beach\n",
    "    'buffer_size': 7,           # radius (in pixels) of disk for buffer around sandy pixels\n",
    "    'min_length_sl': 200,       # minimum length of shoreline perimeter to be kept \n",
    "    'max_dist_ref': 100 ,       # max distance (in meters) allowed from a reference shoreline\n",
    "       \n",
    "    # quality control:\n",
    "    'check_detection': True     # if True, shows each shoreline detection and lets the user \n",
    "                                # decide which shorleines are correct and which ones are false due to\n",
    "                                # the presence of clouds and other artefacts. \n",
    "                                # If set to False, shorelines are extracted from all images.\n",
    "       }\n",
    "\n",
    "# load metadata structure (contains information on the downloaded satellite images and is created\n",
    "# after all images have been successfully downloaded)\n",
    "filepath = os.path.join(os.getcwd(), 'data', settings['sitename'])\n",
    "with open(os.path.join(filepath, settings['sitename'] + '_metadata' + '.pkl'), 'rb') as f:\n",
    "    metadata = pickle.load(f)\n",
    "    \n",
    "# [OPTIONAL] saves .jpg files of the preprocessed images (cloud mask and pansharpening/down-sampling) \n",
    "#SDS_preprocess.preprocess_all_images(metadata, settings)\n",
    "\n",
    "# [OPTIONAL] to avoid false detections and identify obvious outliers there is the option to\n",
    "# create a reference shoreline position (manually clicking on a satellite image)\n",
    "settings['refsl'] = SDS_preprocess.get_reference_sl(metadata, settings)\n",
    "\n",
    "# extract shorelines from all images. Saves out.pkl which contains the shoreline coordinates for each date in the spatial\n",
    "# reference system specified in settings['output_epsg']. Save the output in a file called 'out.pkl'.\n",
    "out = SDS_shoreline.extract_shorelines(metadata, settings)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plot the shorelines"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.figure()\n",
    "plt.axis('equal')\n",
    "plt.xlabel('Eastings [m]')\n",
    "plt.ylabel('Northings [m]')\n",
    "plt.title('Shorelines')\n",
    "for satname in out.keys():\n",
    "    if satname == 'meta':\n",
    "        continue\n",
    "    for i in range(len(out[satname]['shoreline'])):\n",
    "        sl = out[satname]['shoreline'][i]\n",
    "        date = out[satname]['timestamp'][i]\n",
    "        plt.plot(sl[:,0], sl[:,1], '-', label=date.strftime('%d-%m-%Y'))\n",
    "plt.legend()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}