notebooks/concepts/imviz_roman_asdf.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "17b4af6f",
   "metadata": {},
   "source": [
    "# Imviz Demonstration Notebook\n",
    "## Roman/ASDF Edition\n",
    "\n",
    "This notebook demonstrates the Imviz API in the Notebook setting when using simulated observations from The Nancy Grace Roman Space Telescope. 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": {
    "tags": []
   },
   "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\n",
    "from astropy.table import Table\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": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1120d18-65a4-41ec-b831-bc3637718b90",
   "metadata": {},
   "source": [
    "For now, we will use synthetic data for testing. \n",
    "\n",
    "Before downloading the example data, which were generated with schema from `roman_datamodels` and `rad == 0.22.0`, check that the correct version of `roman_datamodels` is installed. Otherwise it may not be possible to open these example files:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "68443a20",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from packaging.version import Version\n",
    "from astropy.utils.data import download_file\n",
    "from roman_datamodels import __version__ as rdm_version\n",
    "\n",
    "assert Version(rdm_version) >= Version('0.22.0'), 'Update roman_datamodels with `pip install -U roman_datamodels`'\n",
    "\n",
    "\n",
    "# Each of these files is ~1 GB:\n",
    "image_model1 = download_file('https://stsci.box.com/shared/static/oor05ut2u5e3xq4kcd244pq5md1el13h.asdf', cache=True)\n",
    "image_model2 = download_file('https://stsci.box.com/shared/static/sw1jvu70q20w6czi8pmd9351f0yqkj5o.asdf', cache=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6fb39d1e-7b10-4e9f-8d42-1d971b035014",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# load the observations into the helper\n",
    "imviz = Imviz()\n",
    "\n",
    "with warnings.catch_warnings():\n",
    "    warnings.simplefilter('ignore')  # ErfaWarning\n",
    "    imviz.load_data(image_model1, ext='data', data_label='exposure 1')\n",
    "    imviz.load_data(image_model2, ext='data', data_label='exposure 2')"
   ]
  },
  {
   "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": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "imviz.show('sidecar:split-right', height=1000)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "52adc3d4-7f44-43aa-af46-6acb390d56e2",
   "metadata": {},
   "source": [
    "We have loaded two sequential exposures with the same pointing. Let's orient both images by their WCS:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8427d4f9-8ea3-4d60-a8b7-3f3f63e3f3e0",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "orientation = imviz.plugins['Orientation']\n",
    "\n",
    "orientation.align_by = 'WCS'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1abb759e",
   "metadata": {},
   "source": [
    "Imviz will initially display Roman images zoomed to fit the display. However, since each detector's images have 4k resolution, the default Imviz zoom makes it hard to tell if the colormap stretch is appropriate.\n",
    "\n",
    "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": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "plot_options = imviz.plugins['Plot Options']\n",
    "\n",
    "for viewer_name in imviz.app.get_viewer_reference_names():\n",
    "    viewer = imviz.app.get_viewer(viewer_name)\n",
    "    plot_options.viewer = viewer_name\n",
    "    \n",
    "    for data in viewer.data():\n",
    "        plot_options.layer = data.label\n",
    "        \n",
    "        # set colormap and stretch for this layer:\n",
    "        plot_options.stretch_function = 'arcsinh'\n",
    "        plot_options.image_colormap = 'Viridis'\n",
    "        plot_options.stretch_vmin = 0\n",
    "        plot_options.stretch_vmax = 20"
   ]
  },
  {
   "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": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "regions = imviz.get_interactive_regions()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a0385234",
   "metadata": {
    "tags": []
   },
   "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": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "wcs = imviz.app.data_collection[-1].coords\n",
    "mask = regions['Subset 1'].to_pixel(wcs).to_mask(mode='subpixels')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0a4e02ef",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "data = imviz.get_data(imviz.app.data_collection[0].label)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "164a1a40",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "plt.imshow(mask.to_image(data.data.shape), origin='lower')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "99766ca8",
   "metadata": {},
   "source": [
    "You can use Astrowidgets API."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f2ce00c9-093c-4bc0-8cb7-b7c8fe38ec64",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "viewer = imviz.default_viewer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5e908421",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Center the image on given pixel position.\n",
    "viewer.center_on((6, 5))  # X, Y (0-indexed)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e68b6306",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Move the image with the given pixel offsets.\n",
    "viewer.offset_by(5, -3)  # dX, dY"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "052ffd09-4094-43bf-a17e-48845c5b69c1",
   "metadata": {},
   "source": [
    "We can convert the coordinates of the interactive subset from pixel to world coordinates like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "05bc5603-9815-433f-8b4b-2556222ce6c5",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "center = regions['Subset 1'].center"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e0f3845a",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Center the image on given sky coordinates.\n",
    "sky = SkyCoord(ra=269.89, dec=66.04, unit=('deg', 'deg'))\n",
    "viewer.center_on(sky)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "20f51452-1858-47f9-a421-2997f54f8433",
   "metadata": {
    "tags": []
   },
   "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": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Get the current zoom level.\n",
    "viewer.zoom_level"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7a834bcf-7d5a-492b-bc54-740e1500a2f4",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Set the zoom level directly.\n",
    "viewer.zoom_level = 100"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "32288b81-1817-4549-b2e4-5e7f55b0ee3d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Set the relative zoom based on current zoom level.\n",
    "viewer.zoom(1.5)"
   ]
  },
  {
   "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": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Add 20 randomly generated X,Y (0-indexed) w.r.t. reference image\n",
    "# using default marker properties.\n",
    "image_shape = data.data.shape\n",
    "t_xy = Table({'x': np.random.randint(0, image_shape[1], 20),\n",
    "              'y': np.random.randint(0, image_shape[0], 20)})\n",
    "\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": "9ecfd0f9-da9e-419b-99a8-cc6efc20568f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "np.random.seed(42)\n",
    "# Mark some sky coordinates using updated marker properties.\n",
    "t_sky = Table({'coord': [\n",
    "    sky.spherical_offsets_by(\n",
    "         *np.random.normal(scale=0.1, size=2) * u.arcsec\n",
    "    ) for i in range(5)\n",
    "]})\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": {
    "tags": []
   },
   "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": {
    "tags": []
   },
   "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, \"exposure 1[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((1500, 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)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5f99d196-036c-4902-bd18-c8e3bdd9a85a",
   "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.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}