Adding Annotations.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Adding Annotations to the WWT View"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this notebook we'll demonstrate the different tools that pywwt offers for adding “annotations” — overlays — to the WWT view."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Step 1: Setting up WWT\n",
    "\n",
    "First, we need to connect to the WWT app. If WWT isn't running yet, activate the JupyterLab command palette from the View menu, and select \"WorldWide Telescope\". Then all we need to do is run:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pywwt.jupyter import connect_to_app\n",
    "wwt = await connect_to_app().becomes_ready()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now the `wwt` variable will let us talk to the WWT app."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Step 2: A basic circle annotation\n",
    "\n",
    "Let's start about as basic as you can get: a circle. pywwt uses Astropy's “units” support for measuring things like circle radii, so let’s import that module, along with another one that will be helpful:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from astropy import units as u\n",
    "from astropy.coordinates import SkyCoord, concatenate        "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "OK, that’s all we need! By default, new circles will be placed at the center of the current WWT view:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "circ = wwt.add_circle(\n",
    "    radius = 2 * u.degree,\n",
    "    line_color = '#008ca8',  # HTML hexadecimal color specification\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can change the circle's position later, though, using Astropy's standard sky-coordinate class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "c = SkyCoord.from_name('Megrez')\n",
    "wwt.center_on_coordinates(c, instant=False)\n",
    "circ.set_center(c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or we can just create a circle in a specified position right off the bat:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "other_circ = wwt.add_circle(center = c, radius = 3 * u.degree)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With pywwt in general, nearly any setting that you can modify after-the-fact, you can also set directly during the creation of your object.\n",
    "\n",
    "You can also create filled circles, if that’s your jam:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "circ.fill = True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That's about it for circles! Let's get rid of them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.clear_annotations()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Step 3: Line Annotations\n",
    "\n",
    "You can also overlay lines. Here we draw out the Big Dipper — note that the `concatenate` function being used here was imported from the Astropy `coordinates` module above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bd = concatenate((\n",
    "    SkyCoord.from_name('Alkaid'), \n",
    "    SkyCoord.from_name('Mizar'),\n",
    "    SkyCoord.from_name('Alioth'), \n",
    "    SkyCoord.from_name('Megrez'),\n",
    "    SkyCoord.from_name('Phecda'), \n",
    "    SkyCoord.from_name('Merak'),\n",
    "    SkyCoord.from_name('Dubhe'),\n",
    "))\n",
    "\n",
    "wwt.center_on_coordinates(SkyCoord.from_name('Megrez'))\n",
    "\n",
    "line = wwt.add_line(bd)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's make the line a little bit easier on the eyes, and complete the circle of the dipper:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "line.add_point(SkyCoord.from_name('Megrez'))\n",
    "line.color = 'salmon'  # HTML \"named\" colors are also allowed\n",
    "line.opacity = 0.3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Step 4: Polygons\n",
    "\n",
    "You can create filled polygons too! Below we have a complex set of commands that will fill in a few parts of the Orion constellation.\n",
    "\n",
    "One thing you should know: WWT's polygon fills use an [even-odd rule] that mean that you must specify your polygon points such that they are **counterclockwise** on the sky (East-from-North position angle increasing). If you create a small polygon with clockwise points, nothing will fill in!\n",
    "\n",
    "[even-odd rule]: https://en.wikipedia.org/wiki/Even%E2%80%93odd_rule"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.center_on_coordinates(SkyCoord.from_name('eta orion'), instant=False)\n",
    "\n",
    "body_coords = concatenate((\n",
    "    SkyCoord.from_name('delta orion'),\n",
    "    SkyCoord.from_name('bellatrix'),\n",
    "    SkyCoord.from_name('betelgeuse'),\n",
    "    SkyCoord.from_name('zeta orion'),\n",
    "))\n",
    "\n",
    "body_poly = wwt.add_polygon(\n",
    "    body_coords,\n",
    "    fill = True, \n",
    "    fill_color = 'lightslategray', \n",
    "    opacity = 0.4,\n",
    "    line_color = 'lightslategray',\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "club_coords = concatenate((\n",
    "    SkyCoord.from_name('67 orionis'),\n",
    "    SkyCoord.from_name('chi1 orionis'),\n",
    "    SkyCoord.from_name('chi2 orionis'),\n",
    "    SkyCoord.from_name('xi orionis'),\n",
    "))\n",
    "\n",
    "club_poly = wwt.add_polygon(\n",
    "    club_coords,\n",
    "    fill = True,\n",
    "    fill_color = 'saddlebrown',\n",
    "    opacity = 0.4,\n",
    "    line_color = 'saddlebrown',\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bow_coords = concatenate((\n",
    "    SkyCoord.from_name('pi5 orionis'),\n",
    "    SkyCoord.from_name('pi4 orionis'),\n",
    "    SkyCoord.from_name('pi3 orionis'),\n",
    "    SkyCoord.from_name('pi2 orionis'),\n",
    "    SkyCoord.from_name('omicron2 orionis'),\n",
    "))\n",
    "\n",
    "bow_poly = wwt.add_polygon(\n",
    "    bow_coords,\n",
    "    opacity = 0.4, \n",
    "    line_color = 'saddlebrown',\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bow_poly.fill = True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## What's Next\n",
    "\n",
    "WWT’s annotations are handy, but they aren’t meant for heavy-duty data analysis. If you want to plot a lot of points, the [NASA Exoplanet Archive](./NASA%20Exoplanet%20Archive.ipynb) tutorial will show you how to load large data tables into WWT with lots of fancy display controls."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Credits\n",
    "\n",
    "This notebook was prepared by O. Justin Otor and Peter K. G. Williams."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.8.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}