dicube 0.1.4__tar.gz

dicube-0.1.4/.cursor/rules/error-handling.mdc

@@ -0,0 +1,39 @@
+---
+description: Guidelines for error handling in DiCube
+---
+# Error Handling in DiCube
+
+DiCube provides a hierarchy of exception classes in [dicube/exceptions.py](mdc:dicube/exceptions.py)
+
+## Key Exceptions
+
+```python
+from dicube.exceptions import (
+    DicomCubeError,       # Base exception for all DiCube errors
+    InvalidCubeFileError, # Invalid file format or corrupted file
+    CodecError,           # Compression/decompression failures
+    MetaDataError,        # Missing or invalid metadata
+    DataConsistencyError  # Inconsistent data structure
+)
+```
+
+## Best Practices
+
+1. **Use specific exceptions** rather than generic ones
+2. **Include descriptive error messages** to aid debugging
+3. **Chain exceptions** when re-raising to preserve context
+4. **Validate early** to catch errors before processing begins
+5. **Clean up resources** in finally blocks or context managers
+
+## Example Usage
+
+```python
+try:
+    image = dicube.load(\"corrupted.dcbs\")
+except InvalidCubeFileError as e:
+    print(f\"Not a valid DiCube file: {e}\")
+except CodecError as e:
+    print(f\"Compression/decompression failed: {e}\")
+except MetaDataError as e:
+    print(f\"Missing or invalid metadata: {e}\")
+```

dicube-0.1.4/.cursor/rules/file-formats.mdc

@@ -0,0 +1,26 @@
+---
+description: Information about DiCube file formats and specifications
+---
+# DiCube File Formats
+
+DiCube defines three file format specifications:
+
+## Currently Implemented
+
+### .dcbs (Speed Format)
+- **Magic**: `DCMCUBES`
+- **Target**: I/O speed suitable for deep learning training with high compression ratio
+- **Codec**: High Throughput JPEG 2000 (HTJ2K)
+- **Implementation**: [storage/dcb_file.py](mdc:dicube/storage/dcb_file.py) and [codecs/jph/](mdc:dicube/codecs/jph/)
+
+## Placeholder Formats (Future Implementation)
+
+### .dcba (Archive Format) 
+- **Magic**: `DCMCUBEA`
+- **Target**: 20% better compression ratio than dcbs
+- **Use case**: Long-term storage and archiving
+
+### .dcbl (Lossy Format)
+- **Magic**: `DCMCUBEL`
+- **Target**: 60%+ compression ratio with imperceptible quality loss
+- **Use case**: High-compression scenarios where minor quality trade-offs are acceptable

dicube-0.1.4/.cursor/rules/key-classes.mdc

@@ -0,0 +1,52 @@
+---
+description: Key classes and interfaces in the DiCube library
+---
+# Key Classes and Interfaces
+
+## DicomCubeImage
+Main interface for medical image handling, defined in [dicube/core/image.py](mdc:dicube/core/image.py)
+
+```python
+import dicube
+
+# Create from DICOM directory
+image = dicube.load_from_dicom_folder(\"path/to/dicom/\")
+
+# Save to compressed format 
+dicube.save(image, \"output.dcbs\", file_type=\"s\")  # HTJ2K (Speed format)
+
+# Load from file
+loaded_image = dicube.load(\"output.dcbs\")
+
+# 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:
+Defined in [dicube/dicom/dicom_meta.py](mdc:dicube/dicom/dicom_meta.py)
+
+```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
+```
+
+## DicomStatus
+DICOM consistency checking provided in [dicube/dicom/dicom_status.py](mdc:dicube/dicom/dicom_status.py)
+
+```python
+from dicube import DicomStatus, get_dicom_status
+
+status = get_dicom_status(meta)
+```
+
+Common status values include: `CONSISTENT`, `MISSING_SERIES_UID`, `DUPLICATE_INSTANCE_NUMBERS`, `NON_UNIFORM_SPACING`, etc.

dicube-0.1.4/.cursor/rules/project-structure.mdc

@@ -0,0 +1,33 @@
+---
+alwaysApply: true
+---
+
+# DiCube Project Structure
+
+DiCube is a Python library for efficient storage and processing of 3D medical images with complete DICOM metadata preservation.
+
+## Project Organization
+
+- **Core modules** in [dicube/core/](mdc:dicube/core/)
+  - [image.py](mdc:dicube/core/image.py): DicomCubeImage (main interface)
+  - [io.py](mdc:dicube/core/io.py): DicomCubeImageIO (file format I/O)
+  - [pixel_header.py](mdc:dicube/core/pixel_header.py): PixelDataHeader (image metadata)
+
+- **DICOM handling** in [dicube/dicom/](mdc:dicube/dicom/)
+  - [dicom_meta.py](mdc:dicube/dicom/dicom_meta.py): DicomMeta (metadata container)
+  - [dicom_status.py](mdc:dicube/dicom/dicom_status.py): DICOM consistency checking
+  - [dicom_tags.py](mdc:dicube/dicom/dicom_tags.py): DICOM tag definitions
+  - [dicom_io.py](mdc:dicube/dicom/dicom_io.py): DICOM file I/O
+  - [merge_utils.py](mdc:dicube/dicom/merge_utils.py): Metadata merging utilities
+
+- **Storage formats** in [dicube/storage/](mdc:dicube/storage/)
+  - [dcb_file.py](mdc:dicube/storage/dcb_file.py): DCB file format implementations
+  - [pixel_utils.py](mdc:dicube/storage/pixel_utils.py): Pixel processing utilities
+
+- **Compression codecs** in [dicube/codecs/](mdc:dicube/codecs/)
+  - [jph/](mdc:dicube/codecs/jph/): HTJ2K codec implementation
+
+- **Entry point**: [dicube/__init__.py](mdc:dicube/__init__.py)
+- **Exceptions**: [dicube/exceptions.py](mdc:dicube/exceptions.py)
+
+This library works alongside `spacetransformer` (for 3D spatial transformations) and `medmask` (for medical image segmentation).

dicube-0.1.4/.cursor/rules/python-style.mdc

@@ -0,0 +1,46 @@
+---
+globs: *.py
+---
+# Python Code Style Guide
+
+When writing or modifying Python code in this project, follow these guidelines:
+
+1. Use **type annotations** wherever possible for improved code clarity and IDE support.
+2. Import order should be:
+   - Standard library imports
+   - Third-party imports
+   - Local imports (from dicube)
+3. Use **Google style docstrings** for all functions, classes, and modules:
+
+```python
+def function_example(param1, param2):
+    """Short description of function purpose.
+    
+    Args:
+        param1 (type): Description of parameter.
+        param2 (type): Description of parameter.
+        
+    Returns:
+        type: Description of return value.
+        
+    Raises:
+        ExceptionType: When and why this exception is raised.
+        
+    Example:
+        >>> result = function_example(1, 2)
+        >>> print(result)
+        3
+    """
+```
+
+4. Keep functions **focused** and **single-purpose**.
+5. For error handling:
+   - Use specific exceptions from [dicube/exceptions.py](mdc:dicube/exceptions.py)
+   - Validate input parameters early
+   - Add clear error messages
+6. For complex operations, add comments explaining the algorithm or approach.
+7. Use constants for magic values and define them at the module level.
+8. Performance matters - use numpy vectorized operations where possible.
+9. Method naming follows standard Python conventions:
+   - Methods that modify state: `set_`, `update_`, etc.
+   - Methods that return new objects without modifying state: `get_`, `compute_`, etc.

dicube-0.1.4/.github/actions/setup-python-env/action.yml

@@ -0,0 +1,39 @@
+name: 'Setup Python Environment'
+description: 'Setup Python with common dependencies'
+inputs:
+  python-version:
+    description: 'Python version to use'
+    required: true
+    default: '3.9'
+  install-dev:
+    description: 'Install development dependencies'
+    required: false
+    default: 'false'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ inputs.python-version }}
+    
+    - name: Cache pip
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ inputs.python-version }}-${{ hashFiles('**/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-${{ inputs.python-version }}-
+    
+    - name: Install base dependencies
+      shell: bash
+      run: |
+        python -m pip install --upgrade pip
+        pip install wheel setuptools
+    
+    - name: Install dev dependencies
+      if: inputs.install-dev == 'true'
+      shell: bash
+      run: |
+        pip install ruff black mypy pytest pytest-cov 

dicube-0.1.4/.github/workflows/build-wheels.yml

@@ -0,0 +1,101 @@
+name: Build Wheels
+
+on:
+  push:
+    tags: ['v*']
+    branches: ['feat/test_build']
+  pull_request:
+    branches: [main, master]
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          ref: ${{ github.ref }}
+          # Ensure full history to prevent setuptools_scm issues
+          fetch-depth: 0
+
+      # For Windows, we need to manually install pip
+      - name: Set up Windows environment
+        if: runner.os == 'Windows'
+        run: |
+          python -m pip install --upgrade pip
+
+      - name: Build wheels
+        # Using explicit command to avoid empty parameter issues on Windows
+        run: |
+          python -m pip install cibuildwheel==2.16.2
+          python -m cibuildwheel
+        env:
+          CIBW_BUILD: cp38-* cp39-* cp310-* cp311-* cp312-*
+          CIBW_SKIP: pp* *-musllinux*
+          CIBW_ARCHS_LINUX: auto
+          CIBW_ARCHS_MACOS: x86_64 arm64
+          CIBW_ARCHS_WINDOWS: auto
+          
+          # 更健壮的依赖安装方式
+          CIBW_BEFORE_ALL_LINUX: |
+            if command -v yum &>/dev/null; then
+              # Try multiple times with increasing timeouts (network issues)
+              for i in 1 2 3; do
+                echo "Attempt $i: Installing dependencies with yum..."
+                yum install -y cmake gcc-c++ && break || sleep 5
+              done
+            elif command -v apt-get &>/dev/null; then
+              echo "Installing dependencies with apt..."
+              apt-get update -y && apt-get install -y cmake g++
+            elif command -v apk &>/dev/null; then
+              echo "Installing dependencies with apk..."
+              apk add --no-cache cmake g++
+            else
+              echo "No supported package manager found!"
+              exit 1
+            fi
+          CIBW_BEFORE_ALL_MACOS: |
+            brew install cmake
+          CIBW_BEFORE_ALL_WINDOWS: |
+            choco install cmake
+          
+          # 简单的测试
+          CIBW_TEST_COMMAND: |
+            python -c "from dicube.codecs.jph import JphCodec; print('Import test passed successfully')"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          ref: ${{ github.ref }}
+          # Ensure full history to prevent setuptools_scm issues
+          fetch-depth: 0
+
+      - uses: ./.github/actions/setup-python-env
+        with:
+          python-version: '3.9'
+
+      - name: Build sdist
+        run: |
+          pip install build setuptools_scm
+          python -m build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz 

dicube-0.1.4/.github/workflows/release.yml

@@ -0,0 +1,86 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag (for manual dispatch)'
+        required: false
+        default: ''
+        type: string
+
+jobs:
+  # 构建 wheels 和 sdist
+  build:
+    uses: ./.github/workflows/build-wheels.yml
+  
+  # 发布到 GitHub Release
+  github-release:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'release'
+    permissions:
+      contents: write
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      
+      - name: List release assets
+        run: |
+          echo "📦 Release assets:"
+          ls -la dist/
+          echo "Total wheels: $(ls dist/*.whl 2>/dev/null | wc -l)"
+          echo "Source dist: $(ls dist/*.tar.gz 2>/dev/null | wc -l)"
+      
+      - name: Upload to GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: dist/*
+          fail_on_unmatched_files: true
+          generate_release_notes: true
+
+  # 发布到 PyPI
+  pypi-release:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'release'
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          verbose: true
+
+  # 发布总结
+  release-summary:
+    runs-on: ubuntu-latest
+    needs: [github-release, pypi-release]
+    if: always()
+    steps:
+      - name: Release Summary
+        run: |
+          echo "## 🚀 Release Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- GitHub Release: ${{ needs.github-release.result == 'success' && '✅ Success' || '❌ Failed' }}" >> $GITHUB_STEP_SUMMARY
+          echo "- PyPI Release: ${{ needs.pypi-release.result == 'success' && '✅ Success' || '❌ Failed' }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          if [[ "${{ needs.github-release.result }}" == "success" && "${{ needs.pypi-release.result }}" == "success" ]]; then
+            echo "✅ Release completed successfully!" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "❌ Release encountered issues" >> $GITHUB_STEP_SUMMARY
+          fi 

dicube-0.1.4/.github/workflows/test.yml

@@ -0,0 +1,43 @@
+name: Test
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  workflow_dispatch:
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ['3.8', '3.12']  # 只测试最低和最高版本
+    
+    runs-on: ${{ matrix.os }}
+    
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      
+      - uses: ./.github/actions/setup-python-env
+        with:
+          python-version: ${{ matrix.python-version }}
+          install-dev: 'true'
+      
+      # 安装和测试
+      - name: Install package
+        run: |
+          pip install -e .[dev]
+      
+      - name: Run tests
+        run: |
+          pytest tests/ -v --tb=short
+          
+          # 基本导入测试
+          python -c "
+          import dicube
+          from dicube.codecs.jph import JphCodec
+          print(f'dicube version: {dicube.__version__} - Import successful')
+          " 

dicube-0.1.4/.gitignore

@@ -0,0 +1,65 @@
+.kiro
+trash
+dicube/_version.py
+*.mska
+*.msk
+*.nii
+*.nii.gz
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+pytest_cache/
+
+# MyPy / Pyright / Pyre type checker
+.mypy_cache/
+.pyre/
+.pytype/
+
+# VS Code
+.vscode/
+
+# IDEs
+.idea/
+
+# Environments
+.env
+.venv
+venv/
+ENV/
+
+# Jupyter Notebook checkpoints
+.ipynb_checkpoints/
+
+# Mac / Linux
+.DS_Store
+*.swp
+
+# Logs
+*.log
+
+# uv local cache
+.uv/ 

dicube-0.1.4/.gitmodules

@@ -0,0 +1,6 @@
+[submodule "source/OpenJPH"]
+	path = source/OpenJPH
+	url = https://github.com/aous72/OpenJPH.git
+[submodule "testdata"]
+	path = testdata
+	url = git@github.com:fastdiag-toolbox/dicube-testdata.git

dicube-0.1.4/CMakeLists.txt

@@ -0,0 +1,141 @@
+cmake_minimum_required(VERSION 3.15.0)
+
+project(dicube-openjph 
+    VERSION 0.1.0
+    DESCRIPTION "DiCube with statically linked OpenJPH"
+    LANGUAGES CXX
+)
+
+# 设置 C++ 标准
+set(CMAKE_CXX_STANDARD 14)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# 构建类型
+if(NOT CMAKE_BUILD_TYPE)
+    set(CMAKE_BUILD_TYPE "Release" CACHE STRING "Build type" FORCE)
+endif()
+
+# 设置输出目录
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
+
+# ================================================================================================
+# 选项配置
+# ================================================================================================
+
+option(DICUBE_BUILD_PYTHON_EXTENSIONS "Build Python extensions" ON)
+
+# ================================================================================================
+# 编译器设置
+# ================================================================================================
+
+if(MSVC)
+    # Windows MSVC 设置
+    add_compile_definitions(_CRT_SECURE_NO_WARNINGS)
+    add_compile_options(/W3 /EHsc)
+    # 静态链接 CRT
+    set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+else()
+    # GCC/Clang 设置
+    add_compile_options(-fexceptions -Wall -Wextra -fPIC)
+    if(CMAKE_BUILD_TYPE STREQUAL "Release")
+        add_compile_options(-O3 -DNDEBUG)
+    endif()
+endif()
+
+# ================================================================================================
+# OpenJPH 构建
+# ================================================================================================
+
+# 检查 OpenJPH 源码
+set(OPENJPH_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/source/OpenJPH")
+if(NOT EXISTS "${OPENJPH_SOURCE_DIR}/CMakeLists.txt")
+    message(FATAL_ERROR 
+        "OpenJPH source not found. Please run: git submodule update --init --recursive"
+    )
+endif()
+
+# OpenJPH 构建选项
+set(BUILD_SHARED_LIBS OFF CACHE BOOL "" FORCE)
+set(OJPH_ENABLE_TIFF_SUPPORT OFF CACHE BOOL "" FORCE)
+set(OJPH_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+set(OJPH_BUILD_EXECUTABLES OFF CACHE BOOL "" FORCE)
+set(OJPH_BUILD_STREAM_EXPAND OFF CACHE BOOL "" FORCE)
+set(OJPH_DISABLE_SIMD OFF CACHE BOOL "" FORCE)  # 启用 SIMD 优化
+
+# 添加 OpenJPH
+add_subdirectory(${OPENJPH_SOURCE_DIR} openjph EXCLUDE_FROM_ALL)
+
+# 设置 OpenJPH 目标和头文件
+set(OPENJPH_TARGET openjph)
+set(OPENJPH_INCLUDE_DIRS 
+    "${OPENJPH_SOURCE_DIR}/src/core/common"
+    "${CMAKE_BINARY_DIR}/openjph/src/core/common"  # 生成的配置文件
+)
+
+# ================================================================================================
+# Python 扩展构建
+# ================================================================================================
+
+if(DICUBE_BUILD_PYTHON_EXTENSIONS)
+    # 查找 Python 和 pybind11
+    find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
+    find_package(pybind11 REQUIRED)
+    
+    # 查找 NumPy
+    execute_process(
+        COMMAND ${Python_EXECUTABLE} -c "import numpy; print(numpy.get_include())"
+        OUTPUT_VARIABLE NUMPY_INCLUDE_DIR
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
+    
+    if(NOT NUMPY_INCLUDE_DIR)
+        message(FATAL_ERROR "NumPy not found")
+    endif()
+    
+    # 构建 Python 扩展
+    pybind11_add_module(ojph_complete dicube/codecs/jph/encode_complete.cpp)
+    pybind11_add_module(ojph_decode_complete dicube/codecs/jph/decode_complete.cpp)
+    
+    # 设置包含目录和链接
+    foreach(target ojph_complete ojph_decode_complete)
+        target_include_directories(${target} PRIVATE
+            ${OPENJPH_INCLUDE_DIRS}
+            ${NUMPY_INCLUDE_DIR}
+        )
+        target_link_libraries(${target} PRIVATE ${OPENJPH_TARGET})
+        
+        # 确保 .pyd/.so 文件直接放在正确的目录，不带 Release 子目录
+        if(MSVC)
+            # Windows特殊处理，防止产生 Release 子目录
+            set_target_properties(${target} PROPERTIES
+                RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/dicube/codecs/jph
+                RUNTIME_OUTPUT_DIRECTORY_RELEASE ${CMAKE_CURRENT_SOURCE_DIR}/dicube/codecs/jph
+                RUNTIME_OUTPUT_DIRECTORY_DEBUG ${CMAKE_CURRENT_SOURCE_DIR}/dicube/codecs/jph
+                LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/dicube/codecs/jph
+                LIBRARY_OUTPUT_DIRECTORY_RELEASE ${CMAKE_CURRENT_SOURCE_DIR}/dicube/codecs/jph
+                LIBRARY_OUTPUT_DIRECTORY_DEBUG ${CMAKE_CURRENT_SOURCE_DIR}/dicube/codecs/jph
+            )
+        else()
+            # Linux/macOS
+            set_target_properties(${target} PROPERTIES
+                LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/dicube/codecs/jph
+            )
+        endif()
+    endforeach()
+    
+    message(STATUS "Python extensions configured (Python ${Python_VERSION})")
+endif()
+
+# ================================================================================================
+# 构建摘要
+# ================================================================================================
+
+message(STATUS "=== Build Configuration ===")
+message(STATUS "Build type: ${CMAKE_BUILD_TYPE}")
+message(STATUS "Python extensions: ${DICUBE_BUILD_PYTHON_EXTENSIONS}")
+if(DICUBE_BUILD_PYTHON_EXTENSIONS)
+    message(STATUS "Python: ${Python_VERSION}")
+endif()
+message(STATUS "===========================")