dcm2bids4ct 0.1.0__tar.gz

dcm2bids4ct-0.1.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.3
+Name: dcm2bids4ct
+Version: 0.1.0
+Summary: A wrapper for dcm2niix that adds BIDS-compliant CT metadata to JSON sidecars
+Author: Christian Hinge
+Author-email: Christian Hinge <christian.hinge@outlook.dk>
+Requires-Dist: pydicom>=2.3.0
+Requires-Dist: numpy>=1.20.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# dcm2bids4ct
+
+A simple wrapper for dcm2niix that adds BIDS-compliant CT metadata to JSON sidecars.
+
+## Installation
+
+```bash
+pip install git+https://github.com/ChristianHinge/dcm2bids4ct.git
+```
+
+Or clone and install:
+
+```bash
+git clone https://github.com/ChristianHinge/dcm2bids4ct.git
+cd dcm2bids4ct
+pip install -e .
+```
+
+## Usage
+
+```bash
+dcm2bids4ct /path/to/dicom/folder
+```
+
+Works exactly like dcm2niix, but automatically extracts CT metadata (tube voltage, dose, exposure, etc.) and adds it to the JSON sidecar.

dcm2bids4ct-0.1.0/README.md

@@ -0,0 +1,25 @@
+# dcm2bids4ct
+
+A simple wrapper for dcm2niix that adds BIDS-compliant CT metadata to JSON sidecars.
+
+## Installation
+
+```bash
+pip install git+https://github.com/ChristianHinge/dcm2bids4ct.git
+```
+
+Or clone and install:
+
+```bash
+git clone https://github.com/ChristianHinge/dcm2bids4ct.git
+cd dcm2bids4ct
+pip install -e .
+```
+
+## Usage
+
+```bash
+dcm2bids4ct /path/to/dicom/folder
+```
+
+Works exactly like dcm2niix, but automatically extracts CT metadata (tube voltage, dose, exposure, etc.) and adds it to the JSON sidecar.

dcm2bids4ct-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "dcm2bids4ct"
+version = "0.1.0"
+description = "A wrapper for dcm2niix that adds BIDS-compliant CT metadata to JSON sidecars"
+readme = "README.md"
+authors = [
+    { name = "Christian Hinge", email = "christian.hinge@outlook.dk" }
+]
+requires-python = ">=3.9"
+dependencies = [
+    "pydicom>=2.3.0",
+    "numpy>=1.20.0",
+]
+
+[project.scripts]
+dcm2bids4ct = "dcm2bids4ct.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.8.16,<0.9.0"]
+build-backend = "uv_build"

dcm2bids4ct-0.1.0/src/dcm2bids4ct/__init__.py

@@ -0,0 +1,24 @@
+"""
+dcm2niix4ct: A wrapper for dcm2niix that adds BIDS-compliant CT metadata to JSON sidecars.
+"""
+
+from .wrapper import Dcm2niixWrapper, run_dcm2niix_wrapper
+from .main import (
+    find_dicom_files,
+    is_dicom_file,
+    is_ct_scan,
+    validate_ct_series,
+    extract_ct_metadata,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Dcm2niixWrapper",
+    "run_dcm2niix_wrapper",
+    "find_dicom_files",
+    "is_dicom_file",
+    "is_ct_scan",
+    "validate_ct_series",
+    "extract_ct_metadata",
+]

dcm2bids4ct-0.1.0/src/dcm2bids4ct/cli.py

@@ -0,0 +1,40 @@
+"""Command-line interface for dcm2niix4ct wrapper."""
+
+import sys
+from pathlib import Path
+from .wrapper import Dcm2niixWrapper
+
+
+def main(argv=None):
+    """Run dcm2niix and add CT metadata to JSON sidecars."""
+    args = argv or sys.argv[1:]
+
+    if not args or args[0] in ['-h', '--help']:
+        print("Usage: dcm2niix4ct <input_dir> [dcm2niix_args...]")
+        print("\nWrapper for dcm2niix that adds BIDS CT metadata to JSON sidecars")
+        print("All arguments are passed directly to dcm2niix")
+        return 0
+
+    input_dir = args[0]
+    dcm2niix_args = args[1:]
+
+    # Extract and remove output dir from args if specified
+    output_dir = None
+    if '-o' in dcm2niix_args:
+        idx = dcm2niix_args.index('-o')
+        if idx + 1 < len(dcm2niix_args):
+            output_dir = dcm2niix_args[idx + 1]
+            # Remove -o and its argument from dcm2niix_args
+            dcm2niix_args = dcm2niix_args[:idx] + dcm2niix_args[idx+2:]
+
+    if not Path(input_dir).is_dir():
+        print(f"Error: {input_dir} is not a directory", file=sys.stderr)
+        return 1
+
+    wrapper = Dcm2niixWrapper()
+    result = wrapper.run(input_dir, output_dir, dcm2niix_args)
+    return result.returncode
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dcm2bids4ct-0.1.0/src/dcm2bids4ct/main.py

@@ -0,0 +1,269 @@
+"""
+DICOM CT metadata extraction and BIDS JSON modification utilities.
+"""
+
+import os
+import sys
+from typing import List, Dict, Any, Optional
+from collections import defaultdict
+
+
+def find_dicom_files(directory: str) -> List[str]:
+    """
+    Find all DICOM files in a directory (non-recursive).
+
+    Args:
+        directory: Path to the directory to search
+
+    Returns:
+        List of DICOM file paths
+    """
+    dicom_files = []
+
+    # List all items in directory
+    for filename in os.listdir(directory):
+        filepath = os.path.join(directory, filename)
+
+        # Skip if not a file
+        if not os.path.isfile(filepath):
+            continue
+
+        # Check if it's a DICOM file by reading the header
+        if is_dicom_file(filepath):
+            dicom_files.append(filepath)
+
+    return dicom_files
+
+
+def is_dicom_file(filepath: str) -> bool:
+    """Check if file is DICOM by looking for DICM magic number at byte 128."""
+    with open(filepath, 'rb') as f:
+        f.seek(128)
+        return f.read(4) == b'DICM'
+
+
+def is_ct_scan(dicom_files: List[str]) -> bool:
+    """
+    Check if DICOM files represent a CT scan.
+
+    Args:
+        dicom_files: List of DICOM file paths
+
+    Returns:
+        True if files are CT scans, False otherwise
+
+    Raises:
+        RuntimeError: If DICOM file cannot be read
+    """
+    if not dicom_files:
+        return False
+
+    import pydicom
+
+    dcm = pydicom.dcmread(dicom_files[0], stop_before_pixels=True)
+    modality_element = dcm.get("Modality")
+
+    if modality_element is None:
+        return False
+
+    # Handle both DataElement objects and plain values
+    if hasattr(modality_element, 'value'):
+        modality = modality_element.value
+    else:
+        modality = modality_element
+
+    return modality == "CT"
+
+
+def validate_ct_series(dicom_files: List[str]) -> None:
+    """
+    Validate that DICOM files represent a single CT series.
+
+    Args:
+        dicom_files: List of DICOM file paths
+
+    Raises:
+        ValueError: If files are not CT modality or contain multiple series
+    """
+    if not dicom_files:
+        raise ValueError("No DICOM files found in directory")
+
+    import pydicom
+
+    # Check first file
+    try:
+        first_dcm = pydicom.dcmread(dicom_files[0], stop_before_pixels=True)
+    except Exception as e:
+        raise ValueError(f"Failed to read DICOM file {dicom_files[0]}: {e}")
+
+    # Get modality
+    modality = first_dcm.get("Modality")
+    if modality is None:
+        raise ValueError("DICOM files do not contain Modality tag")
+
+    modality_value = modality.value if hasattr(modality, "value") else str(modality)
+
+    # Check if CT
+    if modality_value != "CT":
+        raise ValueError(f"DICOM modality is '{modality_value}', expected 'CT'")
+
+    # Get series information from first file
+    first_series_uid = first_dcm.get("SeriesInstanceUID")
+    first_series_number = first_dcm.get("SeriesNumber")
+
+    if first_series_uid is None:
+        raise ValueError("DICOM files do not contain SeriesInstanceUID tag")
+
+    first_series_uid_value = first_series_uid.value if hasattr(first_series_uid, "value") else str(first_series_uid)
+
+    # Check all files belong to the same series
+    unique_series = set()
+    unique_series.add(first_series_uid_value)
+
+    # Sample some files to check for consistency
+    # For large datasets, we don't need to check every single file
+    sample_size = min(len(dicom_files), 10)
+    step = max(1, len(dicom_files) // sample_size)
+
+    for i in range(0, len(dicom_files), step):
+        dcm = pydicom.dcmread(dicom_files[i], stop_before_pixels=True)
+
+        # Check modality
+        modality = dcm.get("Modality")
+        if modality:
+            mod_value = modality.value if hasattr(modality, "value") else str(modality)
+            if mod_value != "CT":
+                raise ValueError(f"Mixed modalities found: CT and {mod_value}")
+
+        # Check series UID
+        series_uid = dcm.get("SeriesInstanceUID")
+        if series_uid:
+            uid_value = series_uid.value if hasattr(series_uid, "value") else str(series_uid)
+            unique_series.add(uid_value)
+
+    if len(unique_series) > 1:
+        raise ValueError(f"Directory contains multiple series (found {len(unique_series)} unique SeriesInstanceUIDs). "
+                        "Please ensure only one CT series is present in the directory.")
+
+
+def extract_ct_metadata(dicom_files: List[str]) -> Dict[str, Any]:
+    """
+    Extract BIDS-compliant CT metadata from DICOM files.
+
+    Args:
+        dicom_files: List of DICOM file paths
+
+    Returns:
+        Dictionary with BIDS CT metadata fields
+
+    Raises:
+        ValueError: If no DICOM files provided
+        RuntimeError: If DICOM files cannot be read
+    """
+    import pydicom
+    import numpy as np
+
+    if not dicom_files:
+        raise ValueError("No DICOM files provided for metadata extraction")
+
+    # Read first file for basic metadata
+    ct_file = pydicom.dcmread(dicom_files[0], stop_before_pixels=True)
+
+    # Initialize parameters dictionary
+    params: Dict[str, Any] = {}
+
+    # Helper to get numeric DICOM values
+    def get_float(dcm, tag, default="n/a"):
+        value = dcm.get(tag)
+        if value is None:
+            return default
+        value = value.value if hasattr(value, 'value') else value
+        return float(value) if value else default
+
+    def get_int(dcm, tag, default="n/a"):
+        value = dcm.get(tag)
+        if value is None:
+            return default
+        value = value.value if hasattr(value, 'value') else value
+        return int(value) if value else default
+
+    def get_str(dcm, tag, default="n/a"):
+        value = dcm.get(tag)
+        if value is None:
+            return default
+        value = value.value if hasattr(value, 'value') else value
+        if hasattr(value, '__iter__') and not isinstance(value, (str, bytes)):
+            return list(value)
+        return value if value else default
+
+    # Extract all parameters
+    params = {
+        "Modality": get_str(ct_file, "Modality", "CT"),
+        "Manufacturer": get_str(ct_file, "Manufacturer"),
+        "ManufacturerModelName": get_str(ct_file, "ManufacturerModelName"),
+        "SeriesDescription": get_str(ct_file, "SeriesDescription"),
+        "ProtocolName": get_str(ct_file, "ProtocolName"),
+        "TubeVoltage": get_float(ct_file, "KVP"),
+        "SliceThickness": get_float(ct_file, "SliceThickness"),
+        "FilterType": get_str(ct_file, "FilterType", "none"),
+        "ConvolutionKernel": get_str(ct_file, "ConvolutionKernel", "none"),
+        "GantryTilt": get_float(ct_file, "GantryDetectorTilt", 0.0),
+        "DiameterFOV": get_float(ct_file, "DataCollectionDiameter"),
+        "ReconstructionDiameter": get_float(ct_file, "ReconstructionDiameter"),
+        "Pitch": get_float(ct_file, "SpiralPitchFactor"),
+        "SingleCollimationWidth": get_float(ct_file, "SingleCollimationWidth"),
+        "TotalCollimationWidth": get_float(ct_file, "TotalCollimationWidth"),
+        "FocalSpots": get_str(ct_file, "FocalSpots"),
+        "CTDIvol": get_float(ct_file, "CTDIvol"),
+        "ContrastBolusAgent": get_str(ct_file, "ContrastBolusAgent", "none"),
+        "ContrastBolusRoute": get_str(ct_file, "ContrastBolusRoute", "n/a"),
+    }
+
+    # Voxel size
+    pixel_spacing = get_str(ct_file, "PixelSpacing")
+    slice_thickness = params["SliceThickness"]
+    if pixel_spacing != "n/a" and slice_thickness != "n/a":
+        params["AcquisitionVoxelSize"] = [float(pixel_spacing[0]), float(pixel_spacing[1]), slice_thickness]
+
+    # Matrix
+    rows = get_int(ct_file, "Rows")
+    cols = get_int(ct_file, "Columns")
+    if rows != "n/a" and cols != "n/a":
+        params["ReconMatrixSize"] = [rows, cols]
+        params["ReconMatrix"] = [rows, cols, len(dicom_files)]
+
+    # Per-slice parameters
+    if len(dicom_files) > 1:
+        z_positions, tube_currents, exposures = [], [], []
+        for filepath in dicom_files:
+            dcm = pydicom.dcmread(filepath, stop_before_pixels=True)
+            pos = get_str(dcm, "ImagePositionPatient")
+            if pos != "n/a":
+                z_positions.append(pos[-1])
+            tc = get_float(dcm, "XRayTubeCurrent")
+            if tc != "n/a":
+                tube_currents.append(tc)
+            exp = get_float(dcm, "Exposure")
+            if exp != "n/a":
+                exposures.append(exp)
+
+        if z_positions:
+            ix = np.argsort(z_positions)
+            if tube_currents and len(tube_currents) == len(z_positions):
+                params["TubeCurrent"] = np.array(tube_currents)[ix].tolist()
+            if exposures and len(exposures) == len(z_positions):
+                params["Exposure"] = np.array(exposures)[ix].tolist()
+
+    # Derived values
+    if slice_thickness != "n/a":
+        params["ScanLength"] = len(dicom_files) * slice_thickness / 10
+        params["ScanLengthUnit"] = "cm"
+        if params["CTDIvol"] != "n/a":
+            params["DLP"] = params["ScanLength"] * params["CTDIvol"]
+            params["DLPUnit"] = "mGy*cm"
+            params["CTDIvolUnit"] = "mGy"
+
+    # Sort so scalar values come first, then lists last
+    scalars = {k: v for k, v in params.items() if not isinstance(v, list)}
+    lists = {k: v for k, v in params.items() if isinstance(v, list)}
+    return {**scalars, **lists}

dcm2bids4ct-0.1.0/src/dcm2bids4ct/wrapper.py

@@ -0,0 +1,137 @@
+"""
+Core wrapper for dcm2niix that modifies JSON sidecars with BIDS CT metadata.
+"""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional, List, Dict, Any
+
+
+class Dcm2niixWrapper:
+    """Wrapper for dcm2niix that adds BIDS CT metadata to JSON sidecars."""
+
+    def __init__(self, dcm2niix_path: str = "dcm2niix"):
+        """
+        Initialize the wrapper.
+
+        Args:
+            dcm2niix_path: Path to dcm2niix executable (default: "dcm2niix" from PATH)
+        """
+        self.dcm2niix_path = dcm2niix_path
+
+    def run(self, input_dir: str, output_dir: Optional[str] = None,
+            dcm2niix_args: Optional[List[str]] = None) -> subprocess.CompletedProcess:
+        """
+        Run dcm2niix and modify the output JSON sidecars with CT metadata.
+
+        Args:
+            input_dir: Directory containing DICOM files
+            output_dir: Output directory (if None, uses dcm2niix default)
+            dcm2niix_args: Additional arguments to pass to dcm2niix
+
+        Returns:
+            CompletedProcess object from subprocess
+
+        Raises:
+            ValueError: If not a CT scan or multiple series found
+        """
+        from .main import is_dicom_file, validate_ct_series
+
+        # Validate the input directory
+        input_path = Path(input_dir)
+        dicom_files = []
+        if input_path.is_dir():
+            for file in input_path.iterdir():
+                if file.is_file() and is_dicom_file(str(file)):
+                    dicom_files.append(str(file))
+
+        if dicom_files:
+            validate_ct_series(dicom_files)
+
+        # Build dcm2niix command
+        cmd = [self.dcm2niix_path]
+
+        if dcm2niix_args:
+            cmd.extend(dcm2niix_args)
+
+        if output_dir:
+            cmd.extend(["-o", output_dir])
+
+        cmd.append(input_dir)
+
+        # Get the actual output directory
+        if output_dir:
+            out_path = Path(output_dir)
+        else:
+            out_path = Path(input_dir)
+
+        # List existing JSON files before conversion
+        existing_jsons = set(out_path.glob("*.json")) if out_path.exists() else set()
+
+        # Run dcm2niix
+        print(f"Running: {' '.join(cmd)}", file=sys.stderr)
+        result = subprocess.run(cmd, capture_output=True, text=True)
+
+        # Print dcm2niix output
+        if result.stdout:
+            print(result.stdout, end='')
+        if result.stderr:
+            print(result.stderr, end='', file=sys.stderr)
+
+        if result.returncode != 0:
+            return result
+
+        # Find newly created JSON files
+        current_jsons = set(out_path.glob("*.json")) if out_path.exists() else set()
+        new_jsons = current_jsons - existing_jsons
+
+        # Modify each new JSON sidecar
+        for json_file in new_jsons:
+            self._modify_json_sidecar(json_file, dicom_files)
+
+        return result
+
+    def _modify_json_sidecar(self, json_file: Path, dicom_files: List[str]):
+        """Add CT metadata to JSON sidecar."""
+        from .main import extract_ct_metadata, is_ct_scan
+
+        if not dicom_files:
+            raise ValueError("No DICOM files found")
+
+        if not is_ct_scan(dicom_files):
+            raise ValueError("Not a CT scan")
+
+        with open(json_file, 'r') as f:
+            data = json.load(f)
+
+        ct_metadata = extract_ct_metadata(dicom_files)
+        data.update(ct_metadata)
+
+        with open(json_file, 'w') as f:
+            json.dump(data, f, indent=2)
+
+        print(f"Added {len(ct_metadata)} CT metadata fields to {json_file.name}", file=sys.stderr)
+
+
+def run_dcm2niix_wrapper(input_dir: str, output_dir: Optional[str] = None,
+                         dcm2niix_args: Optional[List[str]] = None,
+                         additional_metadata: Optional[Dict[str, Any]] = None,
+                         dcm2niix_path: str = "dcm2niix") -> int:
+    """
+    Convenience function to run the dcm2niix wrapper.
+
+    Args:
+        input_dir: Directory containing DICOM files
+        output_dir: Output directory (if None, uses dcm2niix default)
+        dcm2niix_args: Additional arguments to pass to dcm2niix
+        additional_metadata: Additional metadata to add to JSON sidecars
+        dcm2niix_path: Path to dcm2niix executable
+
+    Returns:
+        Exit code from dcm2niix
+    """
+    wrapper = Dcm2niixWrapper(dcm2niix_path)
+    result = wrapper.run(input_dir, output_dir, dcm2niix_args, additional_metadata)
+    return result.returncode