{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This article describes how to read in image scenes from the EarthAI Catalog into a RasterFrame.\n",
    "\n",
    "In a [previous article](https://docs.astraea.earth/hc/en-us/articles/360043451772-Query-Imagery-Data-using-the-EarthAI-Catalog-API), we discussed how to query imagery data using the EarthAI Catalog API. Now we will show how to read that catalog of imagery scenes into a RasterFrame using `spark.read.raster`.\n",
    "\n",
    "# Import Library\n",
    "\n",
    "We import the EarthAI library as a first step."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from earthai.init import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Query EarthAI Catalog\n",
    "\n",
    "The code below queries the EarthAI Catalog for [Landsat 8](https://www.usgs.gov/media/files/landsat-collection-1-level-1-product-definition) imagery with a maximum cloud cover of 10% in the month of August 2018. We pass a single lat-long point of a location within the Yellowstone region. For more information on querying the EarthAI catalog, please refer the [previous article](https://docs.astraea.earth/hc/en-us/articles/360043451772-Query-Imagery-Data-using-the-EarthAI-Catalog-API) where we discuss this in detail. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cat = earth_ondemand.read_catalog(\n",
    "     geo='POINT(-110.0 44.5)',\n",
    "     start_datetime='2018-08-01',\n",
    "     end_datetime='2018-08-31',\n",
    "     max_cloud_cover=10,\n",
    "     collections='landsat8_l1tp',\n",
    ") "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Read Imagery into a RasterFrame\n",
    "\n",
    "__cat__ contains a catalog of Landsat 8 imagery scenes. It contains references to the imagery files, but not actual imagery. To read in the imagery, you can pass __cat__ to `spark.read.raster` and it will read these imagery scenes into a RasterFrame.\n",
    "\n",
    "When passing a catalog to `spark.read.raster`, you must also provide a list of bands you wish to read, in the `catalog_col_names` parameter. To view a list of available Landsat 8 bands, you can run `earth_ondemand.item_assets('landsat8_l1tp')`. This function provides information on the available bands, spatial resolution, and band details for each collection in the EarthAI catalog.\n",
    "\n",
    "The __band_name__ field is what should be passed to `spark.read.raster`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "earth_ondemand.item_assets('landsat8_l1tp').sort_values('asset_name')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this example, we will use `spark.read.raster` to read in __B4__, __B3__, and __B2__, which correspond to the red, green, and blue bands."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rf = spark.read.raster(cat,\n",
    "                      catalog_col_names = ['B4', 'B3', 'B2'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can select the band names to view tile samples."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rf.filter(rf_tile_max('B4') > 0).select('B4', 'B3', 'B2')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`spark.read.raster` breaks imagery scenes up into a gridded set of tiles. By default, the dimensions of each tile will be 256 by 256 pixels, but if you want a different size, then you can pass a Tuple of dimensions, e.g. (512, 512), to the `tile_dimensions` parameter.\n",
    "\n",
    "_You can run `?spark.read.raster` in a cell to get more information about the parameters that `spark.read.raster` can take._"
   ]
  }
 ],
 "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": 360051407332,
   "section_id": 360008732711,
   "title": "Read in Scenes from a Raster Catalog into a RasterFrame"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}