dicube 0.2.2__cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

dicube/__init__.py

@@ -0,0 +1,174 @@
+"""DiCube: Python library for efficient storage and processing of 3D medical images.
+
+DiCube provides functionality for working with DICOM image data while preserving
+complete metadata. It offers efficient storage formats, image processing capabilities,
+and interoperability with various medical image formats.
+
+Main functionality:
+- Load/save 3D medical images with complete DICOM metadata
+- Efficient binary storage format with multiple compression options
+- Spatial transformation and orientation handling
+- Conversion between different medical image formats
+
+Example:
+    >>> import dicube
+    >>> # Load from DICOM folder
+    >>> image = dicube.load_from_dicom_folder("path/to/dicom_folder")
+    >>> # Save to DCB file
+    >>> dicube.save(image, "output.dcb")
+    >>> # Access the data
+    >>> pixel_data = image.get_fdata()
+"""
+
+from .core.image import DicomCubeImage
+from .core.io import DicomCubeImageIO
+from .dicom import (
+    CommonTags,
+    DicomMeta,
+    DicomStatus,
+    SortMethod,
+    get_dicom_status,
+    read_dicom_dir,
+)
+
+from importlib.metadata import version as _pkg_version, PackageNotFoundError
+
+try:
+    __version__ = _pkg_version("dicube")
+except PackageNotFoundError:
+    # editable install / source tree
+    __version__ = "0.1.0+unknown"
+
+# Default to the number of CPU cores, but cap at 8 threads to avoid excessive resource usage
+# Fall back to 4 if cpu_count() returns None (which can happen in some environments)
+_num_threads = 4
+
+def get_num_threads() -> int:
+    """Get the global number of threads for parallel processing.
+    
+    Returns:
+        int: Current number of threads setting.
+    """
+    global _num_threads
+    return _num_threads
+
+def set_num_threads(num_threads: int) -> None:
+    """Set the global number of threads for parallel processing.
+    
+    Args:
+        num_threads (int): Number of threads for parallel processing tasks.
+    """
+    global _num_threads
+    if num_threads < 1:
+        raise ValueError("Number of threads must be at least 1")
+    _num_threads = num_threads
+
+# Top-level convenience methods
+def load(file_path: str) -> DicomCubeImage:
+    """Load a DicomCubeImage from a file.
+    
+    Args:
+        file_path (str): Path to the input file.
+    
+    Returns:
+        DicomCubeImage: The loaded image object.
+    """
+    return DicomCubeImageIO.load(file_path)
+
+
+def save(
+    image: DicomCubeImage,
+    file_path: str,
+    file_type: str = "s",
+) -> None:
+    """Save a DicomCubeImage to a file.
+    
+    Args:
+        image (DicomCubeImage): The image object to save.
+        file_path (str): Output file path.
+        file_type (str): File type, "s" (speed priority), "a" (compression priority), 
+                        or "l" (lossy compression). Defaults to "s".
+    """
+    return DicomCubeImageIO.save(image, file_path, file_type)
+
+
+def load_from_dicom_folder(
+    folder_path: str,
+    sort_method: SortMethod = SortMethod.INSTANCE_NUMBER_ASC,
+) -> DicomCubeImage:
+    """Load a DicomCubeImage from a DICOM folder.
+    
+    Args:
+        folder_path (str): Path to the DICOM folder.
+        sort_method (SortMethod): Method to sort DICOM files. 
+                                 Defaults to SortMethod.INSTANCE_NUMBER_ASC.
+        **kwargs: Additional parameters.
+    
+    Returns:
+        DicomCubeImage: The loaded image object.
+    """
+    return DicomCubeImageIO.load_from_dicom_folder(folder_path, sort_method)
+
+
+def load_from_nifti(file_path: str) -> DicomCubeImage:
+    """Load a DicomCubeImage from a NIfTI file.
+    
+    Args:
+        file_path (str): Path to the NIfTI file.
+        **kwargs: Additional parameters.
+    
+    Returns:
+        DicomCubeImage: The loaded image object.
+    """
+    return DicomCubeImageIO.load_from_nifti(file_path)
+
+
+def save_to_dicom_folder(
+    image: DicomCubeImage,
+    folder_path: str,
+) -> None:
+    """Save a DicomCubeImage as a DICOM folder.
+    
+    Args:
+        image (DicomCubeImage): The image object to save.
+        folder_path (str): Output directory path.
+    """
+    return DicomCubeImageIO.save_to_dicom_folder(image, folder_path)
+
+
+def save_to_nifti(
+    image: DicomCubeImage,
+    file_path: str,
+) -> None:
+    """Save a DicomCubeImage as a NIfTI file.
+    
+    Args:
+        image (DicomCubeImage): The image object to save.
+        file_path (str): Output file path.
+    
+    Raises:
+        ImportError: When nibabel is not installed.
+    """
+    return DicomCubeImageIO.save_to_nifti(image, file_path)
+
+
+__all__ = [
+    "DicomCubeImage",
+    "DicomMeta",
+    "read_dicom_dir",
+    "DicomStatus",
+    "get_dicom_status",
+    "CommonTags",
+    "SortMethod",
+    # Top-level convenience methods
+    "load",
+    "save",
+    "load_from_dicom_folder",
+    "load_from_nifti",
+    "save_to_dicom_folder",
+    "save_to_nifti",
+    "set_num_threads",
+    "get_num_threads",
+    # IO class (for direct use if needed)
+    "DicomCubeImageIO",
+] 

dicube/codecs/__init__.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+"""Image codec sub-package for dicube.
+
+This package defines the codec registry and base interface for image codecs.
+Currently supports JPH format with extensible design for future formats.
+"""
+
+from typing import Dict, Protocol, runtime_checkable, Optional, Union, Any, Tuple
+import numpy as np
+from pathlib import Path
+
+__all__ = [
+    "ImageCodec",
+    "get_codec",
+    "list_codecs",
+    "register_codec",
+    "is_codec_available",
+]
+
+
+@runtime_checkable
+class ImageCodec(Protocol):
+    """Base interface that all image codecs must implement.
+    
+    Attributes:
+        id (int): Unique numeric ID for the codec.
+        name (str): Codec name (e.g., "jph").
+        extensions (Tuple[str, ...]): Supported file extensions (e.g., (".j2k",)).
+    """
+
+    id: int
+    name: str
+    extensions: Tuple[str, ...]
+    
+    def encode(
+        self, 
+        image: np.ndarray, 
+        /, 
+        **kwargs: Any
+    ) -> bytes:
+        """Encode numpy array to compressed bytes.
+        
+        Args:
+            image (np.ndarray): Input image array.
+            **kwargs: Codec-specific parameters.
+            
+        Returns:
+            bytes: Compressed image data.
+        """
+        ...
+    
+    def decode(
+        self, 
+        data: bytes, 
+        /,
+        **kwargs: Any
+    ) -> np.ndarray:
+        """Decode compressed bytes to numpy array.
+        
+        Args:
+            data (bytes): Compressed image data.
+            **kwargs: Codec-specific parameters.
+            
+        Returns:
+            np.ndarray: Decoded image as numpy array.
+        """
+        ...
+    
+    def is_available(self) -> bool:
+        """Check if codec is available and functional.
+        
+        Returns:
+            bool: True if the codec is available and operational.
+        """
+        ...
+    
+    def get_version(self) -> str:
+        """Get codec version information.
+        
+        Returns:
+            str: Version information string.
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Registry implementation ---------------------------------------------------
+# ---------------------------------------------------------------------------
+
+_codec_registry: Dict[str, ImageCodec] = {}
+
+
+def register_codec(codec: ImageCodec) -> None:
+    """Register a codec in the global registry.
+    
+    Args:
+        codec (ImageCodec): The codec instance to register.
+    """
+    _codec_registry[codec.name.lower()] = codec
+
+
+def get_codec(name: str) -> ImageCodec:
+    """Get codec by name (case-insensitive).
+    
+    Args:
+        name (str): Codec name (e.g., "jph").
+        
+    Returns:
+        ImageCodec: Codec instance.
+        
+    Raises:
+        ValueError: If codec not found.
+    """
+    try:
+        return _codec_registry[name.lower()]
+    except KeyError as err:
+        available = list(_codec_registry.keys())
+        raise ValueError(f"Unknown codec '{name}'. Available: {available}") from err
+
+
+def list_codecs() -> list[str]:
+    """List all registered codec names.
+    
+    Returns:
+        list[str]: List of registered codec names.
+    """
+    return list(_codec_registry.keys())
+
+
+def is_codec_available(name: str) -> bool:
+    """Check if a codec is available.
+    
+    Args:
+        name (str): Codec name (e.g., "jph").
+        
+    Returns:
+        bool: True if codec is available and functional, False otherwise.
+    """
+    try:
+        codec = get_codec(name)
+        return codec.is_available()
+    except ValueError:
+        return False
+
+
+# Import and register concrete implementations
+try:
+    from .jph.codec import JphCodec  
+    register_codec(JphCodec())
+except ImportError:
+    pass  # JPH codec not available 

dicube/codecs/jph/__init__.py

@@ -0,0 +1,15 @@
+"""JPEG 2000 (HTJ2K) codec module for DiCube.
+
+This module provides JPEG 2000 High Throughput (HTJ2K) compression functionality
+through the OpenJPH library. It implements the ImageCodec interface for seamless
+integration with DiCube's storage system.
+
+Classes:
+    JphCodec: Implementation of the JPEG 2000 codec using OpenJPH.
+"""
+
+from .codec import JphCodec
+
+__all__ = [
+    "JphCodec",
+]

dicube/codecs/jph/codec.py

@@ -0,0 +1,161 @@
+"""JPH codec adapter implementing ImageCodec interface."""
+
+from __future__ import annotations
+
+import numpy as np
+from pathlib import Path
+from typing import Union, Any, Tuple
+
+from .ojph_complete import encode_image
+from .ojph_decode_complete import decode_image
+
+
+class JphCodec:
+    """JPEG 2000 codec (OpenJPH) implementing ImageCodec interface.
+    
+    Attributes:
+        id (int): Unique numeric ID for the codec.
+        name (str): Codec name ("jph").
+        extensions (Tuple[str, ...]): Supported file extensions (.j2k, .j2c, .jp2).
+    """
+    
+    id: int = 2
+    name: str = "jph"
+    extensions: Tuple[str, ...] = (".j2k", ".j2c", ".jp2")
+    
+    def encode(
+        self, 
+        image: np.ndarray, 
+        /, 
+        reversible: bool = True,
+        num_decompositions: int = 5,
+        block_size: tuple = (64, 64),
+        precinct_size: tuple = None,
+        progression_order: str = "RPCL",
+        color_transform: bool = False,
+        profile: str = None,
+        **kwargs: Any
+    ) -> bytes:
+        """Encode numpy array to JPEG 2000 bytes.
+        
+        Args:
+            image (np.ndarray): Input image array.
+            reversible (bool): Whether to use reversible transform. Defaults to True.
+            num_decompositions (int): Number of wavelet decompositions. Defaults to 5.
+            block_size (tuple): Code block size as (width, height). Defaults to (64, 64).
+            precinct_size (tuple, optional): Precinct size for each level as (width, height).
+                Defaults to None.
+            progression_order (str): Progression order, one of LRCP, RLCP, RPCL, PCRL, CPRL.
+                Defaults to "RPCL".
+            color_transform (bool): Whether to use color transform. Defaults to False.
+            profile (str, optional): Profile to use, one of None, IMF, BROADCAST.
+                Defaults to None.
+            **kwargs: Additional parameters (ignored for compatibility).
+            
+        Returns:
+            bytes: Compressed JPEG 2000 data.
+            
+        Raises:
+            ValueError: If the image dimensions or block size are invalid.
+        """
+        # Parameter validation
+        if len(image.shape) not in (2, 3):
+            raise ValueError("Image must be 2D or 3D array")
+
+        # Validate code block size
+        if not all(
+            size > 0 and size <= 64 and (size & (size - 1)) == 0 for size in block_size
+        ):
+            raise ValueError(
+                "Code block dimensions must be powers of 2 and not larger than 64"
+            )
+
+        # Ensure data is contiguous
+        if not image.flags["C_CONTIGUOUS"]:
+            image = np.ascontiguousarray(image)
+
+        # Call C++ implementation
+        return encode_image(
+            image,
+            reversible=reversible,
+            num_decompositions=num_decompositions,
+            block_size=block_size,
+            precinct_size=precinct_size if precinct_size is not None else (0, 0),
+            progression_order=progression_order,
+            color_transform=color_transform,
+            profile="" if profile is None else profile,
+        )
+    
+    def encode_lossless(
+        self,
+        image: np.ndarray,
+        /,
+        **kwargs: Any
+    ) -> bytes:
+        """Encode numpy array to lossless JPEG 2000 bytes.
+        
+        This is a convenience method that calls encode() with reversible=True.
+        
+        Args:
+            image (np.ndarray): Input image array.
+            **kwargs: Additional parameters passed to encode().
+            
+        Returns:
+            bytes: Compressed JPEG 2000 data.
+        """
+        return self.encode(image, reversible=True, **kwargs)
+    
+    def decode(
+        self, 
+        data: bytes, 
+        /,
+        level: int = 0,
+        resilient: bool = False,
+        **kwargs: Any
+    ) -> np.ndarray:
+        """Decode JPEG 2000 bytes to numpy array.
+        
+        Args:
+            data (bytes): Compressed JPEG 2000 data.
+            level (int): Resolution level to decode at (0 = full resolution).
+                Defaults to 0.
+            resilient (bool): Whether to enable resilient decoding. Defaults to False.
+            **kwargs: Additional parameters (ignored for compatibility).
+            
+        Returns:
+            np.ndarray: Decoded image as numpy array.
+        """
+        # Use C++ implementation
+        return decode_image(data, level=level, resilient=resilient)
+
+    
+    def is_available(self) -> bool:
+        """Check if JPEG 2000 codec is available and functional.
+        
+        Returns:
+            bool: True if the codec is available and operational.
+        """
+        try:
+            # Test with a small image
+            test_image = np.ones((10, 10), dtype=np.uint8)
+            encoded = self.encode(test_image)
+            decoded = self.decode(encoded)
+            return decoded.shape == test_image.shape
+        except Exception:
+            return False
+    
+    def get_version(self) -> str:
+        """Get JPEG 2000 codec version.
+        
+        Returns:
+            str: Version information string.
+        """
+        return "OpenJPH"  # TODO: Get actual version from OpenJPH
+    
+    def __repr__(self) -> str:
+        """Get string representation of the codec.
+        
+        Returns:
+            str: String representation.
+        """
+        return f"<{self.__class__.__name__} id={self.id} name='{self.name}' version='{self.get_version()}'>" 

dicube/core/__init__.py

@@ -0,0 +1,21 @@
+"""Core module for DiCube library.
+
+This module provides the main interfaces and core functionality for working with
+medical images in the DiCube format, including image representation, metadata handling,
+and file I/O operations.
+
+Classes:
+    DicomCubeImage: Main class for representing DICOM image data with metadata.
+    PixelDataHeader: Header class for storing pixel data information.
+    DicomCubeImageIO: Static I/O utility class for file operations.
+"""
+
+from .image import DicomCubeImage
+from .pixel_header import PixelDataHeader
+from .io import DicomCubeImageIO
+
+__all__ = [
+    "DicomCubeImage",
+    "PixelDataHeader",
+    "DicomCubeImageIO",
+]