Merge pull request #20 from DougBurke/change-api

Handle the URL return type

Author: DougBurke

CHANGELOG.md

@@ -1,10 +1,15 @@
 # Changes for ds9samp
 
-## Version 0.0.9 - 2025-01-30
+## Version 0.1.0 - 2025-02-06
 
-Minor linting changes. There is no change to functionality.
+Add the `get_raw` routine which does not try to read in the data
+stored in the URL response. Improved the handling of data from the
+DATA, PIXELTABLE, and REGION commands (when used with `get`) by
+returning a FITS HDUList or NumPy array instead of a string. Added the
+`get_image_info` method to return basic information about the current
+image.
 
-Let's try ruff for code formatting.
+Let's try ruff for linting and code formatting.
 
 ## Version 0.0.8 - 2025-01-30
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ds9samp"
-version = "0.0.9"
+version = "0.1.0"
 authors = [
   { name = "Douglas Burke", email="[email protected]" }
 ]

src/ds9samp/__init__.py

@@ -31,8 +31,8 @@
         ds9.set("zscale")
         ds9.set("cmap viridis")
 
-The get method will return a value (as a string or None if there is
-no response).
+The get method will return a value (as a string, FITS HDUList, NumPy
+array, or None if there is no response).
 
 Syntax errors are displayed as a screen message (to stdout) but they
 do not stop the connection. Lower-level errors - such as the DS9
@@ -155,9 +155,11 @@
 """
 
 from contextlib import contextmanager
+from dataclasses import dataclass
 from enum import Enum
 import importlib.metadata
 import os
+from pathlib import Path
 import sys
 import tempfile
 from typing import Protocol
@@ -202,6 +204,16 @@ class Cube(Enum):
     "Data is stored in Hue, Saturation, Value order."
 
 
+@dataclass(frozen=True)
+class ImgInfo:
+    """Metadata about the image."""
+
+    dtype: np.dtype
+    """The datatype."""
+    shape: tuple[int, ...]
+    """The size of the image. It is expected to be 2D or 3D."""
+
+
 def add_color(txt):
     """Allow ANSI color escape codes unless NO_COLOR env var is set
     or sys.stderr is not a TTY.
@@ -289,7 +301,16 @@ def warning(msg: str) -> None:
     print(f"{lhs} {msg}")
 
 
-def extract_url(url: str) -> str | None:
+def read_array(path: str | Path, img: ImgInfo) -> np.ndarray:
+    """Read in an array from a file."""
+
+    fp = np.memmap(path, mode="r", dtype=img.dtype, shape=img.shape)
+    return fp[:]
+
+
+def extract_url(
+    url: str, img: ImgInfo | None
+) -> str | np.ndarray | fits.HDUList | None:
     """Read in the URL and return the values.
 
     It relies on heuristics to determine the type of the data pointed
@@ -307,18 +328,38 @@ def extract_url(url: str) -> str | None:
         error(f"expected file url, not {url}")
         return None
 
-    if res.path.endswith(".dat"):
+    # Look at all the DS9 samp commands at
+    # https://ds9.si.edu/doc/ref/samp.html
+    # that have an example of "string url = ds9.get(string cmd):
+    #
+    #   command     suffix     encoding
+    #   -------     ------     --------
+    #   array       .arr       binary
+    #   data        .dat.dat   ascii
+    #   pixeltable  .pix.txt   ascii
+    #   region      .reg.rgn   ascii
+    #
+    # Not included on this page are
+    #
+    #   command     suffix     encoding
+    #   -------     ------     --------
+    #   fits        .fits      FITS
+    #
+    #
+    if any(res.path.endswith(f".{end}") for end in ["dat", "rgn", "txt"]):
         # What's the best encoding?
         with open(res.path, mode="rt", encoding="ascii") as fh:
             return fh.read()
 
     if res.path.endswith(".fits"):
-        # Should this extract the data (assuming the input is an
-        # image)? Also, how do we convert to a string?
-        #
-        # return fits.open(res.path)
-        error("Unable to convert FITS file to a string")
-        return None
+        return fits.open(res.path)
+
+    if res.path.endswith(".arr"):
+        if img is None:
+            error("Sent array but no image data")
+            return None
+
+        return read_array(res.path, img)
 
     error(f"Unable to determine contents of {url}")
     return None
@@ -348,15 +389,17 @@ def __str__(self) -> str:
 
         return f"Connection to DS9 {version} (client {self.client})"
 
-    def _get(
+    def get_raw(
         self, command: str, timeout: int | None = None
-    ) -> str | dict[str, str]:
+    ) -> dict[str, str] | None:
         """Call ds9.get for the given command and arguments.
 
         If the call fails then an error message is displayed (to
         stdout) and None is returned. This call will raise an error if
         there is a SAMP commmunication problem.
 
+        .. versionadded:: 0.1.0
+
         Parameters
         ----------
         command
@@ -369,7 +412,12 @@ def _get(
         -------
         retval
            The dictionary represents the 'samp.result' field of the
-           query, and may be empty.
+           query, and may be empty. It will be None if there was an
+           error with the call.
+
+        See Also
+        --------
+        get
 
         """
 
@@ -400,7 +448,9 @@ def _get(
 
         return out["samp.result"]
 
-    def get(self, command: str, timeout: int | None = None) -> str | None:
+    def get(
+        self, command: str, timeout: int | None = None
+    ) -> str | np.ndarray | fits.HDUList | None:
         """Call ds9.get for the given command and arguments.
 
         If the call fails then an error message is displayed (to
@@ -426,14 +476,21 @@ def get(self, command: str, timeout: int | None = None) -> str | None:
            The return value, as a string, or None if there was no
            return value.
 
+        See Also
+        --------
+        get_raw, set
+
         """
 
         # The result is assumed to be one of:
         #  - the value field
         #  - the url field
         #  - otherwise we just return None
         #
-        result = self._get(command=command, timeout=timeout)
+        result = self.get_raw(command=command, timeout=timeout)
+        if result is None:
+            return None
+
         value = result.get("value")
         if value is not None:
             return value
@@ -446,10 +503,78 @@ def get(self, command: str, timeout: int | None = None) -> str | None:
             if self.debug:
                 debug(f"DS9 returned data in URL={url}")
 
-            return extract_url(url)
+            # In order to interpret the data from an array call
+            # we need extra information. This would be easier if
+            # it was sent in-band (i.e. as part of the response).
+            # Are there other cases it is needed?
+            #
+            if command.startswith("array"):
+                img = self.get_image_info(timeout=timeout)
+                if img is None:
+                    # Return an empty array
+                    return np.zeros(0)
+
+            else:
+                img = None
+
+            return extract_url(url, img=img)
 
         return None
 
+    def get_image_info(self, timeout: int | None = None) -> ImgInfo | None:
+        """Return information on the current image.
+
+        Parameters
+        ----------
+        timeout: optional
+           Over-ride the default timeout setting. Use 0 to remove
+           any timeout.
+
+        Returns
+        -------
+        img
+           A structure describing the current image, or None if
+           there is none.
+
+        """
+
+        # These values should convert, so do not try to improve the
+        # error handling.
+        #
+        def convert(arg: str) -> int:
+            result = self.get_raw(f"fits {arg}", timeout=timeout)
+            if result is None:
+                return 0
+
+            value = result.get("value")
+            if value is None:
+                return 0
+
+            return int(value)
+
+        bitpix = convert("bitpix")
+        nx = convert("width")
+        ny = convert("height")
+        nz = convert("depth")
+
+        if nx == 0 or ny == 0:
+            return None
+
+        dtype = bitpix_to_dtype(bitpix)
+        if dtype is None:
+            if self.debug:
+                debug(f"Unsupported BITPIX: {bitpix}")
+
+            return None
+
+        shape: tuple[int, ...]
+        if nz > 1:
+            shape = (nz, ny, nx)
+        else:
+            shape = (ny, nx)
+
+        return ImgInfo(dtype, shape)
+
     def set(self, command: str, timeout: int | None = None) -> None:
         """Call ds9.set for the given command and arguments.
 
@@ -466,6 +591,10 @@ def set(self, command: str, timeout: int | None = None) -> None:
            Over-ride the default timeout setting. Use 0 to remove
            any timeout.
 
+        See Also
+        --------
+        set
+
         """
 
         # Use ecall_and_wait to
@@ -702,41 +831,17 @@ def retrieve_array(
         # Get the data information before creating the temporary file.
         # Do we have to worry about WCS messing around with the units?
         #
-        # These values should convert, so do not try to improve the
-        # error handling.
-        #
-        def convert(arg):
-            val = self.get(f"fits {arg}")
-            if val is None:
-                return 0
-            return int(val)
-
-        bitpix = convert("bitpix")
-        nx = convert("width")
-        ny = convert("height")
-        nz = convert("depth")
-
-        if nx == 0 or ny == 0:
+        img = self.get_image_info(timeout=timeout)
+        if img is None:
+            # We could return an empty array, but is it worth it?
             error("DS9 appears to contain no data")
             return None
 
-        dtype = bitpix_to_dtype(bitpix)
-        if dtype is None:
-            error(f"Unsupported BITPIX: {bitpix}")
-            return None
-
-        shape: tuple[int, ...]
-        if nz > 1:
-            shape = (nz, ny, nx)
-        else:
-            shape = (ny, nx)
-
         with tempfile.NamedTemporaryFile(prefix="ds9samp", suffix=".arr") as fh:
             cmd = f"export array {fh.name} native"
             self.set(cmd, timeout=timeout)
 
-            fp = np.memmap(fh.name, dtype=dtype, mode="r", shape=shape)
-            out = fp[:]
+            out = read_array(fh.name, img)
 
         return out
 
@@ -837,7 +942,10 @@ def retrieve_fits(
         # The result is assumed to be given by the url field.
         # Any other response is an error.
         #
-        result = self._get(command="fits", timeout=timeout)
+        result = self.get_raw(command="fits", timeout=timeout)
+        if result is None:
+            return None
+
         url = result.get("url")
         if url is None:
             error("SAMP call returned unexpected data")
@@ -916,7 +1024,9 @@ def send_cat(
                         "data mut be a table, not image(s)"
                     ) from None
 
-                data.writeto(fh, overwrite=True, output_verify="fix+warn")
+                data.writeto(
+                    fh, overwrite=True, output_verify="fix+warn", checksum=True
+                )
 
             cmd = f"catalog import fits {fh.name}"
             self.set(cmd, timeout=timeout)