BaseWWTWidget

class pywwt.core.BaseWWTWidget(**kwargs: Any)

Bases: HasTraits

A class that can control a WWT viewer from Python.

You should not create instances of this class directly. Instead, you should obtain obtain an instance through one of the following mechanisms, depending on the environment in which you’re running Python and WWT:

• In JupyterLab (the recommended approach), use pywwt.jupyter.connect_to_app(). This requires that you have set up the WWT JupyterLab extension.

• In plain Jupyter, or if you want to use WWT in its widget mode, create an instance of pywwt.jupyter.WWTJupyterWidget. This requires that you have set up the pywwt Jupyter widget.

• If using Qt, create an instance of pywwt.qt.WWTQtClient.

• If you want to control the WWT Windows application, see the pywwt.windows module.

Attributes:

If you modify most of the attributes listed below, your changes will automatically be reflected in the WWT view. However, there are a few special attributes that collect important pieces of WWT functionality:

• layers (pywwt.layers.LayerManager) allows you to add new data layers to the view.

• solar_system (pywwt.solar_system.SolarSystem) provides controls related to WWT’s 3D “solar system” mode (which can display much more than just the solar system!)

The following attributes collect information about data and modes that are available in the connected WWT viewer:

• available_layers (list of str) lists available image sets in a flat array

• available_views (list of str) lists available view modes ("solar system", "jupiter", etc.) in a flat array

• imagery (pywwt.imagery.ImageryLayers) lists available imagery

• instruments (pywwt.instruments.Instruments) lists available instrument FOVs

Attributes Summary

actual_planet_scale	Whether to show planets to scale or as points with a fixed size (bool)
alt_az_grid	Whether to show an altitude-azimuth grid (bool)
alt_az_grid_color	The color of the altitude-azimuth grid (str or tuple)
alt_az_text	Whether to show labels for the altitude-azimuth grid's text (bool)
available_hips_catalog_names	A list of the names of HiPS catalog layers that are currently available in the viewer.
available_layers	A list of the layers that are currently available in the viewer.
available_views	A list of the modes that are currently available in the viewer.
background	The layer to show in the background (str)
constellation_boundaries	Whether to show boundaries for the selected constellations (bool)
constellation_boundary_color	The color of the constellation boundaries (str or tuple)
constellation_figure_color	The color of the constellation figure (str or tuple)
constellation_figures	Whether to show the constellations (bool)
constellation_labels	Whether to show labels for constellations (bool)
constellation_pictures	Whether to show pictures of the constellations' mythological representations (bool)
constellation_selection	Whether to only show boundaries for the selected constellation (bool)
constellation_selection_color	The color of the constellation selection (str or tuple)
crosshairs	Whether to show crosshairs at the center of the field (bool)
crosshairs_color	The color of the crosshairs (str or tuple)
current_mode	The current rendering mode of the engine
ecliptic	Whether to show the path of the ecliptic (bool)
ecliptic_color	The color of the ecliptic (str or tuple)
ecliptic_grid	Whether to show a grid relative to the ecliptic plane (bool)
ecliptic_grid_color	The color of the ecliptic grid (str or tuple)
ecliptic_text	Whether to show labels for the ecliptic grid (bool)
foreground	The layer to show in the foreground (str)
foreground_opacity	The opacity of the foreground layer (float)
galactic_grid	Whether to show a grid relative to the galactic plane (bool)
galactic_grid_color	The color of the galactic grid (str or tuple)
galactic_mode	Whether the galactic plane should be horizontal in the viewer (bool)
galactic_text	Whether to show labels for the galactic grid's text (bool)
grid	Whether to show the equatorial grid (bool)
grid_color	The color of the equatorial grid (str or tuple)
grid_text	Whether to show labels for the equatorial grid (bool)
imagery	Access to the engine's available imagesets
instruments	A list of instruments available for use in add_fov.
layers	Access to the active rendering layers
local_horizon_mode	Whether the view should be that of a local latitude, longitude, and altitude (bool)
location_altitude	The altitude of the viewing location in local horizon mode (Quantity)
location_latitude	The latitude of the viewing location in local horizon mode (Quantity)
location_longitude	The longitude of the viewing location in local horizon mode (Quantity)
most_recent_source	The most recent source selected in the viewer, represented as a dictionary.
precession_chart	Whether to show the precession chart (bool)
precession_chart_color	The color of the precession chart (str or tuple)
selected_sources	A list of the selected sources, with each source represented as a dictionary.
solar_system	Access to solar-system settings and data

Methods Summary

add_circle([center])	Add a circle annotation to the current view.
add_collection(points, **kwargs)	Add a CircleCollection to the current view.
add_fov(telescope[, center, rotate])	Add a telescope's field of view (FOV) to the current view.
add_line([points])	Add a line annotation to the current view.
add_polygon([points])	Add a polygon annotation to the current view.
becomes_ready([timeout])	An async function that finishes when the WWT app becomes ready.
center_on_coordinates(coord[, fov, roll, ...])	Center the view on a particular object or point in the sky.
clear_annotations()	Clears all annotations from the current view.
get_center()	Return the view's current right ascension and declination in degrees.
get_current_time()	Return the viewer's current time as an Time object.
get_fov()	Return the view's current field of view in degrees.
get_roll()	Return the view's roll angle in degrees.
load_image_collection(url[, recursive, ...])	Load a collection of layers for possible use in the viewer.
load_tour(url)	Load and begin playing a tour based on the URL to a .wtt file from the WorldWideTelescope website.
pause_time()	Pause the progression of time in the viewer.
pause_tour()	Pause a loaded tour.
play_time([rate])	Resume the progression of time in the viewer.
reset()	Reset WWT to initial state.
reset_view()	Reset the current view mode's coordinates and field of view to their original states.
resume_tour()	Resume a paused tour.
save_as_html_bundle(dest[, title, ...])	Save the current view as a web page with supporting files.
set_current_time([dt])	Set WWT's internal clock.
set_selection_change_callback(callback)	Set a callback function that will be executed when the widget receives a selection change message.
set_view(mode)	Change the view mode.

Attributes Documentation

actual_planet_scale

Whether to show planets to scale or as points with a fixed size (bool)

alt_az_grid

Whether to show an altitude-azimuth grid (bool)

alt_az_grid_color

The color of the altitude-azimuth grid (str or tuple)

alt_az_text

Whether to show labels for the altitude-azimuth grid’s text (bool)

available_hips_catalog_names

A list of the names of HiPS catalog layers that are currently available in the viewer.

available_layers

A list of the layers that are currently available in the viewer.

available_views

A list of the modes that are currently available in the viewer.

background

The layer to show in the background (str)

constellation_boundaries

Whether to show boundaries for the selected constellations (bool)

constellation_boundary_color

The color of the constellation boundaries (str or tuple)

constellation_figure_color

The color of the constellation figure (str or tuple)

constellation_figures

Whether to show the constellations (bool)

constellation_labels

Whether to show labels for constellations (bool)

constellation_pictures

Whether to show pictures of the constellations’ mythological representations (bool)

constellation_selection

Whether to only show boundaries for the selected constellation (bool)

constellation_selection_color

The color of the constellation selection (str or tuple)

crosshairs

Whether to show crosshairs at the center of the field (bool)

crosshairs_color

The color of the crosshairs (str or tuple)

current_mode = None

The current rendering mode of the engine

ecliptic

Whether to show the path of the ecliptic (bool)

ecliptic_color

The color of the ecliptic (str or tuple)

ecliptic_grid

Whether to show a grid relative to the ecliptic plane (bool)

ecliptic_grid_color

The color of the ecliptic grid (str or tuple)

ecliptic_text

Whether to show labels for the ecliptic grid (bool)

foreground

The layer to show in the foreground (str)

foreground_opacity

The opacity of the foreground layer (float)

galactic_grid

Whether to show a grid relative to the galactic plane (bool)

galactic_grid_color

The color of the galactic grid (str or tuple)

galactic_mode

Whether the galactic plane should be horizontal in the viewer (bool)

galactic_text

Whether to show labels for the galactic grid’s text (bool)

grid

Whether to show the equatorial grid (bool)

grid_color

The color of the equatorial grid (str or tuple)

grid_text

Whether to show labels for the equatorial grid (bool)

imagery = None

Access to the engine’s available imagesets

instruments

A list of instruments available for use in add_fov.

layers = None

Access to the active rendering layers

local_horizon_mode

Whether the view should be that of a local latitude, longitude, and altitude (bool)

location_altitude

The altitude of the viewing location in local horizon mode (Quantity)

location_latitude

The latitude of the viewing location in local horizon mode (Quantity)

location_longitude

The longitude of the viewing location in local horizon mode (Quantity)

most_recent_source

The most recent source selected in the viewer, represented as a dictionary. The items of this dictionary match the entries of the Source object detailed here.

precession_chart

Whether to show the precession chart (bool)

precession_chart_color

The color of the precession chart (str or tuple)

selected_sources

A list of the selected sources, with each source represented as a dictionary. The items of these dictionaries match the entries of the Source object detailed here.

solar_system = None

Access to solar-system settings and data

Methods Documentation

add_circle(center=None, **kwargs)

Add a circle annotation to the current view.

Parameters:

centerQuantity, optional

The coordinates of desired center of the circle. If blank, defaults to the center of the current view.

kwargs

Optional arguments that allow corresponding Circle or Annotation attributes to be set upon shape initialization.

add_collection(points, **kwargs)

Add a CircleCollection to the current view.

Parameters:

pointsQuantity

The desired points that will serve as the centers of the circles that make up the collection. Requires at least two sets of coordinates for initialization.

kwargs

Optional arguments that allow corresponding Circle or Annotation attributes to be set upon shape initialization.

add_fov(telescope, center=None, rotate=<Quantity 0. rad>, **kwargs)

Add a telescope’s field of view (FOV) to the current view.

Parameters:

telescopestr

The telescope whose field of view will be displayed. Be sure to use the instruments attribute to see and select from the preset list of instruments available in pyWWT.

centerQuantity, optional

The coordinates of desired center of the FOV. If blank, defaults to the center of the current view.

rotateQuantity, optional

The amount to rotate the FOV. Both radians and degrees are accepted. If blank, defaults to 0 radians (no rotation).

kwargs

Optional arguments that allow corresponding Polygon or Annotation attributes to be set upon shape initialization.

add_line(points=None, **kwargs)

Add a line annotation to the current view.

Parameters:

pointsQuantity, optional

The desired points that make up the line. If blank or just one point, the annotation will be initialized but will not be visible until more points are added.

kwargs

Optional arguments that allow corresponding Line or Annotation attributes to be set upon shape initialization.

add_polygon(points=None, **kwargs)

Add a polygon annotation to the current view.

Parameters:

pointsQuantity, optional

The desired points that make up the polygon. If blank or just one point, the annotation will be initialized but will not be visible until more points are added. Note that the points should be specified in counter-clockwise order on the sky if you intend to fill the polygon.

kwargs

Optional arguments that allow corresponding Polygon or Annotation attributes to be set upon shape initialization.

async becomes_ready(timeout=30)

An async function that finishes when the WWT app becomes ready.

Returns:

self

Notes

The web browser running WWT needs to initialize the application and download some initial data files, which can take an indeterminate amount of time. This async function will complete once the WWT app has initialized and is ready to respond to control messages from pywwt. After this has happened the first time, this function will complete instantly.

center_on_coordinates(coord, fov=<Quantity 60. deg>, roll=None, instant=True)

Center the view on a particular object or point in the sky.

Parameters:

coordQuantity

The set of coordinates the view should center on.

fovQuantity, optional

The desired field of view.

roll: `~astropy.units.Quantity`, optional

The desired roll angle of the camera. If not specified, the roll angle is not changed.

instantbool, optional

Whether the view changes instantly or smoothly scrolls to the desired location.

clear_annotations()

Clears all annotations from the current view.

get_center()

Return the view’s current right ascension and declination in degrees.

get_current_time()

Return the viewer’s current time as an Time object.

get_fov()

Return the view’s current field of view in degrees.

get_roll()

Return the view’s roll angle in degrees.

load_image_collection(url, recursive=False, remote_only=False)

Load a collection of layers for possible use in the viewer.

Parameters:

urlstr

The URL of the desired image collection.

recursiveoptional bool

If true, will also load any child folders referenced in the specified WTML file. The default behavior is only to load the single file and not recurse into subfolders. Recursive loading can potentially be very time-consuming.

remote_onlyoptional bool

ADASS hack! If true, will only send the load request to the app, and not attempt to open the URL locally.

Notes

The request to load the image collection must be relayed to the WWT JavaScript code, which will then issue a web request and process the response that it gets. Therefore, you can’t rely on this function to take immediate effect; to use an image in a collection that you’ve loaded, you’ll need to pause and give WWT time to receive and process your request.

load_tour(url)

Load and begin playing a tour based on the URL to a .wtt file from the WorldWideTelescope website.

Parameters:

urlstr

The URL of the chosen tour – must be a .wtt file.

pause_time()

Pause the progression of time in the viewer.

pause_tour()

Pause a loaded tour.

play_time(rate=1)

Resume the progression of time in the viewer.

Parameters:

rateint or float

The rate at which time passes (1 meaning real-time)

reset()

Reset WWT to initial state.

reset_view()

Reset the current view mode’s coordinates and field of view to their original states.

resume_tour()

Resume a paused tour.

save_as_html_bundle(dest, title=None, max_width=None, max_height=None)

Save the current view as a web page with supporting files.

This feature is currently under development, so not all settings/features that can be set in pyWWT will be saved

Parameters:

deststr

The path to output the bundle to. The path must represent a directory (which will be created if it does not exist) or a zip file.

titlestr, optional

The desired title for the HTML page. If blank, a generic title will be used.

max_widthint, optional

The maximum width of the WWT viewport on the exported HTML page in pixels. If left blank, the WWT viewport will fill the enitre width of the browser.

max_heightint, optional

The maximum height of the WWT viewport on the exported HTML page in pixels. If left blank, the WWT viewport will fill the enitre height of the browser.

set_current_time(dt=None)

Set WWT’s internal clock.

Parameters:

dtdatetime or Time

A time, either as a datetime.datetime object or an astropy astropy.time.Time object. If not specified, this uses the current time.

Notes

If you call this function and then immediately call get_current_time(), the results will not necessarily agree. This is because this function has to send a command to WWT to tell it to update its internal clock, and in some environments this operation is not instantaneous.

set_selection_change_callback(callback)

Set a callback function that will be executed when the widget receives a selection change message.

Parameters:

callback:

A callable object which takes two arguments: the WWT widget instance, and a list of updated properties.

set_view(mode)

Change the view mode.

Valid options include the default sky mode, a 3D universe mode with different viewing levels (the solar system, the Milky Way, and the observed universe), individual views of major solar system objects, and panoramas from lunar missions and NASA’s Mars rovers.

To find the list of available views, use the available_views.

Parameters:

modestr

The desired view mode. (default: ‘sky’)