guides/dynamic-compute/01 Interactive Computing with Mosaics.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8b5d0a2a-6791-44ef-a62e-1c35f75ee334",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Interactive Computing with Dynamic Compute - Mosaics\n",
    "__________________\n",
    "Dynamic Compute is a raster processing engine which enables users to generate interactive maps from a composable and arbitrary set of Python operations. Together these properties allow data scientists to quickly iterate on hypotheses and the building of complex GIS applications.\n",
    "\n",
    "In this example we provide a light overview to interactive mapping over [Kossuth, Iowa's Highest Corn Producing County](https://www.nass.usda.gov/Statistics_by_State/Iowa/Publications/County_Estimates/2021/IA-CtyEst-Corn-02-21.pdf) by exploring the [`Mosaic`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.Mosaic) class. For a more detailed look at all its classes and their available methods please visit the [`Dynamic Compute`](https://docs.descarteslabs.com/api/dynamic-compute.html) Documentation page."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "17b38345-0086-4bff-aeda-74db181a7b57",
   "metadata": {},
   "source": [
    "*__Note:__* Currently Dynamic Compute is pre-installed on Workbench, however is not included with the main Descartes Labs Python client. You can install Dynamic Compute into your Python>=3.8 environment with the following::\n",
    "\n",
    "    !pip install descarteslabs-dynamic-compute"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "214a427a-2781-4cec-885f-a9af0991d183",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import descarteslabs.dynamic_compute as dc\n",
    "from descarteslabs.dynamic_compute import Mosaic"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "55162fab-80dc-4f52-857c-ec7b44fc9248",
   "metadata": {},
   "source": [
    "## Mosaics\n",
    "\n",
    "In the above cell we imported the Dynamic Compute client and the [`Mosaic`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.Mosaic). We can instantiate a mosaic by calling [`Mosaic.from_product_bands()`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.ImageStack.from_product_bands), which takes a few input arguments:\n",
    "* __Product ID__: [\"esa:sentinel-2:l2a:v1\"](https://app.descarteslabs.com/explorer/datasets/esa:sentinel-2:l2a:v1)\n",
    "* __Bands__: \"red green blue nir\", a space-delimited string or list\n",
    "* __Start Date__: \"2022-06-15\"\n",
    "* __End Date__: \"2022-06-25\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "76a05559-fbf0-46e5-8850-35f847f8c083",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "s2_mosaic = dc.Mosaic.from_product_bands(\n",
    "    \"esa:sentinel-2:l2a:v1\",\n",
    "    \"red green blue nir\",\n",
    "    start_datetime=\"2022-06-15\",\n",
    "    end_datetime=\"2022-06-25\",\n",
    ")\n",
    "type(s2_mosaic)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b08e49b1-0a1e-45dc-9387-8ee9387249f2",
   "metadata": {},
   "source": [
    "**_Note_**: If you are coming from the legacy Workflows client, a Mosaic is analogous to the former ImageCollection with aggregation methods removed. We will discuss more advanced temporal analyses in the subsequent [02 Interactive Computing with ImageStacks.ipynb](./02%20Interactive%20Computing%20with%20ImageStacks.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "251dd483-f287-4f55-8f87-be771a9e51d7",
   "metadata": {},
   "source": [
    "## Interactive Mapping\n",
    "Now that we've defined a pointer to the dataset we want to visualize as a mosaic, in this example Sentinel-2 L2A, we can set up an interactive map over which to view our layers. \n",
    "\n",
    "We start by:\n",
    "* Delcaring a [`map`](https://ipyleaflet.readthedocs.io/en/latest/map_and_basemaps/map.html#ipyleaflet.Map) object*\n",
    "* Setting __center__ coordinates\n",
    "* Setting a start __zoom__ level\n",
    "\n",
    "_Note that Dynamic Compute is integrated with the [ipyleaflet](https://ipyleaflet.readthedocs.io/en/latest/index.html) mapping library.*_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2dd05f01-4310-43e0-b1b5-c233bd3daaac",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "m = dc.map\n",
    "m.center = 43.197541, -94.221831\n",
    "m.zoom = 13"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1d4a4e14-43dc-46d5-8fdb-2b2a1d73ee36",
   "metadata": {},
   "source": [
    "Now we can add our imagery to the map. First we call [`Mosaic.pick_bands()`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.Mosaic.pick_bands) on our __red__, __green__, and __blue__ bands, then [`Mosaic.visualize()`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.Mosaic.visualize) to add to our map viewport with the following arguments:\n",
    "* __name__: Layer name to be shown, a string\n",
    "* __map__: Dynamic Compute or ipyleaflet map object \n",
    "* __scales__ (*optional*): list"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "317fdd33-8be2-426e-ad60-a20b74354a52",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "s2_mosaic.pick_bands(\"red green blue\").visualize(\"Sentinel-2 TCC\", m)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3aa8e358-deea-435b-b410-9425cc5cd0f9",
   "metadata": {},
   "source": [
    "Now we can our map object to view the contents (pan around!):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c99ca722-7c6f-468d-83f1-1332efcd6146",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "m"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e00c0553-7b00-421a-a3f9-f292ae9dc3ad",
   "metadata": {},
   "source": [
    "## RGBs - False Color Composites\n",
    "\n",
    "We just added the __red__, __green__, and __blue__ bands to their respective RGB channels, creating a *True Color Composite* (TCC). However in the field of remote sensing we are not limited to simply the visible spectrum. Earth Observation professionals regularly switch around which bands correspond to which channel to create [RGB Composites](https://www.nesdis.noaa.gov/news/satellite-imagery-rgbs-adding-value-saving-time), which can tease out visual information that our eyes typically wouldn't see with our anatomical rods and cones. \n",
    "\n",
    "In this next cell we will add a standard False Color Composite (FCC) as a new layer, mapping __near-infrared__ to __red__, __red__ to __green__, and __green__ to __blue__ visualization channels. This particular RGB composite is [useful for highlighting healthy vegetation](https://earthobservatory.nasa.gov/features/FalseColor/page6.php) in reds/pinks and unhealthy vegetation in duller blues/greens."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "01be0331-7f04-40bf-bed0-e0aa728b7f55",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "s2_mosaic.pick_bands(\"nir red green\").visualize(\"Sentinel-2 FCC\", m)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f69277f7-e44c-46b7-914c-3fda4b2108b0",
   "metadata": {},
   "source": [
    "Note that the previous map updated in real time, we can re-call that same object as many times as we want!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "abd42f52-5f63-4036-a7ef-cc0b382f10d3",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "m"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3b753a6f-f17a-45ff-b8fc-54a09df93f59",
   "metadata": {},
   "source": [
    "## Band Ratios - NDVI\n",
    "\n",
    "Another common practice in remote sensing is creating band ratios. In this next cell we will how to calculate the *Normalized Difference in Vegetation Index* (NDVI). NDVI values typically range from -1 to +1, with higher values signifying growing vegetation as [plants high in chlorophyll content reflect more of the near-infrared wavelengths of the electromagnetic spectrum](https://earthobservatory.nasa.gov/features/MeasuringVegetation/measuring_vegetation_2.php).\n",
    "\n",
    "Our calculation is as follows:\n",
    "\n",
    "$NDVI = (NIR - RED) / (NIR + RED)$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a3984eec-be76-4730-aa44-f38ed685f388",
   "metadata": {},
   "source": [
    "Here we will use the [`Mosaic.unpack_bands()`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.Mosaic.visualize) method to reference each band as its own independent variable. We can then visualize the resulting NDVI just as we would any other mosaic!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f062b088-83a2-4a2d-9d79-3a9030724824",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "nir, red = s2_mosaic.unpack_bands(\"nir red\")\n",
    "ndvi = (nir - red) / (nir + red)\n",
    "ndvi.visualize(\"NDVI\", m, colormap=\"magma\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "165b8978-865d-40f7-b552-178b83ea44f1",
   "metadata": {},
   "source": [
    "## Masking\n",
    "We also regularly mask one raster layer to another to remove and erroneous pixel values from a visualization or computation. Dynamic Compute makes this simple through [`Mosaic.mask()`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.Mosaic.mask). \n",
    "\n",
    "In this next cell we will mask our input Sentinel-2 RGB Mosaic to our NDVI Mosaic where NDVI is less than 0.8:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a36be470-d1d6-4a84-945b-34606d245747",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "s2_mosaic_masked = s2_mosaic.mask(ndvi < 0.8)\n",
    "s2_mosaic_masked.pick_bands(\"nir red green\").visualize(\"FCC - Masked\", m)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5f3153e7-55db-4982-884d-286547beacee",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "m"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d2422abd-0345-4b31-8261-dc62bee56946",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.18"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}