cardiac-shared 0.3.0__tar.gz

cardiac_shared-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Rong Zhu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cardiac_shared-0.3.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: cardiac-shared
+Version: 0.3.0
+Summary: Shared utilities for cardiac imaging analysis - hardware detection, IO, environment detection
+Author-email: Rong Zhu <zhurong0525@gmail.com>
+Maintainer-email: Rong Zhu <zhurong0525@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/zhurong2020/cardiac-shared
+Project-URL: Documentation, https://github.com/zhurong2020/cardiac-shared/blob/main/README.md
+Project-URL: Repository, https://github.com/zhurong2020/cardiac-shared
+Project-URL: Bug Tracker, https://github.com/zhurong2020/cardiac-shared/issues
+Project-URL: Changelog, https://github.com/zhurong2020/cardiac-shared/blob/main/CHANGELOG.md
+Keywords: cardiac,medical-imaging,dicom,nifti,ct-scan,hardware-detection,gpu,totalsegmentator
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Healthcare Industry
+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.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.0,>=1.19.0
+Requires-Dist: psutil>=5.8.0
+Provides-Extra: dicom
+Requires-Dist: pydicom>=2.0.0; extra == "dicom"
+Provides-Extra: nifti
+Requires-Dist: nibabel>=3.2.0; extra == "nifti"
+Provides-Extra: gpu
+Requires-Dist: torch>=1.9.0; extra == "gpu"
+Provides-Extra: all
+Requires-Dist: pydicom>=2.0.0; extra == "all"
+Requires-Dist: nibabel>=3.2.0; extra == "all"
+Requires-Dist: torch>=1.9.0; extra == "all"
+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"
+Dynamic: license-file
+
+# Cardiac Shared
+
+Shared utilities for cardiac imaging analysis projects.
+
+**Version**: 0.2.0
+
+## Installation
+
+```bash
+# Install with all features
+pip install -e ".[all]"
+
+# Install with DICOM support only
+pip install -e ".[dicom]"
+
+# Install with NIfTI support only
+pip install -e ".[nifti]"
+```
+
+## Modules
+
+### IO Module
+
+| Function | Description |
+|----------|-------------|
+| `read_dicom_series(path)` | Read DICOM series from directory |
+| `get_dicom_metadata(ds)` | Extract metadata from DICOM dataset |
+| `load_nifti(path)` | Load NIfTI file with metadata |
+| `save_nifti(volume, path)` | Save numpy array as NIfTI |
+| `extract_zip(path)` | Context manager for ZIP extraction |
+| `find_dicom_root(path)` | Find DICOM directory in extracted ZIP |
+
+### Hardware Module (v0.2.0)
+
+| Function | Description |
+|----------|-------------|
+| `detect_hardware()` | Detect complete hardware info (GPU/CPU/RAM) |
+| `HardwareInfo` | Dataclass with GPU, CPU, RAM, environment info |
+| `print_hardware_summary(hw)` | Print formatted hardware summary |
+| `get_optimal_config(hw)` | Get optimal inference configuration |
+| `CPUOptimizer` | CPU optimization for hospital deployments |
+| `apply_cpu_optimizations(config)` | Apply PyTorch CPU optimizations |
+
+### Environment Module (v0.2.0)
+
+| Function | Description |
+|----------|-------------|
+| `detect_runtime()` | Detect runtime environment |
+| `RuntimeEnvironment` | Dataclass with environment info |
+| `detect_colab()` | Check if running in Google Colab |
+| `detect_wsl()` | Check if running in WSL |
+| `print_environment_summary(env)` | Print environment summary |
+
+## Usage
+
+### IO Operations
+
+```python
+from cardiac_shared.io import read_dicom_series, load_nifti, extract_zip, find_dicom_root
+
+# Read DICOM series
+volume, metadata = read_dicom_series("/path/to/dicom/")
+
+# Read NIfTI file
+volume, metadata = load_nifti("/path/to/file.nii.gz")
+
+# Extract ZIP and read DICOM
+with extract_zip("/path/to/data.zip") as extracted_dir:
+    dicom_root = find_dicom_root(extracted_dir)
+    volume, metadata = read_dicom_series(dicom_root)
+```
+
+### Hardware Detection
+
+```python
+from cardiac_shared import detect_hardware, print_hardware_summary
+
+hw = detect_hardware()
+print_hardware_summary(hw)
+
+print(f"Performance Tier: {hw.performance_tier}")
+print(f"Recommended Device: {hw.recommended_device}")
+print(f"GPU Available: {hw.gpu.available}")
+print(f"CPU Cores: {hw.cpu.physical_cores}")
+```
+
+### Environment Detection
+
+```python
+from cardiac_shared import detect_runtime, print_environment_summary
+
+env = detect_runtime()
+print_environment_summary(env)
+
+print(f"Runtime Type: {env.runtime_type}")
+print(f"Is WSL: {env.is_wsl}")
+print(f"Is Hospital Environment: {env.is_hospital_environment}")
+```
+
+### CPU Optimization (Hospital Deployment)
+
+```python
+from cardiac_shared import detect_hardware, detect_runtime, CPUOptimizer
+
+hw = detect_hardware()
+env = detect_runtime()
+
+if env.is_hospital_environment and not hw.gpu.available:
+    optimizer = CPUOptimizer()
+    config = optimizer.get_optimal_config()
+
+    print(f"CPU Tier: {config.tier.value}")
+    print(f"Recommended Workers: {config.num_workers}")
+    print(f"Batch Size: {config.batch_size}")
+
+    # Apply PyTorch optimizations
+    optimizer.apply_torch_optimizations(config)
+```
+
+## Projects Using This Package
+
+- cardiac-ml-research (main project)
+- ai-cac-research (CAC scoring research)
+- pcfa (Pericardial Fat Analysis)
+- vbca (Vertebra Body Composition Analysis)
+
+## Changelog
+
+### v0.2.0 (2026-01-01)
+- Added `hardware` module (detector, cpu_optimizer)
+- Added `environment` module (runtime_detector)
+- Migrated from cardiac-ml-research/shared/
+
+### v0.1.0 (2026-01-01)
+- Initial release
+- IO modules: dicom, nifti, zip_handler

cardiac_shared-0.3.0/README.md

@@ -0,0 +1,136 @@
+# Cardiac Shared
+
+Shared utilities for cardiac imaging analysis projects.
+
+**Version**: 0.2.0
+
+## Installation
+
+```bash
+# Install with all features
+pip install -e ".[all]"
+
+# Install with DICOM support only
+pip install -e ".[dicom]"
+
+# Install with NIfTI support only
+pip install -e ".[nifti]"
+```
+
+## Modules
+
+### IO Module
+
+| Function | Description |
+|----------|-------------|
+| `read_dicom_series(path)` | Read DICOM series from directory |
+| `get_dicom_metadata(ds)` | Extract metadata from DICOM dataset |
+| `load_nifti(path)` | Load NIfTI file with metadata |
+| `save_nifti(volume, path)` | Save numpy array as NIfTI |
+| `extract_zip(path)` | Context manager for ZIP extraction |
+| `find_dicom_root(path)` | Find DICOM directory in extracted ZIP |
+
+### Hardware Module (v0.2.0)
+
+| Function | Description |
+|----------|-------------|
+| `detect_hardware()` | Detect complete hardware info (GPU/CPU/RAM) |
+| `HardwareInfo` | Dataclass with GPU, CPU, RAM, environment info |
+| `print_hardware_summary(hw)` | Print formatted hardware summary |
+| `get_optimal_config(hw)` | Get optimal inference configuration |
+| `CPUOptimizer` | CPU optimization for hospital deployments |
+| `apply_cpu_optimizations(config)` | Apply PyTorch CPU optimizations |
+
+### Environment Module (v0.2.0)
+
+| Function | Description |
+|----------|-------------|
+| `detect_runtime()` | Detect runtime environment |
+| `RuntimeEnvironment` | Dataclass with environment info |
+| `detect_colab()` | Check if running in Google Colab |
+| `detect_wsl()` | Check if running in WSL |
+| `print_environment_summary(env)` | Print environment summary |
+
+## Usage
+
+### IO Operations
+
+```python
+from cardiac_shared.io import read_dicom_series, load_nifti, extract_zip, find_dicom_root
+
+# Read DICOM series
+volume, metadata = read_dicom_series("/path/to/dicom/")
+
+# Read NIfTI file
+volume, metadata = load_nifti("/path/to/file.nii.gz")
+
+# Extract ZIP and read DICOM
+with extract_zip("/path/to/data.zip") as extracted_dir:
+    dicom_root = find_dicom_root(extracted_dir)
+    volume, metadata = read_dicom_series(dicom_root)
+```
+
+### Hardware Detection
+
+```python
+from cardiac_shared import detect_hardware, print_hardware_summary
+
+hw = detect_hardware()
+print_hardware_summary(hw)
+
+print(f"Performance Tier: {hw.performance_tier}")
+print(f"Recommended Device: {hw.recommended_device}")
+print(f"GPU Available: {hw.gpu.available}")
+print(f"CPU Cores: {hw.cpu.physical_cores}")
+```
+
+### Environment Detection
+
+```python
+from cardiac_shared import detect_runtime, print_environment_summary
+
+env = detect_runtime()
+print_environment_summary(env)
+
+print(f"Runtime Type: {env.runtime_type}")
+print(f"Is WSL: {env.is_wsl}")
+print(f"Is Hospital Environment: {env.is_hospital_environment}")
+```
+
+### CPU Optimization (Hospital Deployment)
+
+```python
+from cardiac_shared import detect_hardware, detect_runtime, CPUOptimizer
+
+hw = detect_hardware()
+env = detect_runtime()
+
+if env.is_hospital_environment and not hw.gpu.available:
+    optimizer = CPUOptimizer()
+    config = optimizer.get_optimal_config()
+
+    print(f"CPU Tier: {config.tier.value}")
+    print(f"Recommended Workers: {config.num_workers}")
+    print(f"Batch Size: {config.batch_size}")
+
+    # Apply PyTorch optimizations
+    optimizer.apply_torch_optimizations(config)
+```
+
+## Projects Using This Package
+
+- cardiac-ml-research (main project)
+- ai-cac-research (CAC scoring research)
+- pcfa (Pericardial Fat Analysis)
+- vbca (Vertebra Body Composition Analysis)
+
+## Changelog
+
+### v0.2.0 (2026-01-01)
+- Added `hardware` module (detector, cpu_optimizer)
+- Added `environment` module (runtime_detector)
+- Migrated from cardiac-ml-research/shared/
+
+### v0.1.0 (2026-01-01)
+- Initial release
+- IO modules: dicom, nifti, zip_handler

cardiac_shared-0.3.0/cardiac_shared/__init__.py

@@ -0,0 +1,127 @@
+"""
+Cardiac Shared - Common utilities for cardiac imaging projects
+
+This package provides shared IO, hardware detection, environment detection,
+parallel processing, progress tracking, caching, and configuration management
+for cardiac imaging analysis across multiple projects.
+
+Modules:
+- io: DICOM, NIfTI, and ZIP file handling
+- hardware: Hardware detection and CPU optimization
+- environment: Runtime environment detection
+- parallel: Parallel processing with checkpoint support
+- progress: Multi-level progress tracking
+- cache: Result caching with resume capability
+- batch: Batch processing framework
+- config: YAML configuration management
+"""
+
+__version__ = "0.3.0"
+
+# IO modules
+from cardiac_shared.io.dicom import read_dicom_series, get_dicom_metadata
+from cardiac_shared.io.nifti import load_nifti, save_nifti
+from cardiac_shared.io.zip_handler import extract_zip, find_dicom_root
+
+# Hardware detection
+from cardiac_shared.hardware import (
+    detect_hardware,
+    HardwareInfo,
+    GPUInfo,
+    CPUInfo,
+    RAMInfo,
+    print_hardware_summary,
+    get_optimal_config,
+    CPUOptimizer,
+    get_cpu_optimizer,
+    apply_cpu_optimizations,
+)
+
+# Environment detection
+from cardiac_shared.environment import (
+    detect_runtime,
+    RuntimeEnvironment,
+    detect_colab,
+    detect_wsl,
+    print_environment_summary,
+)
+
+# Parallel processing
+from cardiac_shared.parallel import (
+    ParallelProcessor,
+    ProcessingResult,
+    Checkpoint,
+    parallel_map,
+    parallel_map_with_checkpoint,
+)
+
+# Progress tracking
+from cardiac_shared.progress import (
+    ProgressTracker,
+    ProgressLevel,
+    create_tracker,
+)
+
+# Cache management
+from cardiac_shared.cache import CacheManager
+
+# Batch processing
+from cardiac_shared.batch import BatchProcessor, BatchConfig
+
+# Configuration management
+from cardiac_shared.config import ConfigManager, load_config
+
+__all__ = [
+    # Version
+    '__version__',
+
+    # IO
+    'read_dicom_series',
+    'get_dicom_metadata',
+    'load_nifti',
+    'save_nifti',
+    'extract_zip',
+    'find_dicom_root',
+
+    # Hardware
+    'detect_hardware',
+    'HardwareInfo',
+    'GPUInfo',
+    'CPUInfo',
+    'RAMInfo',
+    'print_hardware_summary',
+    'get_optimal_config',
+    'CPUOptimizer',
+    'get_cpu_optimizer',
+    'apply_cpu_optimizations',
+
+    # Environment
+    'detect_runtime',
+    'RuntimeEnvironment',
+    'detect_colab',
+    'detect_wsl',
+    'print_environment_summary',
+
+    # Parallel
+    'ParallelProcessor',
+    'ProcessingResult',
+    'Checkpoint',
+    'parallel_map',
+    'parallel_map_with_checkpoint',
+
+    # Progress
+    'ProgressTracker',
+    'ProgressLevel',
+    'create_tracker',
+
+    # Cache
+    'CacheManager',
+
+    # Batch
+    'BatchProcessor',
+    'BatchConfig',
+
+    # Config
+    'ConfigManager',
+    'load_config',
+]

cardiac_shared-0.3.0/cardiac_shared/batch/__init__.py

@@ -0,0 +1,162 @@
+"""
+Batch Processing Module
+
+Generic batch processor with resume capability for medical imaging pipelines.
+"""
+
+from pathlib import Path
+from typing import Callable, List, Any, Optional, Dict
+from dataclasses import dataclass
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class BatchConfig:
+    """Batch processing configuration"""
+    enable_resume: bool = True
+    cache_dir: Optional[Path] = None
+    save_intermediate: bool = True
+    log_interval: int = 10
+
+
+class BatchProcessor:
+    """
+    Generic batch processor with resume capability
+
+    Features:
+    - Resume from interruption
+    - Progress tracking
+    - Cache management
+    - Flexible callback system
+
+    Example:
+        processor = BatchProcessor(cache_dir=Path("cache"))
+
+        results = processor.process(
+            items=patient_list,
+            process_func=analyze_patient,
+            get_item_id=lambda p: p.id,
+            desc="Analyzing patients"
+        )
+
+        processor.print_summary(results)
+    """
+
+    def __init__(self, config: Optional[BatchConfig] = None, cache_dir: Optional[Path] = None):
+        """
+        Initialize batch processor
+
+        Args:
+            config: BatchConfig instance
+            cache_dir: Directory for cache files
+        """
+        self.config = config or BatchConfig()
+        if cache_dir:
+            self.config.cache_dir = Path(cache_dir)
+
+        self._results: List[Dict] = []
+
+    def process(
+        self,
+        items: List[Any],
+        process_func: Callable[[Any], Any],
+        get_item_id: Optional[Callable[[Any], str]] = None,
+        desc: str = "Processing",
+        on_complete: Optional[Callable[[str, Any], None]] = None,
+        on_error: Optional[Callable[[str, Exception], None]] = None
+    ) -> List[Dict]:
+        """
+        Process items in batch
+
+        Args:
+            items: List of items to process
+            process_func: Function to process each item
+            get_item_id: Function to extract item ID (default: str)
+            desc: Description for logging
+            on_complete: Callback on successful processing
+            on_error: Callback on error
+
+        Returns:
+            List of result dictionaries
+        """
+        if get_item_id is None:
+            get_item_id = str
+
+        self._results = []
+        total = len(items)
+
+        logger.info(f"{desc}: Starting batch of {total} items")
+
+        for i, item in enumerate(items, 1):
+            item_id = get_item_id(item)
+
+            try:
+                result = process_func(item)
+
+                self._results.append({
+                    'item_id': item_id,
+                    'status': 'success',
+                    'result': result
+                })
+
+                if on_complete:
+                    on_complete(item_id, result)
+
+            except Exception as e:
+                self._results.append({
+                    'item_id': item_id,
+                    'status': 'failed',
+                    'error': str(e)
+                })
+
+                if on_error:
+                    on_error(item_id, e)
+
+                logger.warning(f"Failed to process {item_id}: {e}")
+
+            # Log progress periodically
+            if i % self.config.log_interval == 0 or i == total:
+                success = sum(1 for r in self._results if r['status'] == 'success')
+                logger.info(f"{desc}: {i}/{total} completed ({success} successful)")
+
+        return self._results
+
+    def get_statistics(self) -> Dict:
+        """Get processing statistics"""
+        total = len(self._results)
+        success = sum(1 for r in self._results if r['status'] == 'success')
+        failed = total - success
+
+        return {
+            'total': total,
+            'success': success,
+            'failed': failed,
+            'success_rate': (success / total * 100) if total > 0 else 0
+        }
+
+    def print_summary(self, results: Optional[List[Dict]] = None):
+        """Print processing summary"""
+        if results:
+            self._results = results
+
+        stats = self.get_statistics()
+
+        print()
+        print("=" * 60)
+        print("Batch Processing Summary")
+        print("=" * 60)
+        print(f"Total: {stats['total']}")
+        print(f"Success: {stats['success']} ({stats['success_rate']:.1f}%)")
+        print(f"Failed: {stats['failed']}")
+        print("=" * 60)
+
+        if stats['failed'] > 0:
+            print("\nFailed items:")
+            for r in self._results:
+                if r['status'] == 'failed':
+                    print(f"  - {r['item_id']}: {r.get('error', 'Unknown error')}")
+
+
+__all__ = ['BatchProcessor', 'BatchConfig']