dicube 0.2.2__cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

dicube/storage/pixel_utils.py

@@ -0,0 +1,259 @@
+from typing import Tuple
+
+import numpy as np
+
+from ..core.pixel_header import PixelDataHeader
+
+
+def derive_pixel_header_from_array(
+    image: np.ndarray, preferred_dtype=np.uint16
+) -> Tuple[np.ndarray, PixelDataHeader]:
+    """Derive pixel data header information from input numpy array.
+
+    Process different data types in different ways:
+    - For unsigned integers (uint8/16/32): use raw data directly
+    - For signed integers (int8/16/32): convert to unsigned and record offset
+    - For floating point (float16/32/64): normalize to specified unsigned integer range
+
+    Args:
+        image (np.ndarray): Input image array.
+        preferred_dtype (np.dtype): Preferred output data type. Defaults to np.uint16.
+
+    Returns:
+        Tuple[np.ndarray, PixelDataHeader]: A tuple containing:
+            - The converted image array
+            - A PixelDataHeader object with appropriate metadata
+
+    Raises:
+        ValueError: When preferred_dtype is not supported.
+        NotImplementedError: When input array dtype is not supported.
+    """
+    dtype = str(image.dtype)
+    if image.dtype in (np.uint16, np.uint8, np.uint32):
+        return image, PixelDataHeader(
+            RescaleSlope=1,
+            RescaleIntercept=0,
+            PixelDtype=dtype,
+            OriginalPixelDtype=dtype,
+        )
+    elif image.dtype == np.int16:
+        min_val = int(np.min(image))
+        image = (image - min_val).astype("uint16")
+        return image, PixelDataHeader(
+            RescaleSlope=1,
+            RescaleIntercept=min_val,
+            PixelDtype="uint16",
+            OriginalPixelDtype=dtype,
+        )
+    elif image.dtype == np.int8:
+        min_val = int(np.min(image))
+        image = (image - min_val).astype("uint8")
+        return image, PixelDataHeader(
+            RescaleSlope=1,
+            RescaleIntercept=min_val,
+            PixelDtype="uint8",
+            OriginalPixelDtype=dtype,
+        )
+    elif image.dtype == np.int32:
+        min_val = int(np.min(image))
+        image = (image - min_val).astype("uint32")
+        return image, PixelDataHeader(
+            RescaleSlope=1,
+            RescaleIntercept=min_val,
+            PixelDtype="uint32",
+            OriginalPixelDtype=dtype,
+        )
+    elif image.dtype in (np.float16, np.float32, np.float64):
+        if preferred_dtype == "uint8":
+            dtype_max = 255
+        elif preferred_dtype == "uint16":
+            dtype_max = 65535
+        else:
+            raise ValueError(f"Unsupported preferred_dtype: {preferred_dtype}")
+
+        min_val = image.min()
+        max_val = image.max()
+        if np.isclose(min_val, max_val):
+            # For constant value arrays:
+            # Set all pixels to 0, slope=0, intercept=min_val
+            # When reading back: i*slope+intercept = min_val
+            header = PixelDataHeader(
+                RescaleSlope=1.0,
+                RescaleIntercept=float(min_val),
+                PixelDtype=preferred_dtype,
+                OriginalPixelDtype=dtype,
+            )
+            raw_image = np.zeros_like(image, dtype=preferred_dtype)
+            return raw_image, header
+        else:
+            slope = float(max_val - min_val)
+            intercept = float(min_val)
+            raw_image = ((image - intercept) / slope * dtype_max).astype(
+                preferred_dtype
+            )
+            header = PixelDataHeader(
+                RescaleSlope=slope,
+                RescaleIntercept=intercept,
+                PixelDtype=preferred_dtype,
+                OriginalPixelDtype=dtype,
+                MaxVal=max_val,
+                MinVal=min_val,
+            )
+            return raw_image, header
+    else:
+        raise NotImplementedError("Unsupported dtype")
+
+
+def get_float_data(
+    raw_image: np.ndarray, pixel_header: PixelDataHeader, dtype="float32"
+) -> np.ndarray:
+    """Get image data as floating point array with slope/intercept applied.
+
+    Inspired by NIfTI's get_fdata method, this converts the raw image data
+    to floating point format and applies the rescale slope and intercept.
+
+    Args:
+        raw_image (np.ndarray): Raw image data array.
+        pixel_header (PixelDataHeader): Pixel data header containing rescale information.
+        dtype (str): Output data type, must be one of: float16, float32, float64. 
+            Defaults to "float32".
+
+    Returns:
+        np.ndarray: Floating point image data with rescale factors applied.
+
+    Raises:
+        AssertionError: If dtype is not one of the allowed float types.
+    """
+    assert dtype in (
+        "float16",
+        "float32",
+        "float64",
+    ), "only accept float16, float32, float64"
+
+    # Note: Output may be positive or negative depending on original dtype and slope/intercept
+    output_img = raw_image.astype(dtype)
+    if pixel_header.RescaleSlope is not None:
+        slope = np.array(pixel_header.RescaleSlope).astype(dtype)
+        if slope != 1.0:
+            output_img *= slope
+    if pixel_header.RescaleIntercept is not None:
+        intercept = np.array(pixel_header.RescaleIntercept).astype(dtype)
+        if intercept != 0.0:
+            output_img += intercept
+    return output_img
+
+
+def determine_optimal_nifti_dtype(
+    image: np.ndarray, pixel_header: PixelDataHeader
+) -> Tuple[np.ndarray, str]:
+    """Determine the optimal data type for saving to NIfTI and return the converted data.
+
+    This function selects the most appropriate data type for NIfTI export based on the value range
+    of the raw image and the rescale slope/intercept. It minimizes unnecessary data conversion and
+    only applies scaling or offset if needed.
+
+    Args:
+        image (np.ndarray): The raw image data (integer type guaranteed).
+        pixel_header (PixelDataHeader): Pixel header containing rescale information.
+
+    Returns:
+        Tuple[np.ndarray, str]:
+            - The image data converted to the optimal type for NIfTI export.
+            - The name of the chosen data type as a string.
+
+    Raises:
+        ValueError: If the data cannot be represented in any supported NIfTI type.
+
+    Example:
+        >>> arr = np.array([0, 100, 200], dtype=np.uint16)
+        >>> header = PixelDataHeader(RescaleSlope=1.0, RescaleIntercept=0.0, OriginalPixelDtype="uint16", PixelDtype="uint16")
+        >>> data, dtype_name = determine_optimal_nifti_dtype(arr, header)
+        >>> print(data.dtype, dtype_name)
+        uint8 uint8
+    """
+    # 获取slope和intercept
+    slope = pixel_header.RescaleSlope if pixel_header.RescaleSlope is not None else 1.0
+    intercept = pixel_header.RescaleIntercept if pixel_header.RescaleIntercept is not None else 0.0
+    
+    # 直接从原始数据计算值域
+    raw_min = float(image.min())
+    raw_max = float(image.max())
+    
+    # 计算应用slope和intercept后的值域
+    min_val = raw_min * slope + intercept
+    max_val = raw_max * slope + intercept
+    
+    # 如果斜率为负，需要交换min和max
+    if slope < 0:
+        min_val, max_val = max_val, min_val
+    
+    # 检查原始数据类型
+    original_dtype = pixel_header.OriginalPixelDtype
+    is_signed_original = original_dtype in ("int8", "int16", "int32", "int64")
+    
+    # 检查slope和intercept是否为整数值
+    has_integer_transform = (
+        np.isclose(slope % 1, 0) and 
+        np.isclose(intercept % 1, 0)
+    )
+    
+    # 准备最终数据 - 仅在确定dtype后执行一次转换
+    result_dtype = None
+    result_dtype_name = None
+    
+    # 如果slope和intercept都是整数，则可以使用整数类型
+    if has_integer_transform:
+        # 尊重原始数据类型的符号属性
+        if is_signed_original or min_val < 0:
+            # 有符号整数
+            if min_val >= -128 and max_val <= 127:
+                result_dtype = np.int8
+                result_dtype_name = "int8"
+            elif min_val >= -32768 and max_val <= 32767:
+                result_dtype = np.int16
+                result_dtype_name = "int16"
+            elif min_val >= -2147483648 and max_val <= 2147483647:
+                result_dtype = np.int32
+                result_dtype_name = "int32"
+            elif max_val <= 2147483647:  # 值域在int32范围内，但原始类型是int32
+                result_dtype = np.int32
+                result_dtype_name = "int32"
+        else:
+            # 无符号整数
+            if max_val <= 255:
+                result_dtype = np.uint8
+                result_dtype_name = "uint8"
+            elif max_val <= 65535:
+                result_dtype = np.uint16
+                result_dtype_name = "uint16"
+            elif max_val <= 4294967295:
+                result_dtype = np.uint32
+                result_dtype_name = "uint32"
+    
+    # 如果没有找到合适的整数类型，使用浮点类型
+    if result_dtype is None:
+        if np.issubdtype(image.dtype, np.float64) or min_val < -3.4e38 or max_val > 3.4e38:
+            result_dtype = np.float64
+            result_dtype_name = "float64"
+        else:
+            result_dtype = np.float32
+            result_dtype_name = "float32"
+            
+    if has_integer_transform:
+        intercept = int(intercept)
+    else:
+        intercept = np.array(intercept,dtype=result_dtype)
+
+    if slope == 1.0:
+        # 只要加法
+        return image.astype(result_dtype) + intercept, result_dtype_name
+    else:
+        # 需要乘法，生成最终数据
+        if result_dtype in (np.float32, np.float64):
+            # 浮点类型，直接使用浮点运算
+            result = image.astype(result_dtype) * slope + intercept
+        else:
+            # 整数类型，先做浮点运算再转换
+            result = (image.astype(np.float32) * slope + intercept).astype(result_dtype)
+        
+        return result, result_dtype_name 

dicube/utils/__init__.py

@@ -0,0 +1,6 @@
+"""Utility module for DiCube.
+
+This module provides various utility functions and helpers for the DiCube library.
+"""
+
+# No public exports currently 

dicube/validation.py

@@ -0,0 +1,380 @@
+"""Validation utilities for DiCube library.
+
+This module provides reusable validation functions that automatically raise
+appropriate DicomCubeError exceptions with consistent error messages and context.
+These utilities help minimize code duplication and provide clean error handling
+throughout the DiCube library.
+"""
+
+import os
+from typing import Any, Type, Union, Optional
+import numpy as np
+
+from .exceptions import (
+    DicomCubeError,
+    InvalidCubeFileError,
+    DataConsistencyError,
+    MetaDataError
+)
+
+
+def validate_not_none(
+    value: Any, 
+    name: str, 
+    context: str = "",
+    exception_class: Type[DicomCubeError] = DicomCubeError
+) -> Any:
+    """Validate that a value is not None.
+    
+    Args:
+        value: The value to validate.
+        name (str): Name of the parameter being validated.
+        context (str): Context about the operation being performed.
+        exception_class (Type[DicomCubeError]): Exception class to raise on failure.
+        
+    Returns:
+        Any: The validated value if not None.
+        
+    Raises:
+        DicomCubeError: If the value is None.
+    """
+    if value is None:
+        raise exception_class(
+            f"Parameter '{name}' cannot be None",
+            context=context,
+            details={"parameter": name, "value": value}
+        )
+    return value
+
+
+def validate_file_exists(
+    file_path: str, 
+    context: str = "",
+    exception_class: Type[DicomCubeError] = InvalidCubeFileError
+) -> str:
+    """Validate that a file exists.
+    
+    Args:
+        file_path (str): Path to the file to validate.
+        context (str): Context about the operation being performed.
+        exception_class (Type[DicomCubeError]): Exception class to raise on failure.
+        
+    Returns:
+        str: The validated file path.
+        
+    Raises:
+        InvalidCubeFileError: If the file does not exist.
+    """
+    validate_not_none(file_path, "file_path", context, exception_class)
+    
+    if not os.path.exists(file_path):
+        raise exception_class(
+            f"File not found",
+            context=context,
+            details={"file_path": file_path},
+            suggestion="Verify the file path is correct and the file exists"
+        )
+    
+    if not os.path.isfile(file_path):
+        raise exception_class(
+            f"Path exists but is not a file",
+            context=context,
+            details={"file_path": file_path},
+            suggestion="Ensure the path points to a file, not a directory"
+        )
+    
+    return file_path
+
+
+def validate_folder_exists(
+    folder_path: str, 
+    context: str = "",
+    exception_class: Type[DicomCubeError] = InvalidCubeFileError
+) -> str:
+    """Validate that a folder exists.
+    
+    Args:
+        folder_path (str): Path to the folder to validate.
+        context (str): Context about the operation being performed.
+        exception_class (Type[DicomCubeError]): Exception class to raise on failure.
+        
+    Returns:
+        str: The validated folder path.
+        
+    Raises:
+        InvalidCubeFileError: If the folder does not exist or is not a directory.
+    """
+    validate_not_none(folder_path, "folder_path", context, exception_class)
+    
+    if not os.path.exists(folder_path):
+        raise exception_class(
+            f"Folder not found",
+            context=context,
+            details={"folder_path": folder_path},
+            suggestion="Verify the folder path is correct and the folder exists"
+        )
+    
+    if not os.path.isdir(folder_path):
+        raise exception_class(
+            f"Path exists but is not a directory",
+            context=context,
+            details={"folder_path": folder_path},
+            suggestion="Ensure the path points to a directory, not a file"
+        )
+    
+    return folder_path
+
+
+def validate_array_shape(
+    array: np.ndarray, 
+    expected_dims: Optional[int] = None,
+    min_dims: Optional[int] = None,
+    max_dims: Optional[int] = None,
+    name: str = "array",
+    context: str = "",
+    exception_class: Type[DicomCubeError] = DataConsistencyError
+) -> np.ndarray:
+    """Validate numpy array shape and dimensions.
+    
+    Args:
+        array (np.ndarray): The array to validate.
+        expected_dims (int, optional): Expected number of dimensions.
+        min_dims (int, optional): Minimum number of dimensions.
+        max_dims (int, optional): Maximum number of dimensions.
+        name (str): Name of the array parameter.
+        context (str): Context about the operation being performed.
+        exception_class (Type[DicomCubeError]): Exception class to raise on failure.
+        
+    Returns:
+        np.ndarray: The validated array.
+        
+    Raises:
+        DataConsistencyError: If array shape validation fails.
+    """
+    validate_not_none(array, name, context, exception_class)
+    
+    if not isinstance(array, np.ndarray):
+        raise exception_class(
+            f"Parameter '{name}' must be a numpy array",
+            context=context,
+            details={"parameter": name, "type": type(array).__name__},
+            suggestion="Convert the data to a numpy array before passing"
+        )
+    
+    actual_dims = array.ndim
+    
+    if expected_dims is not None and actual_dims != expected_dims:
+        raise exception_class(
+            f"Array '{name}' has incorrect dimensions",
+            context=context,
+            details={
+                "parameter": name,
+                "expected_dims": expected_dims,
+                "actual_dims": actual_dims,
+                "shape": array.shape
+            },
+            suggestion=f"Ensure the array has exactly {expected_dims} dimensions"
+        )
+    
+    if min_dims is not None and actual_dims < min_dims:
+        raise exception_class(
+            f"Array '{name}' has too few dimensions",
+            context=context,
+            details={
+                "parameter": name,
+                "min_dims": min_dims,
+                "actual_dims": actual_dims,
+                "shape": array.shape
+            },
+            suggestion=f"Ensure the array has at least {min_dims} dimensions"
+        )
+    
+    if max_dims is not None and actual_dims > max_dims:
+        raise exception_class(
+            f"Array '{name}' has too many dimensions",
+            context=context,
+            details={
+                "parameter": name,
+                "max_dims": max_dims,
+                "actual_dims": actual_dims,
+                "shape": array.shape
+            },
+            suggestion=f"Ensure the array has at most {max_dims} dimensions"
+        )
+    
+    return array
+
+
+def validate_parameter_type(
+    value: Any, 
+    expected_type: Union[Type, tuple], 
+    name: str,
+    context: str = "",
+    exception_class: Type[DicomCubeError] = DataConsistencyError
+) -> Any:
+    """Validate parameter type.
+    
+    Args:
+        value: The value to validate.
+        expected_type (Type or tuple): Expected type or tuple of types.
+        name (str): Name of the parameter being validated.
+        context (str): Context about the operation being performed.
+        exception_class (Type[DicomCubeError]): Exception class to raise on failure.
+        
+    Returns:
+        Any: The validated value.
+        
+    Raises:
+        DataConsistencyError: If the value is not of the expected type.
+    """
+    validate_not_none(value, name, context, exception_class)
+    
+    if not isinstance(value, expected_type):
+        if isinstance(expected_type, tuple):
+            type_names = [t.__name__ for t in expected_type]
+            expected_str = " or ".join(type_names)
+        else:
+            expected_str = expected_type.__name__
+        
+        raise exception_class(
+            f"Parameter '{name}' has incorrect type",
+            context=context,
+            details={
+                "parameter": name,
+                "expected_type": expected_str,
+                "actual_type": type(value).__name__,
+                "value": repr(value)
+            },
+            suggestion=f"Ensure '{name}' is of type {expected_str}"
+        )
+    
+    return value
+
+
+def validate_shape_consistency(
+    array1: np.ndarray,
+    array2: np.ndarray,
+    name1: str = "array1",
+    name2: str = "array2", 
+    context: str = "",
+    exception_class: Type[DicomCubeError] = DataConsistencyError
+) -> tuple:
+    """Validate that two arrays have consistent shapes.
+    
+    Args:
+        array1 (np.ndarray): First array to compare.
+        array2 (np.ndarray): Second array to compare.
+        name1 (str): Name of the first array parameter.
+        name2 (str): Name of the second array parameter.
+        context (str): Context about the operation being performed.
+        exception_class (Type[DicomCubeError]): Exception class to raise on failure.
+        
+    Returns:
+        tuple: Both validated arrays.
+        
+    Raises:
+        DataConsistencyError: If array shapes are inconsistent.
+    """
+    validate_array_shape(array1, name=name1, context=context, exception_class=exception_class)
+    validate_array_shape(array2, name=name2, context=context, exception_class=exception_class)
+    
+    if array1.shape != array2.shape:
+        raise exception_class(
+            f"Arrays '{name1}' and '{name2}' have inconsistent shapes",
+            context=context,
+            details={
+                name1 + "_shape": array1.shape,
+                name2 + "_shape": array2.shape
+            },
+            suggestion="Ensure both arrays have the same dimensions and shape"
+        )
+    
+    return array1, array2
+
+
+def validate_string_not_empty(
+    value: str,
+    name: str,
+    context: str = "",
+    exception_class: Type[DicomCubeError] = DicomCubeError
+) -> str:
+    """Validate that a string is not None or empty.
+    
+    Args:
+        value (str): The string value to validate.
+        name (str): Name of the parameter being validated.
+        context (str): Context about the operation being performed.
+        exception_class (Type[DicomCubeError]): Exception class to raise on failure.
+        
+    Returns:
+        str: The validated string.
+        
+    Raises:
+        DicomCubeError: If the string is None or empty.
+    """
+    validate_not_none(value, name, context, exception_class)
+    validate_parameter_type(value, str, name, context, exception_class)
+    
+    if not value.strip():
+        raise exception_class(
+            f"Parameter '{name}' cannot be empty",
+            context=context,
+            details={"parameter": name, "value": repr(value)},
+            suggestion=f"Provide a non-empty value for '{name}'"
+        )
+    
+    return value
+
+
+def validate_numeric_range(
+    value: Union[int, float],
+    name: str,
+    min_value: Optional[Union[int, float]] = None,
+    max_value: Optional[Union[int, float]] = None,
+    context: str = "",
+    exception_class: Type[DicomCubeError] = DataConsistencyError
+) -> Union[int, float]:
+    """Validate that a numeric value is within a specified range.
+    
+    Args:
+        value (int or float): The numeric value to validate.
+        name (str): Name of the parameter being validated.
+        min_value (int or float, optional): Minimum allowed value.
+        max_value (int or float, optional): Maximum allowed value.
+        context (str): Context about the operation being performed.
+        exception_class (Type[DicomCubeError]): Exception class to raise on failure.
+        
+    Returns:
+        int or float: The validated value.
+        
+    Raises:
+        DataConsistencyError: If the value is outside the specified range.
+    """
+    validate_not_none(value, name, context, exception_class)
+    validate_parameter_type(value, (int, float), name, context, exception_class)
+    
+    if min_value is not None and value < min_value:
+        raise exception_class(
+            f"Parameter '{name}' is below minimum value",
+            context=context,
+            details={
+                "parameter": name,
+                "value": value,
+                "min_value": min_value
+            },
+            suggestion=f"Ensure '{name}' is at least {min_value}"
+        )
+    
+    if max_value is not None and value > max_value:
+        raise exception_class(
+            f"Parameter '{name}' exceeds maximum value",
+            context=context,
+            details={
+                "parameter": name,
+                "value": value,
+                "max_value": max_value
+            },
+            suggestion=f"Ensure '{name}' is at most {max_value}"
+        )
+    
+    return value