datasets/esa-worldcover/esa-worldcover-example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "a4722cc1-68f8-4a8d-9454-c6c8a885a8b4",
   "metadata": {},
   "source": [
    "## Accessing ESA WorldCover 2020 classification data with the Planetary Computer STAC API\n",
    "\n",
    "The European Space Agency (ESA) [WorldCover](https://esa-worldcover.org/en) product is a global land cover map for the year 2020 produced at 10 meter resolution based on the combination of [Sentinel-1](https://sentinel.esa.int/web/sentinel/missions/sentinel-1) radar data and [Sentinel-2](https://sentinel.esa.int/web/sentinel/missions/sentinel-2) imagery. The discrete classification map provides 11 classes and is defined using the Land Cover Classification System (LCCS) developed by the United Nations (UN) Food and Agriculture Organization (FAO).\n",
    "\n",
    "This notebook demonstrates the use of the Planetary Computer STAC API to query for a portion of ESA WorldCover data that includes Mount Elgon near the border of Uganda and Kenya.\n",
    "\n",
    "### Environment setup\n",
    "\n",
    "This notebook works with or without an API key, but you will be given more permissive access to the data with an API key.\n",
    "- The [Planetary Computer Hub](https://planetarycomputer.microsoft.com/compute) is pre-configured to use your API key.\n",
    "- To use your API key locally, set the environment variable `PC_SDK_SUBSCRIPTION_KEY` or use `pc.settings.set_subscription_key(<YOUR API Key>)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "f50f9f62",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pystac_client\n",
    "import planetary_computer\n",
    "import rasterio\n",
    "from rasterio import windows\n",
    "import matplotlib.pyplot as plt\n",
    "from matplotlib.colors import ListedColormap\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "198b54e7",
   "metadata": {},
   "source": [
    "### Define the area of interest and search the collection\n",
    "\n",
    "Let's define a bounding box around Mount Elgon, which sits on the border of Uganda and Kenya."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "d1a949e6",
   "metadata": {},
   "outputs": [],
   "source": [
    "bbox_of_interest = [33.984, 0.788, 34.902, 1.533]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fa58f1c9",
   "metadata": {},
   "source": [
    "Use [pystac-client](https://github.com/stac-utils/pystac-client) to perform the search over the ESA WorldCover collection."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "a56a65b0",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Returned 1 Items\n"
     ]
    }
   ],
   "source": [
    "catalog = pystac_client.Client.open(\n",
    "    \"https://planetarycomputer.microsoft.com/api/stac/v1\",\n",
    "    modifier=planetary_computer.sign_inplace,\n",
    ")\n",
    "\n",
    "search = catalog.search(\n",
    "    collections=[\"esa-worldcover\"],\n",
    "    bbox=bbox_of_interest,\n",
    ")\n",
    "\n",
    "items = list(search.get_items())\n",
    "print(f\"Returned {len(items)} Items\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a5754154",
   "metadata": {},
   "source": [
    "Our search returned one item, a 3x3 degree tile of classification data. Each Item contains a single \"map\" Asset with a URL to the location of the Asset data on [Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "6b8cf457",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "https://ai4edataeuwest.blob.core.windows.net/esa-worldcover/v100/2020/map/ESA_WorldCover_10m_2020_v100_N00E033_Map.tif\n"
     ]
    }
   ],
   "source": [
    "asset_href = items[0].assets[\"map\"].href\n",
    "print(asset_href.split(\"?\")[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a3673c18",
   "metadata": {},
   "source": [
    "### Render our area of interest\n",
    "\n",
    "Here we use [rasterio](https://rasterio.readthedocs.io/en/latest/) to download the data and matplotlib to display an image of our area of interest."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "4462ea97",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<img src=\"https://ai4edatasetspublicassets.blob.core.windows.net/assets/notebook-output/datasets-esa-worldcover-esa-worldcover-example.ipynb/6.png\"/>"
      ],
      "text/plain": [
       "<Figure size 864x864 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "with rasterio.open(asset_href) as src:\n",
    "    aoi_window = windows.from_bounds(transform=src.transform, *bbox_of_interest)\n",
    "    raster_data = src.read(1, window=aoi_window)\n",
    "\n",
    "fig, ax = plt.subplots(figsize=(12, 12))\n",
    "\n",
    "ax.set_axis_off()\n",
    "ax.imshow(raster_data);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32b63558",
   "metadata": {},
   "source": [
    "This looks interesting, but let's use the classification colors as defined in the [product user manual](https://esa-worldcover.s3.amazonaws.com/v100/2020/docs/WorldCover_PUM_V1.0.pdf). The classification colors are also defined in a colormap contained in the source GeoTIFF image. We'll extract the colormap from the GeoTIFF image and apply it to the plot. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "79bf1ee0",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<img src=\"https://ai4edatasetspublicassets.blob.core.windows.net/assets/notebook-output/datasets-esa-worldcover-esa-worldcover-example.ipynb/7.png\"/>"
      ],
      "text/plain": [
       "<Figure size 864x864 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "with rasterio.open(asset_href) as src:\n",
    "    colormap_def = src.colormap(1)\n",
    "    colormap = [np.array(colormap_def[i]) / 255 for i in range(len(colormap_def))]\n",
    "\n",
    "cmap = ListedColormap(colormap)\n",
    "fig, ax = plt.subplots(figsize=(12, 12))\n",
    "\n",
    "ax.set_axis_off()\n",
    "ax.imshow(\n",
    "    raster_data,\n",
    "    cmap=cmap,\n",
    "    vmin=0,\n",
    "    vmax=(len(colormap_def) - 1),\n",
    "    interpolation=\"nearest\",\n",
    ");"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "63991eb1",
   "metadata": {},
   "source": [
    "Rendering notes:\n",
    "1. The `vmin` and `vmax` values are set to match the number of classes defined in the colormap in the source GeoTIFF image. Even though there are only 11 classes defined in the ESA WorldCover [Product User Manual](https://esa-worldcover.s3.amazonaws.com/v100/2020/docs/WorldCover_PUM_V1.0.pdf), the GeoTIFF colormap is padded to produce 256 class values and corresponding colors. The color black is used for all padded values.\n",
    "2. The `interpolation` value is set to `nearest` to avoid black artifacts that result from interpolated pixel values (the image is interpolated for display). When an interpolated value falls within a padded area of the colormap, it is displayed as black. We use the `nearest` interpolation method since it does not produce new pixel values that will fall within the padded areas of the colormap."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.8.13"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}