dicube 0.2.2__cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

dicube/dicom/dcb_streaming.py

@@ -0,0 +1,248 @@
+"""
+DCB Streaming Reader for PACS Viewer
+
+Provides efficient streaming access to DCB files for on-demand DICOM frame delivery.
+Keeps files open and metadata cached for low-latency responses.
+"""
+
+import io
+import struct
+import warnings
+from typing import Dict, Any
+
+from pydicom import Dataset
+from pydicom.dataset import FileMetaDataset
+from pydicom.encaps import encapsulate
+from pydicom.uid import generate_uid
+import pydicom
+
+from ..storage.dcb_file import DcbFile
+from .dicom_io import save_dicom
+
+# Required minimum PyDicom version
+REQUIRED_PYDICOM_VERSION = "3.0.0"
+
+class DcbStreamingReader:
+    """DCB file streaming reader for PACS Viewer.
+    
+    Keeps files open and supports fast random access to frame data.
+    
+    Example:
+        reader = DcbStreamingReader('study.dcbs')
+        dicom_bytes = reader.get_dicom_for_frame(50)
+        reader.close()
+    """
+    
+    def __init__(self, dcb_file_path: str):
+        """Initialize and preparse all metadata.
+        
+        Args:
+            dcb_file_path: Path to DCB file
+            
+        Warnings:
+            UserWarning: If PyDicom version is below 3.0.0, HTJ2K decoding may not work properly
+        """
+        # Check PyDicom version
+        self._check_pydicom_version()
+        
+        self.file_path = dcb_file_path
+        self.file_handle = None
+        self.transfer_syntax_uid = None
+        
+        # Pre-parsed data
+        self.header = None
+        self.dicom_meta = None
+        self.pixel_header = None
+        self.space = None
+        
+        # Frame index information
+        self.frame_offsets = []
+        self.frame_lengths = []
+        self.frame_count = 0
+        
+        # DcbFile instance (for reading metadata)
+        self.dcb_file = None
+        
+        # Initialize
+        self._open_and_parse()
+    
+    def _check_pydicom_version(self):
+        """Check PyDicom version and warn if requirements not met.
+        
+        Warnings:
+            UserWarning: If PyDicom version is below 3.0.0
+        """
+        current_version = pydicom.__version__
+        if current_version < REQUIRED_PYDICOM_VERSION:
+            warnings.warn(
+                f"DcbStreamingReader requires PyDicom >= {REQUIRED_PYDICOM_VERSION} for full HTJ2K transfer syntax support. "
+                f"Current PyDicom version is {current_version}, which may not be able to read pixel data. "
+                f"Write functionality is not affected, but other applications may have issues reading. "
+                f"Recommended upgrade: pip install pydicom>={REQUIRED_PYDICOM_VERSION}, requires python 3.10 or higher",
+                UserWarning
+            )
+            self._has_pydicom_htj2k_support = False
+        else:
+            self._has_pydicom_htj2k_support = True
+
+    def _open_and_parse(self):
+        """Open file and parse all metadata."""
+        try:
+            # 1. Create DcbFile instance (will auto-detect file type)
+            self.dcb_file = DcbFile(self.file_path, mode='r')
+            
+            # 2. Read and cache header information
+            self.header = self.dcb_file.header
+            self.frame_count = self.header['frame_count']
+            
+            # 3. Read and cache metadata
+            self.dicom_meta = self.dcb_file.read_meta()
+            self.pixel_header = self.dcb_file.read_pixel_header()
+            self.space = self.dcb_file.read_space()
+            
+            # 4. Get transfer syntax UID (directly from file type)
+            self.transfer_syntax_uid = self.dcb_file.get_transfer_syntax_uid()
+            if not self.transfer_syntax_uid:
+                # If file type doesn't define transfer syntax, use default uncompressed format
+                self.transfer_syntax_uid = '1.2.840.10008.1.2.1'  # Explicit VR Little Endian
+            
+            # 5. Open file handle for reading frame data
+            self.file_handle = open(self.file_path, 'rb')
+            
+            # 6. Read all frame offsets and lengths
+            self._read_frame_indices()
+            
+        except Exception as e:
+            self.close()
+            raise RuntimeError(f"Failed to open and parse DCB file: {e}")
+    
+    def _read_frame_indices(self):
+        """Read all frame offset and length information."""
+        self.file_handle.seek(self.header['frame_offsets_offset'])
+        
+        # Read offsets
+        for _ in range(self.frame_count):
+            offset, = struct.unpack('<Q', self.file_handle.read(8))
+            self.frame_offsets.append(offset)
+        
+        # Read lengths
+        self.file_handle.seek(self.header['frame_lengths_offset'])
+        for _ in range(self.frame_count):
+            length, = struct.unpack('<Q', self.file_handle.read(8))
+            self.frame_lengths.append(length)
+    
+    def get_dicom_for_frame(self, frame_index: int) -> bytes:
+        """
+        Get DICOM data for the specified frame.
+        
+        Args:
+            frame_index: Frame index (0-based)
+            
+        Returns:
+            bytes: Complete DICOM file data
+            
+        Raises:
+            IndexError: If frame_index is out of range
+            RuntimeError: If reading fails
+        """
+        # Validate index
+        if not 0 <= frame_index < self.frame_count:
+            raise IndexError(f"Frame index {frame_index} out of range [0, {self.frame_count})")
+        
+        try:
+            # 1. Read encoded data for the frame
+            encoded_pixel_data = self._read_encoded_frame(frame_index)
+            
+            # 2. Generate DICOM Dataset for the frame
+            ds = self._create_dicom_dataset(frame_index, encoded_pixel_data)
+            
+            # 3. Serialize to DICOM file format
+            return self._serialize_to_dicom_bytes(ds)
+            
+        except Exception as e:
+            raise RuntimeError(f"Failed to create DICOM for frame {frame_index}: {e}")
+    
+    def _read_encoded_frame(self, frame_index: int) -> bytes:
+        """Read encoded data for the specified frame directly."""
+        offset = self.frame_offsets[frame_index]
+        length = self.frame_lengths[frame_index]
+        
+        self.file_handle.seek(offset)
+        return self.file_handle.read(length)
+    
+    def _create_dicom_dataset(self, frame_index: int, encoded_data: bytes) -> Dataset:
+        """Quickly create DICOM Dataset."""
+        # 1. Get metadata for the frame from cached DicomMeta
+        if self.dicom_meta:
+            frame_meta_dict = self.dicom_meta.index(frame_index)
+        else:
+            frame_meta_dict = {}
+        
+        # 2. Create Dataset
+        ds = Dataset.from_json(frame_meta_dict)
+        
+        # 3. Create and set file metadata
+        file_meta = FileMetaDataset()
+        file_meta.MediaStorageSOPClassUID = ds.get('SOPClassUID', '1.2.840.10008.5.1.4.1.1.2')
+        file_meta.MediaStorageSOPInstanceUID = ds.get('SOPInstanceUID', generate_uid())
+        file_meta.TransferSyntaxUID = self.transfer_syntax_uid
+        file_meta.ImplementationClassUID = generate_uid()
+        
+        ds.file_meta = file_meta
+        
+        # 4. Ensure necessary SOP information
+        if not hasattr(ds, 'SOPClassUID'):
+            ds.SOPClassUID = file_meta.MediaStorageSOPClassUID
+        if not hasattr(ds, 'SOPInstanceUID'):
+            ds.SOPInstanceUID = file_meta.MediaStorageSOPInstanceUID
+        
+        # 5. Set pixel-related attributes
+        if self.pixel_header:
+            ds.RescaleSlope = self.pixel_header.RescaleSlope
+            ds.RescaleIntercept = self.pixel_header.RescaleIntercept
+        
+        # 6. Set pixel data (using encapsulated format for compressed data)
+        ds.PixelData = encapsulate([encoded_data])
+        
+        return ds
+    
+    def _serialize_to_dicom_bytes(self, ds: Dataset) -> bytes:
+        """Serialize Dataset to DICOM file byte stream."""
+        # Use BytesIO to create DICOM file in memory
+        buffer = io.BytesIO()
+        save_dicom(ds, buffer)
+        buffer.seek(0)
+        return buffer.read()
+    
+    def get_frame_count(self) -> int:
+        """Get total number of frames."""
+        return self.frame_count
+    
+    def get_metadata(self) -> Dict[str, Any]:
+        """Get cached metadata information."""
+        return {
+            'frame_count': self.frame_count,
+            'pixel_header': self.pixel_header.to_dict() if self.pixel_header else {},
+            'has_dicom_meta': self.dicom_meta is not None,
+            'has_space': self.space is not None,
+            'transfer_syntax': self.transfer_syntax_uid,
+            'file_type': self.dcb_file.__class__.__name__,
+        }
+    
+    def close(self):
+        """Close file handle."""
+        if self.file_handle:
+            self.file_handle.close()
+            self.file_handle = None
+    
+    def __enter__(self):
+        """Support with statement."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Automatically close when exiting with statement."""
+        self.close()
+    
+    def __del__(self):
+        """Ensure file is closed on destruction."""
+        self.close() 

dicube/dicom/dicom_io.py

@@ -0,0 +1,153 @@
+import os
+import warnings
+import inspect
+from typing import List, Optional
+
+import numpy as np
+from pydicom import Dataset
+from pydicom.dataset import FileMetaDataset
+from pydicom.uid import JPEG2000, ExplicitVRLittleEndian, JPEG2000Lossless, generate_uid
+
+from ..dicom.dicom_meta import DicomMeta
+
+
+def prepare_output_dir(output_dir: str):
+    """Prepare output directory"""
+    if os.path.exists(output_dir):
+        import shutil
+
+        shutil.rmtree(output_dir)
+    os.makedirs(output_dir, exist_ok=True)
+
+
+def create_file_meta(ds):
+    """Create file meta information"""
+    file_meta = FileMetaDataset()
+
+    MODALITY_SOP_CLASS_MAP = {
+        "CT": "1.2.840.10008.5.1.4.1.1.2",
+        "MR": "1.2.840.10008.5.1.4.1.1.4",
+        "US": "1.2.840.10008.5.1.4.1.1.6.1",
+        "PT": "1.2.840.10008.5.1.4.1.1.128",
+        "CR": "1.2.840.10008.5.1.4.1.1.1",
+        "DX": "1.2.840.10008.5.1.4.1.1.1.1",
+        "NM": "1.2.840.10008.5.1.4.1.1.20",
+    }
+
+    modality = ds.Modality if hasattr(ds, "Modality") else "CT"
+    default_sop_uid = MODALITY_SOP_CLASS_MAP.get(modality, MODALITY_SOP_CLASS_MAP["CT"])
+
+    file_meta.MediaStorageSOPClassUID = (
+        ds.SOPClassUID if hasattr(ds, "SOPClassUID") else default_sop_uid
+    )
+    file_meta.MediaStorageSOPInstanceUID = (
+        ds.SOPInstanceUID if hasattr(ds, "SOPInstanceUID") else generate_uid()
+    )
+    file_meta.TransferSyntaxUID = ExplicitVRLittleEndian
+    file_meta.ImplementationClassUID = generate_uid()
+
+    return file_meta
+
+
+def ensure_required_tags(ds):
+    """Ensure required DICOM tags exist"""
+    if not hasattr(ds, "SOPClassUID"):
+        ds.SOPClassUID = ds.file_meta.MediaStorageSOPClassUID
+    if not hasattr(ds, "SOPInstanceUID"):
+        ds.SOPInstanceUID = ds.file_meta.MediaStorageSOPInstanceUID
+
+
+def set_dicom_pixel_attributes(img, ds):
+    """Set DICOM pixel attributes"""
+    if np.issubdtype(img.dtype, np.integer):
+        bits = img.dtype.itemsize * 8
+        ds.BitsAllocated = bits
+        ds.BitsStored = bits
+        ds.HighBit = bits - 1
+        ds.PixelRepresentation = 1 if np.issubdtype(img.dtype, np.signedinteger) else 0
+    else:
+        warnings.warn(f"Converting float dtype {img.dtype} to uint16")
+        img = img.astype(np.uint16)
+        ds.BitsAllocated = 16
+        ds.BitsStored = 16
+        ds.HighBit = 15
+        ds.PixelRepresentation = 0
+
+    ds.SamplesPerPixel = 1
+    return img
+
+
+def create_dicom_dataset(meta_dict: dict, pixel_header):
+    """Create DICOM dataset"""
+    ds = Dataset.from_json(meta_dict)
+
+    if hasattr(ds, "file_meta"):
+        warnings.warn("Found original file metadata, will be overridden")
+
+    ds.file_meta = create_file_meta(ds)
+    ensure_required_tags(ds)
+    ds.RescaleSlope = pixel_header.RescaleSlope
+    ds.RescaleIntercept = pixel_header.RescaleIntercept
+
+    return ds
+
+
+def save_dicom(ds: Dataset, output_path: str):
+    """Save DICOM file.
+    
+    Args:
+        ds: DICOM dataset
+        output_path: Output file path
+    """
+    
+    sig = inspect.signature(Dataset.save_as)
+    if "enforce_file_format" in sig.parameters:  # pydicom >= 3.0
+        ds.save_as(output_path, enforce_file_format=True)
+    else:
+        # Ensure valid transfer syntax UID
+        if hasattr(ds, 'file_meta') and hasattr(ds.file_meta, 'TransferSyntaxUID'):
+            # Check if valid, replace with standard ExplicitVRLittleEndian if invalid
+            try:
+                from pydicom.uid import UID
+                uid = UID(ds.file_meta.TransferSyntaxUID)
+                if not hasattr(uid, 'is_little_endian'):
+                    ds.file_meta.TransferSyntaxUID = ExplicitVRLittleEndian
+            except (ValueError, AttributeError):
+                # If UID is invalid, use standard ExplicitVRLittleEndian
+                ds.file_meta.TransferSyntaxUID = ExplicitVRLittleEndian
+        ds.save_as(output_path, write_like_original=False)
+
+def save_to_dicom_folder(
+    raw_images: np.ndarray,
+    dicom_meta: DicomMeta,
+    pixel_header,
+    output_dir: str,
+    filenames: Optional[List[str]] = None,
+):
+    """Save image data as DICOM folder.
+    
+    Args:
+        raw_images: Raw image data, can be 2D or 3D array
+        dicom_meta: DICOM metadata
+        pixel_header: Pixel header information
+        output_dir: Output directory
+        filenames: Custom filename list, if None default names will be used
+    """
+    prepare_output_dir(output_dir)
+
+    if raw_images.ndim == 2:
+        raw_images = raw_images[np.newaxis, ...]
+
+    for idx in range(len(raw_images)):
+        ds = create_dicom_dataset(dicom_meta.index(idx), pixel_header)
+        img = raw_images[idx]
+
+        if img.dtype != np.uint16:
+            img = set_dicom_pixel_attributes(img, ds)
+
+        ds.PixelData = img.tobytes()
+
+        output_path = os.path.join(
+            output_dir, filenames[idx] if filenames else f"slice_{idx:04d}.dcm"
+        )
+        save_dicom(ds, output_path)