tutorials/notebooks/24_stac_assets_generator.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# STAC assets generators"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we want to generate STAC metadata from a imagery dataset through EOTDL, we must generate a STACDataFrame, as seen in this [notebook](20_stac.ipynb). When generating the STACDataFrame, there is a needed parameter called `assets_generator`. In this notebook we are going to dive in it.\n",
    "\n",
    "Uncomment the following line to install eotdl if needed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# !pip install eotdl"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The assets_generator parameter defines the strategy to follow with the generation of assets from each image. In this way, it could be the case that from a Sentinel-2 image we want to extract all its bands as assets, or simply extract the RGB bands, or not extract any as assets. By default, three strategies have been established, which can be expanded according to needs.\n",
    "\n",
    "- `STACAssetGenerator`: does not extract new assets from the image bands, so a single asset is generated for the image.\n",
    "- `BandsAssetGenerator`: from the original image it creates a new file for each band established in the 'bands` column, deleting the original file. An asset is added to the STAC item for each band. _Attention: this feature is still under development and could not work._"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from eotdl.curation.stac.stac import STACGenerator\n",
    "from eotdl.curation.stac.assets import STACAssetGenerator, BandsAssetGenerator\n",
    "from eotdl.curation.stac.parsers import UnestructuredParser\n",
    "from eotdl.curation.stac.dataframe_labeling import LabeledStrategy\n",
    "\n",
    "stac_generator = STACGenerator(item_parser=UnestructuredParser, \n",
    "                               assets_generator=STACAssetGenerator, \n",
    "                               labeling_strategy=LabeledStrategy,\n",
    "                               image_format='tif'\n",
    "                               )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>image</th>\n",
       "      <th>label</th>\n",
       "      <th>ix</th>\n",
       "      <th>collection</th>\n",
       "      <th>extensions</th>\n",
       "      <th>bands</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>example_data/jaca_dataset/Jaca_1.tif</td>\n",
       "      <td>Jaca</td>\n",
       "      <td>0</td>\n",
       "      <td>example_data/jaca_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>example_data/jaca_dataset/Jaca_2.tif</td>\n",
       "      <td>Jaca</td>\n",
       "      <td>0</td>\n",
       "      <td>example_data/jaca_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>example_data/jaca_dataset/Jaca_3.tif</td>\n",
       "      <td>Jaca</td>\n",
       "      <td>0</td>\n",
       "      <td>example_data/jaca_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>example_data/jaca_dataset/Jaca_4.tif</td>\n",
       "      <td>Jaca</td>\n",
       "      <td>0</td>\n",
       "      <td>example_data/jaca_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                  image label  ix  \\\n",
       "0  example_data/jaca_dataset/Jaca_1.tif  Jaca   0   \n",
       "1  example_data/jaca_dataset/Jaca_2.tif  Jaca   0   \n",
       "2  example_data/jaca_dataset/Jaca_3.tif  Jaca   0   \n",
       "3  example_data/jaca_dataset/Jaca_4.tif  Jaca   0   \n",
       "\n",
       "                         collection extensions bands  \n",
       "0  example_data/jaca_dataset/source       None  None  \n",
       "1  example_data/jaca_dataset/source       None  None  \n",
       "2  example_data/jaca_dataset/source       None  None  \n",
       "3  example_data/jaca_dataset/source       None  None  "
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df = stac_generator.get_stac_dataframe('example_data/jaca_dataset/')\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A key feature is the `label` column. Using the label of every image we are going to assign parameters like the STAC extensions that this image's item is going to have, or the bands we want to extract using the `BandsAssetGenerator`. We can obtain the existing labels in the STACDataFrame before adding new information."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Jaca']"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "labels = df.label.unique().tolist()\n",
    "labels"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Starting from the found label we are going to define the image bands. To simplify, let's only define the bands `B04`, `B03` and `B02`, which are the RGB bands.\n",
    "\n",
    "To define these parameters for each label, we simply have to declare a dictionary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "bands = {'Jaca': ('B02', 'B03', 'B04')}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>image</th>\n",
       "      <th>label</th>\n",
       "      <th>ix</th>\n",
       "      <th>collection</th>\n",
       "      <th>extensions</th>\n",
       "      <th>bands</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>example_data/jaca_dataset/Jaca_1.tif</td>\n",
       "      <td>Jaca</td>\n",
       "      <td>0</td>\n",
       "      <td>example_data/jaca_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>(B02, B03, B04)</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>example_data/jaca_dataset/Jaca_2.tif</td>\n",
       "      <td>Jaca</td>\n",
       "      <td>0</td>\n",
       "      <td>example_data/jaca_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>(B02, B03, B04)</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>example_data/jaca_dataset/Jaca_3.tif</td>\n",
       "      <td>Jaca</td>\n",
       "      <td>0</td>\n",
       "      <td>example_data/jaca_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>(B02, B03, B04)</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>example_data/jaca_dataset/Jaca_4.tif</td>\n",
       "      <td>Jaca</td>\n",
       "      <td>0</td>\n",
       "      <td>example_data/jaca_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>(B02, B03, B04)</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                  image label  ix  \\\n",
       "0  example_data/jaca_dataset/Jaca_1.tif  Jaca   0   \n",
       "1  example_data/jaca_dataset/Jaca_2.tif  Jaca   0   \n",
       "2  example_data/jaca_dataset/Jaca_3.tif  Jaca   0   \n",
       "3  example_data/jaca_dataset/Jaca_4.tif  Jaca   0   \n",
       "\n",
       "                         collection extensions            bands  \n",
       "0  example_data/jaca_dataset/source       None  (B02, B03, B04)  \n",
       "1  example_data/jaca_dataset/source       None  (B02, B03, B04)  \n",
       "2  example_data/jaca_dataset/source       None  (B02, B03, B04)  \n",
       "3  example_data/jaca_dataset/source       None  (B02, B03, B04)  "
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df = stac_generator.get_stac_dataframe('example_data/jaca_dataset/', bands=bands)\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we just generate STAC metadata using the `generate_stac_metadata` function, those defined bands are useless, since we haven't defined a STAC `eo` extension to define those bands in the STAC item. However, if we were to use the `BandsAssetGenerator`, we would extract the selected bands from the original image, save them as `.tif` files in the image location, and add them to the STAC item as assets. This could be carried out with any combination of bands of both Sentinel-1 (VV, VH) and Sentinel-2, as desired, as long as the bands exist in the original image."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "sen12floods",
   "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.11.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}