Added explanatory text around code cells

jakirkham · Sep 8, 2016 · e02d75e · e02d75e
1 parent cdc665d
commit e02d75e
Showing 1 changed file with 53 additions and 27 deletions.
diff --git a/examples/landsat.ipynb b/examples/landsat.ipynb
@@ -4,15 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Datashader: Custom Transfer Functions for LandSat8"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Setup\n",
-    "The following imports will be needed to complete the exercises or provide for an improved notebook display:"
+    "# Datashading LandSat8 raster satellite imagery\n",
+    "\n",
+    "Datashader is fundamentally a rasterizing library, turning data into rasters (image-like arrays), but it is also useful for already-rasterized data like satellite imagery.  For raster data, datashader uses the separate [rasterio](https://mapbox.github.io/rasterio) library to re-render the data to whatever new bounding box and resolution the user requests, and the rest of the datashader pipeline can then be used to visualize and analyze the data.  This demo shows how to work with a set of raster satellite data, generating images as needed and overlaying them on geographic coordinates."
    ]
   },
   {
@@ -45,22 +39,26 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Load Landsat Data \n",
+    "### Load LandSat Data \n",
     "\n",
-    "Bands\tWavelength\n",
-    "(micrometers)\tResolution\n",
-    "(meters)\n",
-    "- Band 1 - Coastal aerosol\t0.43 - 0.45\t30\n",
-    "- Band 2 - Blue\t0.45 - 0.51\t30\n",
-    "- Band 3 - Green\t0.53 - 0.59\t30\n",
-    "- Band 4 - Red\t0.64 - 0.67\t30\n",
-    "- Band 5 - Near Infrared (NIR)\t0.85 - 0.88\t30\n",
-    "- Band 6 - SWIR 1\t1.57 - 1.65\t30\n",
-    "- Band 7 - SWIR 2\t2.11 - 2.29\t30\n",
-    "- Band 8 - Panchromatic\t0.50 - 0.68\t15\n",
-    "- Band 9 - Cirrus\t1.36 - 1.38\t30\n",
-    "- Band 10 - Thermal Infrared (TIRS) 1\t10.60 - 11.19\t100 * (30)\n",
-    "- Band 11 - Thermal Infrared (TIRS) 2\t11.50 - 12.51\t100 * (30)"
+    "LandSat data is measured in different frequency bands, revealing different types of information:\n",
+    "\n",
+    "```\n",
+    "Band      Wavelength     Resolution   Description\n",
+    "          (micrometers)  (meters)\n",
+    "\n",
+    "Band 1     0.43 - 0.45     30         Coastal aerosol\n",
+    "Band 2     0.45 - 0.51     30         Blue\n",
+    "Band 3     0.53 - 0.59     30         Green\n",
+    "Band 4     0.64 - 0.67     30         Red\n",
+    "Band 5     0.85 - 0.88     30         Near Infrared (NIR)\n",
+    "Band 6     1.57 - 1.65     30         SWIR 1\n",
+    "Band 7     2.11 - 2.29     30         SWIR 2\n",
+    "Band 8     0.50 - 0.68     15         Panchromatic\n",
+    "Band 9     1.36 - 1.38     30         Cirrus\n",
+    "Band 10   10.60 - 11.19   100 * (30)  Thermal Infrared (TIRS) 1\n",
+    "Band 11   11.50 - 12.51   100 * (30)  Thermal Infrared (TIRS) 2\n",
+    "```"
    ]
   },
   {
@@ -100,7 +98,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Datashader Transfer Functions"
+    "### Define geographic plot\n",
+    "\n",
+    "We'll plot this data using Bokeh, overlaying it on map tiles for context:"
    ]
   },
   {
@@ -130,7 +130,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Just the Blue Band"
+    "## Rendering LandSat data as images\n",
+    "\n",
+    "The bands measured by LandSat include wavelengths covering the visible spectrum, but also other ranges, and so it's possible to visualize this data in many different ways, in both true color (using the visible spectrum directly) or false color (usually showing other bands).  Some examples are shown in the sections below.\n",
+    "\n",
+    "### Just the Blue Band\n",
+    "\n",
+    "Using datashader's default histogram-equalized colormapping, the full range of data is visible in the plot:"
    ]
   },
   {
@@ -152,6 +158,15 @@
     "InteractiveImage(p, update_image)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You will usually want to zoom in, which will re-rasterize the image if you are in a live notebook, and then re-equalize the colormap to show all the detail available.  If you are on a static copy of the notebook, only the original resolution at which the image was rendered will be available, but zooming will still update the map tiles to whatever resolution is requested.\n",
+    "\n",
+    "The plots below use a different type of colormap processing, implemented as a custom transfer function:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -203,7 +218,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### True Color (Red=Red, Green=Green, Blue=Blue)"
+    "### True Color (Red=Red, Green=Green, Blue=Blue)\n",
+    "\n",
+    "Mapping the Red, Green, and Blue bands to the R, G, and B channels of an image reconstructs the image as it would appear to an ordinary camera from that viewpoint:"
    ]
   },
   {
@@ -227,6 +244,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "Other combinations highlight particular features of interest based on the different spectral properties of reflectances from various objects and surfaces:\n",
+    "\n",
     "### Color Infrared (Vegetation) (Red=Near Infrared, Green=Red, Blue=Green)"
    ]
   },
@@ -344,6 +363,13 @@
     "p = base_plot(x_range=(xmin, xmax), y_range=(ymin, ymax))\n",
     "InteractiveImage(p, shortwave_infrared)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "All the various ways of combining aggregates supported by [xarray](http://xarray.pydata.org) are available for these channels, making it simple to make your own custom visualizations highlighting any combination of bands that reveal something of interest."
+   ]
   }
  ],
  "metadata": {