{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# First Steps/Workflow"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# installation with pip optional with dependencies\n",
    "# !pip install terragon-downloader[pc]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import geopandas as gpd\n",
    "import terragon"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First you need to initialize the module and specify which data provider should be used.\n",
    "Most APIs also require some authentification, they are provided as dictonary. We will use planetary-computer here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tg = terragon.init(\"pc\")\n",
    "# for other data sources you may need to provide credentials, for example:\n",
    "# credentials = {'username': <your_username>, 'password': <your_password>}\n",
    "# tg = terragon.init('pc', credentials=credentials)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The idea is to specify all of your parameters in the create function and receive a xarray Dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gdf = gpd.read_file(\"data/TUM_OTN.geojson\")\n",
    "args = dict(\n",
    "    shp=gdf,  # the geodataframe including the geometry and CRS (required)\n",
    "    collection=\"sentinel-2-l2a\",  # the name of the collection (required)\n",
    "    bands=[\"B02\"],  # a list of bands of the collection to download\n",
    "    start_date=\"2021-01-01\",  # the start date of the time range as string\n",
    "    end_date=\"2021-01-05\",  # the end date of the time range as string\n",
    "    resolution=10,  # the resolution in meters\n",
    "    clip_to_shp=True,  # clip the data to the shapefile extent or receive the bounding box (default: True)\n",
    "    download_folder=\"eo_download\",  # the folder to save the downloaded and temporary data (default: 'eo_download')\n",
    "    num_workers=1,  # number of workers to use for downloading, currently only for gee (default: 1)\n",
    "    create_minicube=True,  # create a minicube, otherwise save the data as .tif files (default: True)\n",
    ")\n",
    "tg.create(**args)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The 'create' function is a shortcut for the 'search' and 'download' function. Search takes the same parameters as the create function and returns the items which should be downloaded. If needed one can manually filter the items. The download function takes the items, downloads and merges them into a minicube as xarray Dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "items = tg.search(**args)\n",
    "print(items)\n",
    "# here we will filter by taking the first item only\n",
    "items = item[:1]\n",
    "tg.download(items)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Saving meta data as coordinates"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# this parameter allows you to save metadata as coordinates in the minicube, this can be useful for saving ids, orbit directions, etc.\n",
    "args[\"save_metadata\"] = [\"id\", ...]  # list of metadata fields to save in the minicube\n",
    "tg.create(**args)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "v1",
   "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.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}