Add set/get viewport on image_label to interface definition

Author: mwcraig

src/astro_image_display_api/interface_definition.py

@@ -30,7 +30,6 @@ class ImageViewerInterface(Protocol):
     # do any checking at all of these types.
     image_width: int
     image_height: int
-    zoom_level: float
     cursor: str
     marker: Any
 
@@ -47,7 +46,7 @@ class ImageViewerInterface(Protocol):
 
     # Method for loading image data
     @abstractmethod
-    def load_image(self, data: Any) -> None:
+    def load_image(self, data: Any, image_label: str | None = None) -> None:
         """
         Load data into the viewer. At a minimum, this should allow a FITS file
         to be loaded. Viewers may allow additional data types to be loaded, such as
@@ -217,42 +216,71 @@ def get_markers(self, x_colname: str = 'x', y_colname: str = 'y',
 
     # Methods that modify the view
     @abstractmethod
-    def center_on(self, point: tuple | SkyCoord):
+    def set_viewport(
+        self, center: SkyCoord | tuple[float, float] | None = None,
+        fov: Quantity | float | None = None,
+        image_label: str | None = None
+    ) -> None:
         """
-        Center the view on the point.
+        Set the viewport of the image, which defines the center and field of viea.
 
         Parameters
         ----------
-        tuple or `~astropy.coordinates.SkyCoord`
-            If tuple of ``(X, Y)`` is given, it is assumed
-            to be in data coordinates.
+        center : `astropy.coordinates.SkyCoord` or tuple of float, optional
+            The center of the viewport. If not given, the current center is used.
+        fov : `astropy.units.Quantity` or float, optional
+            The field of view (FOV) of the viewport. If not given, the current FOV
+            is used. If a float is given, it is interpreted a size in pixels.
+        image_label : str, optional
+            The label of the image to set the viewport for. If not given and there is
+            only one image loaded, the viewport for that image is set. If there are
+            multiple images and no label is provided, an error is raised.
+
+        Raises
+        ------
+        TypeError
+            If the `center` is not a `SkyCoord` object or a tuple of floats, or if
+            the `fov` is not a angular `Quantity` or a float
+
+        ValueError
+            If `image_label` is not provided when there are multiple images loaded.
+
+        `astropy.units.UnitTypeError`
+            If the `fov` is a `Quantity` but does not have an angular unit.
         """
         raise NotImplementedError
 
     @abstractmethod
-    def offset_by(self, dx: float | Quantity, dy: float | Quantity) -> None:
+    def get_viewport(self, sky_or_pixel: str | None = None, image_label: str | None = None) -> dict[str, Any]:
         """
-        Move the center to a point that is given offset
-        away from the current center.
+        Get the current viewport of the image.
 
         Parameters
         ----------
-        dx, dy : float or `~astropy.units.Quantity`
-            Offset value. Without a unit, assumed to be pixel offsets.
-            If a unit is attached, offset by pixel or sky is assumed from
-            the unit.
-        """
-        raise NotImplementedError
-
-    @abstractmethod
-    def zoom(self, val: float) -> None:
-        """
-        Zoom in or out by the given factor.
+        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.
 
-        Parameters
-        ----------
-        val : float
-            The zoom level to zoom the image.
-            See `zoom_level`.
+        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.
+
+        Raises
+        -------
+        ValueError
+            If the `sky_or_pixel` parameter is not one of 'sky', 'pixel', or `None`, or if
+            the `image_label` is not provided when there are multiple images loaded.
         """
         raise NotImplementedError