"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "010b5b89-32c4-4f6b-81fb-f41d782d251f",
+ "metadata": {},
+ "source": [
+ "In this tutorial, we will walk through the process of requesting on-demand traning data from the [Planetary Computer Data Catalog](https://planetarycomputer.microsoft.com/catalog) to pair with the [BigEarthNet](https://mlhub.earth/data/bigearthnet_v1) dataset downloaded from Radiant MLHub. This is an important workflow for someone in the geospatial community who wants to train an ML model on a datasource outside of a prepackaged dataset, such as those found on MLHub. They can start with any dataset containing source image and label collections in STAC, obtain a random sample to work with, fetch source images from a different collection or satellite product, and then reproject and crop those images to match the spatial and temporal extent of the original dataset.\n",
+ "\n",
+ "**NOTE:** because the workflow documented below uses libraries like `pystac_client` and `stackstac`, the datasets queried need to be organized into STAC Collections."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "f130b365-6fff-4d2a-86a9-39085ab13886",
+ "metadata": {},
+ "source": [
+ "Let's start by importing the Python libraries we'll use in this notebook."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "9fe7b447-cf8a-4cc7-aaed-4e8407d0f270",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "!pip install --upgrade wget # not installed on PC by default"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "7e144460-5549-4ab4-ba98-10a1a7ebd236",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "/Users/kendallsmith/opt/anaconda3/envs/mlhub/lib/python3.9/site-packages/geopandas/_compat.py:111: UserWarning: The Shapely GEOS version (3.10.0-CAPI-1.16.0) is incompatible with the GEOS version PyGEOS was compiled with (3.10.1-CAPI-1.16.0). Conversions between both will be slow.\n",
+ " warnings.warn(\n"
+ ]
+ }
+ ],
+ "source": [
+ "import getpass\n",
+ "import tempfile\n",
+ "from pathlib import Path\n",
+ "import os\n",
+ "import json\n",
+ "from glob import glob\n",
+ "import requests\n",
+ "from typing import List, Tuple\n",
+ "from datetime import datetime as dt\n",
+ "from datetime import timedelta as td\n",
+ "\n",
+ "from radiant_mlhub import Collection\n",
+ "import planetary_computer\n",
+ "import pystac_client\n",
+ "from pystac import ItemCollection, Item, Asset\n",
+ "from dask import delayed, compute, distributed\n",
+ "\n",
+ "import numpy as np\n",
+ "from stackstac import stack\n",
+ "from geopandas import GeoDataFrame\n",
+ "import rasterio as rio\n",
+ "import rioxarray\n",
+ "from xarray import DataArray\n",
+ "from shapely.geometry import shape\n",
+ "from shapely.geometry import Polygon\n",
+ "from pyproj import CRS"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3a5bb87b-9d9c-4140-bac8-3e95f146c029",
+ "metadata": {},
+ "source": [
+ "### Define global variables"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "2de2f657-3229-4037-bf9c-541c503cc269",
+ "metadata": {},
+ "source": [
+ "In addition to the API key, we will also need to define some other initial global variables to get our workflow started. e.g. a temporary working directory to download and write data to, the STAC API endpoints, names of Collections, and other variables like the RGB bands for those collections. These are pretty flexible depending on your individual needs."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 60,
+ "id": "f3bf07a1-3a4a-4207-a449-7be766fa7e36",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Temporary working directory on local machine or PC instance\n",
+ "TMP_DIR = tempfile.gettempdir()\n",
+ "\n",
+ "# API endpoints for MLHub and Planetary Computer catalogs\n",
+ "MLHUB_API_URL = \"https://api.radiant.earth/mlhub/v1\"\n",
+ "MSPC_API_URL = \"https://planetarycomputer.microsoft.com/api/stac/v1\"\n",
+ "\n",
+ "# Names of Collections that will be queried against using pystac_client\n",
+ "BIGEARTHNET_SOURCE_COLLECTION = \"bigearthnet_v1_source\" # sentinel-2 source imagery\n",
+ "BIGEARTHNET_LABEL_COLLECTION = \"bigearthnet_v1_labels\" # geojson classification labels\n",
+ "PLANETARY_COMPUTER_LANDSAT_8 = \"landsat-8-c2-l2\" # landsat 8 source imagery on PC\n",
+ "OUTPUT_DIR = \"landsat_8_source\"\n",
+ "\n",
+ "# Default variables that will be used in the API queries\n",
+ "BIGEARTHNET_TIME_RANGE = \"2017-06-01/2018-05-31\" # full date range for BigEarthNet\n",
+ "LABEL_CRS = CRS(\"EPSG:4326\")\n",
+ "DATE_BUFFER = 60\n",
+ "LANDSAT_8_RGB_BANDS = [\"SR_B4\", \"SR_B3\", \"SR_B2\"] # names of RGB bands from BigEarthNet\n",
+ "BIGEARTHNET_RGB_BANDS = [\"B04\", \"B03\", \"B02\"] # names of RGB bands from PC Landsat 8\n",
+ "\n",
+ "# Bounding box for demonstration fetching Items over Luxembourg\n",
+ "LUXEMBOURG_AOI = [6.06, 49.58, 6.21, 49.66] # aoi around Luxembourg"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "5d5e31b3-5cde-4a7b-af43-dc194b06d0a0",
+ "metadata": {},
+ "source": [
+ "### Authentication with Radiant MLHub"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "5f11e821-b98b-4df1-a26c-826c9bdbec50",
+ "metadata": {},
+ "source": [
+ "Programmatic access to the Radiant MLHub API using the `pystac_client` library requires both the API end-point and an API key. You can obtain an API key for free by registering an account on [mlhub.earth](https://mlhub.earth/). This can be found under `Settings & API Key` from the drop-down once logged in."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "id": "f4c9dd60-3abc-464d-af25-4b23c0d2783b",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdin",
+ "output_type": "stream",
+ "text": [
+ "MLHub API Key: ································································\n"
+ ]
+ }
+ ],
+ "source": [
+ "MLHUB_API_KEY = getpass.getpass(prompt=\"MLHub API Key: \")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "ccad2439-109f-4eef-ac3b-dac65f54e3aa",
+ "metadata": {},
+ "source": [
+ "Once you have your API key, you need to update the default profile file in your home directory. You can use the `mlhub configure` command line tool to do this:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "id": "cfd2681d-56ed-440c-a352-b4ecfd125c03",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Overwrite existing API Key (****b0eced) [y/N]: ^C\n",
+ "Aborted!\n"
+ ]
+ }
+ ],
+ "source": [
+ "!mlhub configure --api-key={MLHUB_API_KEY}"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "5c77d029-191e-42a5-8250-bc451b80f247",
+ "metadata": {},
+ "source": [
+ "### Configure API connection to Radiant MLHub"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "b0480635-eef5-4e3f-847a-5060c409ae4f",
+ "metadata": {},
+ "source": [
+ "This makes a connection to the Radiant MLHub Data Catalog using the API endpoint URL, and the API key from your account."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "id": "bf79c301-76df-4158-bf97-3da53552e143",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "mlhub_catalog = pystac_client.Client.open(\n",
+ " url=MLHUB_API_URL, parameters={\"key\": MLHUB_API_KEY}, ignore_conformance=True\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "637734bc-af77-4c81-ab26-98e808de6415",
+ "metadata": {},
+ "source": [
+ "### Fetch label items from BigEarthNet over Luxembourg"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "e9f19ce4-57fd-43d0-9263-7a5edd106ee8",
+ "metadata": {},
+ "source": [
+ "We will now use the `search` function from the API client to get label Items over Luxembourg as a sample use-case."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "id": "fc61a3d4-cfc0-4da5-9717-bf3c8e427100",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "origin_label_items = mlhub_catalog.search(\n",
+ " collections=BIGEARTHNET_LABEL_COLLECTION,\n",
+ " bbox=LUXEMBOURG_AOI,\n",
+ " datetime=BIGEARTHNET_TIME_RANGE,\n",
+ ").get_all_items()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "id": "917c392c-9ae5-43e2-b7e0-71dd9f749cc2",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "178"
+ ]
+ },
+ "execution_count": 6,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "len(origin_label_items)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "e9d121a9-e54b-4039-9cef-04277962c2ca",
+ "metadata": {},
+ "source": [
+ "This is another helper function that simply displays the geometry for labels from an ItemCollection overlayed on a map of the region."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 7,
+ "id": "2f203e31-5b09-4f2e-bf27-9a3ef8e3fc4d",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def explore_search_extent(items: ItemCollection) -> None:\n",
+ " \"\"\"Extracts geometry from ItemCollection to display polygons on a map.\n",
+ "\n",
+ " Args:\n",
+ " items: ItemCollection of Items retrieved from pystac_client search\n",
+ "\n",
+ " Returns:\n",
+ " GeoDataFrame object with the .explore() method called\n",
+ " \"\"\"\n",
+ " item_feature_collection = items.to_dict()\n",
+ " geom_df = GeoDataFrame.from_features(item_feature_collection).set_crs(4326)\n",
+ " print(geom_df.bounds)\n",
+ " return geom_df[[\"geometry\", \"datetime\"]].explore(\n",
+ " column=\"datetime\", style_kwds={\"fillOpacity\": 0.2}, cmap=\"viridis\"\n",
+ " )"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "ab923855-3c20-4f10-af00-d4175a54fdd4",
+ "metadata": {},
+ "source": [
+ "Here are the BigEarthNet chips with their bounding boxes that matched the spatial parameters for the city of Luxembourg and surrounding areas."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "id": "b86bf5d8-8dc8-491d-b3cd-1ea1263774ca",
+ "metadata": {
+ "tags": []
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ " minx miny maxx maxy\n",
+ "0 6.197958 49.579464 6.215240 49.590700\n",
+ "1 6.198663 49.590240 6.215949 49.601477\n",
+ "2 6.199368 49.601017 6.216659 49.612254\n",
+ "3 6.180682 49.569146 6.197958 49.580381\n",
+ "4 6.181383 49.579923 6.198663 49.591158\n",
+ ".. ... ... ... ...\n",
+ "173 6.151709 49.634721 6.169003 49.645951\n",
+ "174 6.152406 49.645498 6.169703 49.656729\n",
+ "175 6.153102 49.656275 6.170404 49.667506\n",
+ "176 6.135808 49.645951 6.153102 49.657180\n",
+ "177 6.136501 49.656729 6.153800 49.667957\n",
+ "\n",
+ "[178 rows x 4 columns]\n"
+ ]
+ },
+ {
+ "data": {
+ "text/html": [
+ "<xarray.DataArray 'stackstac-9b126e799083670f3b31d7b4408e224e' (time: 1, band: 3, y: 128, x: 128)>\n", + "dask.array<fetch_raster_window, shape=(1, 3, 128, 128), dtype=float64, chunksize=(1, 1, 128, 128), chunktype=numpy.ndarray>\n", + "Coordinates:\n", + " * time (time) datetime64[ns] 2018-04-13T09:50:32\n", + " id (time) <U53 'bigearthnet_v1_source_S2A_MSIL2A_201804...\n", + " * band (band) <U3 'B04' 'B03' 'B02'\n", + " * x (x) float64 3.9e+05 3.9e+05 ... 3.912e+05 3.912e+05\n", + " * y (y) float64 6.67e+06 6.67e+06 ... 6.669e+06 6.669e+06\n", + " instruments <U3 'MSI'\n", + " constellation <U10 'Sentinel-2'\n", + " gsd int64 30\n", + " platform <U10 'Sentinel-2'\n", + " title (band) <U35 'S2A_MSIL2A_20180413T95032_75_25_B04' .....\n", + " common_name (band) <U5 'Red' 'Green' 'Blue'\n", + " center_wavelength object None\n", + " full_width_half_max object None\n", + " epsg int64 32635\n", + "Attributes:\n", + " spec: RasterSpec(epsg=32635, bounds=(389960, 6668780, 391240, 6670...\n", + " crs: epsg:32635\n", + " transform: | 10.00, 0.00, 389960.00|\\n| 0.00,-10.00, 6670060.00|\\n| 0.0...\n", + " resolution: 10
<xarray.DataArray 'stackstac-5d0f877107914bcb285ac37e66d7bcc9' (time: 1, band: 3, y: 24754, x: 24514)>\n",
+ "dask.array<fetch_raster_window, shape=(1, 3, 24754, 24514), dtype=float64, chunksize=(1, 1, 1024, 1024), chunktype=numpy.ndarray>\n",
+ "Coordinates:\n",
+ " * time (time) datetime64[ns] 2018-05-10T09:22:33.46...\n",
+ " id (time) <U31 'LC08_L2SP_187018_20180510_02_T1'\n",
+ " * band (band) <U5 'SR_B4' 'SR_B3' 'SR_B2'\n",
+ " * x (x) float64 3.561e+05 3.561e+05 ... 6.012e+05\n",
+ " * y (y) float64 6.785e+06 6.785e+06 ... 6.538e+06\n",
+ " landsat:processing_level <U4 'L2SP'\n",
+ " landsat:wrs_type <U1 '2'\n",
+ " landsat:cloud_cover_land float64 0.01\n",
+ " instruments object {'oli', 'tirs'}\n",
+ " landsat:collection_number <U2 '02'\n",
+ " landsat:wrs_path <U3 '187'\n",
+ " view:sun_elevation float64 46.7\n",
+ " eo:cloud_cover float64 0.01\n",
+ " platform <U9 'landsat-8'\n",
+ " landsat:collection_category <U2 'T1'\n",
+ " landsat:wrs_row <U3 '018'\n",
+ " view:off_nadir int64 0\n",
+ " landsat:scene_id <U21 'LC81870182018130LGN00'\n",
+ " description (band) <U56 'Collection 2 Level-2 Red Band (...\n",
+ " proj:epsg int64 32635\n",
+ " view:sun_azimuth float64 163.4\n",
+ " proj:bbox object {6537585.0, 6785115.0, 356085.0, 6012...\n",
+ " proj:shape object {8251, 8171}\n",
+ " title (band) <U15 'Red Band (B4)' ... 'Blue Band (...\n",
+ " proj:transform object {0.0, -30.0, 356085.0, 6785115.0, 30.0}\n",
+ " gsd float64 30.0\n",
+ " common_name (band) <U5 'red' 'green' 'blue'\n",
+ " center_wavelength (band) float64 0.65 0.56 0.48\n",
+ " full_width_half_max (band) float64 0.04 0.06 0.06\n",
+ " epsg int64 32635\n",
+ "Attributes:\n",
+ " spec: RasterSpec(epsg=32635, bounds=(356080, 6537580, 601220, 6785...\n",
+ " crs: epsg:32635\n",
+ " transform: | 10.00, 0.00, 356080.00|\\n| 0.00,-10.00, 6785120.00|\\n| 0.0...\n",
+ " resolution: 10<xarray.DataArray 'stackstac-dc63732d805d775831b0a32ce9a525a3' (time: 1, band: 3, y: 128, x: 128)>\n",
+ "dask.array<fetch_raster_window, shape=(1, 3, 128, 128), dtype=float64, chunksize=(1, 1, 128, 128), chunktype=numpy.ndarray>\n",
+ "Coordinates:\n",
+ " * time (time) datetime64[ns] 2018-05-10T09:22:33.46...\n",
+ " id (time) <U31 'LC08_L2SP_187018_20180510_02_T1'\n",
+ " * band (band) <U5 'SR_B4' 'SR_B3' 'SR_B2'\n",
+ " * x (x) float64 3.9e+05 3.9e+05 ... 3.912e+05\n",
+ " * y (y) float64 6.67e+06 6.67e+06 ... 6.669e+06\n",
+ " landsat:processing_level <U4 'L2SP'\n",
+ " landsat:wrs_type <U1 '2'\n",
+ " landsat:cloud_cover_land float64 0.01\n",
+ " instruments object {'oli', 'tirs'}\n",
+ " landsat:collection_number <U2 '02'\n",
+ " landsat:wrs_path <U3 '187'\n",
+ " view:sun_elevation float64 46.7\n",
+ " eo:cloud_cover float64 0.01\n",
+ " platform <U9 'landsat-8'\n",
+ " landsat:collection_category <U2 'T1'\n",
+ " landsat:wrs_row <U3 '018'\n",
+ " view:off_nadir int64 0\n",
+ " landsat:scene_id <U21 'LC81870182018130LGN00'\n",
+ " description (band) <U56 'Collection 2 Level-2 Red Band (...\n",
+ " proj:epsg int64 32635\n",
+ " view:sun_azimuth float64 163.4\n",
+ " proj:bbox object {6537585.0, 6785115.0, 356085.0, 6012...\n",
+ " proj:shape object {8251, 8171}\n",
+ " title (band) <U15 'Red Band (B4)' ... 'Blue Band (...\n",
+ " proj:transform object {0.0, -30.0, 356085.0, 6785115.0, 30.0}\n",
+ " gsd float64 30.0\n",
+ " common_name (band) <U5 'red' 'green' 'blue'\n",
+ " center_wavelength (band) float64 0.65 0.56 0.48\n",
+ " full_width_half_max (band) float64 0.04 0.06 0.06\n",
+ " epsg int64 32635\n",
+ "Attributes:\n",
+ " spec: RasterSpec(epsg=32635, bounds=(389960, 6668780, 391240, 6670...\n",
+ " crs: epsg:32635\n",
+ " transform: | 10.00, 0.00, 389960.00|\\n| 0.00,-10.00, 6670060.00|\\n| 0.0...\n",
+ " resolution: 10"
+ ],
+ "text/plain": [
+ "Client-270dde92-d212-11ec-8442-52879e68a5a2
\n", + "| Connection method: Cluster object | \n", + "Cluster type: distributed.LocalCluster | \n", + " \n", + "
| \n", + " Dashboard: http://127.0.0.1:8787/status\n", + " | \n", + "\n", + " |
9bbc5757
\n", + "| \n", + " Dashboard: http://127.0.0.1:8787/status\n", + " | \n", + "\n", + " Workers: 4\n", + " | \n", + "
| \n", + " Total threads: 8\n", + " | \n", + "\n", + " Total memory: 16.00 GiB\n", + " | \n", + "
| Status: running | \n", + "Using processes: True | \n", + "
Scheduler-01ba10f6-8fc1-44d9-896e-3e746fe1048b
\n", + "| \n", + " Comm: tcp://127.0.0.1:49767\n", + " | \n", + "\n", + " Workers: 4\n", + " | \n", + "
| \n", + " Dashboard: http://127.0.0.1:8787/status\n", + " | \n", + "\n", + " Total threads: 8\n", + " | \n", + "
| \n", + " Started: Just now\n", + " | \n", + "\n", + " Total memory: 16.00 GiB\n", + " | \n", + "
| \n", + " Comm: tcp://127.0.0.1:49781\n", + " | \n", + "\n", + " Total threads: 2\n", + " | \n", + "
| \n", + " Dashboard: http://127.0.0.1:49785/status\n", + " | \n", + "\n", + " Memory: 4.00 GiB\n", + " | \n", + "
| \n", + " Nanny: tcp://127.0.0.1:49770\n", + " | \n", + "\n", + " |
| \n", + " Local directory: /Users/kendallsmith/radiant/repos/PlanetaryComputerExamples/tutorials/dask-worker-space/worker-0h0k44fc\n", + " | \n", + "
| \n", + " Comm: tcp://127.0.0.1:49778\n", + " | \n", + "\n", + " Total threads: 2\n", + " | \n", + "
| \n", + " Dashboard: http://127.0.0.1:49784/status\n", + " | \n", + "\n", + " Memory: 4.00 GiB\n", + " | \n", + "
| \n", + " Nanny: tcp://127.0.0.1:49772\n", + " | \n", + "\n", + " |
| \n", + " Local directory: /Users/kendallsmith/radiant/repos/PlanetaryComputerExamples/tutorials/dask-worker-space/worker-8evp6yze\n", + " | \n", + "
| \n", + " Comm: tcp://127.0.0.1:49780\n", + " | \n", + "\n", + " Total threads: 2\n", + " | \n", + "
| \n", + " Dashboard: http://127.0.0.1:49783/status\n", + " | \n", + "\n", + " Memory: 4.00 GiB\n", + " | \n", + "
| \n", + " Nanny: tcp://127.0.0.1:49771\n", + " | \n", + "\n", + " |
| \n", + " Local directory: /Users/kendallsmith/radiant/repos/PlanetaryComputerExamples/tutorials/dask-worker-space/worker-4xh8i4d4\n", + " | \n", + "
| \n", + " Comm: tcp://127.0.0.1:49779\n", + " | \n", + "\n", + " Total threads: 2\n", + " | \n", + "
| \n", + " Dashboard: http://127.0.0.1:49782/status\n", + " | \n", + "\n", + " Memory: 4.00 GiB\n", + " | \n", + "
| \n", + " Nanny: tcp://127.0.0.1:49773\n", + " | \n", + "\n", + " |
| \n", + " Local directory: /Users/kendallsmith/radiant/repos/PlanetaryComputerExamples/tutorials/dask-worker-space/worker-9dvpa_0q\n", + " | \n", + "