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 photutils.aperture 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": [
    "Now we load observations. If you already have the files on your local machine, you can \n",
    "load them by passing their file paths to `load_data` as strings. For this example, \n",
    "we will retrieve remote data from [MAST](https://mast.stsci.edu/) via `astroquery`\n",
    "by passing the observation's URI as a string. By default, the downloaded files are \n",
    "saved to the current working directory. If you set `cache=False` in the `load_data` \n",
    "call, it will re-download the file if desired.\n",
    "\n",
    "In this example, we use two of the JWST NIRCam\n",
    "observations of the Cartwheel Galaxy. These are large files (~500 MB each), so they make take\n",
    "some time to download, but after the first time running this notebook they will be cached locally.\n",
    "If you want to look at images from other filters, you can uncomment the lines with those filenames.\n",
    "If you want an example using smaller files, see the ImvizDitheredExample notebook, which\n",
    "includes the same workflow as this one, but using two HST ACS files that are much smaller\n",
    "than the JWST files used here.\n",
    "\n",
    "After downloading, each file is loaded into Imviz. We ignore some warnings that appear during parsing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bccca7f4",
   "metadata": {},
   "outputs": [],
   "source": [
    "filenames = [\n",
    "    'jw02727-o002_t062_nircam_clear-f090w_i2d.fits',\n",
    "    # 'jw02727-o002_t062_nircam_clear-f150w_i2d.fits',\n",
    "    # 'jw02727-o002_t062_nircam_clear-f200w_i2d.fits',\n",
    "    'jw02727-o002_t062_nircam_clear-f277w_i2d.fits',\n",
    "    # 'jw02727-o002_t062_nircam_clear-f356w_i2d.fits',\n",
    "    # 'jw02727-o002_t062_nircam_clear-f444w_i2d.fits'\n",
    "]\n",
    "\n",
    "for fn in filenames:\n",
    "    uri = f\"mast:JWST/product/{fn}\"\n",
    "    with warnings.catch_warnings():\n",
    "        warnings.simplefilter('ignore')\n",
    "        imviz.load_data(uri, cache=True)"
   ]
  },
  {
   "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": "99d4bdef",
   "metadata": {},
   "source": [
    "Alternatively, the data and the configuration can be autodetected and loaded simultaneously by calling `jdaviz.open(f'{data_dir}/{fn}')`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e78efeb",
   "metadata": {},
   "source": [
    "The first thing you will probably notice is that the image doesn't take up the entire viewer area. \n",
    "If you press the \"b\" key to blink to the other loaded image, you will see that this image is \n",
    "zoomed correctly by default. The odd default zoom on the other is because the images are linked\n",
    "by pixel when loaded. We can instead link by WCS (world coordinates) so that the images\n",
    "will be properly aligned:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "548a2866",
   "metadata": {},
   "outputs": [],
   "source": [
    "imviz.link_data(align_by='wcs')"
   ]
  },
  {
   "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, 2)"
   ]
  },
  {
   "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.get_data('jw02727-o002_t062_nircam_clear-f090w_i2d[DATA]')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "164a1a40",
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.imshow(mask.to_image(data.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('00h37m41.1171s -33d42m58.5745s')\n",
    "\n",
    "# photutils aperture\n",
    "my_aper = CircularAperture((1714, 1380), r=20)\n",
    "my_aper_sky = SkyCircularAperture(c, 2 * u.arcsec)\n",
    "\n",
    "# regions shape\n",
    "my_reg = CirclePixelRegion(center=PixCoord(x=1526, y=1063), radius=40)\n",
    "my_reg_sky = CircleSkyRegion(c, Angle(2, u.arcsec))\n",
    "\n",
    "my_regions = [my_aper, my_aper_sky, my_reg, my_reg_sky]\n",
    "imviz.plugins['Subset Tools'].import_region(my_regions, combination_mode='new')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "99766ca8",
   "metadata": {},
   "source": [
    "You can also programmatically control the viewer. Note that the following will fail\n",
    "if you have blinked between the two images and have data `B` active, due to the\n",
    "smaller size of that image."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5e908421",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Center the image on given pixel position.\n",
    "viewer.center_on((1900, 2500))  # 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('00h37m41.1171s -33d42m58.5745s')\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 20 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, 4000, 20),\n",
    "              'y': np.random.randint(0, 4000, 20)})\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('00h37m42.278s -33d42m00.271s'),\n",
    "                         SkyCoord('00h37m40.111s -33d42m36.871s'),\n",
    "                         SkyCoord('00h37m43.411s -33d42m55.64s'),\n",
    "                         SkyCoord('00h37m41.611s -33d42m56.15s')]})\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": "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, 'jw02727-o002_t062_nircam_clear-f277w_i2d[DATA]')"
   ]
  },
  {
   "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((995, 1000))"
   ]
  },
  {
   "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)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "jdaviz0",
   "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.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}