dicube 0.1.4__cp312-cp312-macosx_11_0_arm64.whl → 0.2.2__cp312-cp312-macosx_11_0_arm64.whl

dicube/__init__.py

@@ -39,27 +39,47 @@ except PackageNotFoundError:
     # editable install / source tree
     __version__ = "0.1.0+unknown"
 
+# Default to the number of CPU cores, but cap at 8 threads to avoid excessive resource usage
+# Fall back to 4 if cpu_count() returns None (which can happen in some environments)
+_num_threads = 4
+
+def get_num_threads() -> int:
+    """Get the global number of threads for parallel processing.
+    
+    Returns:
+        int: Current number of threads setting.
+    """
+    global _num_threads
+    return _num_threads
+
+def set_num_threads(num_threads: int) -> None:
+    """Set the global number of threads for parallel processing.
+    
+    Args:
+        num_threads (int): Number of threads for parallel processing tasks.
+    """
+    global _num_threads
+    if num_threads < 1:
+        raise ValueError("Number of threads must be at least 1")
+    _num_threads = num_threads
+
 # Top-level convenience methods
-def load(file_path: str, num_threads: int = 4, **kwargs) -> DicomCubeImage:
+def load(file_path: str) -> DicomCubeImage:
     """Load a DicomCubeImage from a file.
     
     Args:
         file_path (str): Path to the input file.
-        num_threads (int): Number of parallel decoding threads. Defaults to 4.
-        **kwargs: Additional parameters passed to the underlying reader.
     
     Returns:
         DicomCubeImage: The loaded image object.
     """
-    return DicomCubeImageIO.load(file_path, num_threads, **kwargs)
+    return DicomCubeImageIO.load(file_path)
 
 
 def save(
     image: DicomCubeImage,
     file_path: str,
     file_type: str = "s",
-    num_threads: int = 4,
-    **kwargs
 ) -> None:
     """Save a DicomCubeImage to a file.
     
@@ -68,16 +88,13 @@ def save(
         file_path (str): Output file path.
         file_type (str): File type, "s" (speed priority), "a" (compression priority), 
                         or "l" (lossy compression). Defaults to "s".
-        num_threads (int): Number of parallel encoding threads. Defaults to 4.
-        **kwargs: Additional parameters passed to the underlying writer.
     """
-    return DicomCubeImageIO.save(image, file_path, file_type, num_threads, **kwargs)
+    return DicomCubeImageIO.save(image, file_path, file_type)
 
 
 def load_from_dicom_folder(
     folder_path: str,
     sort_method: SortMethod = SortMethod.INSTANCE_NUMBER_ASC,
-    **kwargs
 ) -> DicomCubeImage:
     """Load a DicomCubeImage from a DICOM folder.
     
@@ -90,10 +107,10 @@ def load_from_dicom_folder(
     Returns:
         DicomCubeImage: The loaded image object.
     """
-    return DicomCubeImageIO.load_from_dicom_folder(folder_path, sort_method, **kwargs)
+    return DicomCubeImageIO.load_from_dicom_folder(folder_path, sort_method)
 
 
-def load_from_nifti(file_path: str, **kwargs) -> DicomCubeImage:
+def load_from_nifti(file_path: str) -> DicomCubeImage:
     """Load a DicomCubeImage from a NIfTI file.
     
     Args:
@@ -103,24 +120,38 @@ def load_from_nifti(file_path: str, **kwargs) -> DicomCubeImage:
     Returns:
         DicomCubeImage: The loaded image object.
     """
-    return DicomCubeImageIO.load_from_nifti(file_path, **kwargs)
+    return DicomCubeImageIO.load_from_nifti(file_path)
 
 
 def save_to_dicom_folder(
     image: DicomCubeImage,
     folder_path: str,
-    **kwargs
 ) -> None:
     """Save a DicomCubeImage as a DICOM folder.
     
     Args:
         image (DicomCubeImage): The image object to save.
         folder_path (str): Output directory path.
-        **kwargs: Additional parameters.
     """
     return DicomCubeImageIO.save_to_dicom_folder(image, folder_path)
 
 
+def save_to_nifti(
+    image: DicomCubeImage,
+    file_path: str,
+) -> None:
+    """Save a DicomCubeImage as a NIfTI file.
+    
+    Args:
+        image (DicomCubeImage): The image object to save.
+        file_path (str): Output file path.
+    
+    Raises:
+        ImportError: When nibabel is not installed.
+    """
+    return DicomCubeImageIO.save_to_nifti(image, file_path)
+
+
 __all__ = [
     "DicomCubeImage",
     "DicomMeta",
@@ -135,6 +166,9 @@ __all__ = [
     "load_from_dicom_folder",
     "load_from_nifti",
     "save_to_dicom_folder",
+    "save_to_nifti",
+    "set_num_threads",
+    "get_num_threads",
     # IO class (for direct use if needed)
     "DicomCubeImageIO",
 ] 

dicube/core/image.py

@@ -35,7 +35,7 @@ class DicomCubeImage:
         pixel_header (PixelDataHeader): Pixel data header containing metadata about the image pixels.
         dicom_meta (DicomMeta, optional): DICOM metadata associated with the image.
         space (Space, optional): Spatial information describing the image dimensions and orientation.
-        dicom_status (str, optional): DICOM status string. Defaults to DicomStatus.CONSISTENT.value.
+        dicom_status (DicomStatus): DICOM status enumeration. Defaults to DicomStatus.CONSISTENT.
     """
 
     def __init__(
@@ -44,7 +44,7 @@ class DicomCubeImage:
         pixel_header: PixelDataHeader,
         dicom_meta: Optional[DicomMeta] = None,
         space: Optional[Space] = None,
-        dicom_status: str = DicomStatus.CONSISTENT.value,
+        dicom_status: DicomStatus = DicomStatus.CONSISTENT,
     ):
         """Initialize a DicomCubeImage instance.
 
@@ -226,13 +226,13 @@ class DicomCubeImage:
         meta.set_shared_item(CommonTags.PixelRepresentation, 0)
 
         # Rescale Information from pixel_header
-        if self.pixel_header.RESCALE_SLOPE is not None:
+        if self.pixel_header.RescaleSlope is not None:
             meta.set_shared_item(
-                CommonTags.RescaleSlope, float(self.pixel_header.RESCALE_SLOPE)
+                CommonTags.RescaleSlope, float(self.pixel_header.RescaleSlope)
             )
-        if self.pixel_header.RESCALE_INTERCEPT is not None:
+        if self.pixel_header.RescaleIntercept is not None:
             meta.set_shared_item(
-                CommonTags.RescaleIntercept, float(self.pixel_header.RESCALE_INTERCEPT)
+                CommonTags.RescaleIntercept, float(self.pixel_header.RescaleIntercept)
             )
 
     def init_meta(

dicube/core/io.py

@@ -16,7 +16,7 @@ from ..dicom import (
 )
 from ..dicom.dicom_io import save_to_dicom_folder
 from ..storage.dcb_file import DcbSFile, DcbFile, DcbAFile, DcbLFile
-from ..storage.pixel_utils import derive_pixel_header_from_array
+from ..storage.pixel_utils import derive_pixel_header_from_array, determine_optimal_nifti_dtype
 from .pixel_header import PixelDataHeader
 
 from ..validation import (
@@ -52,7 +52,6 @@ class DicomCubeImageIO:
         image: "DicomCubeImage",
         file_path: str,
         file_type: str = "s",
-        num_threads: int = 4,
     ) -> None:
         """Save DicomCubeImage to a file.
         
@@ -61,7 +60,6 @@ class DicomCubeImageIO:
             file_path (str): Output file path.
             file_type (str): File type, "s" (speed priority), "a" (compression priority), 
                              or "l" (lossy compression). Defaults to "s".
-            num_threads (int): Number of parallel encoding threads. Defaults to 4.
             
         Raises:
             InvalidCubeFileError: If the file_type is not supported.
@@ -69,7 +67,6 @@ class DicomCubeImageIO:
         # Validate required parameters
         validate_not_none(image, "image", "save operation", DataConsistencyError)
         validate_string_not_empty(file_path, "file_path", "save operation", InvalidCubeFileError)
-        validate_numeric_range(num_threads, "num_threads", min_value=1, context="save operation")
         
         # Validate file_type parameter
         if file_type not in ("s", "a", "l"):
@@ -82,6 +79,7 @@ class DicomCubeImageIO:
         
         try:
             # Choose appropriate writer based on file type
+            # The writer will automatically ensure correct file extension
             if file_type == "s":
                 writer = DcbSFile(file_path, mode="w")
             elif file_type == "a":
@@ -89,14 +87,16 @@ class DicomCubeImageIO:
             elif file_type == "l":
                 writer = DcbLFile(file_path, mode="w")
             
+            # Update file_path to the corrected path from writer
+            file_path = writer.filename
+            
             # Write to file
             writer.write(
                 images=image.raw_image,
                 pixel_header=image.pixel_header,
                 dicom_meta=image.dicom_meta,
                 space=image.space,
-                num_threads=num_threads,
-                dicom_status=image.dicom_status
+                dicom_status=image.dicom_status,
             )
         except Exception as e:
             if isinstance(e, (InvalidCubeFileError, CodecError)):
@@ -108,13 +108,11 @@ class DicomCubeImageIO:
             ) from e
     
     @staticmethod
-    def load(file_path: str, num_threads: int = 4, **kwargs) -> 'DicomCubeImage':
+    def load(file_path: str) -> 'DicomCubeImage':
         """Load DicomCubeImage from a file.
         
         Args:
             file_path (str): Input file path.
-            num_threads (int): Number of parallel decoding threads. Defaults to 4.
-            **kwargs: Additional parameters passed to the underlying reader.
             
         Returns:
             DicomCubeImage: The loaded object from the file.
@@ -152,7 +150,7 @@ class DicomCubeImageIO:
             pixel_header = reader.read_pixel_header()
             dicom_status = reader.read_dicom_status()
             
-            images = reader.read_images(num_threads=num_threads)
+            images = reader.read_images()
             if isinstance(images, list):
                 # Convert list to ndarray if needed
                 images = np.stack(images)
@@ -180,7 +178,6 @@ class DicomCubeImageIO:
     def load_from_dicom_folder(
         folder_path: str,
         sort_method: SortMethod = SortMethod.INSTANCE_NUMBER_ASC,
-        **kwargs
     ) -> 'DicomCubeImage':
         """Load DicomCubeImage from a DICOM folder.
         
@@ -188,7 +185,6 @@ class DicomCubeImageIO:
             folder_path (str): Path to the DICOM folder.
             sort_method (SortMethod): Method to sort DICOM files. 
                                       Defaults to SortMethod.INSTANCE_NUMBER_ASC.
-            **kwargs: Additional parameters.
             
         Returns:
             DicomCubeImage: The object created from the DICOM folder.
@@ -243,15 +239,21 @@ class DicomCubeImageIO:
             intercept = meta.get_shared_value(CommonTags.RescaleIntercept)
             wind_center = meta.get_shared_value(CommonTags.WindowCenter)
             wind_width = meta.get_shared_value(CommonTags.WindowWidth)
+            try:
+                wind_center = float(wind_center)
+                wind_width = float(wind_width)
+            except:
+                wind_center = None
+                wind_width = None
             
             # Create pixel_header
             pixel_header = PixelDataHeader(
-                RESCALE_SLOPE=float(slope) if slope is not None else 1.0,
-                RESCALE_INTERCEPT=float(intercept) if intercept is not None else 0.0,
-                ORIGINAL_PIXEL_DTYPE=str(images[0].dtype),
-                PIXEL_DTYPE=str(images[0].dtype),
-                WINDOW_CENTER=float(wind_center) if wind_center is not None else None,
-                WINDOW_WIDTH=float(wind_width) if wind_width is not None else None,
+                RescaleSlope=float(slope) if slope is not None else 1.0,
+                RescaleIntercept=float(intercept) if intercept is not None else 0.0,
+                OriginalPixelDtype=str(images[0].dtype),
+                PixelDtype=str(images[0].dtype),
+                WindowCenter=wind_center,
+                WindowWidth=wind_width,
             )
             
             # Validate PixelDataHeader initialization success
@@ -282,12 +284,11 @@ class DicomCubeImageIO:
             ) from e
     
     @staticmethod
-    def load_from_nifti(file_path: str, **kwargs) -> 'DicomCubeImage':
+    def load_from_nifti(file_path: str) -> 'DicomCubeImage':
         """Load DicomCubeImage from a NIfTI file.
         
         Args:
             file_path (str): Path to the NIfTI file.
-            **kwargs: Additional parameters.
             
         Returns:
             DicomCubeImage: The object created from the NIfTI file.
@@ -351,4 +352,57 @@ class DicomCubeImageIO:
             dicom_meta=image.dicom_meta,
             pixel_header=image.pixel_header,
             output_dir=folder_path,
-        ) 
+        ) 
+        
+    @staticmethod
+    def save_to_nifti(
+        image: 'DicomCubeImage',
+        file_path: str,
+    ) -> None:
+        """Save DicomCubeImage as a NIfTI file.
+        
+        Args:
+            image (DicomCubeImage): The DicomCubeImage object to save.
+            file_path (str): Output file path.
+            
+        Raises:
+            ImportError: When nibabel is not installed.
+            InvalidCubeFileError: When saving fails.
+        """
+        # Validate required parameters
+        validate_not_none(image, "image", "save_to_nifti operation", DataConsistencyError)
+        validate_string_not_empty(file_path, "file_path", "save_to_nifti operation", InvalidCubeFileError)
+        
+        try:
+            import nibabel as nib
+        except ImportError:
+            raise ImportError("nibabel is required to write NIfTI files")
+        
+        try:
+            if image.space is None:
+                raise InvalidCubeFileError(
+                    "Cannot save to NIfTI without space information",
+                    context="save_to_nifti operation",
+                    suggestion="Ensure the DicomCubeImage has valid space information"
+                )
+            
+            # Get affine matrix from space
+            affine = image.space.to_nifti_affine()
+            
+            # 根据像素数据和metadata确定最佳的数据类型
+            optimal_data, dtype_name = determine_optimal_nifti_dtype(image.raw_image, image.pixel_header)
+            
+            # Create NIfTI image with optimized data type
+            nii = nib.Nifti1Image(optimal_data, affine)
+            
+            # Save to file
+            nib.save(nii, file_path)
+        except Exception as e:
+            if isinstance(e, (ImportError, InvalidCubeFileError)):
+                raise
+            raise InvalidCubeFileError(
+                f"Failed to save NIfTI file: {str(e)}",
+                context="save_to_nifti operation",
+                details={"file_path": file_path},
+                suggestion="Check file permissions and ensure space information is valid"
+            ) from e 

dicube/core/pixel_header.py

@@ -12,42 +12,42 @@ class PixelDataHeader:
     - Original pixel data type
     - Window settings (center/width)
     - Value range (min/max)
-    - Additional metadata in EXTRAS
+    - Additional metadata in extras
 
     Attributes:
-        RESCALE_SLOPE (float): Slope for linear transformation.
-        RESCALE_INTERCEPT (float): Intercept for linear transformation.
-        PIXEL_DTYPE (str): Pixel data type string (after convert to dcb file).
-        ORIGINAL_PIXEL_DTYPE (str): Original pixel data type string (before convert to dcb file).
-        WINDOW_CENTER (float, optional): Window center value for display.
-        WINDOW_WIDTH (float, optional): Window width value for display.
-        MAX_VAL (float, optional): Maximum pixel value.
-        MIN_VAL (float, optional): Minimum pixel value.
-        EXTRAS (Dict[str, any]): Dictionary for additional metadata.
+        RescaleSlope (float): Slope for linear transformation.
+        RescaleIntercept (float): Intercept for linear transformation.
+        PixelDtype (str): Pixel data type string (after convert to dcb file).
+        OriginalPixelDtype (str): Original pixel data type string (before convert to dcb file).
+        WindowCenter (float, optional): Window center value for display.
+        WindowWidth (float, optional): Window width value for display.
+        MaxVal (float, optional): Maximum pixel value.
+        MinVal (float, optional): Minimum pixel value.
+        Extras (Dict[str, any]): Dictionary for additional metadata.
     """
 
-    RESCALE_SLOPE: float = 1.0
-    RESCALE_INTERCEPT: float = 0.0
-    ORIGINAL_PIXEL_DTYPE: str = "uint16"
-    PIXEL_DTYPE: str = "uint16"
-    WINDOW_CENTER: Optional[float] = None
-    WINDOW_WIDTH: Optional[float] = None
-    MAX_VAL: Optional[float] = None
-    MIN_VAL: Optional[float] = None
-    EXTRAS: Dict[str, any] = field(default_factory=dict)
+    RescaleSlope: float = 1.0
+    RescaleIntercept: float = 0.0
+    OriginalPixelDtype: str = "uint16"
+    PixelDtype: str = "uint16"
+    WindowCenter: Optional[float] = None
+    WindowWidth: Optional[float] = None
+    MaxVal: Optional[float] = None
+    MinVal: Optional[float] = None
+    Extras: Dict[str, any] = field(default_factory=dict)
 
     def to_dict(self) -> dict:
         """Convert the header to a dictionary for serialization.
 
-        Merges EXTRAS field into the main dictionary and removes
-        the redundant EXTRAS key.
+        Merges extras field into the main dictionary and removes
+        the redundant extras key.
 
         Returns:
             dict: Dictionary representation of the header.
         """
         data = asdict(self)
-        data.update(self.EXTRAS)  # Merge EXTRAS into dictionary
-        data.pop("EXTRAS", None)  # Remove redundant EXTRAS field
+        data.update(self.Extras)  # Merge Extras into dictionary
+        data.pop("Extras", None)  # Remove redundant Extras field
         return data
 
     @classmethod
@@ -60,39 +60,42 @@ class PixelDataHeader:
         Returns:
             PixelDataHeader: A new instance with values from the dictionary.
         """
-        rescale_slope = d.get("RESCALE_SLOPE", 1.0)
-        rescale_intercept = d.get("RESCALE_INTERCEPT", 0.0)
-        original_pixel_dtype = d.get("ORIGINAL_PIXEL_DTYPE", "uint16")
-        window_center = d.get("WINDOW_CENTER")  # Defaults to None
-        window_width = d.get("WINDOW_WIDTH")  # Defaults to None
-        max_val = d.get("MAX_VAL")  # Defaults to None
-        min_val = d.get("MIN_VAL")  # Defaults to None
-
-        # All other keys go into EXTRAS
+        rescale_slope = d.get("RescaleSlope", 1.0)
+        rescale_intercept = d.get("RescaleIntercept", 0.0)
+        original_pixel_dtype = d.get("OriginalPixelDtype", "uint16")
+        pixel_dtype = d.get("PixelDtype", "uint16")
+        window_center = d.get("WindowCenter")  # Defaults to None
+        window_width = d.get("WindowWidth")  # Defaults to None
+        max_val = d.get("MaxVal")  # Defaults to None
+        min_val = d.get("MinVal")  # Defaults to None
+
+        # All other keys go into Extras
         extras = {
             k: v
             for k, v in d.items()
             if k
             not in {
-                "RESCALE_SLOPE",
-                "RESCALE_INTERCEPT",
-                "ORIGINAL_PIXEL_DTYPE",
-                "WINDOW_CENTER",
-                "WINDOW_WIDTH",
-                "MAX_VAL",
-                "MIN_VAL",
+                "RescaleSlope",
+                "RescaleIntercept",
+                "OriginalPixelDtype",
+                "PixelDtype",
+                "WindowCenter",
+                "WindowWidth",
+                "MaxVal",
+                "MinVal",
             }
         }
 
         return cls(
-            RESCALE_SLOPE=rescale_slope,
-            RESCALE_INTERCEPT=rescale_intercept,
-            ORIGINAL_PIXEL_DTYPE=original_pixel_dtype,
-            WINDOW_CENTER=window_center,
-            WINDOW_WIDTH=window_width,
-            MAX_VAL=max_val,
-            MIN_VAL=min_val,
-            EXTRAS=extras,
+            RescaleSlope=rescale_slope,
+            RescaleIntercept=rescale_intercept,
+            OriginalPixelDtype=original_pixel_dtype,
+            PixelDtype=pixel_dtype,
+            WindowCenter=window_center,
+            WindowWidth=window_width,
+            MaxVal=max_val,
+            MinVal=min_val,
+            Extras=extras,
         )
 
     def to_json(self) -> str: