fitsview 0.1.0__py3-none-any.whl

fitsview/__init__.py

@@ -0,0 +1,30 @@
+try:
+    from ._version import __version__
+except ImportError:
+    # Fallback when using the package in dev mode without installing
+    # in editable mode with pip. It is highly recommended to install
+    # the package from a stable release or in editable mode: https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs
+    import warnings
+    warnings.warn("Importing 'fitsview' outside a proper installation.")
+    __version__ = "dev"
+
+from .handlers import setup_handlers
+
+
+def _jupyter_labextension_paths():
+    return [{
+        "src": "labextension",
+        "dest": "fitsview"
+    }]
+
+
+def _jupyter_server_extension_points():
+    return [{
+        "module": "fitsview"
+    }]
+
+
+def _load_jupyter_server_extension(server_app):
+    """Register the API handlers."""
+    setup_handlers(server_app.web_app)
+    server_app.log.info("Registered fitsview server extension")

fitsview/_version.py

@@ -0,0 +1,4 @@
+# This file is auto-generated by Hatchling. As such, do not:
+#   - modify
+#   - track in version control e.g. be sure to add to .gitignore
+__version__ = VERSION = '0.1.0'

fitsview/handlers.py

@@ -0,0 +1,248 @@
+"""
+API handlers for FITS file operations.
+"""
+
+import json
+import tornado
+from enum import Enum
+from jupyter_server.base.handlers import APIHandler, JupyterHandler
+from jupyter_server.utils import url_path_join
+from astropy.io import fits
+import numpy as np
+
+
+class ArrayType(str, Enum):
+    """
+    Enum mapping numpy dtypes to Rust-style type specifiers.
+
+    Uses dtype.kind and dtype.itemsize to unambiguously determine the type,
+    avoiding string comparison issues with numpy's various dtype representations.
+
+    Values use Rust-style type names for consistency across the wire protocol.
+    """
+    INT8 = "i8"
+    UINT8 = "u8"
+    INT16 = "i16"
+    UINT16 = "u16"
+    INT32 = "i32"
+    UINT32 = "u32"
+    INT64 = "i64"
+    UINT64 = "u64"
+    FLOAT32 = "f32"
+    FLOAT64 = "f64"
+
+
+def numpy_dtype_to_array_type(dtype: np.dtype) -> ArrayType:
+    """
+    Map a numpy dtype to an ArrayType based on kind and itemsize.
+
+    dtype.kind values:
+      'b' - boolean
+      'i' - signed integer
+      'u' - unsigned integer
+      'f' - floating-point
+      'c' - complex floating-point
+      'S', 'a' - byte string
+      'U' - unicode string
+      'V' - void (raw data)
+    """
+    kind = dtype.kind
+    size = dtype.itemsize
+
+    if kind == 'i':  # Signed integer
+        if size == 1:
+            return ArrayType.INT8
+        elif size == 2:
+            return ArrayType.INT16
+        elif size == 4:
+            return ArrayType.INT32
+        elif size == 8:
+            return ArrayType.INT64
+    elif kind == 'u':  # Unsigned integer
+        if size == 1:
+            return ArrayType.UINT8
+        elif size == 2:
+            return ArrayType.UINT16
+        elif size == 4:
+            return ArrayType.UINT32
+        elif size == 8:
+            return ArrayType.UINT64
+    elif kind == 'f':  # Floating-point
+        if size == 4:
+            return ArrayType.FLOAT32
+        elif size == 8:
+            return ArrayType.FLOAT64
+    elif kind == 'b':  # Boolean - treat as uint8
+        return ArrayType.UINT8
+
+    # Default to float64 for unsupported types
+    return ArrayType.FLOAT64
+
+
+class FITSMetadataHandler(APIHandler):
+    """Handler for retrieving FITS file metadata (headers, dimensions)."""
+
+    @tornado.web.authenticated
+    async def get(self):
+        path = self.get_argument('path')
+
+        # Validate path exists via Contents API
+        cm = self.contents_manager
+        try:
+            await cm.get(path, content=False)
+        except Exception as e:
+            self.set_status(404)
+            self.finish(json.dumps({'error': f'File not found: {path}'}))
+            return
+
+        # Get filesystem path for astropy
+        os_path = cm._get_os_path(path)
+
+        try:
+            with fits.open(os_path) as hdul:
+                hdus = []
+                for i, hdu in enumerate(hdul):
+                    # Use repr() to get the raw 80-column card format with newlines
+                    # str() returns an object description, repr() returns the actual content
+                    header_str = repr(hdu.header)
+
+                    hdu_info = {
+                        'index': i,
+                        'name': hdu.name,
+                        'type': hdu.__class__.__name__,
+                        'header': header_str,  # Raw 80-column format string
+                    }
+                    if hdu.data is not None:
+                        hdu_info['shape'] = list(hdu.data.shape)
+                        # Use ArrayType enum for consistent type representation
+                        hdu_info['arrayType'] = numpy_dtype_to_array_type(hdu.data.dtype).value
+                    else:
+                        hdu_info['shape'] = None
+                        hdu_info['arrayType'] = None
+                    hdus.append(hdu_info)
+
+                result = {
+                    'path': path,
+                    'hdus': hdus
+                }
+                self.finish(json.dumps(result))
+        except Exception as e:
+            self.set_status(500)
+            self.finish(json.dumps({'error': f'Error reading FITS file: {str(e)}'}))
+
+
+class FITSSliceHandler(JupyterHandler):
+    """Handler for retrieving data slices from FITS files.
+
+    Uses JupyterHandler instead of APIHandler to support binary responses.
+
+    The slices parameter uses NumPy/Python conventions:
+    - Zero-indexed
+    - Axis order matches NumPy (e.g., for 3D data: z,y,x or depth,row,col)
+    - Half-open intervals [start, stop) with exclusive upper bound
+    - Format: "start:stop,start:stop,..." for each axis
+    """
+
+    @tornado.web.authenticated
+    async def get(self):
+        path = self.get_argument('path')
+        hdu = int(self.get_argument('hdu', 0))
+        slices_str = self.get_argument('slices')  # e.g., "0:10,5:15" for 2D
+
+        # Parse slices parameter
+        try:
+            slice_tuples = []
+            for s in slices_str.split(','):
+                parts = s.strip().split(':')
+                if len(parts) != 2:
+                    raise ValueError(f"Invalid slice format: '{s}'. Expected 'start:stop'.")
+                start, stop = int(parts[0]), int(parts[1])
+                if start < 0 or stop < 0:
+                    raise ValueError(f"Negative indices not supported: '{s}'")
+                if start >= stop:
+                    raise ValueError(f"Start must be less than stop: '{s}'")
+                slice_tuples.append((start, stop))
+        except ValueError as e:
+            self.set_status(400)
+            self.finish(json.dumps({'error': str(e)}))
+            return
+
+        # Validate path exists via Contents API
+        cm = self.contents_manager
+        try:
+            await cm.get(path, content=False)
+        except Exception as e:
+            self.set_status(404)
+            self.finish(json.dumps({'error': f'File not found: {path}'}))
+            return
+
+        # Get filesystem path for astropy
+        os_path = cm._get_os_path(path)
+
+        try:
+            with fits.open(os_path) as hdul:
+                if hdu >= len(hdul):
+                    self.set_status(400)
+                    self.finish(json.dumps({
+                        'error': f'HDU index {hdu} out of range (file has {len(hdul)} HDUs)'
+                    }))
+                    return
+
+                data = hdul[hdu].data
+                if data is None:
+                    self.set_status(400)
+                    self.finish(json.dumps({
+                        'error': f'HDU {hdu} has no data'
+                    }))
+                    return
+
+                # Validate number of slice dimensions matches data dimensions
+                if len(slice_tuples) != len(data.shape):
+                    self.set_status(400)
+                    self.finish(json.dumps({
+                        'error': f'Number of slice dimensions ({len(slice_tuples)}) does not match '
+                                 f'data dimensions ({len(data.shape)}). Data shape: {list(data.shape)}'
+                    }))
+                    return
+
+                # Validate slice bounds for each axis
+                for axis, ((start, stop), size) in enumerate(zip(slice_tuples, data.shape)):
+                    if stop > size:
+                        self.set_status(400)
+                        self.finish(json.dumps({
+                            'error': f'Slice [{start}:{stop}] on axis {axis} out of bounds '
+                                     f'for dimension size {size}. Data shape: {list(data.shape)}'
+                        }))
+                        return
+
+                # Build the slice tuple and extract data
+                numpy_slices = tuple(slice(start, stop) for start, stop in slice_tuples)
+                slice_data = data[numpy_slices]
+
+                # Convert to little-endian for JavaScript TypedArray compatibility
+                le_dtype = slice_data.dtype.newbyteorder('<')
+                slice_bytes = slice_data.astype(le_dtype).tobytes()
+
+                # Use ArrayType enum for consistent type representation
+                array_type = numpy_dtype_to_array_type(slice_data.dtype)
+
+                self.set_header('Content-Type', 'application/octet-stream')
+                self.set_header('X-FITS-Shape', json.dumps(list(slice_data.shape)))
+                self.set_header('X-FITS-Type', array_type.value)
+                self.finish(slice_bytes)
+
+        except Exception as e:
+            self.set_status(500)
+            self.finish(json.dumps({'error': f'Error reading FITS data: {str(e)}'}))
+
+
+def setup_handlers(web_app):
+    """Register FITS API handlers."""
+    host_pattern = '.*$'
+    base_url = web_app.settings['base_url']
+
+    handlers = [
+        (url_path_join(base_url, 'fitsview', 'metadata'), FITSMetadataHandler),
+        (url_path_join(base_url, 'fitsview', 'slice'), FITSSliceHandler),
+    ]
+    web_app.add_handlers(host_pattern, handlers)

fitsview/tests/__init__.py

@@ -0,0 +1 @@
+# fitsview tests package

fitsview/tests/generate_files.py

@@ -0,0 +1,51 @@
+from astropy.io import fits
+import math
+import numpy as np
+import pathlib
+import sys
+
+
+if __name__ == "__main__":
+    dest = pathlib.Path(sys.argv[1])
+    if not dest.is_dir():
+        raise RuntimeError(f"Make sure the directory {sys.argv[1]} exists for the destination")
+    rng = np.random.default_rng(seed=0)
+    # cases to cover:
+    # - simple 2D image
+    simple_2d = rng.random((16, 16))
+    fits.PrimaryHDU(simple_2d).writeto(dest / 'simple_2d.fits', overwrite=True)
+    # - simple 2D image (integers)
+    simple_2d_uints = (1000 * rng.random((16, 16))).astype(np.uint16)
+    fits.PrimaryHDU(simple_2d_uints).writeto(dest / 'simple_2d_uints.fits', overwrite=True)
+    # - simple 2D image > 5MB
+    min_bytes = 5.5e6
+    bytes_per_double = 4
+    npix_per_side = math.ceil(math.sqrt(min_bytes / bytes_per_double))
+    big_2d = rng.random((npix_per_side, npix_per_side), dtype=np.float64)
+    assert big_2d.nbytes >= min_bytes
+    fits.PrimaryHDU(big_2d).writeto(dest / 'big_2d.fits', overwrite=True)
+    # - 3D data cube
+    simple_3d = rng.random((5, 16, 16))
+    fits.PrimaryHDU(simple_3d).writeto(dest / 'simple_3d.fits', overwrite=True)
+    # - 3D data cube where 1 plane > 5 MB
+    big_3d = rng.random((5, npix_per_side, npix_per_side), dtype=np.float64)
+    assert big_3d[0].nbytes >= min_bytes
+    fits.PrimaryHDU(big_3d).writeto(dest / 'big_3d.fits', overwrite=True)
+    # - 4D hypercube
+    simple_4d = rng.random((4, 5, 16, 16))
+    fits.PrimaryHDU(simple_4d).writeto(dest / 'simple_4d.fits', overwrite=True)
+    # - file with no image extensions
+    table_hdu = fits.TableHDU(np.ones((10,), dtype=[('x', float), ('y', float)]), name='TABLE')
+    table_hdu.writeto(dest / 'no_image.fits', overwrite=True)
+    # - file with multiple extensions
+    fits.HDUList([
+        fits.PrimaryHDU(),
+        fits.ImageHDU(simple_4d, name='FOURDEE'),
+        table_hdu,
+    ]).writeto(dest / 'multi_ext.fits', overwrite=True)
+    # - file with multiple *image* extensions
+    fits.HDUList([
+        fits.PrimaryHDU(),
+        fits.ImageHDU(simple_4d, name='FOURDEE'),
+        fits.ImageHDU(simple_3d, name='THREEDEE')
+    ]).writeto(dest / 'multi_image_ext.fits', overwrite=True)

fitsview/tests/test_handlers.py

@@ -0,0 +1,298 @@
+"""Tests for FITS API handlers."""
+
+import json
+
+import numpy as np
+import pytest
+from astropy.io import fits
+
+
+@pytest.fixture
+def fits_file(jp_root_dir):
+    """Create a test FITS file with multiple HDUs."""
+    # Primary HDU with float32 data
+    primary_data = np.arange(100, dtype=np.float32).reshape(10, 10)
+    primary_hdu = fits.PrimaryHDU(primary_data)
+    primary_hdu.header["OBJECT"] = "Test Object"
+    primary_hdu.header["TELESCOP"] = "Test Telescope"
+
+    # Image extension with int16 data
+    int16_data = np.arange(50, dtype=np.int16).reshape(5, 10)
+    image_hdu = fits.ImageHDU(int16_data, name="SCI")
+    image_hdu.header["EXTNAME"] = "SCI"
+
+    # Table extension
+    col1 = fits.Column(name="ID", format="J", array=np.array([1, 2, 3]))
+    col2 = fits.Column(name="NAME", format="10A", array=np.array(["a", "b", "c"]))
+    table_hdu = fits.BinTableHDU.from_columns([col1, col2], name="TABLE")
+
+    hdul = fits.HDUList([primary_hdu, image_hdu, table_hdu])
+
+    fits_path = jp_root_dir / "test_data.fits"
+    hdul.writeto(fits_path, overwrite=True)
+    hdul.close()
+
+    return "test_data.fits"
+
+
+@pytest.fixture
+def float64_fits_file(jp_root_dir):
+    """Create a test FITS file with float64 data."""
+    data = np.array([[1.5, 2.5], [3.5, 4.5]], dtype=np.float64)
+    hdu = fits.PrimaryHDU(data)
+    hdul = fits.HDUList([hdu])
+
+    fits_path = jp_root_dir / "float64_test.fits"
+    hdul.writeto(fits_path, overwrite=True)
+    hdul.close()
+
+    return "float64_test.fits"
+
+
+@pytest.fixture
+def cube_fits_file(jp_root_dir):
+    """Create a test FITS file with 3D data cube."""
+    # 3D cube: 4 planes of 5x6 data
+    data = np.arange(120, dtype=np.float32).reshape(4, 5, 6)
+    hdu = fits.PrimaryHDU(data)
+    hdul = fits.HDUList([hdu])
+
+    fits_path = jp_root_dir / "cube_test.fits"
+    hdul.writeto(fits_path, overwrite=True)
+    hdul.close()
+
+    return "cube_test.fits"
+
+
+class TestMetadataHandler:
+    """Tests for the FITSMetadataHandler."""
+
+    async def test_get_metadata(self, jp_fetch, fits_file):
+        """Test retrieving metadata from a FITS file."""
+        response = await jp_fetch("fitsview", "metadata", params={"path": fits_file})
+
+        assert response.code == 200
+        data = json.loads(response.body)
+
+        assert data["path"] == fits_file
+
+        # Check primary HDU
+        hdus = data["hdus"]
+        assert len(hdus) == 3
+
+        primary = hdus[0]
+        assert primary["index"] == 0
+        assert primary["name"] == "PRIMARY"
+        assert primary["type"] == "PrimaryHDU"
+        assert primary["shape"] == [10, 10]
+        # arrayType is now a Rust-style type specifier
+        assert primary["arrayType"] == "f32"
+        # header is returned as raw 80-column FITS format string
+        assert "OBJECT" in primary["header"]
+        assert "Test Object" in primary["header"]
+        assert "TELESCOP" in primary["header"]
+        assert "Test Telescope" in primary["header"]
+
+        # Check image extension
+        sci = hdus[1]
+        assert sci["index"] == 1
+        assert sci["name"] == "SCI"
+        assert sci["type"] == "ImageHDU"
+        assert sci["shape"] == [5, 10]
+        assert sci["arrayType"] == "i16"
+
+        # Check table extension
+        table = hdus[2]
+        assert table["index"] == 2
+        assert table["name"] == "TABLE"
+        assert table["type"] == "BinTableHDU"
+
+    async def test_metadata_file_not_found(self, jp_fetch):
+        """Test that 404 is returned for non-existent files."""
+        response = await jp_fetch(
+            "fitsview",
+            "metadata",
+            params={"path": "nonexistent.fits"},
+            raise_error=False,
+        )
+
+        assert response.code == 404
+        data = json.loads(response.body)
+        assert "error" in data
+        assert "not found" in data["error"].lower()
+
+
+class TestSliceHandler:
+    """Tests for the FITSSliceHandler."""
+
+    async def test_get_slice_float32(self, jp_fetch, fits_file):
+        """Test retrieving a slice of float32 data."""
+        # 2D data with shape [10, 10], slice rows 0:2, cols 0:3
+        response = await jp_fetch(
+            "fitsview",
+            "slice",
+            params={"path": fits_file, "hdu": "0", "slices": "0:2,0:3"},
+        )
+
+        assert response.code == 200
+        assert response.headers["Content-Type"] == "application/octet-stream"
+
+        # Check shape header
+        shape = json.loads(response.headers["X-FITS-Shape"])
+        assert shape == [2, 3]
+
+        # Check type header - should be f32 (Rust-style type specifier)
+        array_type = response.headers["X-FITS-Type"]
+        assert array_type == "f32"
+
+        # Verify data content (data is sent as little-endian)
+        data = np.frombuffer(response.body, dtype="<f4").reshape(2, 3)
+        expected = np.arange(100, dtype=np.float32).reshape(10, 10)[0:2, 0:3]
+        np.testing.assert_array_almost_equal(data, expected)
+
+    async def test_get_slice_int16(self, jp_fetch, fits_file):
+        """Test retrieving a slice of int16 data."""
+        # HDU 1 has shape [5, 10], slice rows 1:3, cols 2:6
+        response = await jp_fetch(
+            "fitsview",
+            "slice",
+            params={"path": fits_file, "hdu": "1", "slices": "1:3,2:6"},
+        )
+
+        assert response.code == 200
+
+        # Check type header - should be i16 (Rust-style type specifier)
+        array_type = response.headers["X-FITS-Type"]
+        assert array_type == "i16"
+
+        # Verify data content (data is sent as little-endian)
+        shape = json.loads(response.headers["X-FITS-Shape"])
+        assert shape == [2, 4]
+
+        data = np.frombuffer(response.body, dtype="<i2").reshape(2, 4)
+        expected = np.arange(50, dtype=np.int16).reshape(5, 10)[1:3, 2:6]
+        np.testing.assert_array_equal(data, expected)
+
+    async def test_get_slice_float64(self, jp_fetch, float64_fits_file):
+        """Test retrieving float64 data preserves dtype."""
+        # 2D data with shape [2, 2], slice entire array
+        response = await jp_fetch(
+            "fitsview",
+            "slice",
+            params={"path": float64_fits_file, "hdu": "0", "slices": "0:2,0:2"},
+        )
+
+        assert response.code == 200
+        
+        # Check type header - should be f64 (Rust-style type specifier)
+        array_type = response.headers["X-FITS-Type"]
+        assert array_type == "f64"
+
+        data = np.frombuffer(response.body, dtype="<f8").reshape(2, 2)
+        expected = np.array([[1.5, 2.5], [3.5, 4.5]], dtype=np.float64)
+        np.testing.assert_array_almost_equal(data, expected)
+
+    async def test_get_slice_3d_cube(self, jp_fetch, cube_fits_file):
+        """Test retrieving a slice from a 3D data cube."""
+        # 3D data with shape [4, 5, 6], slice planes 1:3, rows 0:2, cols 2:5
+        response = await jp_fetch(
+            "fitsview",
+            "slice",
+            params={"path": cube_fits_file, "hdu": "0", "slices": "1:3,0:2,2:5"},
+        )
+
+        assert response.code == 200
+
+        # Check shape header
+        shape = json.loads(response.headers["X-FITS-Shape"])
+        assert shape == [2, 2, 3]
+
+        # Verify data content (using type header for reference, but hardcode dtype for parsing)
+        array_type = response.headers["X-FITS-Type"]
+        assert array_type == "f32"
+        data = np.frombuffer(response.body, dtype="<f4").reshape(2, 2, 3)
+        expected = np.arange(120, dtype=np.float32).reshape(4, 5, 6)[1:3, 0:2, 2:5]
+        np.testing.assert_array_almost_equal(data, expected)
+
+    async def test_slice_out_of_bounds(self, jp_fetch, fits_file):
+        """Test that out-of-bounds slices return 400."""
+        response = await jp_fetch(
+            "fitsview",
+            "slice",
+            params={"path": fits_file, "hdu": "0", "slices": "8:15,8:15"},
+            raise_error=False,
+        )
+
+        assert response.code == 400
+        data = json.loads(response.body)
+        assert "error" in data
+        assert "out of bounds" in data["error"].lower()
+
+    async def test_slice_dimension_mismatch(self, jp_fetch, fits_file):
+        """Test that wrong number of slice dimensions returns 400."""
+        # HDU 0 is 2D but we provide 3 slice dimensions
+        response = await jp_fetch(
+            "fitsview",
+            "slice",
+            params={"path": fits_file, "hdu": "0", "slices": "0:2,0:2,0:2"},
+            raise_error=False,
+        )
+
+        assert response.code == 400
+        data = json.loads(response.body)
+        assert "error" in data
+        assert "dimensions" in data["error"].lower()
+
+    async def test_slice_invalid_format(self, jp_fetch, fits_file):
+        """Test that invalid slice format returns 400."""
+        response = await jp_fetch(
+            "fitsview",
+            "slice",
+            params={"path": fits_file, "hdu": "0", "slices": "0:2:1,0:3"},  # step not supported
+            raise_error=False,
+        )
+
+        assert response.code == 400
+        data = json.loads(response.body)
+        assert "error" in data
+
+    async def test_slice_invalid_hdu(self, jp_fetch, fits_file):
+        """Test that invalid HDU index returns 400."""
+        response = await jp_fetch(
+            "fitsview",
+            "slice",
+            params={"path": fits_file, "hdu": "99", "slices": "0:1,0:1"},
+            raise_error=False,
+        )
+
+        assert response.code == 400
+        data = json.loads(response.body)
+        assert "error" in data
+        assert "out of range" in data["error"].lower()
+
+    async def test_slice_table_hdu_error(self, jp_fetch, fits_file):
+        """Test that requesting a slice from a table HDU returns an error."""
+        # HDU 2 is the table extension - tables have no standard shape
+        response = await jp_fetch(
+            "fitsview",
+            "slice",
+            params={"path": fits_file, "hdu": "2", "slices": "0:1,0:1"},
+            raise_error=False,
+        )
+
+        assert response.code == 400
+        data = json.loads(response.body)
+        assert "error" in data
+
+    async def test_slice_file_not_found(self, jp_fetch):
+        """Test that 404 is returned for non-existent files."""
+        response = await jp_fetch(
+            "fitsview",
+            "slice",
+            params={"path": "nonexistent.fits", "hdu": "0", "slices": "0:1,0:1"},
+            raise_error=False,
+        )
+
+        assert response.code == 404
+        data = json.loads(response.body)
+        assert "error" in data

fitsview-0.1.0.data/data/etc/jupyter/jupyter_server_config.d/fitsview.json

@@ -0,0 +1,7 @@
+{
+  "ServerApp": {
+    "jpserver_extensions": {
+      "fitsview": true
+    }
+  }
+}

fitsview-0.1.0.data/data/share/jupyter/labextensions/fitsview/install.json

@@ -0,0 +1,5 @@
+{
+  "packageManager": "python",
+  "packageName": "fitsview",
+  "uninstallInstructions": "Use your Python package manager (pip, conda, etc.) to uninstall the package fitsview"
+}