This notebook walks you through how to open a pywwt viewer "widget" in your Jupyter notebook or JupyterLab environment, and the basic ways that you can control the viewer. pywwt visualizes astronomical data and imagery in context using the AAS WorldWide Telescope rendering engine.
If you want to use pywwt
in a notebook, the first step is always to import the WWTJupyterWidget class:
from pywwt.jupyter import WWTJupyterWidget
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 instance of the widget and assign it to a variable, conventionally named wwt
. You’ll use this variable to control the viewer programmatically:
wwt = WWTJupyterWidget()
(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.)
To actually create a WWT viewer, just “run” a notebook cell containing the widget variable and nothing else:
wwt
A window should appear that looks like a big black box. It might look like something isn't working, but if you click-and-drag inside the window, you should eventually see the galaxy swing into view. WWT is running inside your browser!
If instead you just see a line of text that looks something like:
WWTJupyterWidget()
that means that the pywwt
widget framework is not properly set up within your Jupyter environment — at the moment, additional setup needs to occur beyond simply installing the pywwt
module. See the pywwt installation instructions for guidance about how to set up the integration.
If you're using JupyterLab and not just a plain Jupyter notebook, you can move the WWT view to a separate window pane. This is extremely useful since it lets you keep on typing code without scrolling WWT out of view. Here's how you do that:
If you don't get a menu when you right-click, or the menu doesn't look like the one pictured, you are using a plain Jupyter notebook and will have to scroll back and forth.
You can then click-and-drag the tab corresponding to the new pywwt viewer and stick it to any side of your browser window that you wish.
Finally, if you click the blue bar next to the viewer back in this notebook, you will hide it, decluttering your code.
Here are the ways you can navigate around inside the pywwt viewer:
i
, j
, k
, and l
z
and x
to zoom in and out, respectivelyIf you ever get your viewer into a funky state that you can't escape, try:
wwt.reset()
Or close your widget window and create a new wwt
variable.
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:
wwt.layer_controls
The pywwt viewer 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:
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:
wwt.set_view('sky')
You can also view the major planets as 3D spheres:
wwt.set_view('earth')
This mode allows you to overlay data on planetary surfaces and view topography with DEM maps. Check out Mars!
wwt.set_view('mars')
You can command the pywwt viewer to look at a specific location. To demonstrate this, let's switch back to Sky Mode:
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:
from astropy.coordinates import SkyCoord
wwt.center_on_coordinates(SkyCoord.from_name('M31'))
Or:
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
)
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:
wwt.set_view('solar system')
You can set the time using AstroPy Time objects:
from astropy.time import Time
wwt.set_current_time(Time('1999-01-01'))
You can change the rate at which the clock runs:
wwt.play_time(rate=3000000) # advance the WWT clock at 3,000,000 times realtime
And you can pause it altogether:
wwt.pause_time()
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?