How to Sync Viewers with mast-aladin and jdaviz#
Learning Goals#
This is a beginner tutorial on synchronizing the viewer state between mast-aladin and jdaviz viewers. By the end of this tutorial, you will:
Understand what a viewer’s viewport represents.
Be able to sync viewport properties using the Viewer Sync UI.
Table of Contents#
What is a Viewport?#
A viewport is the part of an image currently visible in a viewer. Both jdaviz and mast-aladin implement the Astro Image Display API (AIDA), which describes a viewport using properties such as its sky-coordinate center, field of view, rotation, and projection.
In this tutorial, we’ll sync the following viewport properties:
Center: The center of the viewport in sky coordinates.
FOV: The field of view of the viewport, measured along the viewer’s shorter side.
Rotation: The rotation applied to the image in the viewport
Projection: The current projection applied to the viewport
Imports#
We will import the following in this tutorial:
mast-aladin: to create sky viewers and manage synchronization.jdaviz: to create an image viewer.Sidecar: to arrange the viewers in the notebook.
import jdaviz as jd
from mast_aladin import MastAladin, MastManager
from sidecar import Sidecar
Widget Setup#
Initialize widgets:
Before syncing viewers, we’ll create two mast-aladin viewers and one jdaviz viewer. We’ll point them at the Cartwheel Galaxy so their views can be compared.
mast_aladin: loads the Cartwheel Galaxy.mast_aladin_2mass: loads the Cartwheel Galaxy using the 2MASS survey.jdaviz: loads a JWST NIRCam image of the Cartwheel Galaxy.
mast_aladin = MastAladin(
target="Cartwheel Galaxy",
fov=1,
height=500
)
mast_aladin_2mass = MastAladin(
target="Cartwheel Galaxy",
fov=1,
height=500,
survey='https://alaskybis.cds.unistra.fr/2MASS/Color/'
)
uri = 'mast:JWST/product/jw02727-o002_t062_nircam_clear-f090w_i2d.fits'
jdaviz = jd.App()
jdaviz.load(uri, format="Image", cache=True)
Downloading URL https://mast.stsci.edu/api/v0.1/Download/file?uri=mast:JWST/product/jw02727-o002_t062_nircam_clear-f090w_i2d.fits to ./jw02727-o002_t062_nircam_clear-f090w_i2d.fits ...
[Done]
Display widgets: We’ll place each viewer in a sidecar so the views remain visible while you use the sync controls. Run the cell below to display the jdaviz app and both mast-aladin viewers. For more information on how this is done, please see the how to organize widgets tutorial.
# Create a sidecar
jdaviz_sc = Sidecar(title="jdaviz", anchor="split-right")
with jdaviz_sc:
jdaviz.show()
# Create a sidecar with defined anchor
mast_aladin_sc = Sidecar(title="mast_aladin", ref=jdaviz_sc, anchor="split-bottom")
with mast_aladin_sc:
display(mast_aladin)
mast_aladin_2mass_sc = Sidecar(title="mast_aladin_2mass", ref=mast_aladin_sc, anchor="split-right")
with mast_aladin_2mass_sc:
display(mast_aladin_2mass)
Register widgets: Next, we’ll register all three viewers with MastManager. This lets the Viewer Sync UI list them as possible sources and destinations.
mm = MastManager()
mm.register_app(mast_aladin, "mast_aladin")
mm.register_app(mast_aladin_2mass, "mast_aladin_2mass")
mm.register_app(jdaviz, "jdaviz")
Viewer Sync UI#
The viewers are registered and visible. Run the cell below to open the Viewer Sync UI, then choose:
Source: The widget whose viewport changes will be shared.
Destinations: One or more widgets that receive those updates.
Aspects: Center, Field of View, Rotation, and Projection.
mm.display_plugin("viewer_sync")
Exercise#
Set mast_aladin as the source and mast_aladin_2mass and jdaviz as destinations. Enable the viewport properties needed to reproduce the example below. Compare the viewers with the screenshot when you’re done.
About this Notebook#
Author(s): Patrick Custer
Keyword(s): Tutorial, mast-aladin, jdaviz, introduction, viewer sync
First published: October 2026
Last updated: October 2026
