notebooks/user_manual.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![eodag logo](https://eodag.readthedocs.io/en/latest/_static/eodag_bycs.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# eodag-labextension: user manual"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `eodag-labextension` JupyterLab plugin brings satellite imagery search ability. With that extension you can search products, see results and check if results corresponds your needs. And finally generate Python code allowing to access to those products in the notebook.\n",
    "\n",
    "That tool is based on [eodag](https://github.com/CS-SI/eodag). See the [Python API User Guide](https://eodag.readthedocs.io/en/stable/api_user_guide.html) for a complete overview of eodag features."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Configuration\n",
    "\n",
    "For some providers we don’t need to set up credentials to search for products. But if you wish to download them, you should set the credentials beforehand, using these two environment variables for instance."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example for PEPS\n",
    "os.environ[\"EODAG__PEPS__AUTH__CREDENTIALS__USERNAME\"] = \"PLEASE_CHANGE_ME\"\n",
    "os.environ[\"EODAG__PEPS__AUTH__CREDENTIALS__PASSWORD\"] = \"PLEASE_CHANGE_ME\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Credendials can be set dynamically using [environment variables](https://eodag.readthedocs.io/en/stable/getting_started_guide/configure.html#environment-variable-configuration) or also stored in the [configuration file](https://eodag.readthedocs.io/en/stable/getting_started_guide/configure.html#yaml-configuration-file) (recommanded). This file will be located at `$HOME/.config/eodag/eodag.yml`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can always choose to configure eodag using the configuration file or dynamically within your code, as shown in the [Configuration](https://eodag.readthedocs.io/en/stable/notebooks/api_user_guide/3_configuration.html) page of eodag's documentation.\n",
    "\n",
    "Configuration also includes providers priority, download destination (`outputs_prefix`), extraction, ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Search\n",
    "\n",
    "![extension logo](https://raw.githubusercontent.com/CS-SI/eodag-labextension/develop/notebooks/images/eodag_labext_icon.png) Click on this icon in the left of JupyterLab interface to open EODAG-Labextension tab.\n",
    "\n",
    "<img style=\"float: left; margin-right: 30px; border: solid; border-color: Gainsboro; \" src=\"https://raw.githubusercontent.com/CS-SI/eodag-labextension/develop/notebooks/images/eodag_labext_form.png\" alt=\"form\">\n",
    "\n",
    "With displayed search form, you can enter search extent and following search criteria:\n",
    "\n",
    "* **Provider**: the provider on which to perform the search. If no provider is selected, search will loop on providers\n",
    "  by [priority](https://eodag.readthedocs.io/en/stable/getting_started_guide/configure.html#priority-setting), and\n",
    "  return the first non empty results.\n",
    "* **Product type**: the searched product type. List filtering is performed using product types description keywords. For each entry of the drop-down list, a tooltip is displayed at hovering time with corresponding title.\n",
    "<img style=\"display: block;\" src=\"https://raw.githubusercontent.com/CS-SI/eodag-labextension/develop/notebooks/images/eodag_labext_product_types.png\" alt=\"product types\">\n",
    "\n",
    "* **Date range**: minimal and maximal dates of the search temporal window.\n",
    "* **Max cloud cover**: maximum cloud cover allowed in search results in percent. 100% will disable cloud cover filtering.\n",
    "* **Additional parameters**: used to enter key-value pairs criteria for the request. See [available parameters in EODAG documentation](https://eodag.readthedocs.io/en/stable/add_provider.html#opensearch-parameters-csv).\n",
    "\n",
    "As **search geometry** you can draw multiple extents, or use none. Each extent can be a rectangle or a free polygon.\n",
    "\n",
    "*Product type is mandatory. Other criteria are optional.*\n",
    "\n",
    "<span style=\"clear: left; display:block;\"></span>\n",
    "Once search criteria are filled out, click on:\n",
    "- `Generate Code` to automatically generate and insert the corresponding eodag search code bellow the active cell.\n",
    "- `Preview Results` to perform a search in background, display results, and generate search code in a second step."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Settings\n",
    "\n",
    "![reload logo](https://raw.githubusercontent.com/CS-SI/eodag-labextension/develop/notebooks/images/eodag_labext_reload_icon.png)\n",
    "Click on this icon to reload [EODAG configuration](https://eodag.readthedocs.io/en/stable/getting_started_guide/configure.html) \n",
    "and take into account your updated credentials or providers settings.\n",
    "\n",
    "![settings logo](https://raw.githubusercontent.com/CS-SI/eodag-labextension/develop/notebooks/images/eodag_labext_settings_icon.png)\n",
    "Click on this icon to open EODAG-Labextension settings. You will be enable to:\n",
    "- choose whether newly inserted code should replace existing search code or not;\n",
    "- configure the default map settings.\n",
    "\n",
    "![settings tab](https://raw.githubusercontent.com/CS-SI/eodag-labextension/develop/notebooks/images/eodag_labext_settings_map.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Results overview\n",
    "\n",
    "![extension popup](https://raw.githubusercontent.com/CS-SI/eodag-labextension/develop/notebooks/images/eodag_labext_popup.png)\n",
    "\n",
    "The results overview popup is composed of 3 parts:\n",
    "\n",
    "* a map showing products extent,\n",
    "* a table listing products,\n",
    "* a pane containing metadata for currently selected product.\n",
    "\n",
    "The results table allows you to access product metadata by clicking on the desired product line. The magnifying glass button allows you to zoom in on the product's in the map view. By scrolling down in the list of results, the search is automatically restarted to retrieve the following results.\n",
    "\n",
    "In the metadata view, clicking on the *Quicklook* displays it in native resolution. Clicking it again reduces its size again."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Apply to the Jupyter notebook\n",
    "\n",
    "If the search result is correct, clicking on the `Generate code` button will insert the Python eodag code in a new cell of the currently open notebook. The popup is automatically closed. From there, it is possible to work in the notebook on the search results by executing the eodag search.\n",
    "\n",
    "Here is an example of generated code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from eodag import EODataAccessGateway, setup_logging\n",
    "\n",
    "setup_logging(1) # 0: nothing, 1: only progress bars, 2: INFO, 3: DEBUG\n",
    "\n",
    "dag = EODataAccessGateway()\n",
    "geometry = \"POLYGON ((0.550136 43.005451, 0.550136 44.151469, 2.572104 44.151469, 2.572104 43.005451, 0.550136 43.005451))\"\n",
    "search_results = dag.search(\n",
    "  productType=\"S2_MSI_L1C\",\n",
    "  geom=geometry,\n",
    "  start=\"2022-11-01\",\n",
    "  end=\"2022-11-10\",\n",
    "  cloudCover=5,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You may want to enforce usage of a particular provider. To do so, use [set_preferred_provider()](https://eodag.readthedocs.io/en/stablesearch/notebooks/api_user_guide/3_configuration.html?#Set-a-provider's-priority) in  your search code after having instanciated [EODataAccessGateway](https://eodag.readthedocs.io/en/stable/api_reference/core.html#eodag.api.core.EODataAccessGateway):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dag = EODataAccessGateway()\n",
    "dag.set_preferred_provider(\"theia\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using results\n",
    "\n",
    "The obtained `SearchResult` will contain several `EOProduct` objects. See [SearchResult and EOProduct](https://eodag.readthedocs.io/en/stable/notebooks/api_user_guide/4_search.html#SearchResult-and-EOProduct) in the documentation for more information.\n",
    "\n",
    "Here are some examples about how to use search results into a notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pprint import pprint\n",
    "\n",
    "# Display results list\n",
    "pprint(search_results)\n",
    "\n",
    "# Display products access paths\n",
    "pprint([p.location for p in search_results])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Extract products extent"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from shapely.geometry import GeometryCollection\n",
    "\n",
    "features = GeometryCollection(\n",
    "    [product.geometry for product in search_results]\n",
    ")\n",
    "features"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Display products extent on a slippy map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from folium import Map, GeoJson, Figure\n",
    "\n",
    "ext = features.bounds\n",
    "bounds = [[ext[1], ext[0]], [ext[3], ext[2]]]\n",
    "m = Map(tiles=\"Stamen Terrain\", control_scale=True,)\n",
    "GeoJson(search_results).add_to(m)\n",
    "m.fit_bounds(bounds)\n",
    "Figure(width=500, height=300).add_child(m)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Downloading products\n",
    "\n",
    "See [Download EO products](https://eodag.readthedocs.io/en/stable/notebooks/api_user_guide/7_download.html#Download-EO-products) in the documentation.\n",
    "\n",
    "To download all products from the search request into a sub-directory called `downloaded`, run:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dag.download_all(search_results, outputs_prefix=\"downloaded\")"
   ]
  }
 ],
 "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.10.12"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}