First Steps With pywwt

This notebook walks you through how to connect a Jupyter notebook to the AAS app using pywwt. Once they're connected, you can control the viewer and import your data into the WWT app.


Starting up the WWT App

If WWT isn't running yet, you'll need to start it up. There are a few ways you can do that:

  • The big handy button in the JupyterLab Launcher window
  • Go to the “View” menu, then “Activate Command Palette”, then select “AAS WorldWide Telescope”
  • As a shortcut to activate the command palette, you can type control-shift-C (or shift-option-c on a Mac)

Once the WWT window is opened up, we recommend dragging it to be side-by-side with your notebook.


Connecting to the App

Once the app is started up, connecting to it is easy. We need to import a function from pywwt:

In [ ]:
from pywwt.jupyter import connect_to_app

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.

Next we create an connection and save it in a variable, conventionally named wwt. You’ll use this variable to control the viewer programmatically:

In [ ]:
wwt = await connect_to_app().becomes_ready()

(If the first command succeeded, this one really ought to work. If an error occurs, file an issue on the pywwt GitHub repository and someone will help you.)


Navigating the WWT Viewer

Here are the ways you can navigate around inside the pywwt viewer:

TODO some of these need to be fixed!

  • To pan around, click-and-drag the mouse like you would in an app like Google Maps
    • Or, you can pan around by pressing the keys i, j, k, and l
  • To zoom in and out, you can use the scroll wheel on your mouse, if you have one
    • Or you can use a two-finger scroll on a Mac mouse or touchpad
    • Or you can press the keys z and x to zoom in and out, respectively
    • Or in some cases the Page-Up and Page-Down keys should work
  • 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.
  • In the planet viewer mode, the Control-click-drag action will change the angle of the camera relative to the planetary surface

If you ever get your viewer into a funky state that you can't escape, try:

In [ ]:
wwt.reset()

Changing the Background Imagery

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. 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:

In [ ]:
wwt.layer_controls

Changing the Viewer Mode

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:

In [ ]:
wwt.set_view('solar system')

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.)

To get back to the 2D sky mode, use:

In [ ]:
wwt.set_view('sky')

You can also view the major planets as 3D spheres:

In [ ]:
wwt.set_view('earth')

This mode allows you to overlay data on planetary surfaces and view topography with DEM maps. Check out Mars!

In [ ]:
wwt.set_view('mars')

Controlling the View Position

You can command the pywwt viewer to look at a specific location. To demonstrate this, let's switch back to Sky Mode:

In [ ]:
wwt.set_view('sky')

You can set the location using AstroPy SkyCoord objects, so all of the flexibility of those objects is available for free:

In [ ]:
from astropy.coordinates import SkyCoord

wwt.center_on_coordinates(SkyCoord.from_name('M31'))

Or:

In [ ]:
from astropy import units as u

wwt.center_on_coordinates(
    SkyCoord(ra = 13.1284 * u.deg, dec = 56.6241 * u.deg), 
    fov = 3 * u.deg,  # specifies the zoom level by setting the viewer's angular height
    instant = False,  # pan smoothly instead of moving abruptly
)

Controlling the Clock

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.

To demonstrate this, let’s switch back to the Solar System Mode:

In [ ]:
wwt.set_view('solar system')

You can set the time using AstroPy Time objects:

In [ ]:
from astropy.time import Time

wwt.set_current_time(Time('1999-01-01'))

You can change the rate at which the clock runs:

In [ ]:
wwt.play_time(rate=3000000)  # advance the WWT clock at 3,000,000 times realtime

And you can pause it altogether:

In [ ]:
wwt.pause_time()

Next Steps

Now that you’ve been introduced to the basics of the pywwt viewer, how about going back to the Start Here notebook and trying some of our more in-depth tutorials?


Credits

This notebook was prepared by:

  • Peter K. G. Williams