dicube 0.1.4__cp311-cp311-macosx_11_0_arm64.whl

dicube/core/image.py

@@ -0,0 +1,349 @@
+# core/image.py
+import warnings
+from typing import Optional
+
+import numpy as np
+
+from ..dicom import (
+    CommonTags,
+    DicomMeta,
+    DicomStatus,
+)
+from .pixel_header import PixelDataHeader
+from ..storage.pixel_utils import get_float_data
+from spacetransformer import Space
+from ..validation import (
+    validate_not_none,
+    validate_parameter_type,
+    validate_array_shape,
+    validate_string_not_empty
+)
+from ..exceptions import (
+    DataConsistencyError,
+    MetaDataError
+)
+
+
+class DicomCubeImage:
+    """A class representing a DICOM image with associated metadata and space information.
+
+    This class handles DICOM image data along with its pixel header, metadata, and space information.
+    It provides methods for file I/O and data manipulation.
+    
+    Attributes:
+        raw_image (np.ndarray): The raw image data array.
+        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.
+    """
+
+    def __init__(
+        self,
+        raw_image: np.ndarray,
+        pixel_header: PixelDataHeader,
+        dicom_meta: Optional[DicomMeta] = None,
+        space: Optional[Space] = None,
+        dicom_status: str = DicomStatus.CONSISTENT.value,
+    ):
+        """Initialize a DicomCubeImage instance.
+
+        Args:
+            raw_image (np.ndarray): Raw image data array.
+            pixel_header (PixelDataHeader): Pixel data header information.
+            dicom_meta (DicomMeta, optional): DICOM metadata. Defaults to None.
+            space (Space, optional): Spatial information. Defaults to None.
+        """
+        # Validate required parameters using validation utilities
+        validate_not_none(raw_image, "raw_image", "DicomCubeImage constructor", DataConsistencyError)
+        validate_not_none(pixel_header, "pixel_header", "DicomCubeImage constructor", DataConsistencyError)
+        validate_array_shape(raw_image, min_dims=2, name="raw_image", context="DicomCubeImage constructor")
+        validate_parameter_type(pixel_header, PixelDataHeader, "pixel_header", "DicomCubeImage constructor", DataConsistencyError)
+        
+        # Validate optional parameters if provided
+        if dicom_meta is not None:
+            validate_parameter_type(dicom_meta, DicomMeta, "dicom_meta", "DicomCubeImage constructor", MetaDataError)
+        if space is not None:
+            validate_parameter_type(space, Space, "space", "DicomCubeImage constructor", DataConsistencyError)
+        
+        self.raw_image = raw_image
+        self.pixel_header = pixel_header
+        self.dicom_meta = dicom_meta
+        self.space = space
+        self.dicom_status = dicom_status 
+        self._validate_shape()
+
+
+    def _generate_uids(self):
+        """Generate necessary UIDs for DICOM metadata.
+        
+        Returns:
+            dict: Dictionary containing generated UIDs.
+        """
+        from pydicom.uid import generate_uid
+        
+        return {
+            'study_uid': generate_uid(),
+            'series_uid': generate_uid(),
+            'sop_uid': generate_uid(),
+            'frame_uid': generate_uid()
+        }
+    
+    def _set_patient_info(self, meta: DicomMeta, patient_name: str, patient_id: str):
+        """Set patient information in DICOM metadata.
+        
+        Args:
+            meta (DicomMeta): The metadata object to update.
+            patient_name (str): Patient name.
+            patient_id (str): Patient ID.
+        """
+        meta.set_shared_item(CommonTags.PatientName, {'Alphabetic': patient_name})
+        meta.set_shared_item(CommonTags.PatientID, patient_id)
+        meta.set_shared_item(CommonTags.PatientBirthDate, "19700101")
+        meta.set_shared_item(CommonTags.PatientSex, "O")
+    
+    def _set_study_info(self, meta: DicomMeta, uids: dict, modality: str):
+        """Set study information in DICOM metadata.
+        
+        Args:
+            meta (DicomMeta): The metadata object to update.
+            uids (dict): Dictionary containing generated UIDs.
+            modality (str): Image modality.
+        """
+        import datetime
+        
+        now = datetime.datetime.now()
+        date_str = now.strftime("%Y%m%d")
+        time_str = now.strftime("%H%M%S")
+        
+        meta.set_shared_item(CommonTags.StudyInstanceUID, uids['study_uid'])
+        meta.set_shared_item(CommonTags.StudyDate, date_str)
+        meta.set_shared_item(CommonTags.StudyTime, time_str)
+        meta.set_shared_item(CommonTags.StudyID, "1")
+        meta.set_shared_item(CommonTags.StudyDescription, f"Default {modality} Study")
+    
+    def _set_series_info(self, meta: DicomMeta, uids: dict, modality: str):
+        """Set series information in DICOM metadata.
+        
+        Args:
+            meta (DicomMeta): The metadata object to update.
+            uids (dict): Dictionary containing generated UIDs.
+            modality (str): Image modality.
+        """
+        meta.set_shared_item(CommonTags.SeriesInstanceUID, uids['series_uid'])
+        meta.set_shared_item(CommonTags.SeriesNumber, "1")
+        meta.set_shared_item(
+            CommonTags.SeriesDescription, f"Default {modality} Series"
+        )
+    
+    def _set_image_info(self, meta: DicomMeta, uids: dict, num_slices: int):
+        """Set image-specific information in DICOM metadata.
+        
+        Args:
+            meta (DicomMeta): The metadata object to update.
+            uids (dict): Dictionary containing generated UIDs.
+            num_slices (int): Number of slices in the image.
+        """
+        from pydicom.uid import generate_uid
+        
+        if num_slices > 1:
+            sop_uids = [generate_uid() for _ in range(num_slices)]
+            instance_numbers = [str(i + 1) for i in range(num_slices)]
+            meta.set_nonshared_item(CommonTags.SOPInstanceUID, sop_uids)
+            meta.set_nonshared_item(CommonTags.InstanceNumber, instance_numbers)
+        else:
+            meta.set_shared_item(CommonTags.SOPInstanceUID, uids['sop_uid'])
+            meta.set_shared_item(CommonTags.InstanceNumber, "1")
+
+        meta.set_shared_item(CommonTags.FrameOfReferenceUID, uids['frame_uid'])
+    
+    def _set_space_info(self, meta: DicomMeta, num_slices: int):
+        """Set spatial information in DICOM metadata.
+        
+        Args:
+            meta (DicomMeta): The metadata object to update.
+            num_slices (int): Number of slices in the image.
+        """
+        if self.space is not None:
+            # Set orientation information
+            orientation = self.space.to_dicom_orientation()
+            meta.set_shared_item(
+                CommonTags.ImageOrientationPatient, list(orientation)
+            )
+            meta.set_shared_item(CommonTags.PixelSpacing, list(self.space.spacing[:2]))
+            meta.set_shared_item(
+                CommonTags.SliceThickness, float(self.space.spacing[2])
+            )
+
+            # Set position information
+            if num_slices > 1:
+                positions = []
+                for i in range(num_slices):
+                    # Calculate position for each slice using space's z_orientation
+                    pos = np.array(self.space.origin) + i * self.space.spacing[
+                        2
+                    ] * np.array(self.space.z_orientation)
+                    positions.append(pos.tolist())
+                meta.set_nonshared_item(CommonTags.ImagePositionPatient, positions)
+            else:
+                meta.set_shared_item(
+                    CommonTags.ImagePositionPatient, list(self.space.origin)
+                )
+        else:
+            # If no space information, set default values
+            meta.set_shared_item(
+                CommonTags.ImageOrientationPatient, [1, 0, 0, 0, 1, 0]
+            )
+            meta.set_shared_item(CommonTags.PixelSpacing, [1.0, 1.0])
+            meta.set_shared_item(CommonTags.SliceThickness, 1.0)
+            if num_slices > 1:
+                positions = [[0, 0, i] for i in range(num_slices)]
+                meta.set_nonshared_item(CommonTags.ImagePositionPatient, positions)
+            else:
+                meta.set_shared_item(CommonTags.ImagePositionPatient, [0, 0, 0])
+    
+    def _set_pixel_info(self, meta: DicomMeta):
+        """Set pixel data information in DICOM metadata.
+        
+        Args:
+            meta (DicomMeta): The metadata object to update.
+        """
+        # Image dimensions
+        shape = self.raw_image.shape
+        if len(shape) == 3:
+            meta.set_shared_item(CommonTags.Rows, shape[1])
+            meta.set_shared_item(CommonTags.Columns, shape[2])
+        else:
+            meta.set_shared_item(CommonTags.Rows, shape[0])
+            meta.set_shared_item(CommonTags.Columns, shape[1])
+
+        # Pixel characteristics
+        meta.set_shared_item(CommonTags.SamplesPerPixel, 1)
+        meta.set_shared_item(CommonTags.PhotometricInterpretation, "MONOCHROME2")
+        meta.set_shared_item(CommonTags.BitsAllocated, 16)
+        meta.set_shared_item(CommonTags.BitsStored, 16)
+        meta.set_shared_item(CommonTags.HighBit, 15)
+        meta.set_shared_item(CommonTags.PixelRepresentation, 0)
+
+        # Rescale Information from pixel_header
+        if self.pixel_header.RESCALE_SLOPE is not None:
+            meta.set_shared_item(
+                CommonTags.RescaleSlope, float(self.pixel_header.RESCALE_SLOPE)
+            )
+        if self.pixel_header.RESCALE_INTERCEPT is not None:
+            meta.set_shared_item(
+                CommonTags.RescaleIntercept, float(self.pixel_header.RESCALE_INTERCEPT)
+            )
+
+    def init_meta(
+        self,
+        modality: str = "OT",
+        patient_name: str = "ANONYMOUS^",
+        patient_id: str = "0000000",
+    ) -> DicomMeta:
+        """Initialize a basic DicomMeta when none is provided.
+
+        Sets required DICOM fields with default values.
+
+        Args:
+            modality (str): Image modality, such as CT/MR/PT. Defaults to "OT".
+            patient_name (str): Patient name. Defaults to "ANONYMOUS^".
+            patient_id (str): Patient ID. Defaults to "0000000".
+
+        Returns:
+            DicomMeta: A new DicomMeta instance with basic required fields.
+        """
+        # Validate input parameters
+        validate_string_not_empty(modality, "modality", "init_meta operation", MetaDataError)
+        validate_string_not_empty(patient_name, "patient_name", "init_meta operation", MetaDataError)
+        validate_string_not_empty(patient_id, "patient_id", "init_meta operation", MetaDataError)
+        
+        try:
+            # Create empty DicomMeta
+            num_slices = self.raw_image.shape[0] if len(self.raw_image.shape) == 3 else 1
+            meta = DicomMeta({}, [f"slice_{i:04d}.dcm" for i in range(num_slices)])
+
+            # Generate necessary UIDs
+            uids = self._generate_uids()
+            
+            # Set metadata sections
+            self._set_patient_info(meta, patient_name, patient_id)
+            self._set_study_info(meta, uids, modality)
+            self._set_series_info(meta, uids, modality)
+            self._set_image_info(meta, uids, num_slices)
+            self._set_space_info(meta, num_slices)
+            self._set_pixel_info(meta)
+            
+            # Set modality
+            meta.set_shared_item(CommonTags.Modality, modality)
+
+            # Validate initialization success
+            if meta is None:
+                raise MetaDataError(
+                    "DicomMeta initialization returned None",
+                    context="init_meta operation",
+                    suggestion="Check DicomMeta constructor parameters and dependencies"
+                )
+            
+            self.dicom_meta = meta
+            return meta
+            
+        except Exception as e:
+            if isinstance(e, MetaDataError):
+                raise
+            raise MetaDataError(
+                f"Failed to initialize DicomMeta: {str(e)}",
+                context="init_meta operation",
+                suggestion="Verify image data and metadata parameters are valid"
+            ) from e
+
+    @property
+    def shape(self):
+        """Get the shape of the raw image.
+        
+        Returns:
+            tuple: The shape of the raw image array.
+        """
+        return self.raw_image.shape
+    
+    @property
+    def dtype(self):
+        """Get the data type of the raw image.
+        
+        Returns:
+            numpy.dtype: The data type of the raw image array.
+        """
+        return self.raw_image.dtype
+    
+    def _validate_shape(self):
+        """Validate that the image shape matches the space shape if both are present.
+        
+        Both raw_image and space are now in (z,y,x) format internally.
+
+        Raises:
+            DataConsistencyError: If space shape doesn't match image dimensions.
+        """
+        if self.space and self.raw_image.ndim >= 3:
+            expected_shape = tuple(self.space.shape)
+            if self.raw_image.shape[-len(expected_shape) :] != expected_shape:
+                raise DataConsistencyError(
+                    f"Space shape mismatch with image dimensions",
+                    context="DicomCubeImage shape validation",
+                    details={
+                        "space_shape": expected_shape,
+                        "image_shape": self.raw_image.shape,
+                        "image_dims": self.raw_image.ndim
+                    },
+                    suggestion="Ensure space dimensions match the image array dimensions"
+                )
+
+    def get_fdata(self, dtype="float32") -> np.ndarray:
+        """Get image data as floating point array with slope/intercept applied.
+
+        Args:
+            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.
+        """
+        return get_float_data(self.raw_image, self.pixel_header, dtype) 

dicube/core/io.py

@@ -0,0 +1,354 @@
+import struct
+import warnings
+from typing import Optional, Union
+
+import numpy as np
+from spacetransformer import Space, get_space_from_nifti
+
+from ..dicom import (
+    CommonTags,
+    DicomMeta,
+    DicomStatus,
+    SortMethod,
+    get_dicom_status,
+    read_dicom_dir,
+    get_space_from_DicomMeta,
+)
+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 .pixel_header import PixelDataHeader
+
+from ..validation import (
+    validate_not_none,
+    validate_file_exists,
+    validate_folder_exists,
+    validate_parameter_type,
+    validate_string_not_empty,
+    validate_numeric_range
+)
+from ..exceptions import (
+    InvalidCubeFileError,
+    CodecError,
+    MetaDataError,
+    DataConsistencyError
+)
+import os
+
+
+class DicomCubeImageIO:
+    """Static I/O utility class responsible for DicomCubeImage file operations.
+    
+    Responsibilities:
+    - Provides unified file I/O interface
+    - Automatically detects file formats
+    - Handles conversion between various file formats
+    """
+    
+
+    
+    @staticmethod
+    def save(
+        image: "DicomCubeImage",
+        file_path: str,
+        file_type: str = "s",
+        num_threads: int = 4,
+    ) -> None:
+        """Save DicomCubeImage to a file.
+        
+        Args:
+            image (DicomCubeImage): The DicomCubeImage object to 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.
+            
+        Raises:
+            InvalidCubeFileError: If the file_type is not supported.
+        """
+        # 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"):
+            raise InvalidCubeFileError(
+                f"Unsupported file type: {file_type}",
+                context="save operation",
+                details={"file_type": file_type, "supported_types": ["s", "a", "l"]},
+                suggestion="Use 's' for speed priority, 'a' for compression priority, or 'l' for lossy compression"
+            )
+        
+        try:
+            # Choose appropriate writer based on file type
+            if file_type == "s":
+                writer = DcbSFile(file_path, mode="w")
+            elif file_type == "a":
+                writer = DcbAFile(file_path, mode="w")
+            elif file_type == "l":
+                writer = DcbLFile(file_path, mode="w")
+            
+            # 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
+            )
+        except Exception as e:
+            if isinstance(e, (InvalidCubeFileError, CodecError)):
+                raise
+            raise InvalidCubeFileError(
+                f"Failed to save file: {str(e)}",
+                context="save operation",
+                details={"file_path": file_path, "file_type": file_type}
+            ) from e
+    
+    @staticmethod
+    def load(file_path: str, num_threads: int = 4, **kwargs) -> '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.
+            
+        Raises:
+            ValueError: When the file format is not supported.
+        """
+        # Validate required parameters
+        validate_not_none(file_path, "file_path", "load operation", InvalidCubeFileError)
+        validate_file_exists(file_path, "load operation", InvalidCubeFileError)
+        
+        try:
+            # Read file header to determine format
+            header_size = struct.calcsize(DcbFile.HEADER_STRUCT)
+            with open(file_path, "rb") as f:
+                header_data = f.read(header_size)
+            magic = struct.unpack(DcbFile.HEADER_STRUCT, header_data)[0]
+            
+            # Choose appropriate reader based on magic number
+            if magic == DcbAFile.MAGIC:
+                reader = DcbAFile(file_path, mode="r")
+            elif magic == DcbSFile.MAGIC:
+                reader = DcbSFile(file_path, mode="r")
+            else:
+                raise InvalidCubeFileError(
+                    f"Unsupported file format",
+                    context="load operation",
+                    details={"file_path": file_path, "magic_number": magic},
+                    suggestion="Ensure the file is a valid DicomCube file"
+                )
+            
+            # Read file contents
+            dicom_meta = reader.read_meta()
+            space = reader.read_space()
+            pixel_header = reader.read_pixel_header()
+            dicom_status = reader.read_dicom_status()
+            
+            images = reader.read_images(num_threads=num_threads)
+            if isinstance(images, list):
+                # Convert list to ndarray if needed
+                images = np.stack(images)
+            
+            # Use lazy import to avoid circular dependency
+            from .image import DicomCubeImage
+            
+            return DicomCubeImage(
+                raw_image=images,
+                pixel_header=pixel_header,
+                dicom_meta=dicom_meta,
+                space=space,
+                dicom_status=dicom_status,
+            )
+        except Exception as e:
+            if isinstance(e, (InvalidCubeFileError, CodecError)):
+                raise
+            raise InvalidCubeFileError(
+                f"Failed to load file: {str(e)}",
+                context="load operation",
+                details={"file_path": file_path}
+            ) from e
+    
+    @staticmethod
+    def load_from_dicom_folder(
+        folder_path: str,
+        sort_method: SortMethod = SortMethod.INSTANCE_NUMBER_ASC,
+        **kwargs
+    ) -> 'DicomCubeImage':
+        """Load DicomCubeImage from a DICOM folder.
+        
+        Args:
+            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.
+            
+        Raises:
+            ValueError: When the DICOM status is not supported.
+        """
+        # Validate required parameters
+        validate_not_none(folder_path, "folder_path", "load_from_dicom_folder operation", InvalidCubeFileError)
+        validate_folder_exists(folder_path, "load_from_dicom_folder operation", InvalidCubeFileError)
+        
+        try:
+            # Read DICOM folder
+            meta, datasets = read_dicom_dir(folder_path, sort_method=sort_method)
+            images = [d.pixel_array for d in datasets]
+            status = get_dicom_status(meta)
+            
+            if status in (
+                DicomStatus.NON_UNIFORM_RESCALE_FACTOR,
+                DicomStatus.MISSING_DTYPE,
+                DicomStatus.NON_UNIFORM_DTYPE,
+                DicomStatus.MISSING_SHAPE,
+                DicomStatus.INCONSISTENT,
+            ):
+                raise MetaDataError(
+                    f"Unsupported DICOM status: {status}",
+                    context="load_from_dicom_folder operation",
+                    details={"dicom_status": status, "folder_path": folder_path},
+                    suggestion="Ensure DICOM files have consistent metadata and proper format"
+                )
+            
+            if status in (
+                DicomStatus.MISSING_SPACING,
+                DicomStatus.NON_UNIFORM_SPACING,
+                DicomStatus.MISSING_ORIENTATION,
+                DicomStatus.NON_UNIFORM_ORIENTATION,
+                DicomStatus.MISSING_LOCATION,
+                DicomStatus.REVERSED_LOCATION,
+                DicomStatus.DWELLING_LOCATION,
+                DicomStatus.GAP_LOCATION,
+            ):
+                warnings.warn(f"DICOM status: {status}, cannot calculate space information")
+                space = None
+            else:
+                if get_space_from_DicomMeta is not None:
+                    space = get_space_from_DicomMeta(meta, axis_order="zyx")
+                else:
+                    space = None
+            
+            # Get rescale parameters
+            slope = meta.get_shared_value(CommonTags.RescaleSlope)
+            intercept = meta.get_shared_value(CommonTags.RescaleIntercept)
+            wind_center = meta.get_shared_value(CommonTags.WindowCenter)
+            wind_width = meta.get_shared_value(CommonTags.WindowWidth)
+            
+            # 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,
+            )
+            
+            # Validate PixelDataHeader initialization success
+            if pixel_header is None:
+                raise MetaDataError(
+                    "PixelDataHeader initialization failed",
+                    context="load_from_dicom_folder operation",
+                    suggestion="Check DICOM metadata for required pixel data information"
+                )
+            
+            # Use lazy import to avoid circular dependency
+            from .image import DicomCubeImage
+            
+            return DicomCubeImage(
+                raw_image=np.array(images),
+                pixel_header=pixel_header,
+                dicom_meta=meta,
+                space=space,
+                dicom_status=status
+            )
+        except Exception as e:
+            if isinstance(e, (InvalidCubeFileError, MetaDataError)):
+                raise
+            raise MetaDataError(
+                f"Failed to load DICOM folder: {str(e)}",
+                context="load_from_dicom_folder operation",
+                details={"folder_path": folder_path}
+            ) from e
+    
+    @staticmethod
+    def load_from_nifti(file_path: str, **kwargs) -> '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.
+            
+        Raises:
+            ImportError: When nibabel is not installed.
+        """
+        # Validate required parameters
+        validate_not_none(file_path, "file_path", "load_from_nifti operation", InvalidCubeFileError)
+        validate_file_exists(file_path, "load_from_nifti operation", InvalidCubeFileError)
+        
+        try:
+            import nibabel as nib
+        except ImportError:
+            raise ImportError("nibabel is required to read NIfTI files")
+        
+        try:
+            nii = nib.load(file_path)
+            space = get_space_from_nifti(nii)
+            
+            # Fix numpy array warning
+            raw_image, header = derive_pixel_header_from_array(
+                np.asarray(nii.dataobj, dtype=nii.dataobj.dtype)
+            )
+            
+            # Use lazy import to avoid circular dependency
+            from .image import DicomCubeImage
+            
+            return DicomCubeImage(raw_image, header, space=space)
+        except Exception as e:
+            if isinstance(e, ImportError):
+                raise
+            raise InvalidCubeFileError(
+                f"Failed to load NIfTI file: {str(e)}",
+                context="load_from_nifti operation",
+                details={"file_path": file_path},
+                suggestion="Ensure the file is a valid NIfTI format and nibabel is installed"
+            ) from e
+    
+    @staticmethod
+    def save_to_dicom_folder(
+        image: 'DicomCubeImage',
+        folder_path: str,
+    ) -> None:
+        """Save DicomCubeImage as a DICOM folder.
+        
+        Args:
+            image (DicomCubeImage): The DicomCubeImage object to save.
+            folder_path (str): Output directory path.
+        """
+        # Validate required parameters
+        validate_not_none(image, "image", "save_to_dicom_folder operation", DataConsistencyError)
+        validate_string_not_empty(folder_path, "folder_path", "save_to_dicom_folder operation", InvalidCubeFileError)
+        
+        if image.dicom_meta is None:
+            warnings.warn("dicom_meta is None, initializing with default values")
+            image.init_meta()
+        
+        save_to_dicom_folder(
+            raw_images=image.raw_image,
+            dicom_meta=image.dicom_meta,
+            pixel_header=image.pixel_header,
+            output_dir=folder_path,
+        )