cft-zarr 0.0.4__tar.gz

cft_zarr-0.0.4/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.3
+Name: cft-zarr
+Version: 0.0.4
+Summary: CFT Zarr codecs for 12-bit fluorescence and RGB compression
+Author: Eli White
+Author-email: eliwhite@gmail.com
+Requires-Python: >=3.11,<=3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: imagecodecs (>=2024.1.1)
+Requires-Dist: numpy (>=1.26.4,<2.0.0)
+Requires-Dist: zarr (>=3.0.0)
+Description-Content-Type: text/markdown
+
+# CFT Zarr Custom Codecs
+
+Custom codecs for Zarr v3 optimized for CFT (Cryo-Fluorescence Tomography) data storage.
+
+## Codecs
+
+This package provides custom Zarr v3 codecs:
+
+- **`cft_zarr.jpeg_compressor`**: JPEG compressor for RGB images (BytesBytesCodec - supports incremental updates)
+- **`cft_zarr.shift12jls_compressor`**: JPEG-LS compressor for 12-bit fluorescent data (BytesBytesCodec - supports incremental updates)
+- **`cft_zarr.jpeg`**: JPEG codec for RGB images (ArrayBytesCodec)
+- **`cft_zarr.shift12jls`**: JPEG-LS codec for 12-bit fluorescent data (ArrayBytesCodec)
+- **`cft_zarr.jpegxl`**: JPEG XL codec (ArrayBytesCodec)
+
+## Installation
+
+```bash
+pip install cft-zarr
+```
+
+## Usage
+
+### Reading Zarr Files
+
+**Important**: You must import `cft_zarr` before opening Zarr files that use these codecs. This registers the codecs with Zarr.
+
+```python
+import cft_zarr  # This registers the codecs
+import zarr
+
+# Now you can open Zarr files that use custom codecs
+arr = zarr.open('rgb.zarr', mode='r')
+```
+
+### Using with napari
+
+When opening Zarr files in napari, `cft_zarr` can be auto-registered via the
+napari plugin system (installed in the same environment as napari). If you
+still have trouble, import `cft_zarr` first:
+
+```python
+import cft_zarr  # Register codecs before opening files
+import napari
+
+# Now napari can read Zarr files with custom codecs
+viewer = napari.Viewer()
+viewer.open('path/to/file.zarr')  # Will work with custom codecs
+```
+
+Or in a Python script before launching napari:
+
+```python
+import cft_zarr  # Must import before opening Zarr files
+import napari
+
+viewer = napari.Viewer()
+viewer.open('rgb.zarr')
+napari.run()
+```
+
+### Creating Zarr Arrays with Custom Codecs
+
+```python
+import cft_zarr
+from cft_zarr import JPEGCompressor, Shift12JLSCompressor
+import zarr
+
+# Create RGB array with JPEG compression
+rgb_array = zarr.create(
+    shape=(100, 512, 512, 3),
+    chunks=(4, 512, 512, 3),
+    dtype='uint8',
+    compressors=[JPEGCompressor(level=85)]
+)
+
+# Create fluorescent array with Shift12JLS compression
+fl_array = zarr.create(
+    shape=(100, 512, 512),
+    chunks=(4, 512, 512),
+    dtype='uint16',
+    compressors=[Shift12JLSCompressor()]
+)
+```
+
+

cft_zarr-0.0.4/README.md

@@ -0,0 +1,84 @@
+# CFT Zarr Custom Codecs
+
+Custom codecs for Zarr v3 optimized for CFT (Cryo-Fluorescence Tomography) data storage.
+
+## Codecs
+
+This package provides custom Zarr v3 codecs:
+
+- **`cft_zarr.jpeg_compressor`**: JPEG compressor for RGB images (BytesBytesCodec - supports incremental updates)
+- **`cft_zarr.shift12jls_compressor`**: JPEG-LS compressor for 12-bit fluorescent data (BytesBytesCodec - supports incremental updates)
+- **`cft_zarr.jpeg`**: JPEG codec for RGB images (ArrayBytesCodec)
+- **`cft_zarr.shift12jls`**: JPEG-LS codec for 12-bit fluorescent data (ArrayBytesCodec)
+- **`cft_zarr.jpegxl`**: JPEG XL codec (ArrayBytesCodec)
+
+## Installation
+
+```bash
+pip install cft-zarr
+```
+
+## Usage
+
+### Reading Zarr Files
+
+**Important**: You must import `cft_zarr` before opening Zarr files that use these codecs. This registers the codecs with Zarr.
+
+```python
+import cft_zarr  # This registers the codecs
+import zarr
+
+# Now you can open Zarr files that use custom codecs
+arr = zarr.open('rgb.zarr', mode='r')
+```
+
+### Using with napari
+
+When opening Zarr files in napari, `cft_zarr` can be auto-registered via the
+napari plugin system (installed in the same environment as napari). If you
+still have trouble, import `cft_zarr` first:
+
+```python
+import cft_zarr  # Register codecs before opening files
+import napari
+
+# Now napari can read Zarr files with custom codecs
+viewer = napari.Viewer()
+viewer.open('path/to/file.zarr')  # Will work with custom codecs
+```
+
+Or in a Python script before launching napari:
+
+```python
+import cft_zarr  # Must import before opening Zarr files
+import napari
+
+viewer = napari.Viewer()
+viewer.open('rgb.zarr')
+napari.run()
+```
+
+### Creating Zarr Arrays with Custom Codecs
+
+```python
+import cft_zarr
+from cft_zarr import JPEGCompressor, Shift12JLSCompressor
+import zarr
+
+# Create RGB array with JPEG compression
+rgb_array = zarr.create(
+    shape=(100, 512, 512, 3),
+    chunks=(4, 512, 512, 3),
+    dtype='uint8',
+    compressors=[JPEGCompressor(level=85)]
+)
+
+# Create fluorescent array with Shift12JLS compression
+fl_array = zarr.create(
+    shape=(100, 512, 512),
+    chunks=(4, 512, 512),
+    dtype='uint16',
+    compressors=[Shift12JLSCompressor()]
+)
+```
+

cft_zarr-0.0.4/cft_zarr/__init__.py

@@ -0,0 +1,184 @@
+"""cft_zarr package - runtime registration of custom Zarr v3 codecs.
+
+This module registers available codecs so Zarr can resolve them by name:
+  - cft_zarr.shift12jls (ArrayBytesCodec serializer - no incremental updates)
+  - cft_zarr.jpeg (ArrayBytesCodec serializer - no incremental updates)
+  - cft_zarr.shift12jls_compressor (BytesBytesCodec compressor - supports incremental updates)
+  - cft_zarr.jpeg_compressor (BytesBytesCodec compressor - supports incremental updates)
+  - cft_zarr.jpegxl
+
+Registration is attempted against the Zarr v3 registry API. If unavailable,
+we try a legacy-style register function as a best effort.
+"""
+
+from typing import Any
+
+__all__ = [
+    "Shift12JLSCodec",
+    "JPEGCodec",
+    "Shift12JLSCompressor",
+    "JPEGCompressor",
+]
+
+# Import codecs if available
+Shift12JLSCodec: Any = None
+JPEGCodec: Any = None
+Shift12JLSCompressor: Any = None
+JPEGCompressor: Any = None
+JPEGXLCodec: Any = None
+
+try:
+    from .shift12jls import Shift12JLSCodec as _Shift12JLSCodec
+    Shift12JLSCodec = _Shift12JLSCodec
+except Exception:
+    Shift12JLSCodec = None
+
+try:
+    from .jpeg import JPEGCodec as _JPEGCodec
+    JPEGCodec = _JPEGCodec
+except Exception:
+    JPEGCodec = None
+
+try:
+    from .shift12jls_compressor import Shift12JLSCompressor as _Shift12JLSCompressor
+    Shift12JLSCompressor = _Shift12JLSCompressor
+except Exception:
+    Shift12JLSCompressor = None
+
+try:
+    from .jpeg_compressor import JPEGCompressor as _JPEGCompressor
+    JPEGCompressor = _JPEGCompressor
+except Exception:
+    JPEGCompressor = None
+
+try:
+    from .jpegxl import JPEGXLCodec as _JPEGXLCodec
+    JPEGXLCodec = _JPEGXLCodec
+except Exception:
+    JPEGXLCodec = None
+
+
+def _register_if_possible(cls: Any) -> None:
+    if cls is None:
+        return
+    # Use Zarr v3 registry API (zarr.registry.register_codec)
+    # Signature: register_codec(key: str, codec_cls: type[Codec])
+    try:
+        from zarr import registry as zregistry  # type: ignore
+        codec_id = getattr(cls, 'codec_id', None)
+        if codec_id:
+            zregistry.register_codec(codec_id, cls)  # type: ignore[attr-defined]
+    except Exception as e:
+        # Log error for debugging but don't fail
+        import warnings
+        warnings.warn(f"Failed to register codec {cls}: {e}", UserWarning)
+
+
+def _force_map(cls: Any) -> None:
+    """Best-effort: insert codec class into known registry maps for immediate availability."""
+    if cls is None:
+        return
+    cid = getattr(cls, 'codec_id', None)
+    cname = getattr(cls, '__name__', None)
+    if not cid and not cname:
+        return
+    # zarr.registry private maps - try all possible registry attribute names
+    try:
+        from zarr import registry as zregistry  # type: ignore
+        for attr_name in ('_CODECS', 'CODECS', '_codecs', 'codecs', '_registry', 'registry'):
+            reg = getattr(zregistry, attr_name, None)
+            if isinstance(reg, dict):
+                if cid:
+                    reg[cid] = cls
+                if cname:
+                    reg[cname] = cls
+                # Also try name lookup (Zarr might look up by class name)
+                if cname and cname != cid:
+                    reg[cname] = cls
+    except Exception:
+        pass
+    # zarr.codecs.registry private maps
+    try:
+        from zarr.codecs import registry as cregistry  # type: ignore
+        for attr_name in ('_CODECS', 'CODECS', '_codecs', 'codecs', '_registry', 'registry'):
+            reg = getattr(cregistry, attr_name, None)
+            if isinstance(reg, dict):
+                if cid:
+                    reg[cid] = cls
+                if cname:
+                    reg[cname] = cls
+                # Also try name lookup
+                if cname and cname != cid:
+                    reg[cname] = cls
+    except Exception:
+        pass
+    # Try registering via get_codec if it exists (Zarr v3 resolver)
+    try:
+        from zarr.codecs import get_codec  # type: ignore
+        # This might register it
+    except Exception:
+        pass
+    # Force register with any resolver functions we can find
+    try:
+        from zarr import registry as zregistry  # type: ignore
+        # Try to find and call a resolver or register function
+        for attr_name in ('resolve_codec', 'get_codec', 'register', 'add'):
+            resolver = getattr(zregistry, attr_name, None)
+            if callable(resolver):
+                try:
+                    if cid:
+                        resolver(cid, cls)  # type: ignore
+                except Exception:
+                    try:
+                        resolver(cls)  # type: ignore
+                    except Exception:
+                        pass
+    except Exception:
+        pass
+
+
+# Runtime registration
+_register_if_possible(Shift12JLSCodec)
+_register_if_possible(JPEGCodec)
+_register_if_possible(Shift12JLSCompressor)
+_register_if_possible(JPEGCompressor)
+_register_if_possible(JPEGXLCodec)
+
+# Force-map as a last resort so reopened arrays can resolve codecs immediately
+_force_map(Shift12JLSCodec)
+_force_map(JPEGCodec)
+_force_map(Shift12JLSCompressor)
+_force_map(JPEGCompressor)
+_force_map(JPEGXLCodec)
+
+from .shift12jls import Shift12JLSCodec
+from .jpeg import JPEGCodec
+from .shift12jls_compressor import Shift12JLSCompressor
+from .jpeg_compressor import JPEGCompressor
+
+__all__ = ["Shift12JLSCodec", "JPEGCodec", "Shift12JLSCompressor", "JPEGCompressor"]
+
+
+def _register_for_napari():
+    """
+    Napari plugin hook - ensures codecs are registered when napari starts.
+    
+    This function is called by napari when the plugin is loaded, ensuring
+    that custom Zarr codecs are registered before any Zarr files are opened.
+    
+    The codecs are already registered during module import (see above),
+    but this function provides an explicit hook for napari.
+    """
+    # Re-register in case napari loads us before any other import side effects.
+    _register_if_possible(Shift12JLSCodec)
+    _register_if_possible(JPEGCodec)
+    _register_if_possible(Shift12JLSCompressor)
+    _register_if_possible(JPEGCompressor)
+    _register_if_possible(JPEGXLCodec)
+
+    # Force-map as a last resort so reopened arrays can resolve codecs immediately
+    _force_map(Shift12JLSCodec)
+    _force_map(JPEGCodec)
+    _force_map(Shift12JLSCompressor)
+    _force_map(JPEGCompressor)
+    _force_map(JPEGXLCodec)

cft_zarr-0.0.4/cft_zarr/chunked_jpeg.py

@@ -0,0 +1,228 @@
+"""Chunked JPEG codec for RGB images in Zarr v3.
+
+This codec handles RGB images in chunks of N slices (default: 4) with JPEG compression,
+optimizing for spatial locality and efficient storage of photographic images.
+"""
+
+import io
+import numpy as np
+from typing import Any, Dict, Optional
+
+try:
+    import cv2
+    CV2_AVAILABLE = True
+except ImportError:
+    CV2_AVAILABLE = False
+
+try:
+    from numcodecs import Codec
+    from numcodecs.registry import register_codec
+except ImportError:
+    # Fallback for Zarr v3 direct codec interface
+    Codec = object
+    register_codec = lambda *args, **kwargs: None
+
+
+class ChunkedJPEGCodec(Codec):
+    """Codec for RGB images using chunked JPEG compression.
+    
+    Encodes N×512×512×3 numpy arrays (RGB images) as JPEG-compressed bytes.
+    Default chunk shape is (4, 512, 512, 3) but is configurable.
+    
+    Configuration:
+        quality: JPEG quality (0-100, default: 85)
+        chunk_shape: Tuple of (N, height, width, channels) or (N, height, width) for grayscale
+                    Default: (4, 512, 512, 3) for RGB, (4, 512, 512) for grayscale
+    """
+    
+    codec_id = "cft_zarr.chunked_jpeg"
+    
+    def __init__(
+        self,
+        quality: int = 85,
+        chunk_shape: Optional[tuple] = None,
+    ):
+        """Initialize chunked JPEG codec.
+        
+        Args:
+            quality: JPEG quality (0-100), default 85
+            chunk_shape: Chunk shape tuple, default (4, 512, 512, 3) for RGB
+        """
+        self.quality = max(0, min(100, quality))
+        self.chunk_shape = chunk_shape or (4, 512, 512, 3)
+        
+        # Validate chunk shape
+        if len(self.chunk_shape) not in (3, 4):
+            raise ValueError(f"chunk_shape must be 3D (grayscale) or 4D (RGB), got {len(self.chunk_shape)}D")
+        
+        self.is_rgb = len(self.chunk_shape) == 4
+        if self.is_rgb:
+            self.n_slices, self.height, self.width, self.channels = self.chunk_shape
+        else:
+            self.n_slices, self.height, self.width = self.chunk_shape
+            self.channels = 1
+    
+    def encode(self, buf: np.ndarray) -> bytes:
+        """Encode numpy array to JPEG-compressed bytes.
+        
+        Args:
+            buf: Numpy array of shape (N, height, width, 3) or (N, height, width)
+            
+        Returns:
+            Compressed bytes containing JPEG-encoded slices
+        """
+        if not CV2_AVAILABLE:
+            raise ImportError("cv2 is required for chunked JPEG codec")
+        
+        if not isinstance(buf, np.ndarray):
+            buf = np.asarray(buf)
+        
+        # Validate shape
+        expected_shape = self.chunk_shape
+        if buf.shape != expected_shape:
+            # Handle partial chunks (last chunk may have fewer slices)
+            if buf.shape[1:] == expected_shape[1:]:
+                # Same spatial dimensions, just fewer slices
+                pass
+            else:
+                raise ValueError(
+                    f"Expected shape {expected_shape}, got {buf.shape}. "
+                    "Partial chunks (fewer slices) are allowed, but spatial dimensions must match."
+                )
+        
+        # Convert to uint8 if needed
+        if buf.dtype != np.uint8:
+            buf = buf.astype(np.uint8)
+        
+        # Encode each slice as JPEG using cv2
+        jpeg_bytes_list = []
+        n_slices = buf.shape[0]
+        
+        # JPEG encoding parameters for cv2
+        encode_params = [cv2.IMWRITE_JPEG_QUALITY, self.quality, cv2.IMWRITE_JPEG_OPTIMIZE, 1]
+        
+        for i in range(n_slices):
+            slice_data = buf[i]
+            
+            # Handle RGB vs grayscale
+            if self.is_rgb:
+                # RGB: shape is (height, width, 3)
+                if slice_data.shape != (self.height, self.width, 3):
+                    # Resize if needed
+                    slice_data = cv2.resize(slice_data, (self.width, self.height), interpolation=cv2.INTER_LANCZOS4)
+                # cv2.imencode expects BGR for color images
+                slice_data_bgr = cv2.cvtColor(slice_data, cv2.COLOR_RGB2BGR)
+            else:
+                # Grayscale: shape is (height, width)
+                if slice_data.shape != (self.height, self.width):
+                    slice_data = cv2.resize(slice_data, (self.width, self.height), interpolation=cv2.INTER_LANCZOS4)
+                slice_data_bgr = slice_data
+            
+            # Encode as JPEG using cv2
+            success, jpeg_bytes = cv2.imencode('.jpg', slice_data_bgr, encode_params)
+            if not success:
+                raise RuntimeError(f"Failed to encode slice {i} as JPEG")
+            
+            jpeg_bytes_list.append(jpeg_bytes.tobytes())
+        
+        # Combine all JPEG bytes with a simple format:
+        # [n_slices (4 bytes)][slice_0_len (4 bytes)][slice_0_data][slice_1_len (4 bytes)][slice_1_data]...
+        result = io.BytesIO()
+        result.write(n_slices.to_bytes(4, byteorder='big'))
+        for jpeg_bytes in jpeg_bytes_list:
+            result.write(len(jpeg_bytes).to_bytes(4, byteorder='big'))
+            result.write(jpeg_bytes)
+        
+        return result.getvalue()
+    
+    def decode(self, buf: bytes, out: Optional[np.ndarray] = None) -> np.ndarray:
+        """Decode JPEG-compressed bytes to numpy array.
+        
+        Args:
+            buf: Compressed bytes containing JPEG-encoded slices
+            out: Optional output array (not used, but required by Codec interface)
+            
+        Returns:
+            Numpy array of shape (N, height, width, 3) or (N, height, width)
+        """
+        if not CV2_AVAILABLE:
+            raise ImportError("cv2 is required for chunked JPEG codec")
+        
+        buffer = io.BytesIO(buf)
+        
+        # Read number of slices
+        n_slices_bytes = buffer.read(4)
+        if len(n_slices_bytes) < 4:
+            raise ValueError("Invalid chunked JPEG format: missing slice count")
+        n_slices = int.from_bytes(n_slices_bytes, byteorder='big')
+        
+        # Decode each slice
+        slices = []
+        for i in range(n_slices):
+            # Read slice length
+            len_bytes = buffer.read(4)
+            if len(len_bytes) < 4:
+                raise ValueError(f"Invalid chunked JPEG format: missing length for slice {i}")
+            slice_len = int.from_bytes(len_bytes, byteorder='big')
+            
+            # Read slice data
+            slice_bytes = buffer.read(slice_len)
+            if len(slice_bytes) < slice_len:
+                raise ValueError(f"Invalid chunked JPEG format: incomplete data for slice {i}")
+            
+            # Decode JPEG using cv2
+            slice_data = cv2.imdecode(np.frombuffer(slice_bytes, dtype=np.uint8), cv2.IMREAD_UNCHANGED)
+            if slice_data is None:
+                raise RuntimeError(f"Failed to decode JPEG slice {i}")
+            
+            # Convert BGR to RGB if needed
+            if self.is_rgb and slice_data.ndim == 3:
+                slice_data = cv2.cvtColor(slice_data, cv2.COLOR_BGR2RGB)
+            
+            # Ensure correct shape
+            if self.is_rgb:
+                if slice_data.shape != (self.height, self.width, 3):
+                    slice_data = cv2.resize(slice_data, (self.width, self.height), interpolation=cv2.INTER_LANCZOS4)
+            else:
+                if slice_data.shape != (self.height, self.width):
+                    slice_data = cv2.resize(slice_data, (self.width, self.height), interpolation=cv2.INTER_LANCZOS4)
+            
+            slices.append(slice_data.astype(np.uint8))
+        
+        # Stack slices
+        result = np.stack(slices, axis=0)
+        
+        # Pad to expected chunk shape if needed (for partial chunks)
+        if result.shape[0] < self.n_slices:
+            if self.is_rgb:
+                padding_shape = (self.n_slices - result.shape[0], self.height, self.width, 3)
+            else:
+                padding_shape = (self.n_slices - result.shape[0], self.height, self.width)
+            padding = np.zeros(padding_shape, dtype=np.uint8)
+            result = np.concatenate([result, padding], axis=0)
+        
+        return result
+    
+    def get_config(self) -> Dict[str, Any]:
+        """Get codec configuration."""
+        return {
+            "id": self.codec_id,
+            "quality": self.quality,
+            "chunk_shape": list(self.chunk_shape),
+        }
+    
+    @classmethod
+    def from_config(cls, config: Dict[str, Any]) -> "ChunkedJPEGCodec":
+        """Create codec from configuration."""
+        quality = config.get("quality", 85)
+        chunk_shape = config.get("chunk_shape")
+        if chunk_shape:
+            chunk_shape = tuple(chunk_shape)
+        return cls(quality=quality, chunk_shape=chunk_shape)
+
+
+# Register codec with numcodecs (for Zarr v2 compatibility)
+try:
+    register_codec(ChunkedJPEGCodec)
+except Exception:
+    pass