Experimental.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Experimental Features\n",
    "Here are some examples of experimental features we're planning to add to our API. These wrappers abstract away some\n",
    "parts of the protobuf structs, and provide easier access to geometries and `datetime`.\n",
    "\n",
    "## First Code Example\n",
    "This is an alternative to the original version [here](./README.md#first-code-example). This simplifies the setting of\n",
    "the `observed` field and hides the use of more verbose protobuf classes for both time filter (`observed`) and spatial\n",
    "filter (`intersects`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "nsl client connecting to stac service at: api.nearspacelabs.net:9090\n",
      "\n",
      "attempting NSL authentication against https://api.nearspacelabs.net\n",
      "fetching new authorization in 60 minutes\n",
      "href: \"https://api.nearspacelabs.net/download/20190822T162258Z_TRAVIS_COUNTY/Published/REGION_0/20190822T183518Z_746_POM1_ST2_P.png\"\n",
      "type: \"image/png\"\n",
      "eo_bands: RGB\n",
      "asset_type: THUMBNAIL\n",
      "cloud_platform: GCP\n",
      "bucket_manager: \"Near Space Labs\"\n",
      "bucket_region: \"us-central1\"\n",
      "bucket: \"swiftera-processed-data\"\n",
      "object_path: \"20190822T162258Z_TRAVIS_COUNTY/Published/REGION_0/20190822T183518Z_746_POM1_ST2_P.png\"\n",
      "extension: .png\n",
      "asset_key: THUMBNAIL_RGB\n"
     ]
    }
   ],
   "source": [
    "import tempfile\n",
    "from datetime import date\n",
    "\n",
    "from shapely.wkt import loads as load_wkt_shapely\n",
    "\n",
    "from IPython.display import Image, display\n",
    "from epl.geometry import Point\n",
    "from nsl.stac import enum, utils\n",
    "from nsl.stac.experimental import NSLClientEx, StacRequestWrap\n",
    "\n",
    "# the client package stubs out a little bit of the gRPC connection code \n",
    "# get a client interface to the gRPC channel. This client singleton is threadsafe\n",
    "client = NSLClientEx()\n",
    "\n",
    "# create our request. this interface allows us to set fields in our protobuf object\n",
    "request = StacRequestWrap()\n",
    "\n",
    "# our area of interest will be the coordinates of the UT Stadium in Austin Texas\n",
    "# the order of coordinates here is longitude then latitude (x, y). The results of our query \n",
    "# will be returned only if they intersect this point geometry we've defined (other geometry \n",
    "# types besides points are supported)\n",
    "#\n",
    "# This string format, POINT(float, float) is the well-known-text geometry format:\n",
    "# https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry\n",
    "#\n",
    "# the epsg # defines the WGS-84 elispsoid (`epsg=4326`) spatial reference \n",
    "# (the latitude longitude  spatial reference most commonly used)\n",
    "#\n",
    "# the epl.geometry Point class is an extension of shapely's Point class that supports\n",
    "# the protobuf definitions we use with STAC. To extract a shapely geometry from it use\n",
    "# the shapely_dump property\n",
    "request.intersects = Point.import_wkt(wkt=\"POINT(-97.7323317 30.2830764)\", epsg=4326)\n",
    "# or using `shapely`\n",
    "request.intersects = load_wkt_shapely(\"POINT(-97.7323317 30.2830764)\")\n",
    "\n",
    "# The `set_observed` method allows for making sql-like queries on the observed field and the\n",
    "# LTE is an enum that means less than or equal to the value in the query field\n",
    "#\n",
    "# This Query is for data from August 25, 2019 UTC or earlier\n",
    "request.set_observed(rel_type=enum.FilterRelationship.LTE, value=date(2019, 8, 25))\n",
    "\n",
    "# search_one_ex method requests only one item be returned that meets the query filters in the StacRequestWrap\n",
    "# the item returned is a wrapper of the protobuf message; StacItemWrap. search_one_ex, will only return the most\n",
    "# recently observed results that matches the time filter and spatial filter\n",
    "stac_item = client.search_one_ex(request)\n",
    "\n",
    "# get the thumbnail asset from the assets map. The other option would be a Geotiff, \n",
    "# with asset key 'GEOTIFF_RGB'\n",
    "asset_wrap = stac_item.get_asset(asset_type=enum.AssetType.THUMBNAIL)\n",
    "\n",
    "print(asset_wrap)\n",
    "# uncomment to display image\n",
    "# with tempfile.TemporaryDirectory() as d:\n",
    "#     filename = utils.download_asset(asset=asset, save_directory=d)\n",
    "#     display(Image(filename=filename))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Simple Query and the Makeup of a StacItem\n",
    "The easiest query to construct is a `StacRequestWrap` constructor with no variables, and the next simplest, is the case\n",
    "where we know the STAC item `id` that we want to search. If we already know the STAC `id` of an item, we can construct\n",
    "the `StacRequestWrap` as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "id: \"20190822T183518Z_746_POM1_ST2_P\"\n",
      "collection: \"NSL_SCENE\"\n",
      "properties {\n",
      "  type_url: \"nearspacelabs.com/proto/st.protobuf.v1.NslDatast.protobuf.v1.NslData/st.protobuf.v1.NslData\"\n",
      "  value: \"\\n\\340\\014\\n\\03620190822T162258Z_TRAVIS_COUNTY\\\"\\003 \\352\\0052\\03520200702T102306Z_746_ST2_POM1:\\03520190822T183518Z_746_POM1_ST2:\\03520200702T101632Z_746_ST2_POM1:\\03520200702T102302Z_746_ST2_POM1:\\03520200702T102306Z_746_ST2_POM1B\\03520190822T183518Z_746_POM1_ST2H\\001R\\374\\n\\n$\\004\\304{?\\216\\371\\350=\\376\\377\\306>\\300\\327\\256\\275\\323rv?2\\026*D3Qy6\\177>\\3675\\000\\000\\200?\\022\\024\\r+}\\303\\302\\025\\033;\\362A\\0353}\\367\\300%g\\232\\250@\\022\\024\\r\\026}\\303\\302\\025\\376?\\362A\\035\\000\\367\\235@%\\232\\t\\331?\\022\\024\\r\\351|\\303\\302\\025\\021A\\362A\\035M\\370\\033\\301%g\\016\\226\\277\\022\\024\\r\\201|\\303\\302\\025\\3709\\362A\\035\\000\\252\\245@%\\315\\3547?\\022\\024\\r\\310|\\303\\302\\025\\245G\\362A\\035\\232\\315l\\301%3\\347\\270\\300\\022\\024\\rq|\\303\\302\\025\\2149\\362A\\035\\000\\376o@%\\000(\\017@\\022\\024\\rD|\\303\\302\\025oD\\362A\\0353\\323\\302\\301%\\315\\306\\230\\300\\022\\024\\r\\031|\\303\\302\\025\\035=\\362A\\035g\\277$A%\\000\\340\\231?\\022\\024\\rE|\\303\\302\\025\\215I\\362A\\0353\\275z\\300%g\\020\\236\\300\\022\\024\\r\\345{\\303\\302\\0258C\\362A\\035\\0008\\242?%\\232\\231\\226\\277\\022\\024\\r\\010|\\303\\302\\025!I\\362A\\0353\\377\\212\\300%\\000V\\241\\300\\022\\024\\r|{\\303\\302\\025\\207F\\362A\\0353\\203Y@%\\315,\\313\\276\\022\\024\\r\\001{\\303\\302\\025FJ\\362A\\035g^\\025@%\\315\\010\\214?\\022\\024\\r\\313z\\303\\302\\025\\353H\\362A\\0353\\3377@%g\\326\\325\\277\\022\\024\\rjz\\303\\302\\025\\260@\\362A\\035\\315F\\006A%g\\246[\\277\\022\\024\\r\\035z\\303\\302\\0254E\\362A\\035\\232\\001|@%\\232!\\265?\\022\\024\\r\\330y\\303\\302\\025\\320@\\362A\\0353Sa\\300%\\000@\\245>\\022\\024\\r\\362y\\303\\302\\025zE\\362A\\035\\232\\221\\020\\300%3U\\206@\\022\\024\\r\\337y\\303\\302\\025\\210F\\362A\\035g\\246l?%gf\\234\\276\\022\\024\\r\\335y\\303\\302\\025aF\\362A\\035\\000\\260\\023@%\\315,#\\277\\022\\024\\r\\321y\\303\\302\\025\\234F\\362A\\035\\000 7@%\\232!\\221?\\022\\024\\r\\307y\\303\\302\\025\\177F\\362A\\035\\232\\371\\371?%\\315\\224\\225?\\022\\024\\r\\213y\\303\\302\\025\\350@\\362A\\0353\\'\\343\\300%3g&\\300\\022\\024\\r\\300y\\303\\302\\025\\tF\\362A\\035\\315h\\312@%g\\266\\013?\\022\\024\\r_y\\303\\302\\025\\236A\\362A\\035\\315\\340\\311@%3\\363j>\\022\\024\\r\\271x\\303\\302\\025G?\\362A\\0353\\334\\272\\301%gb\\201\\300\\022\\024\\r\\307x\\303\\302\\025WG\\362A\\035\\000|6\\301%\\232\\231i>\\022\\024\\r\\200x\\303\\302\\025\\016F\\362A\\035\\315\\007\\244\\301%\\315L\\000>\\022\\024\\rqx\\303\\302\\025jI\\362A\\035\\315\\254\\007\\301%\\232E\\247?\\022\\024\\rjx\\303\\302\\025(I\\362A\\035\\232\\305\\000\\301%\\315L\\'>\\022\\024\\r\\027x\\303\\302\\025\\356A\\362A\\035\\232I\\246?%\\315\\004\\246\\277\\022\\024\\r\\010x\\303\\302\\025AB\\362A\\035\\232y\\305\\300%\\315\\3740?\\022\\024\\r\\032x\\303\\302\\0257D\\362A\\0353\\003\\275\\277%\\232\\311.?\\022\\024\\r\\002x\\303\\302\\025&C\\362A\\035\\315\\014\\301\\277%g*2@\\022\\024\\r\\361w\\303\\302\\025\\330B\\362A\\035\\000T\\347\\300%\\232\\235\\025\\300\\022\\024\\r\\372v\\303\\302\\025\\030<\\362A\\0353\\323\\364?%gNt\\300\\022\\024\\r;w\\303\\302\\025\\273I\\362A\\03533\\335>%\\232\\025\\213?\\022\\024\\r\\324v\\303\\302\\025QC\\362A\\035\\315,\\305\\277%\\232\\375\\035@\\022\\024\\r\\340v\\303\\302\\025@G\\362A\\035\\315@\\234\\300%\\232)\\342?\\022\\024\\r\\312v\\303\\302\\025yC\\362A\\035\\315\\214\\247\\276%g\\246\\375>\\022\\024\\r\\222v\\303\\302\\025\\233A\\362A\\035\\315\\334\\244?%g\\366\\035\\277\\022\\024\\r\\256v\\303\\302\\025\\\\F\\362A\\0353G\\204@%\\232A\\017@\\022\\024\\rov\\303\\302\\025\\215=\\362A\\035\\232\\325\\340@%3\\263\\033\\276\\022\\024\\r\\206v\\303\\302\\025SC\\362A\\0353\\263k?%3\\363\\177\\276\\022\\024\\r\\267v\\303\\302\\025NK\\362A\\035\\315\\0148\\277%3\\323\\000>\\022\\024\\r\\255v\\303\\302\\025kK\\362A\\035gf4\\277%\\000\\312\\201\\277\\022\\024\\r)v\\303\\302\\025\\316=\\362A\\035\\232\\271Z\\277%\\315\\014\\375\\277\\022\\024\\r_v\\303\\302\\025\\356H\\362A\\035\\315\\004n@%3\\243\\240\\276\\022\\024\\r7v\\303\\302\\025\\350H\\362A\\0353#\\212@%g~\\272?\\022\\024\\r\\314u\\303\\302\\025Y;\\362A\\035\\000\\000F=%gF\\253?\\022\\024\\r\\276u\\303\\302\\025q>\\362A\\0353/\\234\\300%g\\246T\\277\\022\\024\\r\\266u\\303\\302\\025\\321>\\362A\\035\\315 \\272\\300%3SW\\300\\022\\024\\r\\307u\\303\\302\\025\\211A\\362A\\035\\000$\\264\\300%3\\243\\r\\277\\022\\024\\r\\360u\\303\\302\\025RK\\362A\\0353\\347\\231@%\\315\\325\\036\\300\\022\\024\\r\\262u\\303\\302\\025\\035F\\362A\\0353\\2633\\276%\\232i3?\\032#m_3009743_sw_14_1_20160928_20161129\\\"Y\\t&\\2068NM\\357\\\"A\\021\\003\\3272rL\\217IA\\031\\267G\\014x\\260\\375\\\"A!\\202I\\225>\\020\\222IA*3\\0221+proj=utm +zone=14 +datum=NAD83 +units=m +no_defs*\\005\\r\\205[\\\"A2\\005\\r\\000\\356\\\\@:\\005\\r\\227\\210\\306AB\\005\\r\\205E\\257@\\022\\315\\001\\n e502fe83507f0d28c826f33619a678e9\\022\\03120200806T033934Z_SWIFTERA\\030\\010 \\377\\377\\377\\377\\377\\377\\377\\377\\377\\001(A0\\0018\\340\\025@\\330\\247\\004H\\270\\275\\004R\\03620190822T162258Z_TRAVIS_COUNTYR\\03120200701T112634Z_SWIFTERAR\\03120200701T112634Z_SWIFTERAR\\03120200701T112634Z_SWIFTERAX\\263\\027\"\n",
      "}\n",
      "assets {\n",
      "  key: \"GEOTIFF_RGB\"\n",
      "  value {\n",
      "    href: \"https://api.nearspacelabs.net/download/20190822T162258Z_TRAVIS_COUNTY/Published/REGION_0/20190822T183518Z_746_POM1_ST2_P.tif\"\n",
      "    type: \"image/vnd.stac.geotiff\"\n",
      "    eo_bands: RGB\n",
      "    asset_type: GEOTIFF\n",
      "    cloud_platform: GCP\n",
      "    bucket_manager: \"Near Space Labs\"\n",
      "    bucket_region: \"us-central1\"\n",
      "    bucket: \"swiftera-processed-data\"\n",
      "    object_path: \"20190822T162258Z_TRAVIS_COUNTY/Published/REGION_0/20190822T183518Z_746_POM1_ST2_P.tif\"\n",
      "  }\n",
      "}\n",
      "assets {\n",
      "  key: \"THUMBNAIL_RGB\"\n",
      "  value {\n",
      "    href: \"https://api.nearspacelabs.net/download/20190822T162258Z_TRAVIS_COUNTY/Published/REGION_0/20190822T183518Z_746_POM1_ST2_P.png\"\n",
      "    type: \"image/png\"\n",
      "    eo_bands: RGB\n",
      "    asset_type: THUMBNAIL\n",
      "    cloud_platform: GCP\n",
      "    bucket_manager: \"Near Space Labs\"\n",
      "    bucket_region: \"us-central1\"\n",
      "    bucket: \"swiftera-processed-data\"\n",
      "    object_path: \"20190822T162258Z_TRAVIS_COUNTY/Published/REGION_0/20190822T183518Z_746_POM1_ST2_P.png\"\n",
      "  }\n",
      "}\n",
      "geometry {\n",
      "  wkb: \"\\001\\006\\000\\000\\000\\001\\000\\000\\000\\001\\003\\000\\000\\000\\001\\000\\000\\000\\005\\000\\000\\000\\352\\244L\\267\\311oX\\300\\316\\340\\320\\247\\234I>@\\241\\273\\2606\\267oX\\300<\\002\\205\\'EG>@\\031\\003\\203\\307\\266nX\\3001z\\244\\372\\233G>@CCAI\\306nX\\300\\326\\013\\351\\023\\343I>@\\352\\244L\\267\\311oX\\300\\316\\340\\320\\247\\234I>@\"\n",
      "  proj {\n",
      "    epsg: 4326\n",
      "  }\n",
      "  envelope {\n",
      "    xmin: -97.7466867683867\n",
      "    ymin: 30.278398961994966\n",
      "    xmax: -97.72990596574927\n",
      "    ymax: 30.288621181865743\n",
      "    proj {\n",
      "      epsg: 4326\n",
      "    }\n",
      "  }\n",
      "  simple: STRONG_SIMPLE\n",
      "}\n",
      "bbox {\n",
      "  xmin: -97.7466867683867\n",
      "  ymin: 30.278398961994966\n",
      "  xmax: -97.72990596574927\n",
      "  ymax: 30.288621181865743\n",
      "  proj {\n",
      "    epsg: 4326\n",
      "  }\n",
      "}\n",
      "datetime {\n",
      "  seconds: 1566498918\n",
      "  nanos: 505476000\n",
      "}\n",
      "observed {\n",
      "  seconds: 1566498918\n",
      "  nanos: 505476000\n",
      "}\n",
      "created {\n",
      "  seconds: 1596743811\n",
      "  nanos: 247169000\n",
      "}\n",
      "updated {\n",
      "  seconds: 1612193286\n",
      "  nanos: 12850810\n",
      "}\n",
      "platform_enum: SWIFT_2\n",
      "platform: \"SWIFT_2\"\n",
      "instrument_enum: POM_1\n",
      "instrument: \"POM_1\"\n",
      "constellation: \"UNKNOWN_CONSTELLATION\"\n",
      "mission_enum: SWIFT\n",
      "mission: \"SWIFT\"\n",
      "gsd {\n",
      "  value: 0.20000000298023224\n",
      "}\n",
      "eo {\n",
      "}\n",
      "view {\n",
      "  off_nadir {\n",
      "    value: 9.42326831817627\n",
      "  }\n",
      "  azimuth {\n",
      "    value: -74.85270690917969\n",
      "  }\n",
      "  sun_azimuth {\n",
      "    value: 181.26959228515625\n",
      "  }\n",
      "  sun_elevation {\n",
      "    value: 71.41288757324219\n",
      "  }\n",
      "}\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from nsl.stac.experimental import NSLClientEx, StacRequestWrap\n",
    "\n",
    "# get a client interface to the gRPC channel\n",
    "client_ex = NSLClientEx()\n",
    "\n",
    "# create a request for a specific STAC item\n",
    "request = StacRequestWrap(id='20190822T183518Z_746_POM1_ST2_P')\n",
    "\n",
    "# for this request we might as well use the search one, as STAC ids ought to be unique\n",
    "stac_item = client.search_one_ex(request)\n",
    "print(stac_item)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Spatial Queries\n",
    "\n",
    "### Query by Bounds\n",
    "You can query for STAC items intersecting a bounding box of minx, miny, maxx, and maxy. An\n",
    "[epsg](https://en.wikipedia.org/wiki/EPSG_Geodetic_Parameter_Dataset) code is required (4326 is the most common epsg\n",
    "code used for longitude and latitude). Remember, this finds STAC items that intersect the bounds, **not** STAC items\n",
    "contained by the bounds."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "STAC item id: 20200703T174443Z_650_POM1_ST2_P\n",
      "bounds:\n",
      "(-97.74591162787891, 30.279053855446275, -97.7277773253055, 30.292199081479485)\n",
      "bbox (EnvelopeData protobuf):\n",
      "xmin: -97.74591162787891\n",
      "ymin: 30.279053855446275\n",
      "xmax: -97.7277773253055\n",
      "ymax: 30.292199081479485\n",
      "proj {\n",
      "  epsg: 4326\n",
      "}\n",
      "\n",
      "geometry:\n",
      "MULTIPOLYGON (((-97.74591162787891 30.28747759413035, -97.74220557686867 30.27905385544627, -97.7277773253055 30.28386159376494, -97.73145460028107 30.29219908147948, -97.74591162787891 30.28747759413035))) epsg: 4326\n",
      "\n",
      "STAC item id: 20200703T174303Z_595_POM1_ST2_P\n",
      "bounds:\n",
      "(-97.75153797990234, 30.269721707638205, -97.73325611269058, 30.28300247580166)\n",
      "bbox (EnvelopeData protobuf):\n",
      "xmin: -97.75153797990234\n",
      "ymin: 30.269721707638205\n",
      "xmax: -97.73325611269058\n",
      "ymax: 30.28300247580166\n",
      "proj {\n",
      "  epsg: 4326\n",
      "}\n",
      "\n",
      "geometry:\n",
      "MULTIPOLYGON (((-97.75153797990234 30.27820420412512, -97.74797016158224 30.2697217076382, -97.73325611269058 30.27455757923618, -97.73689448438766 30.28300247580166, -97.75153797990234 30.27820420412512))) epsg: 4326\n",
      "\n",
      "STAC item id: 20200703T174258Z_592_POM1_ST2_P\n",
      "bounds:\n",
      "(-97.75173081772343, 30.27574130837018, -97.73339335367488, 30.289420847305855)\n",
      "bbox (EnvelopeData protobuf):\n",
      "xmin: -97.75173081772343\n",
      "ymin: 30.27574130837018\n",
      "xmax: -97.73339335367488\n",
      "ymax: 30.289420847305855\n",
      "proj {\n",
      "  epsg: 4326\n",
      "}\n",
      "\n",
      "geometry:\n",
      "MULTIPOLYGON (((-97.75173081772343 30.28402515650995, -97.74761771913884 30.27574130837018, -97.73339335367488 30.28124021004074, -97.73745378448336 30.28942084730586, -97.75173081772343 30.28402515650995))) epsg: 4326\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from nsl.stac.experimental import StacRequestWrap, NSLClientEx\n",
    "\n",
    "# get a client interface to the gRPC channel\n",
    "client_ex = NSLClientEx()\n",
    "\n",
    "# request wrapper\n",
    "request = StacRequestWrap()\n",
    "\n",
    "# define our area of interest bounds using the xmin, ymin, xmax, ymax coordinates of an area on \n",
    "# the WGS-84 ellipsoid\n",
    "neighborhood_box = (-97.7352547645, 30.27526474757116, -97.7195692, 30.28532)\n",
    "# setting the bounds tests for intersection (not contains)\n",
    "request.set_bounds(neighborhood_box, epsg=4326)\n",
    "request.limit = 3\n",
    "\n",
    "# Search for data that intersects the bounding box\n",
    "epsg_4326_ids = []\n",
    "for stac_item in client_ex.search_ex(request):\n",
    "    print(\"STAC item id: {}\".format(stac_item.id))\n",
    "    print(\"bounds:\")\n",
    "    print(stac_item.geometry.bounds)\n",
    "    print(\"bbox (EnvelopeData protobuf):\")\n",
    "    print(stac_item.bbox)\n",
    "    print(\"geometry:\")\n",
    "    print(stac_item.geometry)\n",
    "    epsg_4326_ids.append(stac_item.id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Query by Bounds; Projection Support\n",
    "Querying using geometries defined in a different projection requires defining the epsg number for the spatial reference\n",
    "of the data. In this example we use an epsg code for a [UTM projection](https://epsg.io/3744).\n",
    "\n",
    "Notice that the results below are the same as the cell above (look at the `TEST-->` section of the printout)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "STAC item id: 20200703T174443Z_650_POM1_ST2_P\n",
      "bounds:\n",
      "(-97.74591162787891, 30.279053855446275, -97.7277773253055, 30.292199081479485)\n",
      "bbox (EnvelopeData protobuf):\n",
      "xmin: -97.74591162787891\n",
      "ymin: 30.279053855446275\n",
      "xmax: -97.7277773253055\n",
      "ymax: 30.292199081479485\n",
      "proj {\n",
      "  epsg: 4326\n",
      "}\n",
      "\n",
      "geometry:\n",
      "MULTIPOLYGON (((-97.74591162787891 30.28747759413035, -97.74220557686867 30.27905385544627, -97.7277773253055 30.28386159376494, -97.73145460028107 30.29219908147948, -97.74591162787891 30.28747759413035))) epsg: 4326\n",
      "\n",
      "TEST RESULT 'True': stac_item id 20200703T174443Z_650_POM1_ST2_P from 3744 bounds is in the set of the 4326 bounds search results.\n",
      "\n",
      "STAC item id: 20200703T174303Z_595_POM1_ST2_P\n",
      "bounds:\n",
      "(-97.75153797990234, 30.269721707638205, -97.73325611269058, 30.28300247580166)\n",
      "bbox (EnvelopeData protobuf):\n",
      "xmin: -97.75153797990234\n",
      "ymin: 30.269721707638205\n",
      "xmax: -97.73325611269058\n",
      "ymax: 30.28300247580166\n",
      "proj {\n",
      "  epsg: 4326\n",
      "}\n",
      "\n",
      "geometry:\n",
      "MULTIPOLYGON (((-97.75153797990234 30.27820420412512, -97.74797016158224 30.2697217076382, -97.73325611269058 30.27455757923618, -97.73689448438766 30.28300247580166, -97.75153797990234 30.27820420412512))) epsg: 4326\n",
      "\n",
      "TEST RESULT 'True': stac_item id 20200703T174303Z_595_POM1_ST2_P from 3744 bounds is in the set of the 4326 bounds search results.\n",
      "\n",
      "STAC item id: 20200703T174258Z_592_POM1_ST2_P\n",
      "bounds:\n",
      "(-97.75173081772343, 30.27574130837018, -97.73339335367488, 30.289420847305855)\n",
      "bbox (EnvelopeData protobuf):\n",
      "xmin: -97.75173081772343\n",
      "ymin: 30.27574130837018\n",
      "xmax: -97.73339335367488\n",
      "ymax: 30.289420847305855\n",
      "proj {\n",
      "  epsg: 4326\n",
      "}\n",
      "\n",
      "geometry:\n",
      "MULTIPOLYGON (((-97.75173081772343 30.28402515650995, -97.74761771913884 30.27574130837018, -97.73339335367488 30.28124021004074, -97.73745378448336 30.28942084730586, -97.75173081772343 30.28402515650995))) epsg: 4326\n",
      "\n",
      "TEST RESULT 'True': stac_item id 20200703T174258Z_592_POM1_ST2_P from 3744 bounds is in the set of the 4326 bounds search results.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from nsl.stac.experimental import StacRequestWrap, NSLClientEx\n",
    "\n",
    "# get a client interface to the gRPC channel\n",
    "client_ex = NSLClientEx()\n",
    "\n",
    "# request wrapper\n",
    "request = StacRequestWrap()\n",
    "\n",
    "# define our area of interest bounds using the xmin, ymin, xmax, ymax coordinates of in UTM 14N in NAD83 (epsg 3744)\n",
    "neighborhood_box = (621636.1875228449, 3349964.520449501, 623157.4212553708, 3351095.8075163467)\n",
    "# setting the bounds tests for contains query\n",
    "request.set_bounds(neighborhood_box, epsg=3744)\n",
    "request.limit = 3\n",
    "\n",
    "# Search for data that intersects the bounding box\n",
    "for stac_item in client_ex.search_ex(request):\n",
    "    print(\"STAC item id: {}\".format(stac_item.id))\n",
    "    print(\"bounds:\")\n",
    "    print(stac_item.geometry.bounds)\n",
    "    print(\"bbox (EnvelopeData protobuf):\")\n",
    "    print(stac_item.bbox)\n",
    "    print(\"geometry:\")\n",
    "    print(stac_item.geometry)\n",
    "    print(\"TEST RESULT '{1}': stac_item id {0} from 3744 bounds is in the set of the 4326 bounds search results.\"\n",
    "          .format(stac_item.id, stac_item.id in epsg_4326_ids))\n",
    "    print()\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Query by GeoJSON\n",
    "Use a GeoJSON geometry to define the `intersects` property."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "STAC item id: 20201001T211834Z_2012_POM1_ST2_P\n",
      "Stac item observed: 2020-10-01 21:18:34+00:00\n",
      "STAC item id: 20201001T211832Z_2011_POM1_ST2_P\n",
      "Stac item observed: 2020-10-01 21:18:32+00:00\n"
     ]
    }
   ],
   "source": [
    "import json\n",
    "import requests\n",
    "from epl.geometry import shape as epl_shape\n",
    "\n",
    "from nsl.stac.experimental import StacRequestWrap, NSLClientEx\n",
    "\n",
    "# get a client interface to the gRPC channel\n",
    "client_ex = NSLClientEx()\n",
    "\n",
    "request = StacRequestWrap()\n",
    "\n",
    "# retrieve a coarse geojson foot print of Travis County, Texas\n",
    "r = requests.get(\"http://raw.githubusercontent.com/johan/world.geo.json/master/countries/USA/TX/Travis.geo.json\")\n",
    "travis_shape = epl_shape(r.json()['features'][0]['geometry'], epsg=4326)\n",
    "\n",
    "# search for any data that intersects the travis county geometry\n",
    "request.intersects = travis_shape\n",
    "\n",
    "# limit results to 2 (instead of default of 10)\n",
    "request.limit = 2\n",
    "\n",
    "geojson_ids = []\n",
    "# get a client interface to the gRPC channel\n",
    "for stac_item in client_ex.search_ex(request):\n",
    "    print(\"STAC item id: {}\".format(stac_item.id))\n",
    "    print(\"Stac item observed: {}\".format(stac_item.observed))\n",
    "    geojson_ids.append(stac_item.id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Query by WKT\n",
    "Use a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) geometry to define the\n",
    "`intersects` property."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "STAC item id: 20201001T211834Z_2012_POM1_ST2_P from wkt filter intersects result from geojson filter: True\n",
      "STAC item id: 20201001T211832Z_2011_POM1_ST2_P from wkt filter intersects result from geojson filter: True\n"
     ]
    }
   ],
   "source": [
    "from epl.geometry import Polygon\n",
    "\n",
    "# Same geometry as above, but a wkt geometry instead of a geojson\n",
    "travis_wkt = \"POLYGON((-97.9736 30.6251, -97.9188 30.6032, -97.9243 30.5703, -97.8695 30.5484, \\\n",
    "              -97.8476 30.4717, -97.7764 30.4279, -97.5793 30.4991, -97.3711 30.4170, \\\n",
    "              -97.4916 30.2089, -97.6505 30.0719, -97.6669 30.0665, -97.7107 30.0226, \\\n",
    "              -98.1708 30.3567, -98.1270 30.4279, -98.0503 30.6251, -97.9736 30.6251))\" \n",
    "request.intersects = Polygon.import_wkt(wkt=travis_wkt, epsg=4326)\n",
    "request.limit = 2\n",
    "for stac_item in client_ex.search_ex(request):\n",
    "    print(\"STAC item id: {0} from wkt filter intersects result from geojson filter: {1}\"\n",
    "          .format(stac_item.id, stac_item.id in geojson_ids))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Temporal Queries\n",
    "When it comes to Temporal queries there are a few things to note. \n",
    "\n",
    "- we assume all dates are UTC unless specified\n",
    "- datetime and date are treated differently in different situations\n",
    "  - date for EQ and NEQ is a 24 hour period\n",
    "  - datetime for EQ and NEQ is almost useless (it is a timestamp accurate down to the nanosecond)\n",
    "  - date for GTE or LT is defined as the date from the first nanosecond of that date\n",
    "  - date for LTE or GT is defined as the date at the final nanosecond of that date\n",
    "  - date for start and end with BETWEEN has a start with minimum time and an end with the max time. same for NOT_BETWEEN\n",
    "  - datetime for GTE, GT, LTE, LT, BETWEEN and NOT_BETWEEN is interpreted strictly according to the nanosecond of that\n",
    "  datetime definition(s) provided\n",
    "\n",
    "When creating a time query filter, we want to use the >, >=, <, <=, ==, != operations and inclusive and exclusive range\n",
    "requests. We do this by using the `set_observed` method and the `value` set to a date/datetime combined with `rel_typ`\n",
    "set to `GTE`,`GT`, `LTE`, `LT`, `EQ`, or `NEQ`. If we use `rel_type` set to `BETWEEN` OR `NOT_BETWEEN` then we must set\n",
    "the `start` **and** the `end` variables.\n",
    "\n",
    "### Everything After A Specific Date"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "STAC item date, 2021-02-07 20:29:00+00:00, is after 2019-08-21 00:00:00: True\n",
      "STAC item date, 2021-02-07 20:28:58+00:00, is after 2019-08-21 00:00:00: True\n"
     ]
    }
   ],
   "source": [
    "from datetime import date, datetime\n",
    "from nsl.stac.experimental import NSLClientEx, StacRequestWrap\n",
    "from nsl.stac import enum\n",
    "\n",
    "# get a client interface to the gRPC channel\n",
    "client_ex = NSLClientEx()\n",
    "\n",
    "request = StacRequestWrap()\n",
    "\n",
    "# make a filter that selects all data on or after August 21st, 2019\n",
    "request.set_observed(rel_type=enum.FilterRelationship.GTE, value=date(2019, 8, 21))\n",
    "request.limit = 2\n",
    "\n",
    "demonstration_datetime = datetime.combine(date(2019, 8, 21), datetime.min.time())\n",
    "\n",
    "for stac_item in client_ex.search_ex(request):\n",
    "    print(\"STAC item date, {0}, is after {1}: {2}\".format(\n",
    "        stac_item.observed,\n",
    "        demonstration_datetime,\n",
    "        datetime.timestamp(stac_item.observed) > datetime.timestamp(demonstration_datetime)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Everything Between Two Dates\n",
    "\n",
    "Now we're going to do a range request and select data between two dates using the `start` and `end` parameters instead\n",
    "of the `value` parameter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "STAC item date, 2019-08-06 20:42:53+00:00, is between 2019-08-01 00:00:00 and 2019-08-10 00:00:00\n",
      "STAC item date, 2019-08-06 20:42:51+00:00, is between 2019-08-01 00:00:00 and 2019-08-10 00:00:00\n"
     ]
    }
   ],
   "source": [
    "from datetime import datetime, timezone, timedelta\n",
    "from nsl.stac import enum\n",
    "\n",
    "# Query data from August 1, 2019\n",
    "start = datetime(2019, 8, 1, 0, 0, 0, tzinfo=timezone.utc)\n",
    "# ... up until August 10, 2019\n",
    "end = start + timedelta(days=9)\n",
    "\n",
    "request.set_observed(rel_type=enum.FilterRelationship.BETWEEN, start=start, end=end)\n",
    "request.limit = 2\n",
    "\n",
    "# get a client interface to the gRPC channel\n",
    "client_ex = NSLClientEx()\n",
    "\n",
    "for stac_item in client_ex.search_ex(request):\n",
    "    print(\"STAC item date, {0}, is between {1} and {2}\".format(\n",
    "        stac_item.observed,\n",
    "        datetime.combine(start, datetime.min.time()),\n",
    "        datetime.combine(end, datetime.min.time())))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the above print out we are returned STAC items that are between the dates of Aug 1 2019 and Aug 10 2019. Also, notice\n",
    "there's no warnings as we defined our utc timezone on the datetime objects.\n",
    "\n",
    "#### Select Data for One Day\n",
    "\n",
    "Now we'll search for everything on a specific day using a python `datetime.date` for the `value` and `rel_type` set to\n",
    "use equals (`FilterRelationship.EQ`). Python's `datetime.datetime` is a specific value and if you use it combined with\n",
    "`EQ` the query would insist that the time relationship match down to the second. But since `datetime.date` is only\n",
    "specific down to the day, the filter is created for the entire day. This will check for everything from the start until\n",
    "the end of the 8th of August, specifically in the Austin, Texas timezone (UTC -6)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2019-08-06 20:42:53+00:00\n",
      "2019-08-06 20:42:51+00:00\n"
     ]
    }
   ],
   "source": [
    "from datetime import datetime, timezone, timedelta, date\n",
    "from nsl.stac.experimental import NSLClientEx, StacItemWrap\n",
    "from nsl.stac import utils, enum\n",
    "\n",
    "request = StacRequestWrap()\n",
    "\n",
    "# Query all data for the entire day of August 6, 2019 (in TX time)\n",
    "texas_utc_offset = timezone(timedelta(hours=-6))\n",
    "request.set_observed(value=date(2019, 8, 6), rel_type=enum.FilterRelationship.EQ, tzinfo=texas_utc_offset)\n",
    "\n",
    "request.limit = 2\n",
    "\n",
    "# get a client interface to the gRPC channel\n",
    "client_ex = NSLClientEx()\n",
    "for stac_item in client_ex.search_ex(request):\n",
    "    print(datetime.fromtimestamp(stac_item.observed.timestamp(), tz=timezone.utc))"
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Query by GSD (ground sampling distance)\n",
    "\n",
    "Our sample imagery contains both 30cm (0.15-0.20m gsd) and 10cm (0.05m gsd) scenes. Here is a snippet below detailing how to\n",
    "filter by GSD."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "from itertools import islice\n",
    "\n",
    "from nsl.stac.experimental import NSLClientEx\n",
    "from nsl.stac import enum\n",
    "\n",
    "request = StacRequestWrap()\n",
    "\n",
    "# Query for all imagery whose GSD is less than 0.051 (to account for minor floating point variations)\n",
    "request.set_gsd(rel_type=enum.FilterRelationship.LTE, value=0.051)\n",
    "\n",
    "# Restrict search to areas of publicly available 10cm imagery in Austin, TX\n",
    "request.intersects = Polygon.import_wkt(epsg=4326, wkt='POLYGON((-97.7344436645508 30.326004681223694,'\n",
    "                                                       '-97.7344436645508 30.29517998555933,'\n",
    "                                                       '-97.73650360107423 30.28569351372147,'\n",
    "                                                       '-97.73616027832033 30.273834133861683,'\n",
    "                                                       '-97.71796417236328 30.274130635825372,'\n",
    "                                                       '-97.71796417236328 30.28539704669346,'\n",
    "                                                       '-97.68397521972658 30.293994226755345,'\n",
    "                                                       '-97.68466186523439 30.32630102546601,'\n",
    "                                                       '-97.7344436645508 30.326004681223694))')\n",
    "\n",
    "client_ex = NSLClientEx()\n",
    "\n",
    "# filter results by the first we can download with basic credentials\n",
    "items = islice(filter(lambda item: 'REGION_0' in item.get_asset(asset_type=enum.AssetType.GEOTIFF).href,\n",
    "                      client_ex.search_ex(request, auto_paginate=True)), 1)\n",
    "\n",
    "stac_item = next(items)\n",
    "print(stac_item.id)\n",
    "print(stac_item.gsd)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Downloading from AssetWrap"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "href: \"https://api.nearspacelabs.net/download/20190822T162258Z_TRAVIS_COUNTY/Published/REGION_0/20190822T183418Z_716_POM1_ST2_P.png\"\n",
      "type: \"image/png\"\n",
      "eo_bands: RGB\n",
      "asset_type: THUMBNAIL\n",
      "cloud_platform: GCP\n",
      "bucket_manager: \"Near Space Labs\"\n",
      "bucket_region: \"us-central1\"\n",
      "bucket: \"swiftera-processed-data\"\n",
      "object_path: \"20190822T162258Z_TRAVIS_COUNTY/Published/REGION_0/20190822T183418Z_716_POM1_ST2_P.png\"\n",
      "extension: .png\n",
      "asset_key: THUMBNAIL_RGB\n",
      "\n",
      "downloaded file 20190822T183418Z_716_POM1_ST2_P.png\n",
      "\n",
      "href: \"https://api.nearspacelabs.net/download/20190822T162258Z_TRAVIS_COUNTY/Published/REGION_0/20190822T183410Z_712_POM1_ST2_P.png\"\n",
      "type: \"image/png\"\n",
      "eo_bands: RGB\n",
      "asset_type: THUMBNAIL\n",
      "cloud_platform: GCP\n",
      "bucket_manager: \"Near Space Labs\"\n",
      "bucket_region: \"us-central1\"\n",
      "bucket: \"swiftera-processed-data\"\n",
      "object_path: \"20190822T162258Z_TRAVIS_COUNTY/Published/REGION_0/20190822T183410Z_712_POM1_ST2_P.png\"\n",
      "extension: .png\n",
      "asset_key: THUMBNAIL_RGB\n",
      "\n",
      "downloaded file 20190822T183410Z_712_POM1_ST2_P.png\n",
      "\n",
      "href: \"https://api.nearspacelabs.net/download/20190822T162258Z_TRAVIS_COUNTY/Published/REGION_0/20190822T183400Z_707_POM1_ST2_P.png\"\n",
      "type: \"image/png\"\n",
      "eo_bands: RGB\n",
      "asset_type: THUMBNAIL\n",
      "cloud_platform: GCP\n",
      "bucket_manager: \"Near Space Labs\"\n",
      "bucket_region: \"us-central1\"\n",
      "bucket: \"swiftera-processed-data\"\n",
      "object_path: \"20190822T162258Z_TRAVIS_COUNTY/Published/REGION_0/20190822T183400Z_707_POM1_ST2_P.png\"\n",
      "extension: .png\n",
      "asset_key: THUMBNAIL_RGB\n",
      "\n",
      "downloaded file 20190822T183400Z_707_POM1_ST2_P.png\n",
      "\n"
     ]
    }
   ],
   "source": [
    "import os\n",
    "import tempfile\n",
    "from IPython.display import Image, display\n",
    "\n",
    "from epl.geometry import LineString\n",
    "from nsl.stac.experimental import NSLClientEx, StacRequestWrap\n",
    "from nsl.stac import utils, enum\n",
    "\n",
    "request = StacRequestWrap()\n",
    "request.intersects = LineString.import_wkt(wkt='LINESTRING(622301.8284206488 3350344.236542711,'\n",
    "                                               '622973.3950196661 3350466.792693002)',\n",
    "                                           epsg=3744)\n",
    "request.set_observed(value=date(2019, 8, 25), rel_type=enum.FilterRelationship.LTE)\n",
    "request.limit = 3\n",
    "\n",
    "client_ex = NSLClientEx()\n",
    "\n",
    "stac_item = client_ex.search_one_ex(request)\n",
    "# get the thumbnail asset from the assets map\n",
    "asset_wrap = stac_item.get_asset(asset_type=enum.AssetType.THUMBNAIL)\n",
    "print(asset_wrap)\n",
    "\n",
    "# (side-note delete=False in NamedTemporaryFile is only required for windows.)\n",
    "with tempfile.NamedTemporaryFile(suffix=\".png\", delete=False) as file_obj:\n",
    "    asset_wrap.download(file_obj=file_obj)\n",
    "    print(\"downloaded file {}\".format(os.path.basename(asset_wrap.object_path)))\n",
    "    print()\n",
    "    # uncomment to display            \n",
    "    # display(Image(filename=file_obj.name))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## View\n",
    "For our ground sampling distance query we're using another query filter; this time it's the\n",
    "[FloatFilter](https://geo-grpc.github.io/api/#epl.protobuf.v1.FloatFilter). It behaves just as the TimestampFilter, but\n",
    "with floats for `value` or for `start` + `end`.\n",
    "\n",
    "In order to make our off nadir query we need to insert it inside of an\n",
    "[ViewRequest](https://geo-grpc.github.io/api/#epl.protobuf.v1.ViewRequest) container and set that to the `view` field of\n",
    "the `StacRequest`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "SWIFT STAC item '20190806T202221Z_9007_POM1_ST2_P' from 2019-08-06 20:22:21+00:00\n",
      "has a off_nadir\t34.28, which should be greater than or equal to requested off_nadir\t30.000 (confirmed True)\n",
      "has a gsd\t0.200, which should be less than the requested\t\t  gsd\t\t1.000 (confirmed False)\n",
      "SWIFT STAC item '20190806T202219Z_9006_POM1_ST2_P' from 2019-08-06 20:22:19+00:00\n",
      "has a off_nadir\t34.51, which should be greater than or equal to requested off_nadir\t30.000 (confirmed True)\n",
      "has a gsd\t0.200, which should be less than the requested\t\t  gsd\t\t1.000 (confirmed False)\n",
      "SWIFT STAC item '20190806T202153Z_8993_POM1_ST2_P' from 2019-08-06 20:21:53+00:00\n",
      "has a off_nadir\t32.85, which should be greater than or equal to requested off_nadir\t30.000 (confirmed True)\n",
      "has a gsd\t0.200, which should be less than the requested\t\t  gsd\t\t1.000 (confirmed False)\n",
      "SWIFT STAC item '20190806T202151Z_8992_POM1_ST2_P' from 2019-08-06 20:21:51+00:00\n",
      "has a off_nadir\t33.23, which should be greater than or equal to requested off_nadir\t30.000 (confirmed True)\n",
      "has a gsd\t0.200, which should be less than the requested\t\t  gsd\t\t1.000 (confirmed False)\n"
     ]
    }
   ],
   "source": [
    "from datetime import datetime, timezone\n",
    "from epl.geometry import Point\n",
    "from nsl.stac.experimental import NSLClientEx, StacRequestWrap\n",
    "from nsl.stac.enum import FilterRelationship, Mission\n",
    "\n",
    "request = StacRequestWrap()\n",
    "\n",
    "# create our off_nadir query to only return data captured with an angle of less than or \n",
    "# equal to 10 degrees\n",
    "request.set_off_nadir(rel_type=FilterRelationship.GTE, value=30.0)\n",
    "\n",
    "request.set_gsd(rel_type=FilterRelationship.LT, value=1.0)\n",
    "\n",
    "# define ourselves a point in Texas\n",
    "request.intersects = Point.import_wkt(\"POINT(621920.1090935947 3350833.389847579)\", epsg=26914)\n",
    "# the above could also be defined using longitude and latitude as follows:\n",
    "# request.intersects = Point.import_wkt(\"POINT(-97.7323317 30.2830764)\", epsg=4326)\n",
    "\n",
    "# create a StacRequest with geometry, gsd, and off nadir and a limit of 4\n",
    "request.limit = 4\n",
    "\n",
    "# get a client interface to the gRPC channel\n",
    "client_ex = NSLClientEx()\n",
    "for stac_item in client_ex.search_ex(request):\n",
    "    print(\"{0} STAC item '{1}' from {2}\\nhas a off_nadir\\t{3:.2f}, which should be greater than or \"\n",
    "          \"equal to requested off_nadir\\t{4:.3f} (confirmed {5})\".format(\n",
    "        stac_item.mission.name,\n",
    "        stac_item.id,\n",
    "        stac_item.observed,\n",
    "        stac_item.off_nadir,\n",
    "        request.stac_request.view.off_nadir.value,\n",
    "        request.stac_request.view.off_nadir.value < stac_item.off_nadir))\n",
    "    print(\"has a gsd\\t{0:.3f}, which should be less than \"\n",
    "          \"the requested\\t\\t  gsd\\t\\t{1:.3f} (confirmed {2})\".format(\n",
    "        stac_item.gsd,              \n",
    "        request.stac_request.gsd.value,\n",
    "        request.stac_request.gsd.value < stac_item.gsd))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Shapely Geometry\n",
    "\n",
    "Both `StacItemWrap` and `StacRequestWrap` support `shapely` geometries by default, and can be used in place of\n",
    "`epl.geometry` types."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "POLYGON ((-97.73904613302376 30.28558379365554, -97.7391983503974 30.2875173500651, -97.72321588821087 30.28827923391159, -97.72318191531373 30.28782344215122, -97.71713732528039 30.28831646331542, -97.71693109816546 30.28666272574028, -97.70874633971988 30.28734610398103, -97.70818071127752 30.28287053252838, -97.70808905472636 30.28287930690277, -97.70677365314802 30.27386748307901, -97.7170478085542 30.27277749017812, -97.71706056512183 30.27243547076341, -97.71909405701686 30.27256040213442, -97.7213917618061 30.27231663689927, -97.7211668184693 30.27047840774788, -97.73716286590115 30.26897383853585, -97.73753540641121 30.27221456038255, -97.74030883925472 30.27238987412984, -97.7401564450095 30.27643992828877, -97.74061099516257 30.27646759248412, -97.74006387853352 30.28564189160005, -97.73904613302376 30.28558379365554))\n"
     ]
    }
   ],
   "source": [
    "from shapely.wkt import loads as loads_wkt\n",
    "\n",
    "from nsl.stac.experimental import NSLClientEx, StacRequestWrap\n",
    "from nsl.stac import utils, enum\n",
    "\n",
    "request = StacRequestWrap()\n",
    "\n",
    "request.intersects = loads_wkt('LINESTRING(-97.72842049283962 30.278624772098176,'\n",
    "                               '-97.72142529172878 30.2796624743974)')\n",
    "\n",
    "request.set_observed(value=date(2019, 8, 20), rel_type=enum.FilterRelationship.LTE)\n",
    "request.limit = 10\n",
    "\n",
    "client_ex = NSLClientEx()\n",
    "\n",
    "unioned = None\n",
    "for stac_item in client_ex.search_ex(request):\n",
    "    if unioned is None:\n",
    "        unioned = stac_item.geometry\n",
    "    else:\n",
    "        # execute shapely union\n",
    "        unioned = unioned.union(stac_item.geometry)\n",
    "\n",
    "print(unioned)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Enum Classes\n",
    "There are a number of different enum classes used for both STAC requests and STAC items."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('AssetType', <enum 'AssetType'>),\n",
       " ('Band', <enum 'Band'>),\n",
       " ('CloudPlatform', <enum 'CloudPlatform'>),\n",
       " ('Constellation', <enum 'Constellation'>),\n",
       " ('FilterRelationship', <enum 'FilterRelationship'>),\n",
       " ('Instrument', <enum 'Instrument'>),\n",
       " ('Mission', <enum 'Mission'>),\n",
       " ('Platform', <enum 'Platform'>),\n",
       " ('SortDirection', <enum 'SortDirection'>)]"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from nsl.stac import enum\n",
    "import inspect\n",
    "[m for m in inspect.getmembers(enum) if not m[0].startswith('_') and m[0][0].isupper() and m[0] != 'IntFlag']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "for defining the sort direction of a query\n",
      "NOT_SORTED\n",
      "DESC\n",
      "ASC\n",
      "for defining the query relationship with a value (EQ, LTE, GTE, LT, GT, NEQ), a start-end range \n",
      "(BETWEEN, NOT_BETWEEN), a set (IN, NOT_IN) or a string (LIKE, NOT_LIKE). To be noted, EQ is the default relationship type\n",
      "EQ\n",
      "LTE\n",
      "GTE\n",
      "LT\n",
      "GT\n",
      "BETWEEN\n",
      "NOT_BETWEEN\n",
      "NEQ\n",
      "IN\n",
      "NOT_IN\n",
      "LIKE\n",
      "NOT_LIKE\n"
     ]
    }
   ],
   "source": [
    "# Specific to Queries\n",
    "print(\"for defining the sort direction of a query\")\n",
    "for s in enum.SortDirection:\n",
    "    print(s.name)\n",
    "print(\"for defining the query relationship with a value (EQ, LTE, GTE, LT, GT, NEQ), a start-end range \\n\"\n",
    "      \"(BETWEEN, NOT_BETWEEN), a set (IN, NOT_IN) or a string (LIKE, NOT_LIKE). \"\n",
    "      \"NOTE: EQ is the default relationship type\")\n",
    "for f in enum.FilterRelationship:\n",
    "    print(f.name)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "these can be useful when getting a specific Asset from a STAC item by the type of Asset\n",
      "UNKNOWN_ASSET\n",
      "JPEG\n",
      "GEOTIFF\n",
      "LERC\n",
      "MRF\n",
      "MRF_IDX\n",
      "MRF_XML\n",
      "CO_GEOTIFF\n",
      "RAW\n",
      "THUMBNAIL\n",
      "TIFF\n",
      "JPEG_2000\n",
      "XML\n",
      "TXT\n",
      "PNG\n",
      "OVERVIEW\n",
      "JSON\n",
      "HTML\n",
      "WEBP\n"
     ]
    }
   ],
   "source": [
    "# Specific to Assets\n",
    "print(\"these can be useful when getting a specific Asset from a STAC item by the type of Asset\")\n",
    "for a in enum.AssetType:\n",
    "    print(a.name)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Mission, Platform and Instrument are aspects of data that can be used in queries.\n",
      "But as NSL currently only has one platform and one instrument, these may not be useful\n",
      "missions:\n",
      "UNKNOWN_MISSION\n",
      "LANDSAT\n",
      "NAIP\n",
      "SWIFT\n",
      "PNOA\n",
      "\n",
      "platforms:\n",
      "UNKNOWN_PLATFORM\n",
      "LANDSAT_1\n",
      "LANDSAT_2\n",
      "LANDSAT_3\n",
      "LANDSAT_123\n",
      "LANDSAT_4\n",
      "LANDSAT_5\n",
      "LANDSAT_45\n",
      "LANDSAT_7\n",
      "LANDSAT_8\n",
      "SWIFT_2\n",
      "\n",
      "instruments:\n",
      "UNKNOWN_INSTRUMENT\n",
      "OLI\n",
      "TIRS\n",
      "OLI_TIRS\n",
      "POM_1\n",
      "TM\n",
      "ETM\n",
      "MSS\n",
      "POM_2\n"
     ]
    }
   ],
   "source": [
    "# STAC Item details\n",
    "print(\"Mission, Platform and Instrument are aspects of data that can be used in queries.\\n\"\n",
    "      \"But as NSL currently only has one platform and one instrument, these may not be useful\")\n",
    "print(\"missions:\")\n",
    "for a in enum.Mission:\n",
    "    print(a.name)\n",
    "print(\"\\nplatforms:\")\n",
    "for a in enum.Platform:\n",
    "    print(a.name)\n",
    "print(\"\\ninstruments:\")\n",
    "for a in enum.Instrument:\n",
    "    print(a.name)"
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Subscriptions and Data Delivery\n",
    "This feature is useful if you want to be subscribed to a `StacRequest`, receiving published assets to a cloud bucket.\n",
    "\n",
    "### Cloud Accounts\n",
    "\n",
    "    - AWS id: `275780812376`\n",
    "    - GCP email: `thirdparty-bucket-access@swiftera-processed-data.iam.gserviceaccount.com`\n",
    "\n",
    "### Example\n",
    "\n",
    "Set up for the destination bucket is slightly different between AWS and GCP, so we'll review both.\n",
    "\n",
    "Assume that we have an upcoming flight covering Austin, TX and you'd like only some STAC items to be copied to your \n",
    "bucket as they're published:"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "from datetime import datetime, timezone\n",
    "\n",
    "from nsl.stac import enum\n",
    "from nsl.stac.destinations import AWSDestination, GCPDestination\n",
    "from nsl.stac.experimental import StacRequestWrap, NSLClientEx\n",
    "\n",
    "# get a client interface to the gRPC channel\n",
    "client_ex = NSLClientEx()\n",
    "\n",
    "# create a new request\n",
    "request = StacRequestWrap()\n",
    "# a polygon containing two University of Texas at Austin stadiums\n",
    "request.intersects = Polygon.import_wkt('POLYGON((-97.73521184921263 30.28551192777313,'\n",
    "                                        '-97.73522257804868 30.279369307168608,'\n",
    "                                        '-97.72501945495603 30.279313716086122,'\n",
    "                                        '-97.7251052856445 30.285530456966953,'\n",
    "                                        '-97.73521184921263 30.28551192777313))',\n",
    "                                        epsg=4326)\n",
    "# we only want images delivered after the flight was conducted\n",
    "request.set_observed(rel_type=enum.FilterRelationship.GTE, value=datetime(2021, 11, 1, tzinfo=timezone.utc))"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### GCP Delivery\n",
    "\n",
    "The destination bucket preparation process for GCP is fairly simple:\n",
    "\n",
    "1. Create a GCP Role with only `storage.objectAdmin` permissions for your bucket (e.g. `my-bucket`).\n",
    "\n",
    "2. Assign the newly created role (e.g. `NSLSubscription`) to our GCP service account,\n",
    "`thirdparty-bucket-access@swiftera-processed-data.iam.gserviceaccount.com`. This can be done from the terminal, e.g.:\n",
    "\n",
    "```bash\n",
    "$ gsutil iam ch \\\n",
    "    serviceAccount:thirdparty-bucket-access@swiftera-processed-data.iam.gserviceaccount.com:roles/storage.objectAdmin \\\n",
    "    gs://my-bucket\n",
    "```\n",
    "\n",
    "Finally, lets create a `BaseDestination` object and finish creating our subscription:"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "# creates a destination object to describe how assets should be delivered\n",
    "dst = GCPDestination(asset_type=enum.AssetType.GEOTIFF, # GEOTIFF by default, can also be THUMBNAIL\n",
    "                     bucket='my-bucket',                # the name of your bucket\n",
    "                     region='us-central1',              # region your bucket is located in\n",
    "                     save_directory='/')                # directory in which assets will be copied, <stac_id>.<file_ext>\n",
    "\n",
    "# create the subscription, returning its id\n",
    "sub_id = client_ex.subscribe_ex(request, destination=dst)\n",
    "print(sub_id)\n",
    "\n",
    "# retrieve all of your current subscriptions, viewing the most recent\n",
    "subs = client_ex.subscriptions_ex()\n",
    "most_recent_sub = subs[len(subs) - 1]\n",
    "print(most_recent_sub)\n",
    "\n",
    "# deactivate a subscription, pausing all deliveries\n",
    "client_ex.unsubscribe_ex(sub_id=sub_id)\n",
    "\n",
    "# reactivate a subscription, resuming all deliveries\n",
    "client_ex.resubscribe_ex(sub_id=sub_id)\n"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### AWS Delivery\n",
    "\n",
    "The destination bucket preparation process for AWS is slightly more involved. We're ultimately going to create an AWS\n",
    "IAM Role (e.g. `NSLDelivery`) to be assumed by NSL's AWS account,\n",
    "and an accompanying policy giving NSL's AWS account access to the destination bucket (e.g. `my-bucket`).\n",
    "  \n",
    "1. In your AWS account where the bucket is located, browse to IAM service.\n",
    "  \n",
    "2. Choose Roles -> \"Create role\". Choose \"Another AWS account\", providing NSL's AWS account ID: `275780812376`.\n",
    "  \n",
    "3. Click next to Permissions\n",
    "  \n",
    "4. Click \"Create Policy\", select the tab \"JSON\" and adjust the template below, which will whitelist actions NSL can\n",
    "perform on your chosen destination bucket.\n",
    "```\n",
    "{\n",
    "  \"Version\": \"2012-10-17\",\n",
    "  \"Statement\": [\n",
    "    {\n",
    "      \"Sid\": \"VisualEditor0\",\n",
    "      \"Effect\": \"Allow\",\n",
    "      \"Action\": \"s3:ListBucket\",\n",
    "      \"Resource\": \"arn:aws:s3:::my-bucket\"\n",
    "    },\n",
    "    {\n",
    "      \"Sid\": \"VisualEditor1\",\n",
    "      \"Effect\": \"Allow\",\n",
    "      \"Action\": [\n",
    "        \"s3:PutObject\",\n",
    "        \"s3:GetObject\",\n",
    "        \"s3:DeleteObject\"\n",
    "      ],\n",
    "      \"Resource\": \"arn:aws:s3:::my-bucket/*\"\n",
    "    }\n",
    "  ]\n",
    "}\n",
    "```\n",
    "  \n",
    "5. Click \"Next: Tags\", adding any optional tags.\n",
    "  \n",
    "6. Name this policy (e.g. `NSLBucketAccess`), and finally click \"Create policy\" to finish creating the policy.\n",
    "  \n",
    "7. Go back to Roles, refresh, and then select the `NSLBucketAccess` policy you just created.\n",
    "  \n",
    "8. Now we're back to finalizing the creation of the Role, so give it a meaningful name, e.g. `NSLBucketDeliverer`.\n",
    "\n",
    "9. Contact us so we can update our AWS account to assume this role and begin deliveries. \n",
    "\n",
    "Finally, lets create a `BaseDestination` object and finish creating our subscription:"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "# creates a destination object to describe how assets should be delivered\n",
    "dst = AWSDestination(asset_type=enum.AssetType.GEOTIFF, # GEOTIFF by default, can also be THUMBNAIL\n",
    "                     role_arn='arn:aws:iam::<YOUR_ACCESS_KEY_ID>:role/NSLBucketDeliverer',\n",
    "                     bucket='my-bucket',                # the name of your bucket\n",
    "                     region='us-central1',              # region your bucket is located in\n",
    "                     save_directory='/')                # directory in which assets will be copied, <stac_id>.<file_ext>\n",
    "\n",
    "# create the subscription, returning its id\n",
    "sub_id = client_ex.subscribe_ex(request, destination=dst)\n",
    "print(sub_id)\n",
    "\n",
    "# retrieve all of your current subscriptions, viewing the most recent\n",
    "subs = client_ex.subscriptions_ex()\n",
    "most_recent_sub = subs[len(subs) - 1]\n",
    "print(most_recent_sub)\n",
    "\n",
    "# deactivate a subscription, pausing all deliveries\n",
    "client_ex.unsubscribe_ex(sub_id=sub_id)\n",
    "\n",
    "# reactivate a subscription, resuming all deliveries\n",
    "client_ex.resubscribe_ex(sub_id=sub_id)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.2"
  },
  "pycharm": {
   "stem_cell": {
    "cell_type": "raw",
    "source": [],
    "metadata": {
     "collapsed": false
    }
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}