Adding Annotations to the WWT View

In this notebook we'll demonstrate the different tools that pywwt offers for adding “annotations” — overlays — to the WWT view.

Step 1: Setting up WWT

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 "AAS WorldWide Telescope". Then all we need to do is run:

In [ ]:
from pywwt.jupyter import connect_to_app
wwt = await connect_to_app().becomes_ready()

Now the wwt variable will let us talk to the WWT app.

Step 2: A basic circle annotation

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:

In [ ]:
from astropy import units as u
from astropy.coordinates import SkyCoord, concatenate        

OK, that’s all we need! By default, new circles will be placed at the center of the current WWT view:

In [ ]:
circ = wwt.add_circle(
    radius = 2 *,
    line_color = '#008ca8',  # HTML hexadecimal color specification

We can change the circle's position later, though, using Astropy's standard sky-coordinate class:

In [ ]:
c = SkyCoord.from_name('Megrez')
wwt.center_on_coordinates(c, instant=False)

Or we can just create a circle in a specified position right off the bat:

In [ ]:
other_circ = wwt.add_circle(center = c, radius = 3 *

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.

You can also create filled circles, if that’s your jam:

In [ ]:
circ.fill = True

That's about it for circles! Let's get rid of them:

In [ ]:

Step 3: Line Annotations

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.

In [ ]:
bd = concatenate((


line = wwt.add_line(bd)

Let's make the line a little bit easier on the eyes, and complete the circle of the dipper:

In [ ]:
line.color = 'salmon'  # HTML "named" colors are also allowed
line.opacity = 0.3

Step 4: Polygons

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.

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!

In [ ]:
wwt.center_on_coordinates(SkyCoord.from_name('eta orion'), instant=False)

body_coords = concatenate((
    SkyCoord.from_name('delta orion'),
    SkyCoord.from_name('zeta orion'),

body_poly = wwt.add_polygon(
    fill = True, 
    fill_color = 'lightslategray', 
    opacity = 0.4,
    line_color = 'lightslategray',
In [ ]:
club_coords = concatenate((
    SkyCoord.from_name('67 orionis'),
    SkyCoord.from_name('chi1 orionis'),
    SkyCoord.from_name('chi2 orionis'),
    SkyCoord.from_name('xi orionis'),

club_poly = wwt.add_polygon(
    fill = True,
    fill_color = 'saddlebrown',
    opacity = 0.4,
    line_color = 'saddlebrown',
In [ ]:
bow_coords = concatenate((
    SkyCoord.from_name('pi5 orionis'),
    SkyCoord.from_name('pi4 orionis'),
    SkyCoord.from_name('pi3 orionis'),
    SkyCoord.from_name('pi2 orionis'),
    SkyCoord.from_name('omicron2 orionis'),

bow_poly = wwt.add_polygon(
    opacity = 0.4, 
    line_color = 'saddlebrown',
In [ ]:
bow_poly.fill = True

What's Next

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 tutorial will show you how to load large data tables into WWT with lots of fancy display controls.


This notebook was prepared by O. Justin Otor and Peter K. G. Williams.