{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Overview" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This overview demonstrates the basic capabilities of `eodag` in a simple worflow, whose steps are introduced in more details in the following pages.\n", "\n", "The workflow consists of the following steps:\n", "\n", "1. [Configure](#Configure): `eodag` is configured to use the provider *PEPS* (registering to *PEPS* is required to download the products, see [how to register to a provider](../../getting_started_guide/register.rst))\n", "2. [Search](#Search): *Sentinel 2 Level-1C* products (i.e. images) are searched for over an area in France in March 2021.\n", "3. [Crunch](#Crunch): A decicated filter - that we call *cruncher* - provided by `eodag` is used to select products with a cloud cover less than 10%.\n", "4. [Serialize](#Serialize): Save the filtered products as a GeoJSON file.\n", "4. [Download](#Download): The products are downloaded.\n", "5. [Post-process](#Post-process): [eodag-cube](https://github.com/CS-SI/eodag-cube) is an external package that is used to access a product's data, it is going to be used to calculate the NDVI of a product." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Configure" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Let us first create a workspace directory to save products downloaded during this workflow." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "import os\n", "\n", "workspace = 'eodag_workspace_overview'\n", "if not os.path.isdir(workspace):\n", " os.mkdir(workspace)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now we will configure `eodag` to be able to download using *PEPS*. For that we need to fill our credentials:\n", "\n", "* in the user configuration file `~/.config/eodag.eodag.yml`:\n", "\n", "```yaml\n", "peps:\n", " priority: # Lower value means lower priority (Default: 1)\n", " search: # Search parameters configuration\n", " download:\n", " extract: # whether to extract the downloaded products (true or false).\n", " outputs_prefix: # where to store downloaded products.\n", " dl_url_params: # additional parameters to pass over to the download url as an url parameter\n", " delete_archive: # whether to delete the downloaded archives (true or false, Default: true).\n", " auth:\n", " credentials:\n", " username: PLEASE_CHANGE_ME\n", " password: PLEASE_CHANGE_ME\n", "```\n", "\n", "* or using environment variables: (we also set `outputs_prefix`, the directory where to store downloaded products)" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "os.environ[\"EODAG__PEPS__AUTH__CREDENTIALS__USERNAME\"] = \"PLEASE_CHANGE_ME\"\n", "os.environ[\"EODAG__PEPS__AUTH__CREDENTIALS__PASSWORD\"] = \"PLEASE_CHANGE_ME\"\n", "os.environ[\"EODAG__PEPS__DOWNLOAD__OUTPUTS_PREFIX\"] = os.path.abspath(workspace)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Logging is then activated with the [setup_logging()](../../api_reference/utils.rst#eodag.utils.logging.setup_logging) method. It's a useful way to see what `eodag` does under the hood, e.g. requesting the provider, adapting the response. It's also useful to detect when things go wrong, and, if relevant, create an [issue on GitHub](https://github.com/CS-SI/eodag/issues) with the log messages." ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [], "source": [ "from eodag import setup_logging\n", "setup_logging(2) # 3 for even more information" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The next object to import, and this is certainly one of the most important objects provided by `eodag`, is the [EODataAccessGateway](../../api_reference/core.rst#eodag.api.core.EODataAccessGateway) class. The creation of a single instance of this class is enough in a workflow, it is going to take care of configuring the providers, exposing the products configured off-the-shelf by `eodag`, and many more things." ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "2023-10-16 17:36:28,855 eodag.config [INFO ] Loading user configuration from: /home/sylvain/.config/eodag/eodag.yml\n", "2023-10-16 17:36:29,052 eodag.core [INFO ] Locations configuration loaded from /home/sylvain/.config/eodag/locations.yml\n" ] } ], "source": [ "from eodag import EODataAccessGateway\n", "dag = EODataAccessGateway()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "`eodag` stores an internal catalog of products it makes easily accessible. *Sentinel 2 Level-1C* products are designated with the identifier *S2_MSI_L1C*. It's possible to check that it's made available by *PEPS* with the method [list_product_types()](../../api_reference/core.rst#eodag.api.core.EODataAccessGateway.list_product_types) which returns a list of dictionnaries, each one of them containing general metadata (`eodag`'s product type ID, platform, sensor type, etc.)." ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "['S1_SAR_GRD', 'S1_SAR_OCN', 'S1_SAR_SLC', 'S2_MSI_L1C', 'S2_MSI_L2A']" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "[product_type[\"ID\"] for product_type in dag.list_product_types(\"peps\")]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The method [available_providers()](../../api_reference/core.rst#eodag.api.core.EODataAccessGateway.available_providers) allows to get the list of providers that make available a given product." ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "['astraea_eod',\n", " 'aws_eos',\n", " 'cop_dataspace',\n", " 'creodias',\n", " 'earth_search',\n", " 'earth_search_gcs',\n", " 'onda',\n", " 'peps',\n", " 'sara',\n", " 'usgs',\n", " 'wekeo']" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "dag.available_providers(\"S2_MSI_L1C\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Finally *PEPS* is declared as the preferred provider, which means that `eodag` will look for products with this provider (all the providers are pre-configured)." ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [], "source": [ "dag.set_preferred_provider(\"peps\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Search" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The [EODataAccessGateway](../../api_reference/core.rst#eodag.api.core.EODataAccessGateway) class provides three search methods which have a similar signature but behave in different ways:\n", "\n", "[search()](../../api_reference/core.rst#eodag.api.core.EODataAccessGateway.search) returns a tuple with:\n", "\n", "* a [SearchResult](../../api_reference/searchresult.rst#eodag.api.search_result.SearchResult) that stores the products obtained from a given **page** (default: `page=1`) and a given maximum **number of items per page** (default: `items_per_page=20`)\n", "* an integer that is the **estimated** total number of products matching the search criteria\n", "\n", "