{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "f2abaca9-0dca-448b-8698-2cf164d3fbd3",
   "metadata": {},
   "source": [
    "# what is specific to TOPS SLC products?\n",
    "Contrarily to GRD products SLC ones preserve the signal described in time per burst. \n",
    "\n",
    "It means that a portion of SAR image can be seen up to 4 times by the sensor.\n",
    "\n",
    "The different bursts are overlapping, and the subswaths are also overlapping.\n",
    "\n",
    "SLC products also contains the phase information, and digital number in .tiff products are complex values."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a238e3b4-0ebd-46cc-b174-750ad0a08b6d",
   "metadata": {},
   "source": [
    "# How to read a TOPS SLC product with xsar ?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f9d71fba-1269-4877-bccc-3b09577f0244",
   "metadata": {},
   "source": [
    "the TOPS (IW and EW) SLC products are distributed by ESA in .SAFE directories containing measurement and annotations per subswath and polarizations."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c3f503c1-37cf-43dd-9b1d-34cc6fd42255",
   "metadata": {},
   "source": [
    "## to open a multi dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4f01f555-7122-4a00-9c1f-2bdf4703105a",
   "metadata": {},
   "outputs": [],
   "source": [
    "import xsar\n",
    "import geoviews as gv\n",
    "import holoviews as hv\n",
    "import geoviews.feature as gf\n",
    "hv.extension('bokeh')\n",
    "path = xsar.get_test_file('S1A_IW_SLC__1SDV_20170907T102951_20170907T103021_018268_01EB76_Z020.SAFE')\n",
    "sub_swath_IDs = xsar.Sentinel1Meta(path).subdatasets\n",
    "sub_swath_IDs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a0cd6b95-5138-4aa1-8a41-fcaadc64199c",
   "metadata": {},
   "outputs": [],
   "source": [
    "multids = xsar.Sentinel1Meta(path)\n",
    "#print(dir(multids.subdatasets))\n",
    "for subswath in multids.subdatasets.index:\n",
    "    print(subswath)\n",
    "    onesubswath = xsar.Sentinel1Dataset(subswath)\n",
    "    print(onesubswath.get_bursts_polygons()['geometry'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7bb22e9a-47ec-4b04-a3c5-117331d047bf",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "#gv.tile_sources.Wikipedia*gv.Polygons(multids.bursts(only_valid_location=True)['geometry']).opts(width=800,height=450,alpha=0.5)\n",
    "import pandas as pd\n",
    "tmp = pd.concat([xsar.Sentinel1Dataset(onesubswath).get_bursts_polygons(only_valid_location=True) for onesubswath in multids.subdatasets.index])\n",
    "gv.tile_sources.EsriImagery*gv.Polygons(tmp['geometry']).opts(width=800,height=450,alpha=0.5)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e79e91f7-7134-48ff-aa2c-b8ae8fe1d4fe",
   "metadata": {},
   "outputs": [],
   "source": [
    "tmp2 = pd.concat([xsar.Sentinel1Dataset(onesubswath).get_bursts_polygons(only_valid_location=False) for onesubswath in multids.subdatasets.index])\n",
    "gv.tile_sources.EsriImagery*gv.Polygons(tmp2['geometry']).opts(width=800,height=450,alpha=0.2)*gv.Polygons(tmp['geometry']).opts(width=800,height=450,alpha=0.2)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e0fc0776-400c-45fe-b0ac-5a2c73254f1a",
   "metadata": {},
   "source": [
    "## to open a specific subswath\n",
    "to open a subswath one can use [xsar.Sentinel1Meta](../basic_api.rst#xsar.Sentinel1Meta) class to get an overview of the meta-data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "aaca7491-b202-48de-a0dd-fdb39e222c1b",
   "metadata": {},
   "outputs": [],
   "source": [
    "s1meta = xsar.sentinel1_meta.Sentinel1Meta(\"SENTINEL1_DS:%s:IW3\" % path)\n",
    "s1meta"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b532cc90-ce03-42f8-9727-8cd64e6541db",
   "metadata": {},
   "source": [
    "to manipulate the data, the user have to open `Sentinel1Dataset` instance."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "11f11577-4b1a-4652-b104-e2ad48803aa7",
   "metadata": {},
   "outputs": [],
   "source": [
    "s1ds = xsar.sentinel1_dataset.Sentinel1Dataset(\"SENTINEL1_DS:%s:IW3\" % path)\n",
    "s1ds"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f7e086f-bbfb-456c-a1dd-fb11c58d86eb",
   "metadata": {
    "tags": []
   },
   "source": [
    "## content of the Sentinel1Dataset python object\n",
    "\n",
    " - a datatree (xarray)\n",
    " - a dataset (xarray)\n",
    " - a s1meta object (class instance)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9e6138b-ea3d-4155-bbc5-6f56c6178b0f",
   "metadata": {},
   "source": [
    "## open the datatree"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c81b914e-4283-4a5c-8167-4a4cc594c6da",
   "metadata": {},
   "outputs": [],
   "source": [
    "s1ds.datatree"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81eb5d5c-f682-43a4-8b5e-72576d97b20a",
   "metadata": {},
   "source": [
    "## open dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ce2faa34-66b2-41b9-bb2f-b0a2080dba8d",
   "metadata": {},
   "outputs": [],
   "source": [
    "s1ds.dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9adef17c-c308-4972-a743-d5389abd0b63",
   "metadata": {},
   "source": [
    "## get the sar_meta"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c83ffa95-7eca-4fd3-98d2-5a1e96af93ef",
   "metadata": {},
   "outputs": [],
   "source": [
    "s1ds.sar_meta"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f7c7dcb6-827e-4fff-9293-b3eb69142061",
   "metadata": {},
   "source": [
    "# add high resolution interpolated variables\n",
    "\n",
    "for instance longitudes, latitudes, incidence angle,...\n",
    "\n",
    "Note that this step is automatically done by default for GRD products but not for SLC."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e6c891e3-055c-428f-ad4e-f9e4151c09e7",
   "metadata": {},
   "outputs": [],
   "source": [
    "s1ds.add_high_resolution_variables()\n",
    "s1ds.dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f639184d-92d8-485d-af11-6b697f5bd8fb",
   "metadata": {},
   "source": [
    "# alternatively compute the value of a geolocation field (longitude, latitude, incidence,..) at given image coordinates\n",
    "this method has been added to avoid adding hig resolution grids for some variable while we only need specific points"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2cc9e861-013c-4c91-8af5-1d05e54b7566",
   "metadata": {},
   "outputs": [],
   "source": [
    "s1ds.get_ll_from_SLC_geoloc(line=5,sample=3000,varname='incidence')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "99f4389d-9b72-41e7-a3af-d54d4bfce294",
   "metadata": {},
   "source": [
    "# perform calibration and denoizing on sigma0, gamma0 and beta0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "21c43292-f707-4bf1-9db9-4e2ce5a70c83",
   "metadata": {},
   "outputs": [],
   "source": [
    "s1ds.apply_calibration_and_denoising() \n",
    "s1ds.dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "56ef1c15-ee3f-4cc4-a752-53b91ccdba59",
   "metadata": {},
   "outputs": [],
   "source": [
    "s1ds.dataset['ground_heading']"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9dbf7a01-05b1-4f71-8d36-cb2425604c64",
   "metadata": {},
   "source": [
    "# get azimuth time variable \n",
    "the variable `azimuth_time` is given in annotations .xml files, it describes the date of acquisition of each pixel in the subswath. it is also called SAR \"long time\", in opposition to the \"short time\" given by the `slant_range_time` variable"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "affbbe27-2f35-4997-9383-aa0f65842fb8",
   "metadata": {},
   "outputs": [],
   "source": [
    "aziHr = s1ds.dataset['time']\n",
    "hv.Curve(aziHr.values)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d20503c-a59d-4a42-b476-49d40650ed11",
   "metadata": {},
   "source": [
    "`azimuth time` variable estimated at the middle (in range) of the dataset selected is showing the bursts overlapping.\n",
    "\n",
    "This variable is used to rasterize the 7 variables (longitude, latitude,...) described in the `geolocationGrid` at low resolution."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d0322224-84a8-43aa-a4e8-1a63b0a7881f",
   "metadata": {},
   "source": [
    "# get the ground range spacing\n",
    "One specificity of the SLC products is that the ground range spacing is not equal to the slant range spacing (it is the case in GRD products).\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c9e46eab-24a9-4719-aa39-edaf85dfcff8",
   "metadata": {},
   "outputs": [],
   "source": [
    "#print(s1ds.sar_meta.image['ground_pixel_spacing'])\n",
    "#print(s1ds.sar_meta.image['slant_pixel_spacing'])\n",
    "print(s1ds.dataset['sampleSpacing'])\n",
    "print(s1ds.dataset['lineSpacing'])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1b757a39-03b0-4d11-89c9-fa763548d3eb",
   "metadata": {},
   "source": [
    "The ground range spacing depends of the incidence angle.\n",
    "\n",
    "$$ grdRangeSpacing = \\frac{slantRangeSpacing}{sinus(\\theta)} $$\n",
    "\n",
    "\n",
    "\n",
    "It is possible for the users to get the ground range spacing vector along the range axis.\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "005fa242-477d-491f-bdaf-0ec51359545d",
   "metadata": {},
   "outputs": [],
   "source": [
    "rgs = s1ds.dataset['range_ground_spacing']\n",
    "rgs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2126e888-b08a-4b23-9238-13f52b034a74",
   "metadata": {},
   "outputs": [],
   "source": [
    "hv.Curve(rgs).opts(width=400,show_grid=True)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ecf8f606-c60e-4902-aa84-3e9e9fdbf706",
   "metadata": {},
   "source": [
    "# get complex digital number"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "17a6fd94-2d33-432e-b076-76e270cd7890",
   "metadata": {},
   "outputs": [],
   "source": [
    "s1ds.datatree['measurement']['digital_number']"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9c631097-54d7-4f1f-b5e1-2af10e3b9b19",
   "metadata": {},
   "source": [
    "equivalent to"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d4dfcc70-6af7-4be3-94b8-b43e0423aed6",
   "metadata": {},
   "outputs": [],
   "source": [
    "s1ds.dataset['digital_number']"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "990e41be-5a40-4e65-b395-d8eaa5fc605b",
   "metadata": {},
   "source": [
    "# additional informations\n",
    "\n",
    " - deramping TOPS SLC :[https://sentinels.copernicus.eu](https://sentinels.copernicus.eu/web/sentinel/user-guides/sentinel-1-sar/document-library/-/asset_publisher/1dO7RF5fJMbd/content/definition-of-the-tops-slc-deramping-function-for-products-generated-by-the-sentinel-1-ipf;jsessionid=DCEF041CCD5D10A93C637B6121D4D062.jvm1?redirect=https%3A%2F%2Fsentinels.copernicus.eu%2Fweb%2Fsentinel%2Fuser-guides%2Fsentinel-1-sar%2Fdocument-library%3Bjsessionid%3DDCEF041CCD5D10A93C637B6121D4D062.jvm1%3Fp_p_id%3D101_INSTANCE_1dO7RF5fJMbd%26p_p_lifecycle%3D0%26p_p_state%3Dnormal%26p_p_mode%3Dview%26p_p_col_id%3Dcolumn-1%26p_p_col_count%3D1)\n",
    " - TOPS technic: https://sentinels.copernicus.eu/web/sentinel/technical-guides/sentinel-1-sar/products-algorithms/level-1-algorithms/topsar-processing\n",
    " - SLC products: https://sentinel.esa.int/web/sentinel/technical-guides/sentinel-1-sar/products-algorithms/level-1-algorithms/single-look-complex "
   ]
  }
 ],
 "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.9.15"
  },
  "toc-autonumbering": true
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
