{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this tutorial, we show how to display RGB (true-color) and false-color image tiles contained in a [RasterFrames](https://rasterframes.io) data structure.\n",
    "\n",
    "RasterFrames brings the characteristics and capabilities of DataFrames to raster imagery data.  Tiles are subsets of scenes and scenes are discrete instances of Earth observation data with specified spatial extent, date-time, and coordinate reference system.\n",
    "\n",
    "RGB images are also called true- or natural-color images as these contain the wavelengths that human vision processes.\n",
    "\n",
    "RGB channels can also be assigned to other spectral bands, such as the near-infrared and short-wave infrared bands.  In this instance, the composite RGB images are now called false-color images. Below we give examples of how to produce false-color image tiles in addition to true color image tiles.\n",
    "\n",
    "# Import Libraries\n",
    "\n",
    "We will start by importing the Python libraries used in this example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from earthai.init import *\n",
    "from pyrasterframes.rasterfunctions import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Query the Earth OnDemand Catalog\n",
    "\n",
    "Next, we query the Earth OnDemand catalog to obtain imagery with the `earth_ondemand.read_catalog` function.  There are a number of ways to query the catalog.  This example is querying the MODIS Terra and Aqua surface reflectivity catalog centered on a specific point with longitude-latitude coordinates.  This geospatial point corresponds to a location near Palmas, Brazil.  We have also arbitrarily selected images collected during the months of September and October of 2019."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "catalog = earth_ondemand.read_catalog(\n",
    "    geo=\"POINT(-50.8 -10.5)\",\n",
    "    start_datetime='2019-09-01',\n",
    "    end_datetime='2019-10-31',\n",
    "    max_cloud=5,\n",
    "    collections='mcd43a4',\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Create and Display True-color Tiles\n",
    "\n",
    "Now we read the results of the Earth OnDemand query into a RasterFrame using the `spark.read.raster` function. For this example, we'll select the red, green, and blue MODIS bands: B01, B04, B03, respectively. Simply for clarity we also rename the **B01**, **B04**, and **B03** columns as **red**, **green**, and **blue** with the `withColumnRenamed` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "true_color_rf = spark.read.raster(catalog, catalog_col_names=['B01', 'B04', 'B03']) \\\n",
    "                     .withColumnRenamed('B01', 'red') \\\n",
    "                     .withColumnRenamed('B04', 'green') \\\n",
    "                     .withColumnRenamed('B03', 'blue')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we will create a new tile column that represents the composite image tiles of the red, green, and blue channels.  This is otherwise known as a true-color image.  To accomplish this we use the `rf_render_png` function from the pyrasterframes.rasterfunctions library.  This function takes three tile columns, which in this case are the red, green, and blue bands of the MODIS imagery, and combines them into a single composite.  It then converts this composite to a PNG-encoded image.  The two lines of code below create a new column **png** that is made up of true-color composite tiles and displays the first five true color tiles in a notebook cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "true_color_rf = true_color_rf.withColumn('png', rf_render_png('red', 'green', 'blue'))\n",
    "true_color_rf.select('png')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Create and Display False-color Tiles"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also assign other spectral bands to the RGB channels producing false-color images.  This can highlight Earth image properties such as differentiating between snow, ice, and clouds or showing where flooding has occurred.  A very common false-color image utilizes the near-infrared, green, and red bands to show vegetation and vegetated areas.  The code below follows the same steps as for generating the true color image tiles, but now we assign the MODIS near-infrared band to the red channel, the red band to the green channel, and the green band to the blue channel.  In these image tiles, the red colors depict areas of vegetation. Dark red represents dense vegetation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "false_color_rf = spark.read.raster(catalog, catalog_col_names=['B02', 'B01', 'B04'])\\\n",
    "                      .withColumnRenamed('B02', 'nir') \\\n",
    "                      .withColumnRenamed('B04', 'green') \\\n",
    "                      .withColumnRenamed('B01', 'red')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "false_color_rf = false_color_rf.withColumn('png', rf_render_png('nir', 'red', 'green'))\n",
    "false_color_rf.select('png')"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "EarthAI Environment",
   "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.7.9"
  },
  "zendesk": {
   "draft": true,
   "id": 360051906152,
   "section_id": 360010176352,
   "title": "How to Create and Display RGB Image Tiles with RasterFrames"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}