{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "59c5ad41-af85-41ab-b893-7535f9333336",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Advanced explanation for RadarSat2\n",
    "Contrary to Sentinel-1, RadarSat-2 doesn't have the notion of multi dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e1eadce8-9883-49c1-a5d1-cf580c212607",
   "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('RS2_OK135107_PK1187782_DK1151894_SCWA_20220407_182127_VV_VH_SGF')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1ce56392-3141-4c00-a2d2-b044fd57322f",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Access metadata from a product\n",
    "Raw information is stocked in different files such as tiff ones (for digital numbers).\n",
    "A file named product.xml is constitued of the main information (geolocation grid, orbit attitude, noise look up tables...).\n",
    "Calibration look up tables are located in xml files.\n",
    "All the useful data is grouped in a datatree thanks to dependencie [xradarsat2](https://github.com/umr-lops/xradarsat2).\n",
    "This datatree is than used as an attribute of [RadarSat2Meta](../basic_api.rst#xsar.RadarSat2Meta)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "adaeb3d8-aba7-4ff8-95be-50748477ee9f",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Instanciate a RadarSat2Meta object\n",
    "rs2meta = xsar.RadarSat2Meta(name=path)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "36e8851f-e249-453c-bd55-9edb499e0d3c",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Access the datatree extracted from the reader\n",
    "rs2meta.dt"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d3a23fa-855c-4290-a6f6-4e0b2c01226f",
   "metadata": {},
   "source": [
    "### Examples of alias to datasets (from the datatree above)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5514bdfc-9f1f-44b7-baa3-51629e4dcbe0",
   "metadata": {},
   "outputs": [],
   "source": [
    "#geolocation grid (low resolution)\n",
    "rs2meta.geoloc"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1b1daefb-076b-4124-9396-9963f1953795",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Calibration look up tables in range\n",
    "rs2meta.lut"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "85f0d8da-23ea-4b0e-9848-2c8fc6188cae",
   "metadata": {},
   "source": [
    "## Open a dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c3576ce4-a18f-4e4d-9ae4-d8e5d723fa57",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define the resolution to load the dataset at a lower resolution (if not specified or None, the dataset is loaded at high resolution)\n",
    "resolution = '1000m'\n",
    "\n",
    "# Instanciate a RadarSatDataset object\n",
    "rs2ds = xsar.RadarSat2Dataset(dataset_id=path, resolution=resolution)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21e7c1b8-f32a-4739-88fb-a8c9a6d335cb",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Get the Dataset object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2edf21ee-c0a0-4b6a-bbf5-3fc35e4946c5",
   "metadata": {},
   "outputs": [],
   "source": [
    "rs2ds"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ddd90774-385f-4640-a538-48319744b61d",
   "metadata": {},
   "source": [
    "### Access the metadata object from the Dataset object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "81a701d3-ebcf-4a18-a334-5490fa3389c7",
   "metadata": {},
   "outputs": [],
   "source": [
    "rs2ds.sar_meta"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e750d0b9-e739-49e4-90de-d49946448d61",
   "metadata": {},
   "source": [
    "### Access the dataset\n",
    "In this dataset, we can find variables like latitude, longitude, look up tables (before and after denoising), incidence..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ee93e584-7e2d-412e-8e9a-d7ee6b4f7a22",
   "metadata": {},
   "outputs": [],
   "source": [
    "rs2ds.dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19303837-04c7-45c4-beac-875439ee23cf",
   "metadata": {},
   "source": [
    "Variables `lines_flipped`and `samples_flipped` are added to the dataset to know if these have been flipped (in order to follow xsar convention)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b08b414a-e69e-4305-aaac-044b6b0d91a6",
   "metadata": {},
   "source": [
    "### Alternatives solutions to open dataset and datatree"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a73a8dc8-0980-40e6-b034-2e6d0c92c660",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Open dataset\n",
    "xsar.open_dataset(path, resolution=resolution)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "18831ae2-c6a0-42ed-9c16-cbaf11dd4b81",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Open datatree\n",
    "xsar.open_datatree(path, resolution=resolution)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "096dfbdb-8667-444e-9498-26d083dd78d3",
   "metadata": {
    "tags": []
   },
   "source": [
    "## How to apply calibration?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f8736ec-8f69-4ae2-8f0d-7825d15a9496",
   "metadata": {},
   "source": [
    "All the operation below are already performed by default for GRD products. So, what is following is a simple explanation about how is made calibration."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "53131639-4058-464f-95c5-9eb9f9359304",
   "metadata": {},
   "source": [
    "### Load digital numbers "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6cccbe7c-2f0a-4e21-8903-7c80f665383f",
   "metadata": {},
   "source": [
    "[load_digital_number](https://cerweb.ifremer.fr/datarmor/doc_lib_reader_RS2/html/generated/xradarsat2.load_digital_number.html) is a function that allows to load digital numbers from tiff files at chosen resolution and return it as a `DataArray`. \n",
    "Resampling is made thanks to `rasterio.open(tiff_file).read`. \n",
    "For dual pol products, there is a tiff file for each pol. So that digital numbers are computed for both pol. Posting of lines and samples is computed thanks to `Affine.translation` and `Affine.scale`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dacd21a7-629a-476a-b34a-31f293c76c2d",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xradarsat2 import load_digital_number\n",
    "import rasterio\n",
    "\n",
    "#Define resampling method (here it is the root mean square from rasterio)\n",
    "resampling = rasterio.enums.Resampling.rms\n",
    "\n",
    "#Define the chunks size for line and samples\n",
    "chunks = {'line': 5000, 'sample': 5000}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9e217df6-b021-412b-9982-57840e03436b",
   "metadata": {},
   "outputs": [],
   "source": [
    "dn_low_res = load_digital_number(rs2ds.sar_meta.dt, resolution=resolution, resampling=resampling, chunks=chunks)['digital_numbers'].ds\n",
    "dn_low_res"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d7bfa338-94c3-4e6c-85aa-3f1f7bd09e2e",
   "metadata": {},
   "source": [
    "### Get the raw normalized radar cross section"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1253a381-2b68-4a7d-824c-10304b31c44b",
   "metadata": {},
   "source": [
    "`_apply_calibration_lut` is a method that applies a calibration look up table to digital numbers to compute gamma0, beta0 and sigma0 (depending on the variable name passed in argument) and return the result as a `DataArray`. It first get the high resolution calibration look up table. But it isn't at the good resolution (already high resolution). So, this functions uses another one named `_resample_lut_values`. Once the calibration look up table is at the good resolution, we can apply the following formula :\n",
    "\n",
    "$$ \\frac{(digitalNumbers^2)+offset}{Gain} $$\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a24779f3-3f55-4de9-b840-e764cd8c42d5",
   "metadata": {},
   "source": [
    "Reference : `Radarsat2 Product Format Definition` (7.2) : https://earth.esa.int/eogateway/documents/20142/0/Radarsat-2-Product-Format-Definition.pdf/1ca0cf1e-5a15-a29b-6187-9e5cb1650048#page=77"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "769679de-8e35-4e3b-b3b1-1173517d3c58",
   "metadata": {},
   "source": [
    " `_resample_lut_values` uses `RectBivariateSpline`for the interpolation, but it is necessary that data is expressed as a 2D vector. Here, calibration look up tables are expressed as 1D vector (range sample). Consequently, we need to convert these in 2D (adding an azimuth dimension dependency) before applying the interpolation. Conversion is made thanks to `numpy.tile`, using the low resolution lines expressed in the geolocation grid part of the reader; reducing the calculation. A template of a `DataArray` that uses the posting of digital numbers (with applied resolution) is given on this interpolation function so the result is now at the right resolution."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d671b606-6ff3-4b0a-840c-e786429a3458",
   "metadata": {},
   "source": [
    "Different resampling method were tried such as `scipy.ndimage.gaussian_filter1d` that had the convenience to accept 1d vectors. Data was computed with this function and the chosen posting was this of digital numbers. But in order to be homogenous with other operations made in `xsar`, we chose to keep the solution with `RectBivariateSpline`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "eef4d32f-0c30-4a86-92d0-305b8e133d46",
   "metadata": {},
   "outputs": [],
   "source": [
    "sigma0_raw = rs2ds._apply_calibration_lut('sigma0').sigma0_raw\n",
    "sigma0_raw"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9893f301-880f-4047-be0b-82427631ab1f",
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "73e72c33-e3a9-4c5c-8000-b14d0a6cf864",
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.figure(figsize=(13, 6)) \n",
    "\n",
    "plt.subplot(1, 2, 1)\n",
    "sigma0_raw_cross = sigma0_raw.sel(pol='VH')\n",
    "plt.pcolor(sigma0_raw_cross, vmax=0.02, cmap='Greys_r')\n",
    "plt.title('sigma0_raw VH')\n",
    "plt.xlabel('samples')\n",
    "plt.ylabel('lines')\n",
    "plt.colorbar()\n",
    "\n",
    "plt.subplot(1, 2, 2)\n",
    "sigma0_raw_co = sigma0_raw.sel(pol='VV')\n",
    "plt.pcolor(sigma0_raw_co, vmax=0.7, cmap='Greys_r')\n",
    "plt.title('sigma0_raw VV')\n",
    "plt.xlabel('samples')\n",
    "plt.ylabel('lines')\n",
    "plt.colorbar()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fc1a4fa3-2562-4cbf-8e45-460b836f1288",
   "metadata": {},
   "source": [
    "## How to apply denoising ?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "77d40b42-9639-4b28-b8f4-f0a1e59b6067",
   "metadata": {},
   "source": [
    "All the operation below are already performed by default for GRD products. So, what is following is a simple explanation about how is made denoising."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9546fe03-f362-451d-baba-6a218d36e756",
   "metadata": {
    "tags": []
   },
   "source": [
    "### How to get the Noise Equivalent Sigma Zero ?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6b6e3fb8-6618-4c89-a0bf-401d90f117a2",
   "metadata": {},
   "source": [
    "`NoiseLevelValues` at low resolution are extracted from product.xml and then located in the datatree of the metadata (`dt['radarParameters']`). They are already calibrated so we don't have to apply a calibration on theseThey are expressed in `dB`, and are given with a `pixelFirstNoiseValue` and a `stepSize`.\n",
    "With these information we have now to build the `noise_lut`. The first thing to do is to convert the NoiseLevelValues in linear : \n",
    "<font size=\"5\">\n",
    "$$ NoiseLevelValues_{linear} = 10^\\frac{NoiseLevelValues_{dB}}{10} $$\n",
    "</font>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "57989162-4a17-49aa-8eec-39f0bde0c3d7",
   "metadata": {},
   "source": [
    "Right now we compute the nesz thanks to the following documentation : https://earth.esa.int/eogateway/documents/20142/0/Radarsat-2-Product-Format-Definition.pdf/1ca0cf1e-5a15-a29b-6187-9e5cb1650048#page=70"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1a4ff245-531f-42db-9803-6193bc339d21",
   "metadata": {},
   "outputs": [],
   "source": [
    "nesz_low_res = rs2ds._interpolate_for_noise_lut('sigma0')\n",
    "nesz_low_res"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a323b20a-6749-4a19-9ed3-361872ec53da",
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.pcolor(nesz_low_res, vmax=0.005, cmap='Greys_r')\n",
    "plt.title('nesz')\n",
    "plt.xlabel('samples')\n",
    "plt.ylabel('lines')\n",
    "plt.colorbar()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a741c220-68e1-4e4b-b44a-0bd8fb4a77fb",
   "metadata": {},
   "source": [
    "### How to get the noise substracted Sigma0"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "98689414-952c-4f74-b333-ff6e2e6919d9",
   "metadata": {},
   "source": [
    "Right now we only have to substract the noise_lut to the raw normalized radar cross section. It is made with the function `_add_denoised`, that add the variables to the [RadarSat2Dataset.dataset](../basic_api.rst#xsar.RadarSat2Dataset.dataset)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "416b33b9-28ca-449c-b47c-9b467985bb14",
   "metadata": {},
   "outputs": [],
   "source": [
    "sigma0 = sigma0_raw - nesz_low_res\n",
    "sigma0"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "02b45fd1-1456-4930-9597-43cbbdb02cb3",
   "metadata": {},
   "source": [
    "### Comparison between noised sigma0 and noised substracted sigma0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4b645cf5-d10d-42d6-a4ea-bde16b37c02a",
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.figure(figsize=(26, 12))\n",
    "\n",
    "sigma0_cross = sigma0.sel(pol='VH')\n",
    "sigma0_co = sigma0.sel(pol='VV')\n",
    "\n",
    "plt.subplot(2,2,1)\n",
    "plt.pcolor(sigma0_raw_cross, vmax=0.02, cmap='Greys_r')\n",
    "plt.title('Sigma0 VH with noise')\n",
    "plt.xlabel('samples')\n",
    "plt.ylabel('lines')\n",
    "plt.colorbar()\n",
    "\n",
    "plt.subplot(2,2,3)\n",
    "plt.pcolor(sigma0_cross, vmax=0.02, cmap='Greys_r')\n",
    "plt.title('Sigma0 VH without noise')\n",
    "plt.xlabel('samples')\n",
    "plt.ylabel('lines')\n",
    "plt.colorbar()\n",
    "\n",
    "plt.subplot(2,2,2)\n",
    "plt.pcolor(sigma0_raw_co, vmax=0.7, cmap='Greys_r')\n",
    "plt.title('Sigma0 VV with noise')\n",
    "plt.xlabel('samples')\n",
    "plt.ylabel('lines')\n",
    "plt.colorbar()\n",
    "\n",
    "plt.subplot(2,2,4)\n",
    "plt.pcolor(sigma0_co, vmax=0.7, cmap='Greys_r')\n",
    "plt.title('Sigma0 VV without noise')\n",
    "plt.xlabel('samples')\n",
    "plt.ylabel('lines')\n",
    "plt.colorbar()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6c39d764-5982-4ab5-b990-4df4077c1e92",
   "metadata": {},
   "source": [
    "## How to get the incidence ?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e7373f9e-8bd4-4225-b79d-30aaab849f35",
   "metadata": {},
   "source": [
    "Radarsat2 product format definition (7.2) provides a formula of look up tables, depending on the incidence. We already have information about look up tables, so we determine incidence with these look up tables: \n",
    "\n",
    "$$ Incidence = \\arctan{\\frac{\\gamma}{\\beta}} $$\n",
    "\n",
    "reference link : https://earth.esa.int/eogateway/documents/20142/0/Radarsat-2-Product-Format-Definition.pdf/1ca0cf1e-5a15-a29b-6187-9e5cb1650048#page=78\n",
    "\n",
    "We have the choice between 2 types of look up tables: denoised and not denoised. We have chosen to determine incidence with not denoised look up tables.\n",
    "This computation is made by the function `_load_incidence_from_lut` that returns a DatArray"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d648204d-869b-48a4-8846-f792cb67771f",
   "metadata": {},
   "outputs": [],
   "source": [
    "incidence = rs2ds._load_incidence_from_lut()\n",
    "incidence"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f00cae4-caf2-4d0e-b110-d4d8c47e3ec8",
   "metadata": {},
   "source": [
    "## How to get the elevation ?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "abdada4b-bb0c-4374-9c9a-5f441f1b684d",
   "metadata": {},
   "source": [
    "To get the incidence, we apply a formula :\n",
    "    \n",
    "$$ \\theta = \\arcsin{[\\sin{(Incidence)} . \\frac{r}{r + h}]} $$\n",
    "\n",
    "$$ ( r \\text{ is the earth radius} , h \\text{ is the orbit altitude} ) $$\n",
    "\n",
    "Reference : Data Products Specifications (https://asf.alaska.edu/wp-content/uploads/2019/03/r1_prod_spec.pdf#page=47)\n",
    "\n",
    "2 variables give orbit altitude so we considered the`SatelliteHeight` (and not the`altitude`).\n",
    "`RadarSat2Dataset._load_elevation_from_lut` permit to calculate the elevation (in degrees)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "14dc8d91-7325-4069-b4f4-e93be7d31c9d",
   "metadata": {},
   "outputs": [],
   "source": [
    "elevation = rs2ds._load_elevation_from_lut()\n",
    "elevation"
   ]
  }
 ],
 "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.8"
  },
  "toc-autonumbering": true
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
