astrowidgets.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "1d41cbd6-0226-48fc-83e8-dc0727cbbc65",
   "metadata": {},
   "source": [
    "<img align=\"left\" src = https://project.lsst.org/sites/default/files/Rubin-O-Logo_0.png width=170 style=\"padding: 10px\"> \n",
    "<b>Little Demo: Astrowidgets</b> <br>\n",
    "Contact author(s): Melissa Graham <br>\n",
    "Last verified to run: 2024-06-27 <br>\n",
    "LSST Science Pipelines version: Weekly 2024_16 <br>\n",
    "Container Size: medium"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1fc1e5d7-daa6-487b-8d95-ebf5baab5ec6",
   "metadata": {},
   "source": [
    "**Credit:** This little demo is essentially the same as the astrowidgets demo by Chris Waters that is available in the [astrowidgets repository](https://github.com/lsst/display_astrowidgets/tree/main).\n",
    "\n",
    "## 1. Set up"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "795121d9-388b-470f-be58-becfe797d2ab",
   "metadata": {},
   "outputs": [],
   "source": [
    "import lsst.afw.display as afwDisplay\n",
    "import lsst.display.astrowidgets\n",
    "from lsst.daf.butler import Butler"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2dbb124c-baf4-4009-850f-52bc85bf96dd",
   "metadata": {},
   "outputs": [],
   "source": [
    "lsst.afw.display.setDefaultBackend(\"astrowidgets\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0095bd80-510e-424a-ad76-a4e2fb321cf8",
   "metadata": {},
   "source": [
    "### 1.1. Retrieve an image"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "522e1a85-eb61-47fc-8c71-7477b5d2d7d3",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataId = {'visit': 192350, 'detector': 175}\n",
    "butler = Butler('dp02', collections='2.2i/runs/DP0.2')\n",
    "calexp = butler.get('calexp', **dataId)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "963ad627-70bc-4d91-b609-110a03d2d66d",
   "metadata": {},
   "source": [
    "## 2. Astrowidgets display\n",
    "\n",
    "Create the display.\n",
    "Use dimensions of 800 by 600 in screen pixels."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5cbf0308-963e-43c0-b49a-94b69a3a3e99",
   "metadata": {},
   "outputs": [],
   "source": [
    "display = lsst.afw.display.Display(dims=(800, 600))\n",
    "display.embed()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1d7e23de-9deb-4e49-bd06-953ce8062008",
   "metadata": {},
   "source": [
    "Display the `calexp.image`. If just `calexp` is used below, the mask data will be visualized."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e1f0be44-19d0-4c98-a391-91898d73cd00",
   "metadata": {},
   "outputs": [],
   "source": [
    "display.mtv(calexp.image)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "192a936d-ab4f-4197-8a74-4d4da3d0fd72",
   "metadata": {},
   "source": [
    "## 3. Keyboard shortcuts\n",
    "\n",
    "Astrowidgets is built with [ginga](https://ginga.readthedocs.io/en/stable/), which \n",
    "supplies interactive keyboard commands.\n",
    "More details are available in [the ginga quick references](https://ginga.readthedocs.io/en/stable/quickref.html).\n",
    "\n",
    "With the mouse, left-click-and-drag will change the contrast (scaling).\n",
    "\n",
    "This set of shortcuts is always active.\n",
    "    \n",
    "| Key | Action |\n",
    "|:----|:----------------------------------------------|\n",
    "|  \\` | Recenter and zoom to fit. |\n",
    "|{1-0}| Zoom to #x scale. |\n",
    "|S-{1-0} | Zoom to 1/#x scale. |\n",
    "|  p  | Recenter image to mouse location. |\n",
    "|  c  | Recenter to image center. |\n",
    "| Middle mouse | Recenter image to mouse location. |\n",
    "|  \\[ | Horizontal flip. |\n",
    "|  \\] | Vertical flip. |\n",
    "|  \\\\ | Transpose image. |\n",
    "|  R  | Reset image to default orientation. |\n",
    "|  a  | Auto-contrast. |\n",
    "|  D  | Reset color distribution to linear. |\n",
    "|  T  | Reset contrast to default. |\n",
    "|  Y  | Reset colormap to grayscale. |\n",
    "|  I  | Invert colormap. |\n",
    "\n",
    "\n",
    "This set of shortcuts needs to have the appropriate mode selected by typing space-\\<letter>.\n",
    "\n",
    "Click the space bar again to remove the mode.\n",
    "\n",
    "| Mode   | Key | Action |\n",
    "|:-------|:----|:-------|\n",
    "| Space-d|     | Distribution mode: |\n",
    "|        | b, Up | Previous distribution function. |\n",
    "|        | n, Down | Next distribution function. |\n",
    "| Space-s|     | Cut mode: |\n",
    "|        | b, Up | Previous cut function. |\n",
    "|        | n, Down | Next cut function. |\n",
    "|        | Left mouse | Drag to set high/low cut levels. |\n",
    "|        | C-Left mouse | Drag to set only low cut level. |\n",
    "|        | S-Left mouse | Drag to set only high cut level. |\n",
    "|        | h   | Set high cut level to current pixel value. |\n",
    "|        | l   | Set low cut level to current pixel value. |\n",
    "|        | S   | Set cut levels to min/max. |\n",
    "| Space-t|     | Contrast mode: |\n",
    "|        | Left mouse | Drag to set contrast and offset. |\n",
    "| Space-y|     | Colormap mode: |\n",
    "|        | b, Up | Previous color map. |\n",
    "|        | n, Down | Next color map. |\n",
    "|        | c   | Toggle color bar. |\n",
    "| Space-r|     | Rotation mode: |\n",
    "|        | Left mouse | Free rotation about current center. |\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0e6f2b29-012f-4311-ac95-ba36d6702c46",
   "metadata": {},
   "source": [
    "## 4. Python commands\n",
    "\n",
    "### 4.1. Color bar\n",
    "\n",
    "Show and then remove a color bar from the bottom of the astrowidgets display."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "178260df-73b9-4fc4-8d35-802d37fdd3fc",
   "metadata": {},
   "outputs": [],
   "source": [
    "display.show_color_bar(show=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "49062a36-8b9c-4f81-97b9-81410ff13f79",
   "metadata": {},
   "outputs": [],
   "source": [
    "display.show_color_bar(show=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "29010f87-9289-4a70-86a6-671398701e61",
   "metadata": {},
   "source": [
    "### 4.2. Pan mark\n",
    "\n",
    "Show and then remove a + at the center of the display."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d52687b9-947e-446f-b5df-b70e881ec967",
   "metadata": {},
   "outputs": [],
   "source": [
    "display.show_pan_mark(show=True, color='blue')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a7517e2f-ad57-47bb-8ba3-377edd52cc31",
   "metadata": {},
   "outputs": [],
   "source": [
    "display.show_pan_mark(show=False, color='blue')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a634c806-9ef0-4259-87d8-96f7070b9533",
   "metadata": {},
   "source": [
    "### 4.3. Mask plane\n",
    "\n",
    "Excute this cell to plot the `calexp` with the mask plane.\n",
    "\n",
    "**Action:** mouse-over the astrowidgets display and click ` to display the mask plane."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "57fc654c-2644-4616-9b9d-0709c7f9c7cb",
   "metadata": {},
   "outputs": [],
   "source": [
    "display.mtv(calexp)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b458ab38-6abd-46f6-a8c8-a5dc41e30e24",
   "metadata": {},
   "source": [
    "Execute this cell to change the mask transparency to be quite opaque, and re-display the `calexp`.\n",
    "\n",
    "**Action:** mouse-over the astrowidgets display and click ` to refresh the display."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0f40a39a-ec17-4923-9fa9-4c04ad1d445f",
   "metadata": {},
   "outputs": [],
   "source": [
    "display._setMaskTransparency(90)\n",
    "display.mtv(calexp)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e9637cb4-3031-4ff1-aa34-5e2083364200",
   "metadata": {},
   "source": [
    "Same as above, but for a more transparent (less opaque) mask plane."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "468e0a19-f96c-4d6a-bf7a-6e37cd66ec79",
   "metadata": {},
   "outputs": [],
   "source": [
    "display._setMaskTransparency(20)\n",
    "display.mtv(calexp)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d811fa8c-a5fd-41ab-8ce8-88f79f350821",
   "metadata": {},
   "source": [
    "### 4.4. Zoom, rescale, pan\n",
    "\n",
    "Change the pixel flux scale, zoom in, and pan to a bright object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b74ab67d-c5f7-4f44-9abb-c8dbe344d42d",
   "metadata": {},
   "outputs": [],
   "source": [
    "display._scale('linear', 20, 100, '')\n",
    "display._zoom(0.9)\n",
    "display._pan(410, 1710)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e719f09-9c28-4ad5-bebb-5813c6cd45ba",
   "metadata": {},
   "source": [
    "### 4.5. Static image\n",
    "\n",
    "Create a static (non-interactive) image of the current display."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8b21daf8-ab01-4528-8798-ac6467506106",
   "metadata": {},
   "outputs": [],
   "source": [
    "display._show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "69e74c87-e501-4be2-b6ae-b9a75f4d261f",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-06-27T19:31:44.910323Z",
     "iopub.status.busy": "2024-06-27T19:31:44.910036Z",
     "iopub.status.idle": "2024-06-27T19:31:44.913867Z",
     "shell.execute_reply": "2024-06-27T19:31:44.913274Z",
     "shell.execute_reply.started": "2024-06-27T19:31:44.910305Z"
    }
   },
   "source": [
    "### 4.6. Multiple interactive displays\n",
    "\n",
    "Create a new display."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cc4475d6-8b33-4aaf-be1f-ebe1d86e218d",
   "metadata": {},
   "outputs": [],
   "source": [
    "display.embed()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bc2e0b03-6e9c-4f8e-b960-ab38a42c6a83",
   "metadata": {},
   "source": [
    "## 5. Marking objects\n",
    "\n",
    "Start fresh. Use a smaller display size"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "64471c6d-0de0-417a-b6de-9ddff4c9fa98",
   "metadata": {},
   "outputs": [],
   "source": [
    "display = lsst.afw.display.Display(dims=(500, 500))\n",
    "display.embed()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9f2e175-445f-4e2d-90d9-421bda59ebf6",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-06-27T19:34:00.700839Z",
     "iopub.status.busy": "2024-06-27T19:34:00.700552Z",
     "iopub.status.idle": "2024-06-27T19:34:00.704147Z",
     "shell.execute_reply": "2024-06-27T19:34:00.703653Z",
     "shell.execute_reply.started": "2024-06-27T19:34:00.700823Z"
    }
   },
   "source": [
    "Display the image without a mask."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ffaf5ea6-3d0f-44fd-8e85-0fb025157cc3",
   "metadata": {},
   "outputs": [],
   "source": [
    "display.mtv(calexp.image)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32491ec8-1f42-4f81-b335-dc11b04d8f5e",
   "metadata": {},
   "source": [
    "### 5.1. Pre-defined coordinates\n",
    "\n",
    "Place markers on the image."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "54cc1380-87ac-43aa-82e1-a43d497bfe9e",
   "metadata": {},
   "outputs": [],
   "source": [
    "display._dot('*', 100, 100, 50, 'green')\n",
    "display._dot('+', 90, 90, 40, 'red')\n",
    "display._dot('x', 80, 80, 30, 'blue')\n",
    "display._dot('o', 70, 70, 20, 'yellow')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ce0a310c-b0ce-4764-b7d2-11e8bb64aefe",
   "metadata": {},
   "source": [
    "Pan and zoom to take a closer look at the markers in the lower-left corner.\n",
    "\n",
    "Print out the marker locations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b8a83ce1-1f64-4108-9be5-ea2f70ab5518",
   "metadata": {},
   "outputs": [],
   "source": [
    "display.getMarkers('_dot')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "084ffd09-787b-4704-ba15-bd446047a6e5",
   "metadata": {},
   "source": [
    "### 5.2. Interactively defined coordinates\n",
    "\n",
    "Enable click-to-define marking.\n",
    "\n",
    "Symbol options are '*', 'x', 'o', '+', '.'.\n",
    "\n",
    "A pink error warning might appear to inform the user that the display is in interactive marking mode."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "03eac825-4a50-4265-a21b-cf56480fd0a1",
   "metadata": {},
   "outputs": [],
   "source": [
    "display.beginMarking(symb='o', ctype='cyan', size=10, label='test1')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0e1433a6-31a2-4e60-bbd0-d8d0d49d6a93",
   "metadata": {},
   "outputs": [],
   "source": [
    "display.endMarking()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b29c2b33-2d77-4b24-aa4b-2a9cfb3cd375",
   "metadata": {},
   "source": [
    "Get the data for the objects just marked and display it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1d5b072f-0b95-48a2-a774-6de2c5bde583",
   "metadata": {},
   "outputs": [],
   "source": [
    "T = display.getMarkers(label='test1')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "477086bc-448b-44b3-9822-b3af7241ff41",
   "metadata": {},
   "outputs": [],
   "source": [
    "T"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "963953ba-8353-4fd6-9de8-c720767234c4",
   "metadata": {},
   "source": [
    "### 5.3. Draw lines\n",
    "\n",
    "Link markers with a line."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0bf03760-7a2c-42ae-90f6-33477b6cd0ff",
   "metadata": {},
   "outputs": [],
   "source": [
    "display.linkMarkers(label='test1', ctype='cyan')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "90097c72-a7b5-4c86-bd35-0e5f4eab0daf",
   "metadata": {},
   "source": [
    "Draw lines by defining vertices."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "18040fc1-0a24-493b-8ae1-f428c565541c",
   "metadata": {},
   "outputs": [],
   "source": [
    "display._drawLines([(50, 50), (40, 40), (0, 100), (100, 0)], 'magenta')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a603a76d-7b0d-4c39-83cf-fff46e333933",
   "metadata": {},
   "source": [
    "### 5.4. Clear marks"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8244bafb-9f1c-477f-b270-047214fe5553",
   "metadata": {},
   "outputs": [],
   "source": [
    "display.clearMarkers()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b7df2fea-8e58-4edb-ab41-913224295d3d",
   "metadata": {},
   "source": [
    "Clear everything."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c86f9988-f063-4477-ac6b-6489120a7965",
   "metadata": {},
   "outputs": [],
   "source": [
    "display._gingaViewer.canvas.delete_all_objects()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3fe033bd-f24c-42c4-8379-0a74931922bd",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "LSST",
   "language": "python",
   "name": "lsst"
  },
  "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.11.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}