initial implementation of astro image display api (AIDA) (#3622)

bmorris3 · web-flow · commit f1c88079c447 · 2025-07-21T16:02:26.000-04:00
* initial implementation of astro image display api (AIDA) * adapt to astropy/astro-image-display-api#56 * addressing comments on #3622 * use zoom_radius where possible * use zoom_radius in set_viewport * delay callback on set_viewport, remove changelog entry
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -33,7 +33,6 @@ New Features
 
 - Allow custom resolutions when exporting viewers to png or mp4. [#3478]
 
-
 Cubeviz
 ^^^^^^^
 
diff --git a/jdaviz/configs/default/aida.py b/jdaviz/configs/default/aida.py
@@ -0,0 +1,194 @@
+from echo import delay_callback
+
+import numpy as np
+import astropy.units as u
+from astropy.coordinates import SkyCoord, Angle
+from astropy.wcs import WCS
+from gwcs.wcs import WCS as GWCS
+
+from jdaviz.utils import get_top_layer_index
+
+
+class AID:
+    """
+    Common API methods for image viewers in astronomy, called
+    the Astro Image Display API (AIDA)[1]_.
+
+    References
+    ----------
+    .. [1] https://github.com/astropy/astro-image-display-api/
+
+    """
+
+    def __init__(self, viewer):
+        self.viewer = viewer
+        self.app = viewer.jdaviz_app
+
+    def _get_image_glue_data(self, image_label):
+        if image_label is None:
+            i_top = get_top_layer_index(self.viewer)
+            image = self.viewer.layers[i_top].layer
+
+        else:
+            for lyr in self.viewer.layers:
+                image = lyr.layer
+                if image.label == image_label:
+                    break
+            else:
+                raise ValueError(f"No data with data_label `{image_label}` found in viewer.")
+
+        return image, image.label
+
+    def set_viewport(self, center=None, fov=None, image_label=None, **kwargs):
+        """
+        Parameters
+        ----------
+        center : `~astropy.coordinates.SkyCoord` or tuple of floats
+            Center the viewer on this coordinate.
+
+        fov : `~astropy.units.Quantity` or tuple of floats
+            Set the width of the viewport to span `field_of_view`.
+
+        image_label : str
+            Set the viewport with respect to the image
+            with the data label: ``image_label``.
+        """
+        image, image_label = self._get_image_glue_data(image_label)
+        imviz_aligned_by_wcs = self.app._align_by == 'wcs'
+
+        with delay_callback(
+            self.viewer.state,
+            'x_min', 'x_max', 'y_min', 'y_max',
+            'zoom_center_x', 'zoom_center_y', 'zoom_radius'
+        ):
+            if center is not None:
+                if isinstance(center, SkyCoord):
+                    if imviz_aligned_by_wcs:
+                        (
+                            self.viewer.state.zoom_center_x,
+                            self.viewer.state.zoom_center_y
+                        ) = center.ra.degree, center.dec.degree
+                    else:
+                        reference_wcs = self.viewer.state.reference_data.coords
+
+                        if isinstance(reference_wcs, GWCS):
+                            reference_wcs = WCS(reference_wcs.to_fits_sip())
+
+                        (
+                            self.viewer.state.zoom_center_x,
+                            self.viewer.state.zoom_center_y
+                        ) = reference_wcs.world_to_pixel(center)
+
+                elif hasattr(center, '__len__') and isinstance(center[0], (float, int)):
+                    (
+                        self.viewer.state.zoom_center_x,
+                        self.viewer.state.zoom_center_y
+                    ) = center
+                else:
+                    raise ValueError(
+                        "The AID API supports `center` arguments as SkyCoords or as "
+                        f"a tuple of floats in pixel coordinates, got {center=}."
+                    )
+
+            if fov is not None:
+                if isinstance(fov, (u.Quantity, Angle)):
+                    current_fov = self._get_current_fov('sky', image_label)
+                    scale_factor = float(fov / current_fov)
+
+                elif isinstance(fov, (float, int)):
+                    current_fov = self._get_current_fov('pixel', image_label)
+                    scale_factor = float(fov / current_fov)
+
+                else:
+                    raise ValueError(
+                        f"`fov` must be a Quantity or tuple of floats, got {fov=}"
+                    )
+
+                self.viewer.state.zoom_radius = self.viewer.state.zoom_radius * scale_factor
+
+    def _mean_pixel_scale(self, data):
+        """get the mean of the x and y pixel scales from the low level wcs"""
+        wcs = data.coords
+
+        # for now, convert GWCS to FITS SIP so pixel to world
+        # transformations can be done outside of the bounding box
+        if isinstance(wcs, GWCS):
+            wcs = WCS(wcs.to_fits_sip())
+
+        abs_cdelts = u.Quantity([
+            abs(cdelt) * u.Unit(cunit)
+            for cdelt, cunit in zip(wcs.wcs.cdelt, wcs.wcs.cunit)
+        ])
+        return np.mean(abs_cdelts)
+
+    def _get_current_fov(self, sky_or_pixel, image_label):
+        imviz_aligned_by_wcs = self.app._align_by == 'wcs'
+
+        # `zoom_radius` is the distance from the center of the viewer
+        # to the nearest edge in units of pixels
+        zoom_radius = self.viewer.state.zoom_radius
+
+        # default to 'sky' if sky/pixel not specified and WCS is available:
+        if sky_or_pixel in (None, 'sky'):
+            if not imviz_aligned_by_wcs:
+                ref_data, _ = self._get_image_glue_data(image_label)
+                pixel_scale = self._mean_pixel_scale(ref_data)
+                return pixel_scale * 2 * zoom_radius * u.deg
+            else:
+                return 2 * zoom_radius * u.deg
+
+        return 2 * zoom_radius
+
+    def _get_current_center(self, sky_or_pixel, image_label=None):
+        # center pixel coordinates on the reference data:
+        center_x = self.viewer.state.zoom_center_x
+        center_y = self.viewer.state.zoom_center_y
+
+        if self.app._align_by == 'wcs':
+            reference_data = self.viewer.state.reference_data
+        else:
+            reference_data, image_label = self._get_image_glue_data(image_label)
+
+        reference_wcs = reference_data.coords
+
+        # # if the image data have WCS, get the center sky coordinate:
+        if sky_or_pixel == 'sky':
+            if self.app._align_by == 'wcs':
+                center = self.viewer._get_center_skycoord()
+            else:
+                center = reference_wcs.pixel_to_world(center_x, center_y)
+        else:
+            center = (center_x, center_y)
+
+        return center
+
+    def get_viewport(self, sky_or_pixel=None, image_label=None, **kwargs):
+        """
+        sky_or_pixel : str, optional
+            If 'sky', the center will be returned as a `SkyCoord` object.
+            If 'pixel', the center will be returned as a tuple of pixel coordinates.
+            If `None`, the default behavior is to return the center as a `SkyCoord` if
+            possible, or as a tuple of floats if the image is in pixel coordinates and has
+            no WCS information.
+
+        image_label : str, optional
+            The label of the image to get the viewport for. If not given and there is only one
+            image loaded, the viewport for that image is returned. If there are multiple images
+            and no label is provided, an error is raised.
+
+        Returns
+        -------
+        dict
+            A dictionary containing the current viewport settings.
+            The keys are 'center', 'fov', and 'image_label'.
+            - 'center' is an `astropy.coordinates.SkyCoord` object or a tuple of floats.
+            - 'fov' is an `astropy.units.Quantity` object or a float.
+            - 'image_label' is a string representing the label of the image.
+        """
+        image, image_label = self._get_image_glue_data(image_label)
+
+        return dict(
+            center=self._get_current_center(sky_or_pixel=sky_or_pixel, image_label=image_label),
+            fov=self._get_current_fov(sky_or_pixel=sky_or_pixel, image_label=image_label),
+            image_label=image_label
+        )
diff --git a/jdaviz/configs/default/tests/test_aida.py b/jdaviz/configs/default/tests/test_aida.py
@@ -0,0 +1,85 @@
+import pytest
+import numpy as np
+import astropy.units as u
+from astropy.coordinates import SkyCoord
+from astropy.wcs import WCS
+from astropy.tests.helper import assert_quantity_allclose
+
+
+def assert_coordinate_close(coord1, coord2, atol=1 * u.arcsec):
+    # check that two coordinates are within some separation tolerance
+    separation = coord1.separation(coord2)
+    assert_quantity_allclose(separation, desired=0*u.arcsec, atol=atol)
+
+
+def assert_angle_close(angle1, angle2, atol=1 * u.arcsec):
+    # check that two angles are within some separation tolerance
+    difference = abs(angle1 - angle2)
+    assert_quantity_allclose(difference, desired=0*u.arcsec, atol=atol)
+
+
+def test_get_viewport_sky(imviz_helper, image_hdu_wcs):
+    imviz_helper.load_data(image_hdu_wcs)
+    imviz_helper.plugins['Orientation'].align_by = 'WCS'
+
+    viewer = imviz_helper.app.get_viewer('imviz-0')
+    viewport = viewer.aid.get_viewport('sky')
+
+    expected_center = SkyCoord(ra=337.51894337, dec=-20.83208305, unit='deg')
+    expected_fov = 0.00277778 * u.deg
+    expected_image_label = imviz_helper.app.data_collection[0].label
+
+    # by default, the viewer y-axis is the narrower axis, which is used to
+    # define the FOV parameter. Use the WCS to find what the actual
+    # viewport dimensions are in the x-axis, which maps onto RA in this case:
+    wcs = WCS(image_hdu_wcs.header)
+    dec_unit = u.Unit(wcs.wcs.cunit[1])
+    delta_dec = abs(wcs.wcs.cdelt[1]) * dec_unit
+    expected_fov = (
+        abs(viewer.state.y_max - viewer.state.y_min) * delta_dec
+    )
+    assert_coordinate_close(viewport['center'], expected_center)
+    assert_angle_close(viewport['fov'], expected_fov)
+
+    assert viewport['image_label'] == expected_image_label
+
+
+def test_set_viewport_sky(imviz_helper, image_hdu_wcs):
+    imviz_helper.load_data(image_hdu_wcs)
+    imviz_helper.plugins['Orientation'].align_by = 'WCS'
+    viewer = imviz_helper.app.get_viewer('imviz-0')
+
+    # change only the center:
+    new_viewport_settings = dict(
+        center=SkyCoord(ra=337.5, dec=-20.8, unit='deg'),
+        fov=0.01 * u.deg
+    )
+    viewer.aid.set_viewport(**new_viewport_settings)
+    new_viewport = viewer.aid.get_viewport('sky')
+
+    assert_coordinate_close(new_viewport['center'], new_viewport_settings['center'])
+
+    # todo: investigate why this tolerance needs to be larger than expected:
+    assert_angle_close(new_viewport['fov'], new_viewport_settings['fov'], atol=1 * u.arcsec)
+
+    with pytest.raises(ValueError, match='The AID API supports `center` arguments as'):
+        viewer.aid.set_viewport(center=u.Quantity([0, 1]))
+
+
+def test_set_viewport_pixel(imviz_helper, image_hdu_wcs):
+    imviz_helper.load_data(image_hdu_wcs)
+
+    viewer = imviz_helper.app.get_viewer('imviz-0')
+
+    # change only the center:
+    new_viewport_settings = dict(
+        center=[5, 5],
+        fov=10
+    )
+    viewer.aid.set_viewport(**new_viewport_settings)
+    new_viewport = viewer.aid.get_viewport('pixel')
+
+    np.testing.assert_allclose(new_viewport['center'], new_viewport_settings['center'])
+
+    # todo: investigate why this tolerance needs to be larger than expected:
+    np.testing.assert_allclose(new_viewport['fov'], new_viewport_settings['fov'], atol=1e-4)
diff --git a/jdaviz/configs/imviz/plugins/viewers.py b/jdaviz/configs/imviz/plugins/viewers.py
@@ -7,6 +7,7 @@
 from glue_jupyter.bqplot.image import BqplotImageView
 
 from jdaviz.configs.imviz import wcs_utils
+from jdaviz.configs.default import aida
 from jdaviz.core.astrowidgets_api import AstrowidgetsImageViewerMixin
 from jdaviz.core.events import SnackbarMessage
 from jdaviz.core.registries import viewer_registry
@@ -66,6 +67,7 @@ def __init__(self, *args, **kwargs):
         self.state.image_external_padding = 0.5
 
         self.data_menu._obj.dataset.add_filter('is_image')
+        self.aid = aida.AID(self)
 
     def on_mouse_or_key_event(self, data):
         active_image_layer = self.active_image_layer
diff --git a/notebooks/concepts/aida.ipynb b/notebooks/concepts/aida.ipynb

-Original file line number
+Diff line change
 - Allow custom resolutions when exporting viewers to png or mp4. [#3478]
+-
 Cubeviz
 ^^^^^^^