storage-describe.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# max-ard storage describe\n",
    "\n",
    "Usage: `max-ard storage describe LOCATION`\n",
    "\n",
    "Returns info about ARD tiles store in LOCATION. Location can be S3 or local. Currently only gives a basic overview of contents.\n",
    "\n",
    "`--format` Output format, \"qlr\" for QGIS Layer Definition<br/>\n",
    "`--aoi` Geometry to filter tiles to, only WKT supported.<br/>\n",
    "`--cat_id` Limit result to this Catalog ID (can use more than once)<br/>\n",
    "`--zone` Limit tiles to those in this zone. Can be used multiple times. This option can speed up scan time of large collections.<br/>\n",
    "`--earliest_date` Return results from on or after this date (YYYY-MM-DD)<br/>\n",
    "`--latest_date` Return results from this date or earlier (YYYY-MM-DD)\n",
    "\n",
    "The following example uses sample ARD data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Examining ARD data in s3://maxar-ard-samples/sample-001/...\n",
      "3 acquisitions\n",
      "6 tiles\n",
      "Earliest date: 2016-02-21\n",
      "Latest date: 2019-07-12\n",
      "UTM zone: 10\n"
     ]
    }
   ],
   "source": [
    "!max-ard storage describe --public s3://maxar-ard-samples/sample-001/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "Examining ARD data in s3://maxar-ard-samples/sample-001/...\n",
    "3 acquisitions\n",
    "6 tiles\n",
    "Earliest date: 2016-02-21\n",
    "Latest date: 2019-07-12\n",
    "UTM zone: 10\n",
    "```\n",
    "\n",
    "To filter dates, use the `--earliest_date` and/or `--latest_date` options, like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Examining ARD data in s3://maxar-ard-samples/sample-001/...\n",
      "1 acquisition\n",
      "2 tiles\n",
      "Earliest date: 2019-05-21\n",
      "Latest date: 2019-05-21\n",
      "UTM zone: 10\n"
     ]
    }
   ],
   "source": [
    "!max-ard storage describe --public --earliest_date 2019-03-01 --latest_date 2019-06-01 s3://maxar-ard-samples/sample-001/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "Examining ARD data in s3://maxar-ard-samples/sample-001/...\n",
    "1 acquisition\n",
    "2 tiles\n",
    "Earliest date: 2019-05-21\n",
    "Latest date: 2019-05-21\n",
    "UTM zone: 10\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(In the example below we remove the date filters.) \n",
    "\n",
    "To generate a QGIS layer definition of the files stored in S3, add `--format qlr` and send the output to the file of choice:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "try:\n",
    "    os.mkdir('./outputs')\n",
    "except:\n",
    "    pass\n",
    "\n",
    "!max-ard storage describe --public s3://maxar-ard-samples/sample-001/ --format qlr > outputs/san_francisco.qlr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will create a QGIS layer for every acquisition, with subdirectories for each grid cell, which has layers for the visual ARD tile, cloud mask polygons, and STAC metadata feature.\n",
    "\n",
    "![assets/layer-tree.png](assets/layer-tree.png)\n",
    "\n",
    "The layers are linked directly to the source files. If they are in S3 they will read directly from the cloud.\n",
    "\n",
    "*(Note: QGIS layers files with large amounts of tiles can be slow to generate and even slower to open in QGIS. You may want to limit the number of layers generated using an AOI or date range.)*\n",
    "\n",
    "**Click [here](outputs/san_francisco.qlr) to download the example output.**\n",
    "\n",
    "Now open QGIS and, as shown in the image below, navigate to the `Layer` menu and click on `Add from Layer Definition File...`.\n",
    "\n",
    "![assets/qgis-add-from-layer-defn-file.png](assets/qgis-add-from-layer-defn-file.png)\n",
    "\n",
    "This will open a file browser; navigate to your `Downloads` folder, click on `san_francisco.qlr`, and click `Open`. Don't worry if the layers take a while to load; this is normal.\n",
    "\n",
    "Now the example QGIS layers should show up in your `Layers` panel (see image below). They will be unchecked when you bring them in, so nothing will show up on your map canvas until you check one or more groups. Click on the little arrows on the left of each group to expand it and check/uncheck the layers inside.\n",
    "\n",
    "![assets/unchecked-layers.png](assets/unchecked-layers.png)\n",
    "\n",
    "If you still don't see anything after clicking a checkbox, your map canvas may not be centered on the right location. Right-click on a layer or group and click `Zoom to Group` or `Zoom to Layer`, as shown below.\n",
    "\n",
    "![assets/zoom-to-group.png](assets/zoom-to-group.png)\n",
    "\n",
    "If you check all the groups and the layers within them, you should see something like this on your map canvas:\n",
    "\n",
    "![assets/final-map.png](assets/final-map.png)\n"
   ]
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "7275032a1130b57b8c00988b1ab7359517d973d1345a9c974619b2f0c186240c"
  },
  "kernelspec": {
   "display_name": "Python 3.9.5 64-bit ('test-env': pyenv)",
   "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.5"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}