{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# First Steps With pywwt\n",
    "\n",
    "This notebook walks you through how to connect a Jupyter notebook to the [AAS] [WorldWide Telescope] app using [pywwt]. Once they're connected, you can control the viewer and import your data into the WWT app.\n",
    "\n",
    "[pywwt]: https://pywwt.readthedocs.io/\n",
    "[AAS]: https://aas.org/\n",
    "[WorldWide Telescope]: http://worldwidetelescope.org/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "# Starting up the WWT App\n",
    "\n",
    "If WWT isn't running yet, you'll need to start it up. There are a few ways you can do that:\n",
    "\n",
    "- The big handy button in the JupyterLab Launcher window\n",
    "- Go to the “View” menu, then “Activate Command Palette”, then select “AAS WorldWide Telescope”\n",
    "- As a shortcut to activate the command palette, you can type control-shift-C (or shift-option-c on a Mac)\n",
    "\n",
    "Once the WWT window is opened up, we recommend dragging it to be side-by-side with your notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "# Connecting to the App\n",
    "\n",
    "Once the app is started up, connecting to it is easy. We need to import a function from pywwt:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pywwt.jupyter import connect_to_app"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you're running this notebook in the cloud, this command should *definitely* work — which, in this case, means that it will run without printing any error messages or warnings. If you get an `ImportError` error, your notebook session isn't able to load the `pywwt` Python module for some reason. The most straightforward reason might be that you haven't installed it — if that's the case, visit [the pywwt installation instructions](https://pywwt.readthedocs.io/en/stable/installation.html).\n",
    "\n",
    "Next we create an connection and save it in a variable, conventionally named `wwt`. You’ll use this variable to control the viewer programmatically:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt = connect_to_app()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(If the first command succeeded, this one *really* ought to work. If an error occurs, [file an issue on the pywwt GitHub repository](https://github.com/WorldWideTelescope/pywwt/issues/new) and someone will help you.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "# Navigating the WWT Viewer\n",
    "\n",
    "Here are the ways you can navigate around inside the pywwt viewer:\n",
    "\n",
    "**TODO some of these need to be fixed!**\n",
    "\n",
    "- To pan around, click-and-drag the mouse like you would in an app like Google Maps\n",
    "  - Or, you can pan around by pressing the keys `i`, `j`, `k`, and `l`\n",
    "- To zoom in and out, you can use the scroll wheel on your mouse, if you have one\n",
    "  - Or you can use a two-finger scroll on a Mac mouse or touchpad\n",
    "  - Or you can press the keys `z` and `x` to zoom in and out, respectively\n",
    "  - Or in some cases the Page-Up and Page-Down keys should work\n",
    "- In the standard sky exploration mode, you can *roll* the angle of the viewer by holding down the Control key and then click-and-dragging.\n",
    "- In the planet viewer mode, the Control-click-drag action will change the angle of the camera relative to the planetary surface\n",
    "\n",
    "If you ever get your viewer into a funky state that you can't escape, try:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.reset()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "# Changing the Background Imagery\n",
    "\n",
    "By default, the pywwt viewer opens in a 2D \"sky mode\" showing a terapixel optical map of the entire sky, derived from the [Digitized Sky Survey](https://en.wikipedia.org/wiki/Digitized_Sky_Survey). Running the following cell will create some controls in your notebook that will let you choose a different all-sky map, or even blend between two maps:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.layer_controls"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "# Changing the Viewer Mode\n",
    "\n",
    "WWT can do more than just 2D sky exploration, however. This command will change the view to the 3D “Solar System” mode, which is actually a misnomer since it allows 3D exploration of much more than just the Solar System:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.set_view('solar system')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once you enter this mode, keep on zooming out as far as you can go. The view will seem to stall once the solar system shrinks into a dot, but if you keep on going, you’ll eventually see the local stars move in 3D, then an artist’s conception of the Milky Way, then relatively nearby galaxies from the SDSS catalog. (The last of these might take some time to appear since the viewer needs to first download all of the galaxy data, then create a fairly intensive 3D rendering data structure.)\n",
    "\n",
    "To get back to the 2D sky mode, use:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.set_view('sky')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also view the major planets as 3D spheres:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.set_view('earth')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This mode allows you to overlay data on planetary surfaces and view topography with [DEM](https://en.wikipedia.org/wiki/Digital_elevation_model) maps. Check out Mars!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.set_view('mars')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "# Controlling the View Position\n",
    "\n",
    "You can command the pywwt viewer to look at a specific location. To demonstrate this, let's switch back to Sky Mode:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.set_view('sky')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can set the location using [AstroPy SkyCoord](https://docs.astropy.org/en/stable/coordinates/index.html) objects, so all of the flexibility of those objects is available for free:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from astropy.coordinates import SkyCoord\n",
    "\n",
    "wwt.center_on_coordinates(SkyCoord.from_name('M31'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from astropy import units as u\n",
    "\n",
    "wwt.center_on_coordinates(\n",
    "    SkyCoord(ra = 13.1284 * u.deg, dec = 56.6241 * u.deg), \n",
    "    fov = 3 * u.deg,  # specifies the zoom level by setting the viewer's angular height\n",
    "    instant = False,  # pan smoothly instead of moving abruptly\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "# Controlling the Clock\n",
    "\n",
    "We say that the pywwt viewer is actually four-dimensional, not just three-dimensional, since it has an internal clock that is integrated into the simulation: planet positions are calculated to high accuracy and data rendering can take into account the current time.\n",
    "\n",
    "To demonstrate this, let’s switch back to the Solar System Mode:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.set_view('solar system')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can set the time using [AstroPy Time](https://docs.astropy.org/en/stable/time/) objects:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from astropy.time import Time\n",
    "\n",
    "wwt.set_current_time(Time('1999-01-01'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can change the rate at which the clock runs:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.play_time(rate=3000000)  # advance the WWT clock at 3,000,000 times realtime"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And you can pause it altogether:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.pause_time()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "# Next Steps\n",
    "\n",
    "Now that you’ve been introduced to the basics of the pywwt viewer, how about going back to the [Start Here](./Start%20Here.ipynb) notebook and trying some of our more in-depth tutorials?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "# Credits\n",
    "\n",
    "This notebook was prepared by:\n",
    "\n",
    "- 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
}