notebooks/ImvizExample.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "17b4af6f",
   "metadata": {},
   "source": [
    "# Imviz Demonstration Notebook\n",
    "\n",
    "\n",
    "This notebook demonstrates the Imviz API in the Notebook setting. UI equivalents for these actions, as well as additional documentation about Imviz, can be found here: https://jdaviz.readthedocs.io/en/latest/imviz/"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7c73155f-c062-461a-8ca7-0891ce142901",
   "metadata": {},
   "source": [
    "Import modules needed for this notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0915bde6-e3cc-4038-aca1-c2ae852f7a69",
   "metadata": {},
   "outputs": [],
   "source": [
    "import warnings\n",
    "\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "from astropy import units as u\n",
    "from astropy.coordinates import SkyCoord, Angle\n",
    "from astropy.table import Table\n",
    "from astropy.utils.data import download_file\n",
    "from photutils import CircularAperture, SkyCircularAperture\n",
    "from regions import PixCoord, CirclePixelRegion, CircleSkyRegion\n",
    "\n",
    "from jdaviz import Imviz"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc45bbab-ddb7-4d24-8066-998a1ba17fd3",
   "metadata": {},
   "source": [
    "We also need this to display Matplotlib in the notebook later."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "53fb47da-0427-4a43-9d11-39567a12cdb0",
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1120d18-65a4-41ec-b831-bc3637718b90",
   "metadata": {},
   "source": [
    "We create an Imviz instance and grab the default viewer instance as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0e81c635-97eb-459c-bfc0-3136839c2844",
   "metadata": {},
   "outputs": [],
   "source": [
    "imviz = Imviz()\n",
    "viewer = imviz.default_viewer"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "60eb5782-264f-4af4-bb6e-ae583398277d",
   "metadata": {},
   "source": [
    "Download some data. In this example, we use two 47 Tuc observations from HST/ACS."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bccca7f4",
   "metadata": {},
   "outputs": [],
   "source": [
    "acs_47tuc_1 = download_file('https://mast.stsci.edu/api/v0.1/Download/file?uri=mast:HST/product/jbqf03gjq_flc.fits', cache=True)\n",
    "acs_47tuc_2 = download_file('https://mast.stsci.edu/api/v0.1/Download/file?uri=mast:HST/product/jbqf03h1q_flc.fits', cache=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0ec7c554",
   "metadata": {},
   "source": [
    "Load the data into Imviz. Data are linked by pixels as they load. We ignore some warnings that appear during parsing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "77c97590",
   "metadata": {},
   "outputs": [],
   "source": [
    "with warnings.catch_warnings():\n",
    "    warnings.simplefilter('ignore')\n",
    "    imviz.load_data(acs_47tuc_1, data_label='acs_47tuc_1')\n",
    "    imviz.load_data(acs_47tuc_2, data_label='acs_47tuc_2')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f38a4e4d-d4ce-4bd6-9f6f-43eed3813f1b",
   "metadata": {},
   "source": [
    "Alternately, we can also visualize some simulated JWST imager data. If you wish to do this, do not run the two ACS-related cells above; turn the following cell into code and run it instead.\n",
    "\n",
    "*Note: Some subsequent cells, especially those involving sky coordinates, might not work with the JWST data.*"
   ]
  },
  {
   "cell_type": "raw",
   "id": "525074e2",
   "metadata": {},
   "source": [
    "jwf277w = download_file('https://stsci.box.com/shared/static/iao1zxtigyrhq7k3wtu5nchrxzlhj9kv.fits', cache=True)\n",
    "jwf444w = download_file('https://stsci.box.com/shared/static/rey83o5wq6g7qd7xym6r1jq9wlsxaqnt.fits', cache=True)\n",
    "\n",
    "imviz.load_data(jwf277w, data_label='JWST_F277W')\n",
    "imviz.load_data(jwf444w, data_label='JWST_F444W')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e28b9919-6f9e-410c-83f6-554631407d4b",
   "metadata": {},
   "source": [
    "Then, we visualize the data and start off by looking at some of the basic features:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "229d64f3-843f-4a7f-ac98-989f2a95d4c1",
   "metadata": {},
   "outputs": [],
   "source": [
    "imviz.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1abb759e",
   "metadata": {},
   "source": [
    "Panning and zooming is possible by showing the viewer toolbar and clicking on the '+'-shaped icon, then dragging around in the image and using scrolling to zoom in and out. To change the stretch and colormap, show the **Layer** options accessible through the last icon in the viewer toolbar.\n",
    "\n",
    "We can also change these programmatically, for example the stretch:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f117ebce-c7a0-44fa-82a4-0c0876663093",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer.stretch_options"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d76b335d",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer.stretch = 'sqrt'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11888383",
   "metadata": {},
   "source": [
    "the colormap:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "28c82ed4-eb6c-4bd1-856f-3bc3a856dca3",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer.colormap_options"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fec4de61",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer.set_colormap('Viridis')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "def18589",
   "metadata": {},
   "source": [
    "the limits via the autocut using percentile option:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "40da11da-f562-4ed3-aa5a-b556047c0c5c",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer.autocut_options"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7c41f17a",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer.cuts = '95%'\n",
    "viewer.cuts"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c59d150e",
   "metadata": {},
   "source": [
    "or the limits directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2a3ac022",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer.cuts = (0, 1000)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2f25ccd8",
   "metadata": {},
   "source": [
    "Note also that in the above example there are mouse-over coordinates visible by default."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a7848d0",
   "metadata": {},
   "source": [
    "It possible to make selections/regions in images and export these to Astropy regions. Click on the viewer toolbar then click on the circular selection tool, and drag and click to select an interesting region on the sky. We can then export this region with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1e369edd",
   "metadata": {},
   "outputs": [],
   "source": [
    "regions = imviz.get_interactive_regions()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a0385234",
   "metadata": {},
   "outputs": [],
   "source": [
    "regions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11afa633",
   "metadata": {},
   "source": [
    "Since the region is an Astropy region, we can e.g. convert it to a mask:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "71e2191b",
   "metadata": {},
   "outputs": [],
   "source": [
    "mask = regions['Subset 1'].to_mask(mode='subpixels')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0a4e02ef",
   "metadata": {},
   "outputs": [],
   "source": [
    "data = imviz.app.get_data_from_viewer('imviz-0', 'acs_47tuc_1[SCI,1]')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "164a1a40",
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.imshow(mask.to_image(data.shape), origin='lower')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee3e07b9",
   "metadata": {},
   "source": [
    "It is also possible to programmatically pass a `regions` shape, a `photutils` aperture shape, or a Numpy mask into Imviz."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "56d11528",
   "metadata": {},
   "outputs": [],
   "source": [
    "c = SkyCoord('00h24m07.33s -71d52m50.71s')\n",
    "\n",
    "# photutils aperture\n",
    "my_aper = CircularAperture((600, 400), r=10)\n",
    "my_aper_sky = SkyCircularAperture(c, 1 * u.arcsec)\n",
    "\n",
    "# regions shape\n",
    "my_reg = CirclePixelRegion(center=PixCoord(x=600, y=200), radius=20)\n",
    "my_reg_sky = CircleSkyRegion(c, Angle(2, u.arcsec))\n",
    "\n",
    "# Numpy mask\n",
    "idx = (np.array([350, 350, 350, 350, 350, 350, 351, 351, 351, 351, 352, 352, 352,\n",
    "                 352, 352, 352, 352, 352, 352, 352, 353, 353, 353, 353, 353, 353,\n",
    "                 353, 353, 353, 353, 353, 353, 354, 354, 354, 354, 354, 354, 354,\n",
    "                 354, 355, 355, 355, 355, 355, 355, 355, 355, 356, 356, 356, 356,\n",
    "                 356, 356, 356, 357, 357, 358, 358]),\n",
    "       np.array([353, 354, 355, 356, 357, 358, 350, 352, 359, 361, 350, 352, 353,\n",
    "                 354, 355, 356, 357, 358, 359, 361, 350, 351, 352, 353, 354, 355,\n",
    "                 356, 357, 358, 359, 360, 361, 351, 352, 354, 355, 356, 357, 359,\n",
    "                 360, 352, 353, 354, 355, 356, 357, 358, 359, 352, 353, 354, 355,\n",
    "                 356, 357, 358, 353, 358, 352, 359]))\n",
    "my_mask = np.zeros(data.shape, dtype=np.bool_)\n",
    "my_mask[idx] = True\n",
    "\n",
    "my_regions = [my_aper, my_aper_sky, my_reg, my_reg_sky, my_mask]\n",
    "imviz.load_regions(my_regions)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "99766ca8",
   "metadata": {},
   "source": [
    "You can also programmatically control the viewer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5e908421",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Center the image on given pixel position.\n",
    "viewer.center_on((1173, 1013))  # X, Y (0-indexed)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e68b6306",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Move the image with the given pixel offsets.\n",
    "viewer.offset_by(500, -100)  # dX, dY"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e0f3845a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Center the image on given sky coordinates.\n",
    "sky = SkyCoord('00h24m07.33s -71d52m50.71s')\n",
    "viewer.center_on(sky)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "20f51452-1858-47f9-a421-2997f54f8433",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Move the image with the given sky offsets.\n",
    "viewer.offset_by(0.5 * u.arcsec, -1.5 * u.arcsec)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2744c0c-8721-480a-811e-87904373e66f",
   "metadata": {},
   "source": [
    "You can programmatically zoom in and out.\n",
    "\n",
    "Zoom level:\n",
    "\n",
    "* 1 means real-pixel-size.\n",
    "* 2 means zoomed in by a factor of 2.\n",
    "* 0.5 means zoomed out by a factor of 2.\n",
    "* 'fit' means zoomed to fit the whole image width into display."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1bad9bdf-b959-4b74-9a77-07212095c2ce",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the current zoom level.\n",
    "viewer.zoom_level"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7a834bcf-7d5a-492b-bc54-740e1500a2f4",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Set the zoom level directly.\n",
    "viewer.zoom_level = 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "32288b81-1817-4549-b2e4-5e7f55b0ee3d",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Set the relative zoom based on current zoom level.\n",
    "viewer.zoom(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11fab067-7428-4ce4-bc9b-f5462fe52e2a",
   "metadata": {},
   "source": [
    "It is also possible to programmatically add non-interactive markers to the image."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "270a6dd2-ce21-457f-845e-19cf5405fee7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Add 100 randomly generated X,Y (0-indexed) w.r.t. reference image\n",
    "# using default marker properties.\n",
    "t_xy = Table({'x': np.random.randint(0, 4096, 100),\n",
    "              'y': np.random.randint(0, 2048, 100)})\n",
    "viewer.add_markers(t_xy)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f1c1aa0d-46b7-42f6-b6d7-395305c15f91",
   "metadata": {},
   "source": [
    "You could customize marker color, alpha, size, and fill with values that Glue supports."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7c8edb6f-c928-4aee-8e64-73a34ab020d0",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer.marker = {'color': 'green', 'alpha': 0.8, 'markersize': 10, 'fill': False}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9ecfd0f9-da9e-419b-99a8-cc6efc20568f",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Mark some sky coordinates using updated marker properties.\n",
    "t_sky = Table({'coord': [SkyCoord('00h24m07.33s -71d52m50.71s'),\n",
    "                         SkyCoord('00h24m01.57s -71d53m17.77s'),\n",
    "                         SkyCoord('00h24m11.70s -71d52m29.21s'),\n",
    "                         SkyCoord('00h24m22.29s -71d53m28.04s')]})\n",
    "viewer.add_markers(t_sky, use_skycoord=True, marker_name='my_sky')\n",
    "t_sky"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bf02dfc5-088b-4745-8dbc-2de1106c53ea",
   "metadata": {},
   "source": [
    "When you do not need the markers anymore, you could remove them by name."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "776c3b75-a1a9-4141-9d6d-8aa766c58d21",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer.remove_markers(marker_name='my_sky')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "594e8b67-6725-416b-814e-8d49055821f2",
   "metadata": {},
   "source": [
    "You can also remove all the markers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "046641de-b173-4377-92d3-344bd4ba48f3",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer.reset_markers()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "70698430-2683-4bb2-b273-e2ae436e641d",
   "metadata": {},
   "source": [
    "You can save the active display as PNG file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d6af9b27-e5b6-45b6-ac85-5d008faa88b1",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer.save('myimage.png')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "96fee8ea-66e3-489c-be27-b06223dd8809",
   "metadata": {},
   "source": [
    "If you want to align the images by WCS instead of pixels, you can run this but it will remove all markers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0e59c379-20ec-4125-83eb-07f56ac22f9b",
   "metadata": {},
   "outputs": [],
   "source": [
    "imviz.link_data(link_type='wcs')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7a4f7c3f",
   "metadata": {},
   "source": [
    "If you want a second viewer, run the following cell *or* click on the \"picture with +\" icon on top of the image viewer.\n",
    "\n",
    "If you click the icon, the viewer name will be auto-generated. Instead of running the next cell, you can run this instead:\n",
    "\n",
    "    viewer_2_name = 'imviz-1'\n",
    "    viewer_2 = imviz.app.get_viewer_by_id(viewer_2_name)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "44f83ce2-1443-48cf-814f-85900878b494",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer_2_name = 'my-viewer-1'\n",
    "\n",
    "# Do not pass in viewer_name if you want it auto-generated.\n",
    "# If auto-generated, viewer name will be 'imviz-1'.\n",
    "viewer_2 = imviz.create_image_viewer(viewer_name=viewer_2_name)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "44c28c5e-104c-4c9a-b2df-536ed3e6d6c6",
   "metadata": {},
   "source": [
    "You can also programmatically control the new viewer, as follows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "77368ba8",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Show the first image in the second viewer.\n",
    "imviz.app.add_data_to_viewer(viewer_2_name, 'acs_47tuc_1[SCI,1]')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "448f72f8-eb53-4c45-9afc-54dc69a9798f",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer_2.zoom(4)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4df7c9de-4da3-415d-8255-c0c570783316",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer_2.cuts = '95%'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "74c81ca4",
   "metadata": {},
   "outputs": [],
   "source": [
    "viewer_2.center_on((1173, 1013))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8194c11e-f947-489f-9484-f85863f23797",
   "metadata": {},
   "source": [
    "To destroy this new viewer, run the following cell *or* click the \"x\" that is right next to the viewer ID."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8fe18946-a01c-452e-9ac0-9fc8b847266d",
   "metadata": {},
   "outputs": [],
   "source": [
    "imviz.destroy_viewer(viewer_2_name)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "55452e5b-8dba-4340-9567-526d9d723691",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}