dicube 0.1.4__cp311-cp311-macosx_11_0_arm64.whl

dicube-0.1.4.dist-info/METADATA

@@ -0,0 +1,271 @@
+Metadata-Version: 2.2
+Name: dicube
+Version: 0.1.4
+Summary: Medical Image Storage Library with DICOM compatibility
+Author: Fangzhou Liao
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Project-URL: Homepage, https://github.com/fastdiag-toolbox/dicube
+Project-URL: Bug Reports, https://github.com/fastdiag-toolbox/dicube/issues
+Project-URL: Source, https://github.com/fastdiag-toolbox/dicube
+Requires-Python: >=3.8
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: pydicom>=2.3.0
+Requires-Dist: zstandard>=0.18.0
+Requires-Dist: spacetransformer-core>=0.1.0
+Provides-Extra: jph
+Requires-Dist: pybind11>=2.10.0; extra == "jph"
+Provides-Extra: nifti
+Requires-Dist: nibabel>=3.2.0; extra == "nifti"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: build>=0.8.0; extra == "dev"
+Requires-Dist: pylibjpeg>=2.0; extra == "dev"
+Requires-Dist: pylibjpeg-openjpeg>=2.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: pybind11>=2.10.0; extra == "all"
+Requires-Dist: nibabel>=3.2.0; extra == "all"
+Description-Content-Type: text/markdown
+
+# DiCube: Medical Image Storage Library
+
+DiCube is a Python library for efficient storage and processing of 3D medical images with complete DICOM metadata preservation. It provides a high-compression, single-file format that combines DICOM compatibility with modern compression techniques.
+
+## Overview
+
+DiCube was extracted from the larger DICOMCube project to focus specifically on medical image storage. It works alongside:
+- **spacetransformer**: For 3D spatial transformations and coordinate systems
+- **medmask**: For medical image segmentation mask processing
+
+## Why DiCube?
+
+Although the DICOM standard is indispensable for clinical interoperability, it was never designed for today’s high-volume, AI-driven workflows.  In practice it exposes four chronic pain-points:
+
+1. **Fragmented storage → slow I/O** A single CT/MR study can contain hundreds of small `.dcm` files.  Traversing the file system and parsing each header one-by-one wastes precious milliseconds that quickly add up when training deep-learning models/ building realtime application.
+2. **Redundant metadata** Every slice repeats identical patient/study/series tags, inflating storage size and network traffic with no benefit.
+3. **Too many transfer syntaxes** Vendors ship proprietary or rarely-used encodings; no open-source decoder reliably supports *all* of them, so pipelines break on edge-cases.
+
+DiCube mitigates these issues by:
+
+* **Single-file design** All slices, metadata and spatial information are consolidated into one `.dcbs` file, eliminating filesystem overhead.
+* **Deduplicated metadata** A compact JSON schema separates *shared* and *per-slice* tags, then compresses them with Zstandard.
+* **Conservative codec policy** Only codecs that pass extensive performance and stability tests are adopted. Currently `.dcbs` uses HTJ2K for fast, lossless compression. Archive (`.dcba`) and lossy (`.dcbl`) variants are planned but not yet released. This package is a self-contained lib, users do not need to install codecs independently.
+* **Round-trip safety** Every DiCube file can always be converted back to standard DICOM, preserving full clinical fidelity.
+
+> In typical benchmarks DiCube cuts CT series load time from ~150 ms (PyDICOM) to <40 ms and shrinks storage by up to **3×**, all while remaining 100 % DICOM-compatible.
+
+## Architecture
+
+### Core Modules
+
+```
+dicube/
+├── core/                 # Core data structures
+│   ├── image.py         # DicomCubeImage (main interface)
+|   ├── io.py            # DicomCubeImageIO (from and to many file formats)
+│   └── pixel_header.py  # PixelDataHeader (image metadata)
+├── storage/             # File storage formats
+│   ├── dcb_file.py      # DCB file format implementations
+│   └── pixel_utils.py   # Pixel processing utilities
+├── dicom/               # DICOM functionality
+│   ├── dicom_meta.py    # DicomMeta (metadata container)
+│   ├── dicom_status.py  # DICOM consistency checking
+│   ├── dicom_tags.py    # DICOM tag definitions
+│   ├── dicom_io.py      # DICOM file I/O
+│   └── merge_utils.py   # Metadata merging utilities
+├── codecs/              # Compression codecs
+│   └── jph/            # HTJ2K codec (dcbs format)
+└── exceptions.py        # Custom exceptions
+```
+
+## File Formats
+
+DiCube defines three file format specifications for different use cases:
+
+### .dcbs (Speed format) - **Currently Implemented**
+- **Magic**: `DCMCUBES`
+- **Target**: I/O speed suitable for deep learning training while high compression ratio.
+- **Codec**: High Throughput JPEG 2000 (HTJ2K)
+- **Use case**: High-speed encoding/decoding for processing pipelines
+- **Features**: Optimized for throughput, lossless compression
+
+### .dcba (Archive format) - **Placeholder**
+- **Magic**: `DCMCUBEA`
+- **Target**: 20% better compression ratio than dcbs
+- **Use case**: Long-term storage and archiving
+- **Status**: Awaiting suitable codec that meets compression targets
+
+### .dcbl (Lossy format) - **Placeholder**
+- **Magic**: `DCMCUBEL`
+- **Target**: 60%+ compression ratio with imperceptible quality loss
+- **Use case**: High-compression scenarios where minor quality trade-offs are acceptable
+- **Status**: Awaiting suitable codec that meets quality/compression targets
+
+> **Codec Selection Philosophy**: We take a conservative approach to codec adoption, requiring extensive testing and clear performance benefits before implementation. This avoids the complexity issues seen in DICOM's numerous format variations.
+
+## Key Classes and Interfaces
+
+### DicomCubeImage
+Main interface for medical image handling:
+
+```python
+import dicube
+
+# Create from DICOM directory
+image = dicube.load_from_dicom_folder('path/to/dicom/')
+
+# Create from NIfTI file
+image = dicube.load_from_nifti('image.nii.gz')
+
+# Save to compressed format (currently only dcbs is implemented)
+dicube.save(image, 'output.dcbs', file_type='s')  # HTJ2K (Speed format)
+
+# Load from file
+loaded_image = dicube.load('output.dcbs')
+
+# Export back to DICOM
+dicube.save_to_dicom_folder(image, 'output_dicom/')
+
+# Get pixel data
+pixel_data = image.get_fdata()  # Returns float array
+raw_data = image.raw_image       # Returns original dtype
+```
+
+### DicomMeta
+DICOM metadata container with efficient shared/non-shared value handling:
+
+```python
+from dicube import DicomMeta, read_dicom_dir
+
+# Read DICOM directory
+meta = read_dicom_dir('dicom_folder/')
+
+# Access shared values (same across all slices)
+patient_name = meta.get('PatientName')  # Returns single value
+
+# Access non-shared values (different per slice)
+positions = meta.get('ImagePositionPatient')  # Returns list
+
+# Check status
+from dicube import get_dicom_status
+status = get_dicom_status(meta)
+```
+
+
+
+## Integration with spacetransformer
+
+DiCube uses `spacetransformer.Space` for 3D coordinate system handling:
+
+```python
+from spacetransformer import Space, warp_image
+
+# DicomCubeImage automatically creates Space from DICOM
+image = dicube.load_from_dicom_folder('dicom/')
+space = image.space  # spacetransformer.Space object
+
+# Apply spatial transformations
+space2 = space.apply_flip(axis=2)
+space2 = space2.apply_rotate(axis=0, angle=90, unit='degree')
+
+# Update image with new space
+image2 = warp_image(image, space, space2)
+```
+
+## DICOM Status Checking
+
+DiCube provides comprehensive DICOM consistency checking:
+
+```python
+from dicube import DicomStatus, get_dicom_status
+
+status = get_dicom_status(meta)
+
+# Possible status values:
+# DicomStatus.CONSISTENT - All checks pass
+# DicomStatus.MISSING_SERIES_UID - No series UID
+# DicomStatus.DUPLICATE_INSTANCE_NUMBERS - Non-unique instance numbers
+# DicomStatus.NON_UNIFORM_SPACING - Inconsistent pixel spacing
+# DicomStatus.GAP_LOCATION - Missing slices in Z direction
+# ... and more
+```
+
+## Compression Codecs
+
+### HTJ2K (jph/)
+- **Status**: Currently implemented for .dcbs format
+- **Files**: `_encode.py`, `_decode.py`, pybind11 bindings  
+- **Functions**: `imencode_jph()`, `imdecode_jph()`
+- **Build**: Uses pybind11 for C++ bindings to OpenJPH library
+- **Performance**: Optimized for high-speed encoding/decoding
+
+## Best Practices
+
+### For Medical Images
+1. Always preserve DICOM metadata when possible
+2. Currently use `.dcbs` format for all storage needs (fast HTJ2K)
+3. Check DICOM status before processing: `get_dicom_status(meta)`
+4. Monitor for updates as `.dcba` and `.dcbl` formats become available
+
+### For Integration
+1. Use spacetransformer for all spatial operations
+2. Use medmask for segmentation mask processing  
+3. Convert coordinates between voxel and world space using `Space` transforms
+4. Validate file format compatibility with `dicube.load()`
+
+### Performance Tips
+1. Use `num_threads` parameter for parallel compression
+2. For large datasets, process in chunks to manage memory
+3. Check DicomStatus before processing to avoid corrupted data
+4. Use HTJ2K's high-speed capabilities for processing pipelines
+
+## Error Handling
+
+```python
+from dicube.exceptions import (
+    DicomCubeError,
+    InvalidCubeFileError, 
+    CodecError,
+    MetaDataError,
+    DataConsistencyError
+)
+
+try:
+    image = dicube.load('corrupted.dcbs')
+except InvalidCubeFileError:
+    print("Not a valid DiCube file")
+except CodecError:
+    print("Compression/decompression failed")
+except MetaDataError:
+    print("Missing or invalid metadata")
+```
+
+## Dependencies
+
+### Required
+- numpy: Array operations
+- pydicom: DICOM file handling
+- spacetransformer: Spatial transformations
+- zstandard: Metadata compression
+
+### Optional (for full functionality)
+- OpenJPH library: For .dcbs format implementation
+- nibabel: For NIfTI file support
+
+ 

dicube-0.1.4.dist-info/RECORD

@@ -0,0 +1,33 @@
+dicube/__init__.py,sha256=QRyaQXqrzwSo8utXhGsbToE_lCEsjlzdzwFwVHINS8I,4189
+dicube/exceptions.py,sha256=YrwBD93oWI4yhvFfO-SOPCNMQ4z_1FSVL2gCVSnx-LU,6689
+dicube/validation.py,sha256=Edmx3yKhRShdzvM7uRK6N9j58GNV8rUv_k9w43JcaMs,12478
+dicube/codecs/__init__.py,sha256=NNus-iAv4JXsNH1kALf5vnLYnESFBoYaN72yJ7kQoqk,3754
+dicube/codecs/jph/ojph_complete.cpython-39-darwin.so,sha256=VIPp4NMamuf3zbUMsgHadBm0Y7Sl2nRLm9tzwkdgGRs,432048
+dicube/codecs/jph/__init__.py,sha256=wLwzqAHCKT_7CdNrcEUtM2AyfvYgPJOj9nsm5CC_3F0,392
+dicube/codecs/jph/ojph_complete.cpython-38-darwin.so,sha256=Bv7L0i6T1u8AUa7uKHpxCfp6HGX_2eyLEpmSB59pLgY,431872
+dicube/codecs/jph/ojph_complete.cpython-310-darwin.so,sha256=XYpfkPuUinxZbE2T6jvrA1Jv0wBzpuJ9fiEy0ha-N_s,432048
+dicube/codecs/jph/ojph_decode_complete.cpython-38-darwin.so,sha256=HHzNB5C3xZ0yhBA_tnzvAHlRdxZ7SBzbwbgjRWvNQ_g,448712
+dicube/codecs/jph/ojph_decode_complete.cpython-310-darwin.so,sha256=QGryn2an05KfDHa9-WDSp5Z1MbZFNTO0WEiWxLGEyUY,448968
+dicube/codecs/jph/ojph_complete.cpython-311-darwin.so,sha256=SmXvkyjn1iCLHfLcmavDWakNC5qE_P4dkMqlNu4dJBc,432144
+dicube/codecs/jph/ojph_decode_complete.cpython-311-darwin.so,sha256=1aXbLZWb6nDX4e2S73dcWW8BnMUytk5AtWIzyxt4aiM,449096
+dicube/codecs/jph/ojph_decode_complete.cpython-39-darwin.so,sha256=OMAfYyAQra6xF_Zv5Y-LGBkg68MYpTK4qwB8lWqlf6U,448968
+dicube/codecs/jph/codec.py,sha256=d4bAoVAatSrWiC1k7gQLzWODZZTGo_1xeRRXO0NAtqo,5460
+dicube/core/io.py,sha256=9Wg9dmVCnZpXQH5fKiS152sKDyy4vOO7ChYpgRL-vzE,13763
+dicube/core/__init__.py,sha256=tU9vaPHbTkF8V78T8D6werr0nC7k6bMPIlatEIEdHU4,656
+dicube/core/pixel_header.py,sha256=M-zu5hFG0BWj0chWgxyGFAQP7oH7r-1iN44acKOLm7k,3929
+dicube/core/image.py,sha256=5XafyshOQbife6M8_G3vmrensjc1jTjyeUkAfAOCKiI,14182
+dicube/utils/__init__.py,sha256=m3pYJfuk4hISVes_cfG2eDjTyGF-y40xbxV07IOjbi0,149
+dicube/storage/__init__.py,sha256=q36sJqdI9acURBXjOW_g3QiyHw0XLGFCukMsQ-qioZc,465
+dicube/storage/dcb_file.py,sha256=Gsb_LXHAm7DqAdrh4Kgo0rrj1mUuz7sY6tVt8HiKXyI,30379
+dicube/storage/pixel_utils.py,sha256=thyYO-YNtWEvg1ROPLC-zPWqa37O0vJ8e26h3aF6dXM,5136
+dicube/dicom/dcb_streaming.py,sha256=6HUmk5QEdg8WhkaiiUDjdX8yMwQxABjmaXaDjxwQuQU,9042
+dicube/dicom/dicom_meta.py,sha256=Iv-kEcV39vhK2qgSqGpqDhgg28RuUm8ddzSdpToIVPc,26813
+dicube/dicom/dicom_io.py,sha256=P-arcQu-CUB0Uf5daLku_Wf-3D3NpY3PiWHaosoe3dA,4941
+dicube/dicom/dicom_status.py,sha256=NXi-sj3mhyaFGfpechewTjhI201vziVsyfLotsLr3Fs,10117
+dicube/dicom/__init__.py,sha256=9b7liSXx5vlpEYAr59GZGkcUw16kULELTX5SlLfcXPw,371
+dicube/dicom/merge_utils.py,sha256=6flzoK_6gzpvv4WSTaWq4SjVdr1gh3gtUPMsRfKDSNM,9312
+dicube/dicom/space_from_meta.py,sha256=__B7UTmvgV1N-LMJg9O_ObHgNWa39mbRF4ZSkQXm3Vs,2420
+dicube/dicom/dicom_tags.py,sha256=sOjrK9SoAhGqynF0e3YH70j8wbtvwGRezV-tM0wp40Q,3945
+dicube-0.1.4.dist-info/RECORD,,
+dicube-0.1.4.dist-info/WHEEL,sha256=11XKa4Dev4vCpAj_5tDGngF8FY4Lo7Z3Hr9WVz5BJMc,114
+dicube-0.1.4.dist-info/METADATA,sha256=lLPPqXaJcIOIHhGuU3buJPhmi3GCMeKi5KW0FhlY0nk,10581

dicube-0.1.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: scikit-build-core 0.11.5
+Root-Is-Purelib: false
+Tag: cp311-cp311-macosx_11_0_arm64
+