dicube 0.2.2__cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

dicube/dicom/dicom_status.py

@@ -0,0 +1,259 @@
+from enum import Enum
+
+import numpy as np
+from pydicom.tag import Tag
+
+from .dicom_tags import CommonTags
+
+
+class DicomStatus(Enum):
+    """
+    Enumeration of possible DICOM series status conditions.
+
+    Each status represents a specific condition or issue that may be present
+    in a DICOM series. The conditions are grouped into categories:
+    - Series UID Issues
+    - Instance Number Issues
+    - Spacing Issues
+    - Shape Issues
+    - Orientation Issues
+    - Data Type Issues
+    - Location Issues
+    - Consistency Status
+    """
+
+    # Series UID Issues
+    NON_UNIFORM_SERIES_UID = (
+        "non_uniform_series_uid"  # Multiple Series UIDs in one series
+    )
+    MISSING_SERIES_UID = "missing_series_uid"  # No Series UIDs present
+
+    # Instance Number Issues
+    DUPLICATE_INSTANCE_NUMBERS = (
+        "duplicate_instance_numbers"  # Duplicated instance numbers (e.g., 1,1,2,2,3,3)
+    )
+    MISSING_INSTANCE_NUMBER = "missing_instance_number"  # Missing Instance Number
+    GAP_INSTANCE_NUMBER = "gap_instance_number"  # Gaps in instance numbering
+
+    # Spacing Issues
+    MISSING_SPACING = "missing_spacing"  # Missing Pixel Spacing
+    NON_UNIFORM_SPACING = (
+        "non_uniform_spacing"  # Inconsistent Pixel Spacing (XY intervals)
+    )
+
+    # Shape Issues
+    MISSING_SHAPE = "missing_shape"  # Missing image dimensions (Columns or Rows)
+    NON_UNIFORM_SHAPE = "non_uniform_shape"  # Inconsistent image dimensions
+
+    # Orientation Issues
+    MISSING_ORIENTATION = "missing_orientation"  # Missing Image Orientation Patient
+    NON_UNIFORM_ORIENTATION = (
+        "non_uniform_orientation"  # Inconsistent Image Orientation Patient
+    )
+
+    # Data Type Issues
+    NON_UNIFORM_RESCALE_FACTOR = (
+        "non_uniform_rescale_factor"  # Inconsistent intercept or slope
+    )
+    MISSING_DTYPE = "missing_dtype"  # Missing data type information
+    NON_UNIFORM_DTYPE = "non_uniform_dtype"  # Inconsistent data types
+
+    # Location Issues
+    MISSING_LOCATION = (
+        "missing_location"  # Missing Slice Location and Image Position Patient
+    )
+    REVERSED_LOCATION = "reversed_location"  # Z-values reversed when sorted by instance (e.g., 1,2,3,2,1)
+    DWELLING_LOCATION = (
+        "dwelling_location"  # Z-values show stagnation (e.g., 1,2,3,3,4,5)
+    )
+    GAP_LOCATION = "gap_location"  # Z-values have gaps (e.g., 1,2,3,5,6)
+
+    # Consistency Status
+    CONSISTENT = "consistent"  # All checks pass, data is consistent
+    INCONSISTENT = "inconsistent"  # Other inconsistencies not covered above
+
+
+def calculate_average_z_gap(z_locations: np.ndarray) -> float:
+    """
+    Calculate the average gap between Z-axis locations.
+
+    Uses a robust method to estimate the typical Z-axis interval:
+    1. If a single interval appears in >80% of cases, use that value
+    2. Otherwise, use the larger absolute value between median and mean
+
+    Args:
+        z_locations: Sorted array of Z-axis locations
+
+    Returns:
+        float: Estimated typical Z-axis interval; 0 if cannot be calculated
+    """
+    if len(z_locations) < 2:
+        return 0.0
+    diffs = np.diff(z_locations)
+    if len(diffs) == 0:
+        return 0.0
+
+    # If one interval appears in >80% of cases, use it
+    uniq_diffs, counts = np.unique(diffs, return_counts=True)
+    if np.max(counts) / len(diffs) > 0.8:
+        return uniq_diffs[np.argmax(counts)]
+
+    # Otherwise use the larger of median or mean
+    median_diff = np.median(diffs)
+    mean_diff = np.mean(diffs)
+    return max([median_diff, mean_diff], key=abs)
+
+
+def get_dicom_status(meta) -> DicomStatus:
+    """
+    Check DICOM metadata and return the corresponding status.
+
+    Performs a series of checks on the DICOM metadata to determine its status.
+    Checks include:
+    - Series UID consistency
+    - Instance number sequence
+    - Pixel spacing uniformity
+    - Image dimensions
+    - Patient orientation
+    - Data type consistency
+    - Z-axis location sequence
+
+    Args:
+        meta: DicomMeta instance providing access to DICOM metadata
+
+    Returns:
+        DicomStatus: The status enum value representing the check results
+    """
+    # --------------------------  Series UID --------------------------
+    if meta.is_missing(CommonTags.SeriesInstanceUID):
+        return DicomStatus.MISSING_SERIES_UID
+    if not meta.is_shared(CommonTags.SeriesInstanceUID):
+        return DicomStatus.NON_UNIFORM_SERIES_UID
+
+    # --------------------------  Instance Number --------------------------
+    if meta.is_missing(CommonTags.InstanceNumber):
+        return DicomStatus.MISSING_INSTANCE_NUMBER
+
+    # Get instance numbers (always treat as non-shared for this check)
+    instance_numbers = meta.get_values(CommonTags.InstanceNumber)
+    
+    # Check for single image
+    if meta.slice_count == 1:
+        # Single image is fine, continue to next check
+        pass
+    else:
+        # Check for duplicate instance numbers
+        if len(set(instance_numbers)) < len(instance_numbers):
+            return DicomStatus.DUPLICATE_INSTANCE_NUMBERS
+
+        # Check for gaps in instance numbering
+        # First convert to integers and sort
+        try:
+            int_instances = [int(num) if num is not None else None for num in instance_numbers]
+            sorted_instances = sorted([num for num in int_instances if num is not None])
+            
+            # If we have a sequence with more than one image
+            if len(sorted_instances) > 1:
+                # Check if they form a continuous sequence
+                diffs = np.diff(sorted_instances)
+                if not np.all(diffs == 1):
+                    return DicomStatus.GAP_INSTANCE_NUMBER
+        except (ValueError, TypeError):
+            # If conversion fails, we can't check for gaps
+            pass
+
+    # --------------------------  Dtype (Bits) --------------------------
+    dtype_tags = [
+        CommonTags.BitsStored,
+        CommonTags.BitsAllocated,
+        CommonTags.HighBit,
+        CommonTags.PixelRepresentation
+    ]
+    
+    # Check if any are missing
+    if any(meta.is_missing(tag) for tag in dtype_tags):
+        return DicomStatus.MISSING_DTYPE
+        
+    # Check if any are non-shared
+    if any(not meta.is_shared(tag) for tag in dtype_tags):
+        return DicomStatus.NON_UNIFORM_DTYPE
+
+    # --------------------------  Pixel Spacing --------------------------
+    if meta.is_missing(CommonTags.PixelSpacing):
+        return DicomStatus.MISSING_SPACING
+    if not meta.is_shared(CommonTags.PixelSpacing):
+        return DicomStatus.NON_UNIFORM_SPACING
+
+    # --------------------------  Image Shape (Columns/Rows) --------------------------
+    if meta.is_missing(CommonTags.Columns) or meta.is_missing(CommonTags.Rows):
+        return DicomStatus.MISSING_SHAPE
+    if not meta.is_shared(CommonTags.Columns) or not meta.is_shared(CommonTags.Rows):
+        return DicomStatus.NON_UNIFORM_SHAPE
+
+    # --------------------------  Orientation --------------------------
+    if meta.is_missing(CommonTags.ImageOrientationPatient):
+        return DicomStatus.MISSING_ORIENTATION
+    if not meta.is_shared(CommonTags.ImageOrientationPatient):
+        return DicomStatus.NON_UNIFORM_ORIENTATION
+
+    # --------------------------  Location (Z direction) --------------------------
+    # Need either ImagePositionPatient or SliceLocation
+    has_position = not meta.is_missing(CommonTags.ImagePositionPatient)
+    has_location = not meta.is_missing(CommonTags.SliceLocation)
+
+    # If both are missing, mark as missing location
+    if not has_position and not has_location:
+        return DicomStatus.MISSING_LOCATION
+
+    # Get Z locations and check for issues
+    # For multi-slice datasets only
+    if meta.slice_count > 1:
+        # Get Z locations from the DicomMeta helper method
+        z_locations = meta._get_projection_location()
+        
+        # Get the order of instance numbers
+        instance_numbers = meta.get_values(CommonTags.InstanceNumber)
+        try:
+            # Convert to integers and get sort order
+            int_instances = [int(num) if num is not None else float('inf') for num in instance_numbers]
+            sort_idx = np.argsort(int_instances)
+            
+            # Sort Z locations by instance number
+            sorted_z = np.array([z_locations[i] for i in sort_idx if i < len(z_locations)])
+            
+            # Check for direction changes
+            if len(sorted_z) > 1:
+                diffs_z = np.diff(sorted_z)
+                
+                # Check for direction changes (sign changes in differences)
+                if np.min(diffs_z) < 0 < np.max(diffs_z):
+                    return DicomStatus.REVERSED_LOCATION
+                
+                # Check for duplicate positions (zero differences)
+                if np.any(diffs_z == 0):
+                    return DicomStatus.DWELLING_LOCATION
+                
+                # Check for gaps in Z locations
+                avg_gap = calculate_average_z_gap(sorted_z)
+                if avg_gap > 0.0:
+                    # Calculate relative deviations from average gap
+                    ratio_diffs = np.abs(diffs_z - avg_gap) / (avg_gap + 1e-8)
+                    # If any gap is more than 50% different from average, mark as gap
+                    if np.any(ratio_diffs > 0.5):
+                        return DicomStatus.GAP_LOCATION
+        except (ValueError, TypeError):
+            # If conversion fails, we can't check for sequence issues
+            pass
+
+    # --------------------------  Rescale Factor (Intercept/Slope) --------------------------
+    # These may not exist, so only check if they're present
+    has_intercept = not meta.is_missing(CommonTags.RescaleIntercept)
+    has_slope = not meta.is_missing(CommonTags.RescaleSlope)
+    
+    if has_intercept and has_slope:
+        # If present, check for consistency
+        if not meta.is_shared(CommonTags.RescaleIntercept) or not meta.is_shared(CommonTags.RescaleSlope):
+            return DicomStatus.NON_UNIFORM_RESCALE_FACTOR
+
+    # --------------------------  All checks passed --------------------------
+    return DicomStatus.CONSISTENT 

dicube/dicom/dicom_tags.py

@@ -0,0 +1,121 @@
+from pydicom.tag import Tag
+from typing import Union, Tuple, Set
+
+
+def get_tag_key(tag: Tag) -> str:
+    """Get the hexadecimal string representation of a DICOM Tag (format: 'ggggeeee').
+    
+    Args:
+        tag: pydicom Tag object
+        
+    Returns:
+        str: Hexadecimal string, e.g., '00100020' for PatientID
+    """
+    return f"{tag:08X}"  # or format(tag, "08X")
+
+
+class CommonTags:
+    """Common DICOM tags used throughout the library.
+    
+    This class provides convenient access to frequently used DICOM tags
+    organized by category (patient, study, series, instance, etc.).
+    All tags are pydicom Tag objects.
+    """
+    
+    # Patient tags
+    PatientID = Tag("PatientID")
+    PatientName = Tag("PatientName")
+    PatientBirthDate = Tag("PatientBirthDate")
+    PatientSex = Tag("PatientSex")
+    PatientAge = Tag("PatientAge")
+    PatientWeight = Tag("PatientWeight")
+    
+    # Study tags
+    StudyInstanceUID = Tag("StudyInstanceUID")
+    StudyID = Tag("StudyID")
+    StudyDate = Tag("StudyDate")
+    StudyTime = Tag("StudyTime")
+    AccessionNumber = Tag("AccessionNumber")
+    StudyDescription = Tag("StudyDescription")
+    
+    # Series tags
+    SeriesInstanceUID = Tag("SeriesInstanceUID")
+    SeriesNumber = Tag("SeriesNumber")
+    Modality = Tag("Modality")
+    SeriesDescription = Tag("SeriesDescription")
+    
+    # Instance tags
+    SOPInstanceUID = Tag("SOPInstanceUID")
+    SOPClassUID = Tag("SOPClassUID")
+    InstanceNumber = Tag("InstanceNumber")
+    
+    # Image tags
+    Rows = Tag("Rows")
+    Columns = Tag("Columns")
+    BitsAllocated = Tag("BitsAllocated")
+    BitsStored = Tag("BitsStored")
+    HighBit = Tag("HighBit")
+    SamplesPerPixel = Tag("SamplesPerPixel")
+    PhotometricInterpretation = Tag("PhotometricInterpretation")
+    PixelRepresentation = Tag("PixelRepresentation")
+    
+    # Spatial tags
+    ImagePositionPatient = Tag("ImagePositionPatient")
+    ImageOrientationPatient = Tag("ImageOrientationPatient")
+    PixelSpacing = Tag("PixelSpacing")
+    SliceThickness = Tag("SliceThickness")
+    SpacingBetweenSlices = Tag("SpacingBetweenSlices")
+    SliceLocation = Tag("SliceLocation")
+    
+    # Value transformations
+    RescaleIntercept = Tag("RescaleIntercept")
+    RescaleSlope = Tag("RescaleSlope")
+    WindowCenter = Tag("WindowCenter")
+    WindowWidth = Tag("WindowWidth")
+    PatientPosition = Tag("PatientPosition")
+    BodyPartExamined = Tag("BodyPartExamined")
+    
+    # Pixel data
+    PixelData = Tag("PixelData")
+    
+    # Enhanced MR specific tags
+    DimensionIndexSequence = Tag("DimensionIndexSequence")
+    FrameContentSequence = Tag("FrameContentSequence")
+    
+    # UID tags
+    ImplementationClassUID = Tag("ImplementationClassUID")
+    
+    # Other important tags
+    TransferSyntaxUID = Tag("TransferSyntaxUID")
+    MediaStorageSOPClassUID = Tag("MediaStorageSOPClassUID")
+    MediaStorageSOPInstanceUID = Tag("MediaStorageSOPInstanceUID")
+    SpecificCharacterSet = Tag("SpecificCharacterSet")
+        
+    # Manufacturer Information
+    Manufacturer = Tag("Manufacturer")
+    ManufacturerModelName = Tag("ManufacturerModelName")
+    SoftwareVersions = Tag("SoftwareVersions")
+    
+    # Other Common Tags
+    FrameOfReferenceUID = Tag("FrameOfReferenceUID")
+    ReferencedImageSequence = Tag("ReferencedImageSequence")
+    ReferencedSOPInstanceUID = Tag("ReferencedSOPInstanceUID")
+    AcquisitionNumber = Tag("AcquisitionNumber")
+    ContrastBolusAgent = Tag("ContrastBolusAgent")
+    
+    # Tag sets for hierarchical DICOM levels
+    PATIENT_LEVEL_TAGS: Set[Tag] = {
+        PatientID, PatientName, PatientBirthDate, PatientSex
+    }
+    
+    STUDY_LEVEL_TAGS: Set[Tag] = {
+        StudyInstanceUID, StudyID, StudyDate, StudyTime, AccessionNumber
+    }
+    
+    SERIES_LEVEL_TAGS: Set[Tag] = {
+        SeriesInstanceUID, SeriesNumber, Modality
+    }
+    
+    INSTANCE_LEVEL_TAGS: Set[Tag] = {
+        SOPInstanceUID, SOPClassUID, InstanceNumber
+    } 

dicube/dicom/merge_utils.py

@@ -0,0 +1,283 @@
+from typing import Any, Dict, List, Optional, Tuple
+
+
+###############################################################################
+# Helper Functions: Check Value Equality
+###############################################################################
+def _all_identical(values: List[Any]) -> bool:
+    """
+    Check if all elements in a list are identical (including None).
+
+    Args:
+        values: List of values to compare
+
+    Returns:
+        bool: True if list is empty, has one element, or all elements are identical
+    """
+    if (not values) or (len(values) <= 1):
+        return True
+    first = values[0]
+    return all(v == first for v in values[1:])
+
+
+###############################################################################
+# Recursively Merge Dataset JSONs
+###############################################################################
+def _merge_dataset_list(
+    dataset_jsons: List[Dict[str, Any]]
+) -> Dict[str, Dict[str, Any]]:
+    """
+    Merge a list of pydicom JSON representations at the top level.
+
+    Creates a merged dictionary where each tag entry contains:
+    {
+      "vr": str,                   # DICOM Value Representation
+      "shared": True/False/None,   # None for sequences (SQ)
+      "Value": [single value/list/sequence structure]
+    }
+
+    Args:
+        dataset_jsons: List of pydicom JSON dictionaries to merge
+
+    Returns:
+        dict: Merged data with format {tag: merged_entry, ...}
+    """
+    # 1. Collect all unique tags
+    all_tags = set()
+    for js in dataset_jsons:
+        all_tags.update(js.keys())
+
+    merged_data = {}
+    for tag in sorted(all_tags):
+        # Collect values for this tag from all datasets
+        # Note: Each value is like {"vr": "XX", "Value": [...]} or None
+        tag_values = [ds_js.get(tag, None) for ds_js in dataset_jsons]
+
+        # 2. Get VR if present in any dataset
+        vrs = [tv["vr"] for tv in tag_values if tv is not None]
+        vr = vrs[0] if vrs else None
+
+        # 3. Merge values
+        merged_data[tag] = _merge_tag_values(vr, tag_values)
+    return merged_data
+
+
+def _get_value_and_name(tv: Optional[Dict[str, Any]]) -> Tuple[Optional[str], Any]:
+    """
+    Extract the value and its field name from a tag value dictionary.
+
+    Handles different value storage methods in DICOM:
+    - Standard Value field
+    - InlineBinary for binary data
+    - BulkDataURI for external references
+
+    Args:
+        tv: Tag value dictionary or None
+
+    Returns:
+        tuple: (field_name, actual_value) where both may be None
+    """
+    if tv is not None and "Value" in tv:
+        value_name = "Value"
+        actual_value = tv["Value"]
+    elif tv is not None and "InlineBinary" in tv:
+        actual_value = tv["InlineBinary"]
+        value_name = "InlineBinary"
+    elif tv is not None and "BulkDataURI" in tv:
+        actual_value = tv["BulkDataURI"]
+        value_name = "BulkDataURI"
+    else:
+        value_name = None
+        actual_value = None
+    return value_name, actual_value
+
+
+def _merge_tag_values(
+    vr: Optional[str], tag_values: List[Optional[Dict[str, Any]]]
+) -> Dict[str, Any]:
+    """
+    Merge values for a single tag across multiple datasets.
+
+    For sequences (VR=SQ), recursively merges nested structures.
+    For other VRs, determines if values are shared across datasets.
+
+    Args:
+        vr: DICOM Value Representation (VR) code
+        tag_values: List of value dictionaries from each dataset
+
+    Returns:
+        dict: Merged entry with format:
+            {
+                "vr": str,
+                "shared": bool/None,
+                "Value": merged_value
+            }
+    """
+    # If tag is missing from all datasets, return empty shell
+    if all(tv is None for tv in tag_values):
+        return {"vr": vr, "shared": True}
+
+    if vr == "SQ":
+        # Handle sequences recursively
+        return _merge_sequence(tag_values)
+    else:
+        # Handle standard values
+        # Extract actual values (may be list[str], list[float], or single value)
+        actual_values = []
+        value_name = "Value"
+        for tv in tag_values:
+            value_name, actual_value = _get_value_and_name(tv)
+            actual_values.append(actual_value)
+
+        # Check if all values are identical
+        if _all_identical(actual_values):
+            if actual_values[0] is None:
+                return {"vr": vr, "shared": True}
+            else:
+                return {
+                    "vr": vr,
+                    "shared": True,
+                    value_name: actual_values[0],
+                }  # Store single value
+        else:
+            for i, v in enumerate(actual_values):
+                if v is None:
+                    actual_values[i] = 'None'
+            # Flatten single-element lists
+            if all([len(v) == 1 for v in actual_values]):
+                actual_values = [v[0] for v in actual_values]
+            return {
+                "vr": vr,
+                "shared": False,
+                value_name: actual_values,  # Store list for each dataset
+            }
+
+
+def _merge_sequence(sq_values: List[Optional[Dict[str, Any]]]) -> Dict[str, Any]:
+    """
+    Merge sequence values across datasets.
+
+    Each element has format: {"vr": "SQ", "Value": [item1, item2, ...]} or None.
+    Returns merged structure:
+    {
+      "vr": "SQ",
+      "shared": None,  # Shared status determined at item level
+      "Value": [
+         # Merged items, each a dict with {tag: {vr, shared, Value}}
+      ]
+    }
+
+    Args:
+        sq_values: List of sequence value dictionaries from each dataset
+
+    Returns:
+        dict: Merged sequence structure
+    """
+    # 1. Extract actual sequence values, replacing None with empty list
+    list_of_item_lists = []
+    for sq_val in sq_values:
+        if sq_val and "Value" in sq_val:
+            list_of_item_lists.append(sq_val["Value"])
+        else:
+            list_of_item_lists.append([])
+
+    # 2. Find maximum sequence length
+    max_len = max(len(items) for items in list_of_item_lists)
+
+    # 3. Merge items at each index
+    merged_items = []
+    for i in range(max_len):
+        # Collect i-th item from each dataset (None if index out of range)
+        item_jsons = []
+        for items in list_of_item_lists:
+            if i < len(items):
+                item_jsons.append(items[i])
+            else:
+                item_jsons.append(None)
+
+        # Recursively merge items
+        merged_item = _merge_item(item_jsons)
+        merged_items.append(merged_item)
+
+    return {
+        "vr": "SQ",
+        "shared": None,  # Sequence sharing determined at item level
+        "Value": merged_items,
+    }
+
+
+def _merge_item(item_jsons: List[Optional[Dict[str, Any]]]) -> Dict[str, Any]:
+    """
+    Merge corresponding sequence items from multiple datasets.
+
+    Each item_json is a simplified dataset with format:
+    {"xxxx": {"vr": "...", "Value": ...}, "yyyy": {"vr": "...", "Value": ...}}
+
+    Args:
+        item_jsons: List of item dictionaries from each dataset
+
+    Returns:
+        dict: Merged item dictionary
+    """
+    # Replace None with empty dict
+    actual_jsons = [js if js is not None else {} for js in item_jsons]
+    return _merge_dataset_list(actual_jsons)
+
+
+###############################################################################
+# Helper Functions: Split Merged Dataset Back to Original DICOM JSON Format
+###############################################################################
+
+
+def _slice_merged_data(merged_dataset: Dict[str, Any], idx: int) -> Dict[str, Any]:
+    """
+    Extract data for a single dataset from merged data.
+
+    Args:
+        merged_dataset: Merged dataset dictionary
+        idx: Index of the dataset to extract
+
+    Returns:
+        dict: Dataset dictionary containing only the specified slice
+    """
+    json_dict = {}
+    for tag_key, tag_entry in merged_dataset.items():
+        vr = tag_entry.get("vr")
+        shared = tag_entry.get("shared")
+
+        if shared is True:
+            # Shared tags have same value across all datasets
+            tmp = tag_entry.copy()
+            tmp.pop("shared")
+            json_dict[tag_key] = tmp
+        elif shared is False:
+            if "Value" in tag_entry:
+                valuename = "Value"
+            elif "InlineBinary" in tag_entry:
+                valuename = "InlineBinary"
+            elif "BulkDataURI" in tag_entry:
+                valuename = "BulkDataURI"
+            else:
+                valuename = None
+            value = tag_entry.get(valuename)
+
+            value_idx = value[idx]
+            if value_idx is None:
+                json_dict[tag_key] = {"vr": vr}
+            elif isinstance(value_idx, list) or (valuename != "Value"):
+                json_dict[tag_key] = {"vr": vr, valuename: value_idx}
+            else:
+                json_dict[tag_key] = {"vr": vr, valuename: [value_idx]}
+        else:
+            # Handle sequences and special cases
+            if vr == "SQ":
+                value = tag_entry.get("Value")
+
+                if value == []:
+                    json_dict[tag_key] = {"vr": vr, "Value": value}
+                else:
+                    json_dict[tag_key] = {
+                        "vr": vr,
+                        "Value": [_slice_merged_data(value[0], idx)],
+                    }
+    return json_dict