Adding masked image plotting

Visualization/AFW_Display_Demo.ipynb

@@ -25,7 +25,7 @@
     "\n",
     "This tutorial is designed to help users get a brief feel for the `lsst.afw.display` library that enables the visual inspection of data. The [`lsst.afw` library](https://github.com/lsst/afw) provides an \"Astronomical Framework\" (afw) while the `lsst.daf.*` libraries (see, e.g., [daf_base](https://github.com/lsst/daf_base)) provides a Data Access Framework (daf). Both libraries are used in this tutorial, with the `lsst.daf.persistence` library used to access a calibrated exposure (calexp) and the `lsst.afw.display` library used to show the exposure image on the screen.\n",
     "\n",
-    "This tutorial made use of the [`LowSurfaceBrightness.ipynb` StackClub notebook](https://nbviewer.jupyter.org/github/LSSTScienceCollaborations/StackClub/blob/rendered/SourceDetection/LowSurfaceBrightness.nbconvert.ipynb) by [Alex Drlica-Wagner](https://github.com/LSSTScienceCollaborations/StackClub/issues/new?body=@kadrlica)."
+    "This tutorial made use of the [`LowSurfaceBrightness.ipynb` StackClub notebook](https://nbviewer.jupyter.org/github/LSSTScienceCollaborations/StackClub/blob/rendered/SourceDetection/LowSurfaceBrightness.nbconvert.ipynb) by [Alex Drlica-Wagner](https://github.com/LSSTScienceCollaborations/StackClub/issues/new?body=@kadrlica). More examples of the use of `lsst.afw.display` can be found in the [Stack ](https://pipelines.lsst.io/getting-started/display.html)."
    ]
   },
   {
@@ -167,7 +167,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "With the `Butler` instance now generated using our data directory, we can retrieve the desired calibrated exposure by telling the butler which filter, raft, sensor, and visit we wish to view. To do this, we definie dictionary with the required information."
+    "With the `Butler` instance now generated using our data directory, we can retrieve the desired calibrated exposure by telling the butler which filter, raft, sensor, and visit we wish to view. To do this, we define dictionary with the required information."
    ]
   },
   {
@@ -185,7 +185,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## **Step 3) Use AFWDisplay to Visualize the Image**\n",
+    "## **Step 3.1) Use AFWDisplay to Visualize the Image**\n",
     "\n",
     "Now, with a `Butler` instance defined and a calibrated exposure retrieved, we can use [`lsst.afw.display`](https://github.com/lsst/afw/tree/master/python/lsst/afw/display) to visualize the data.  The next task is to let AFWDisplay know that we want it to enroll `matplotlib` as our default display backend. To do this, we use the `setDefaultBackend()` function. Remember that we made an alias to `lsst.afw.display` called `afwDisplay`, so we'll use that to call `setDefaultBackend()`."
    ]
@@ -233,6 +233,59 @@
     "**Congrats!** We've plotted an image using `lsst.afw.display`!"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## **Step 3.2) Use AFWDisplay to Visualize the Image and Mask Plane**\n",
+    "\n",
+    "The `calexp` returned by the butler contains more than just the image pixel values (see the [calexp tutorial](https://github.com/LSSTScienceCollaborations/StackClub/blob/master/Basics/Calexp_guided_tour.ipynb) for more details). One other component is the mask plane associated with the image. `AFWDisplay` provides a nice pre-packaged interface for overplotting the mask associated with an image. A mask is composed of a set of \"mask planes\", 2D binary bit maps corresponding to pixels that are masked for various reasons (see [here](https://pipelines.lsst.io/v/DM-11392/getting-started/display.html#interpreting-displayed-mask-colors) for more details)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We'll follow the same steps as above to display the image, but we'll add a few modifications\n",
+    "\n",
+    "* We explicitly set the transparency of the overplotted mask (0 = transparent, 1 = opaque)\n",
+    "* We explicitly set the color of the 'DETECTED' mask plane to 'blue' (i.e. all pixels associated with detected objects).\n",
+    "* We pass the full `calexp` object to `mtv` instead of just the image plane."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plt.figure()                                     #create a matplotlib.pyplot figure\n",
+    "afw_display = afwDisplay.Display()               #get an alias to the lsst.afw.display.Display() method\n",
+    "afw_display.scale('asinh', 'zscale')             #set the image stretch algorithm and range\n",
+    "afw_display.setMaskTransparency(0.4)             #set the transparency of the mask plane (1 = opaque)\n",
+    "afw_display.setMaskPlaneColor('DETECTED','blue') #set the color for a single plane in the mask\n",
+    "afw_display.mtv(calexp)                          #load the image and mask plane into the display\n",
+    "plt.show()                                       #show the corresponding pyplot figure"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `afw_display` object contains more information about the mask planes that can be accessed"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(\"Mask plane bit definitions:\\n\", afw_display.getMaskPlaneColor())  # Print the colors associated to each plane in the mask\n",
+    "print(\"\\nMask plane methods:\\n\")\n",
+    "help(afw_display.setMaskPlaneColor)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},