{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "f9ee7e1d-c9d4-4d2a-8959-f4a242a887d6",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Advanced explanation for RCM\n",
    "Contrary to Sentinel-1, Radarsat Constellation Mission doesn't have the notion of multi dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b12158f1-e2cd-445d-b74f-8dacfbb387f3",
   "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('RCM1_OK1050603_PK1050605_1_SC50MB_20200214_115905_HH_HV_Z010')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "89f81cfe-0b0f-4eb5-b69d-782fc1b3bfc3",
   "metadata": {},
   "outputs": [],
   "source": [
    "import warnings\n",
    "warnings.filterwarnings('ignore')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2e48d37d-70d3-46fd-9726-7d3e25a0ab74",
   "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 [xarray-safe-rcm](https://github.com/umr-lops/xarray-safe-rcm).\n",
    "This datatree is than used as an attribute of [RcmMeta](../basic_api.rst#xsar.RcmMeta)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "adaeb3d8-aba7-4ff8-95be-50748477ee9f",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Instanciate a RadarSat2Meta object\n",
    "meta = xsar.RcmMeta(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",
    "meta.dt"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "27d70e7e-ef3b-4197-9fde-a687324a3b32",
   "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",
    "meta.geoloc"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ed6956fa-967e-4437-bc8b-924e73c7da00",
   "metadata": {},
   "source": [
    "In the metadata class : noise lut, calibration lut and incidence are processed because samples are expressed thanks to a firstPixelValue, a step and a nbOfValues.\n",
    "It is made internally to the reader's datatree thanks to the method [assign_index](../basic_api.rst#xsar.RcmMeta.assign_index)\n",
    "See Documentation : RCM Image Product Format Definition (7.5.1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1b1daefb-076b-4124-9396-9963f1953795",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Calibration look up tables in range\n",
    "meta.lut"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "325b8973-4611-40c1-9ec0-3013c4534781",
   "metadata": {},
   "outputs": [],
   "source": [
    "#noise look up tables in range\n",
    "meta.noise_lut"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8358a21e-35d4-4dae-8ee1-7e81e70c0b2e",
   "metadata": {},
   "outputs": [],
   "source": [
    "#incidence angles\n",
    "meta.incidence"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "547ae8e7-89a6-4da6-8b33-5d02a63c220e",
   "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",
    "rcmds = xsar.RcmDataset(dataset_id=path, resolution=resolution)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "24da7a01-fc07-407d-8196-f0c5bf7fd78c",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Get the Dataset object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2edf21ee-c0a0-4b6a-bbf5-3fc35e4946c5",
   "metadata": {},
   "outputs": [],
   "source": [
    "rcmds"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a501c6e0-53fa-4c00-9cd0-701057f92f1d",
   "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": [
    "rcmds.sar_meta"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bfea8982-1c0f-4067-9c36-2aac99a46626",
   "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": [
    "rcmds.dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "54f59306-e80c-4e1f-9ba6-1be83348b06b",
   "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).\n",
    "\n",
    "See RCM Image Product Format Definition (4.2.1) for more explication about the different cases when lines or samples are flipped"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "220bb60c-7218-4bea-89f6-c210fc54a82f",
   "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": "8822d0bf-a103-44d2-8655-fbbf75b92359",
   "metadata": {
    "tags": []
   },
   "source": [
    "## How to apply calibration?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "27662456-da70-4135-a4c4-4a1722b91bc9",
   "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": "aae79788-43af-4e74-bf2b-411312665683",
   "metadata": {},
   "source": [
    "### Load digital numbers "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "740e846e-31d8-455b-8cc3-e54d5333ea72",
   "metadata": {},
   "source": [
    "[load_digital_number](../basic_api.rst#xsar.RcmDataset.load_digital_number) 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": [
    "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 = rcmds.load_digital_number(resolution=resolution, resampling=resampling, chunks=chunks)\n",
    "dn_low_res"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4b2eb7f5-d2f6-4be5-a6ca-e69cc3f4e8f6",
   "metadata": {},
   "source": [
    "### Get the raw normalized radar cross section"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b506a9b5-df74-4788-81b4-733f4d5537e0",
   "metadata": {},
   "source": [
    "First the calibration look up tables are loaded at the good resolution in `xsar.RcmDataset._luts` thanks to the method [lazy_load_luts](../basic_api.rst#xsar.RcmDataset.lazy_load_luts). \n",
    "The resampling is made thanks to an interpolation with the method ̀`xsar.RcmDataset._interpolate_var`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f36c3a3-bd09-423d-ba14-e9065e5269d4",
   "metadata": {},
   "source": [
    "This last method uses `RectBivariateSpline`for the interpolation, but it is necessary that data is expressed as a 2D vector. Here, calibration/noise look up tables and incidence 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": "25756802-d112-47e1-ad0a-bfa586ae6ca1",
   "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 applies the following formula :\n",
    "\n",
    "$$ \\frac{(digitalNumbers^2)+offset}{Gain} $$\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "299ce38a-ddf0-47c3-ac73-07398f8dcd25",
   "metadata": {},
   "source": [
    "Reference : `RCM Image Product Format Definition` (7.5.1)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16d5a7f1-cb26-4f2b-8bb3-2986224bb7cd",
   "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 = rcmds._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='HV')\n",
    "plt.pcolor(sigma0_raw_cross, vmax=0.02, cmap='Greys_r')\n",
    "plt.title('sigma0_raw HV')\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='HH')\n",
    "plt.pcolor(sigma0_raw_co, vmax=0.7, cmap='Greys_r')\n",
    "plt.title('sigma0_raw HH')\n",
    "plt.xlabel('samples')\n",
    "plt.ylabel('lines')\n",
    "plt.colorbar()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "783f8c11-f4c4-4b3d-ac84-567d1bade5d1",
   "metadata": {},
   "source": [
    "## How to apply denoising ?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e5bbadd-15ad-4ce3-bf00-97692f5ff965",
   "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": "5e137f4f-7a9b-4b99-9df7-cb40b1a669b2",
   "metadata": {
    "tags": []
   },
   "source": [
    "### How to get the Noise Equivalent Sigma Zero ?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eefbcf40-2c59-43ca-8800-57e17a677ef6",
   "metadata": {},
   "source": [
    "The noise look up tables are loaded at the good resolution in `xsar.RcmDataset._noise_luts` thanks to the method [lazy_load_noise_luts](../basic_api.rst#xsar.RcmDataset.lazy_load_noise_luts). \n",
    "The resampling is made thanks to an interpolation with the method ̀`xsar.RcmDataset._interpolate_var`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "06234b52-fd82-4931-a779-2732cbc18e60",
   "metadata": {},
   "source": [
    "Notes:\n",
    "- noise luts are already calibrated so we don't have to apply a calibration on these\n",
    "- `interpolate_var` method explained above converts the NoiseLevelValues in linear beacause these are expressed in `dB` in the reader. The formula used is : \n",
    "    <font size=\"5\">\n",
    "    $$ NoiseLevelValues_{linear} = 10^\\frac{NoiseLevelValues_{dB}}{10} $$\n",
    "    </font>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1a4ff245-531f-42db-9803-6193bc339d21",
   "metadata": {},
   "outputs": [],
   "source": [
    "nesz_low_res = rcmds.lazy_load_noise_luts().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.sel(pol='HH'), cmap='Greys_r')\n",
    "plt.title('nesz (pol = HH)')\n",
    "plt.xlabel('samples')\n",
    "plt.ylabel('lines')\n",
    "plt.colorbar()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d41ce7e3-dca3-4e29-9148-492ec46ace30",
   "metadata": {},
   "source": [
    "### How to get the noise substracted Sigma0"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eaf4c18f-ef7d-4263-9628-aeca44342a98",
   "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 [RcmDataset.dataset](../basic_api.rst#xsar.RcmDataset.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": "fdb16247-b53a-4121-bee5-434abff49643",
   "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='HV')\n",
    "sigma0_co = sigma0.sel(pol='HH')\n",
    "\n",
    "plt.subplot(2,2,1)\n",
    "plt.pcolor(sigma0_raw_cross, vmax=0.02, cmap='Greys_r')\n",
    "plt.title('Sigma0 HV 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 HV 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 HH 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 HH without noise')\n",
    "plt.xlabel('samples')\n",
    "plt.ylabel('lines')\n",
    "plt.colorbar()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6f7d249b-e81d-4367-b14f-cbffa0ca5288",
   "metadata": {},
   "source": [
    "## How to get the incidence ?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c6f23854-21b6-458c-9980-1b28f00e5006",
   "metadata": {},
   "source": [
    "Such as noise/calibration look up tables, incidence depends on samples, which are expressed in the reader thanks to step, firstPixelValue and nbOfValues. Samples are computed in the meta class directly on the datatree thanks to the method [assign_index](../basic_api.rst#xsar.RcmMeta.assign_index)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "794e6d47-2246-425f-b6d8-63b6a039c406",
   "metadata": {},
   "source": [
    "`_load_incidence_from_lut` is a function that applies an interpolation with `_interpolate_var` and then return the incidence at the good resolution"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d648204d-869b-48a4-8846-f792cb67771f",
   "metadata": {},
   "outputs": [],
   "source": [
    "incidence = rcmds._load_incidence_from_lut()\n",
    "incidence"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5256446f-97d8-46ae-bbac-d856492f2800",
   "metadata": {},
   "source": [
    "## How to get the elevation ?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c6dd1a89-0f2c-48c6-aee5-91b39f0db5bd",
   "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",
    "2 variables give orbit altitude so we considered the`SatelliteHeight` (and not the`altitude`).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "109b5fc5-ae08-4013-8c9e-6044155b4be0",
   "metadata": {},
   "source": [
    "`RcmDataset._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 = rcmds._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"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
