[Feature] <Allow reading of DICOM images> #68

Squashed some bugs and tried some more use case testing. Wrote up a function to save simulated DWI as DICOM images with headers configured for all in x-direction.

provided pyproject.toml for separation of dependenccies and setuptools configured for the different root packages.

Author: jph6366

Docker/README.md

@@ -65,8 +65,6 @@ Before running the Docker container, here are the available options for the `Doc
 
     Replace `brain.nii.gz`, `brain.bvec`, and `brain.bval` with the actual file names you want to use.
 
-
-
 ## Running the Docker container for reading in DICOM Images
 
 - You can run the dicom2nifti Docker container using the `docker run` command. This command runs the Docker image with the specified input files:
@@ -76,53 +74,48 @@ Before running the Docker container, here are the available options for the `Doc
         -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/src/app \
         -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/app/output \
         tf2.4_ivim-mri_codecollection \
-        /usr/src/app/dicom_folder /usr/app/output
+        /usr/src/app/dicom_folder
     ```
 
 - You can run the dicom2niix_wrapper.py script either directly or from inside a Docker container (non-interactive only). Here are the available options:
 
-##### example usage:
+### Example usage
 
-    ```sh
-    sudo docker run -it --rm --name TF2.4_IVIM-MRI_CodeCollection \
-        -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/src/app \
-        -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/app/output \
-        tf2.4_ivim-mri_codecollection \
-        /usr/src/app/dicom_folder /usr/app/output -n -1
-    ```
+```sh
+sudo docker run -it --rm --name TF2.4_IVIM-MRI_CodeCollection \
+    -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/src/app \
+    -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/app/output \
+    tf2.4_ivim-mri_codecollection \
+    /usr/src/app/dicom_folder -o /usr/app/output
+```
 
-    ```sh
-    sudo docker run -it --rm --name TF2.4_IVIM-MRI_CodeCollection \
-        -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/src/app \
-        -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/app/output \
-        tf2.4_ivim-mri_codecollection \
-        /usr/src/app/dicom_folder /usr/app/output -m
-    ```
+```sh
+sudo docker run -it --rm --name TF2.4_IVIM-MRI_CodeCollection \
+    -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/src/app \
+    -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/app/output \
+    tf2.4_ivim-mri_codecollection \
+    /usr/src/app/dicom_folder -o /usr/app/output -m
+```
 
-    ```sh
-    sudo docker run -it --rm --name TF2.4_IVIM-MRI_CodeCollection \
-        -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/src/app \
-        -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/app/output \
-        tf2.4_ivim-mri_codecollection \
-        /usr/src/app/dicom_file /usr/app/output -s
-    ```
+```sh
+sudo docker run -it --rm --name TF2.4_IVIM-MRI_CodeCollection \
+    -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/src/app \
+    -v ~/TF2.4_IVIM-MRI_CodeCollection:/usr/app/output \
+    tf2.4_ivim-mri_codecollection \
+    /usr/src/app/dicom_file -o /usr/app/output -s
+```
 
 #### Required parameters
 
-input: Path to the input DICOM directory.
+input: Path to the input DICOM directory. Some scanners store images in nested subfolders, so a single session might be stored in the folders "/usr/subj22/111", "/usr/subj22/112" and "/usr/subj22/123". In this case you should simply provide the parent directly ("/usr/subj22") and dcm2niix will recursively search the sub directories and organize all your images for you.
 
 output: Path to the output directory for the converted NIfTI files.
 
 #### Optional Flags
 
-#### -n, --series-number
-
-Convert only the specified DICOM series number.
-A special feature of this option is unleashed when you provide a negative series number ("-n -1"): in this case the software will report the series numbers available in the input folder, but will convert nothing.
-
 #### -m, --merge-2d
 
-Merge 2D slices into a 3D or 4D NIfTI image regardless of study time, echo, coil, orientation, etc. 
+Merge 2D slices into a 3D or 4D NIfTI image regardless of study time, echo, coil, orientation, etc.
 Depending on your vendor, you may want to keep images segmented based on these attributes or merge/combine them.
 
 #### -s, --single-file
@@ -143,4 +136,9 @@ Run the tool in interactive mode. This launches a terminal-based wizard where yo
 
 #### It is strongly recommend that users check validate the b-vector directions for their hardware and sequence as [described in a dedicated document](https://www.nitrc.org/docman/?group_id=880)
 
+![DICOM2NiFTI](dicom2nifti/DICOM2NiFTI.png)
+
+#### Output of NIFTI and DICOM objects generated from signal generation test
+
+- NIfTI follows the Talairach/MNI coordinate system where the X value increases as we move toward the participant's right, the Y increases as we move anteriorly. In contrast, for bipeds DICOM specifies the the X increases as we more toward the participant's left, while the Y increases as we move posteriorly. Both agree that the Z coordinate increases as we move superiorly. 
 ---

Docker/dicom2nifti/DICOM2NiFTI.png

@@ -1,8 +1,9 @@
+from pathlib import Path
 import numpy as np
 import nibabel as nib
 from utilities.data_simulation.GenerateData import GenerateData
 from WrapImage.nifti_wrapper import save_nifti_file
-
+from WrapImage.dicom2niix_wrapper import save_dicom_objects
 
 def save_bval_bvec(filename, values):
     if filename.endswith('.bval'):
@@ -34,9 +35,28 @@ def save_bval_bvec(filename, values):
 # Generate IVIM signal
 signals = gd.ivim_signal(D_in, Dp_in, f_in, S0, bvals_reshaped)
 
+
+# Generate 4D signal by stacking volumes for each bval
+signals_4d = np.stack([
+    gd.ivim_signal(D_in, Dp_in, f_in, S0, np.full(shape, bval))
+    for bval in bvals
+], axis=-1)
+
 # Save the generated image as a NIfTI file
 save_nifti_file(signals, "ivim_simulation.nii.gz")
 # Save the bval in a file
 save_bval_bvec("ivim_simulation.bval", [0, 50, 100, 500, 1000])
 # Save the bvec value 
 save_bval_bvec("ivim_simulation.bvec", [[1, 0, 0], [0, 1, 0], [0, 0, 1]])
+
+bvecs = [[1, 0, 0]] * len(bvals)  # Assuming all x-direction
+
+save_dicom_objects(
+    volume_4d=signals_4d,
+    bvals=bvals.tolist(),
+    bvecs=bvecs,
+    out_dir=Path("ivim_simulation_dicom"),
+    f_vals=f_in,
+    D_vals=D_in,
+    Dp_vals=Dp_in
+)

Docker/generate_signal_docker_test.py

@@ -6,6 +6,101 @@
 import subprocess
 import sys
 import inquirer
+import itk
+import numpy as np
+import datetime
+import uuid
+
+def save_dicom_objects(
+    volume_4d: np.ndarray,
+    bvals: list,
+    bvecs: list,
+    out_dir: Path,
+    f_vals: np.ndarray = None,
+    D_vals: np.ndarray = None,
+    Dp_vals: np.ndarray = None,
+    patient_id: str = "SIM123",
+    modality: str = "MR",
+    pixel_spacing=(1.0, 1.0),
+    slice_thickness=1.0,
+    series_description="Simulated IVIM",
+    protocol_name="SimulatedProtocol",
+    patient_position="HFS",
+    manufacturer="Simulated Manufacturer",
+):
+    out_dir.mkdir(parents=True, exist_ok=True)
+    x, y, z, t = volume_4d.shape
+    assert t == len(bvals) == len(bvecs), "Mismatch in timepoints and bvals/bvecs"
+
+    # Define 2D image type (DICOM expects 2D slices)
+    ImageType = itk.Image[itk.SS, 2]  # 2D image with short (int16) pixel type
+    WriterType = itk.ImageFileWriter[ImageType]
+
+    for t_idx in range(t):
+        volume_3d = volume_4d[:, :, :, t_idx].astype(np.int16)
+
+        # Generate common metadata for this timepoint
+        study_uid = f"1.2.826.0.1.3680043.2.1125.{uuid.uuid4().int >> 64}"
+        series_uid = f"1.2.826.0.1.3680043.2.1125.{uuid.uuid4().int >> 64}"
+        now = datetime.datetime.now().strftime("%Y%m%d")
+        series_number = str(t_idx + 1)
+
+        for slice_idx in range(z):
+            # Create 2D slice
+            slice_2d = volume_3d[:, :, slice_idx]
+            image_2d = itk.image_view_from_array(slice_2d.T)  # Transpose for proper orientation
+            image_2d = itk.cast_image_filter(image_2d, ttype=(type(image_2d), ImageType))
+
+            # Set image properties
+            image_2d.SetSpacing(pixel_spacing)
+            image_2d.SetOrigin([0.0, 0.0])
+
+            # Create metadata dictionary
+            meta_dict = itk.MetaDataDictionary()
+            meta_dict["0010|0010"] = "Simulated^Patient"
+            meta_dict["0010|0020"] = patient_id
+            meta_dict["0008|0060"] = modality
+            meta_dict["0008|0020"] = now
+            meta_dict["0008|0030"] = "120000"
+            meta_dict["0020|000d"] = study_uid
+            meta_dict["0020|000e"] = series_uid
+            meta_dict["0020|0011"] = series_number
+            meta_dict["0008|103e"] = f"{series_description} Volume {series_number}"
+            meta_dict["0018|1030"] = protocol_name
+            meta_dict["0018|5100"] = patient_position 
+            meta_dict["0008|0070"] = manufacturer
+
+            meta_dict["0018|9087"] = str(float(bvals[t_idx]))
+            gx, gy, gz = bvecs[t_idx]
+            meta_dict["0018|9089"] = f"{gx}\\{gy}\\{gz}"
+
+            if f_vals is not None:
+                meta_dict["0011|1001"] = f"f_in_mean={np.mean(f_vals):.6f}"
+            if D_vals is not None:
+                meta_dict["0011|1002"] = f"D_in_mean={np.mean(D_vals):.6e}"
+            if Dp_vals is not None:
+                meta_dict["0011|1003"] = f"Dp_in_mean={np.mean(Dp_vals):.6e}"
+
+            sop_uid = f"1.2.826.0.1.3680043.8.498.{uuid.uuid4().int >> 64}"
+            meta_dict["0008|0018"] = sop_uid
+            meta_dict["0020|0013"] = str(slice_idx + 1)
+            meta_dict["0020|0032"] = f"0\\0\\{slice_idx * slice_thickness}"
+            meta_dict["0020|0037"] = "1\\0\\0\\0\\1\\0"
+
+            # Create and configure writer
+            writer = WriterType.New()
+            writer.SetInput(image_2d)
+            writer.SetFileName(str(out_dir / f"vol_{t_idx:03d}_slice_{slice_idx:03d}.dcm"))
+
+            # Use GDCMImageIO for DICOM writing
+            gdcm_io = itk.GDCMImageIO.New()
+            gdcm_io.SetMetaDataDictionary(meta_dict)
+            gdcm_io.KeepOriginalUIDOn()
+
+            writer.SetImageIO(gdcm_io)
+            writer.Update()
+
+    print(f" DICOMs written to {out_dir.resolve()}")
 
 def prompt_input_directory():
     return inquirer.prompt([
@@ -49,26 +144,24 @@ def prompt_output_directory(input_dir):
         return os.path.abspath(os.path.join(input_dir, answer.strip("./")))
 
 
-def dicom_to_niix(vol_dir: Path, out_dir: Path, merge_2d: bool = False, series_num: int = -2, is_single_file: bool = False):
+def dicom_to_niix(vol_dir: Path, out_dir: Path = None, merge_2d: bool = False, is_single_file: bool = False):
     """
     For converting DICOM images to a (compresssed) 4d nifti image
     """
-
-    os.makedirs(out_dir, exist_ok=True)
+    if not out_dir:
+        os.makedirs(out_dir, exist_ok=True)
 
     cmd = [
         "dcm2niix",
         "-f", "%s_%p", # dcm2niix attempts to provide a sensible file naming scheme
-        "-o", out_dir, # output directory
-        "-z", "y", #specifying compressed nii.gz file
+        "-o", out_dir if out_dir else "",  # Add merge option
+        "-z", "y", # parallel pigz compressed nii.gz file; 'optimal'"-z o" which pipes data directly to pigz
         "-m", "y" if merge_2d else "n",  # Add merge option
         "-s", "y" if is_single_file else "n",
         # https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage
         # for further configuration for general usage see page above
+        vol_dir
     ]
-    if series_num >= -1:
-        cmd.extend(["-n", str(series_num)])
-    cmd.append(str(vol_dir)) # input directory
 
     try:
         success, output = capture_subprocess_output(cmd)
@@ -78,18 +171,15 @@ def dicom_to_niix(vol_dir: Path, out_dir: Path, merge_2d: bool = False, series_n
 
         nifti_files = list(Path(out_dir).glob("*.nii.gz"))
 
-        if (is_single_file or merge_2d or series_num >= 0):
-            if len(nifti_files) != 1:
-                raise RuntimeError(
-                    f"Expected a single .nii.gz output due to flags "
-                    f"{'-s' if is_single_file else ''} "
-                    f"{'-m' if merge_2d else ''} "
-                    f"{f'-n {series_num}' if series_num >= 0 else ''}, "
-                    f"but found {len(nifti_files)} files."
-                )
-        else:
-            if len(nifti_files) < 1:
-                raise RuntimeError("No NIfTI (.nii.gz) files were generated.")
+        if is_single_file and len(nifti_files) != 1:
+            raise RuntimeError("Expected a single .nii.gz output due to flags"
+                               " Please collect your  NIfTI files in the output directory prior to execution.")
+        if merge_2d and len(nifti_files) != 1:
+            raise RuntimeError("Expected a single .nii.gz output due to flags"
+                               " Check the Warnings logged by dicom2niix to see source of error.")
+        if len(nifti_files) < 1:
+            raise RuntimeError("No NIfTI (.nii.gz) files were generated."
+                               " Check the Warnings logged by dicom2niix and Double-check your input before running again.")
 
         bval_files = list(out_dir.glob("*.bval"))
         bvec_files = list(out_dir.glob("*.bvec"))
@@ -104,7 +194,9 @@ def dicom_to_niix(vol_dir: Path, out_dir: Path, merge_2d: bool = False, series_n
     except subprocess.CalledProcessError as e:
         raise RuntimeError(f"dcm2niix failed: {e.stderr}")
 
-
+### Adapted from https://gist.github.com/nawatts/e2cdca610463200c12eac2a14efc0bfb ###
+### for further breakdown and see gist above ###
+### for future improvements https://me.micahrl.com/blog/magicrun/ to be called over SSH OR SLURM. ###
 def capture_subprocess_output(subprocess_args):
     process = subprocess.Popen(
         subprocess_args,
@@ -165,18 +257,13 @@ def run_interactive():
         if not add_more:
             break
 
-    series_num = inquirer.prompt([
-        inquirer.Text("series", message="🔢 Enter series number to convert (-n <num>) [Leave blank for all]", default="")
-    ])["series"]
-    series_num = int(series_num) if series_num.isdigit() else -1
-
     merge_answer = inquirer.prompt([
         inquirer.Confirm("merge", message="🧩 Merge 2D slices into a single NIfTI (-m y)?", default=True)
     ])
     merge_2d = merge_answer["merge"]
 
     single_file = inquirer.prompt([
-        inquirer.Confirm("single", message="📦 Force single file output (-s y)?", default=False)
+        inquirer.Confirm("single", message="📦 Force single file input (-s y)?", default=False)
     ])["single"]
 
     for in_dir, out_dir in zip(input_dirs, output_dirs):
@@ -185,22 +272,21 @@ def run_interactive():
 
         print(f"Converting:\n → Input: {vol_dir}\n → Output: {out_path}")
         try:
-            nifti, bval, bvec = dicom_to_niix(vol_dir, out_path, merge_2d, series_num, single_file)
+            nifti, bval, bvec = dicom_to_niix(vol_dir, out_path, merge_2d, single_file)
             print(f" Conversion succeeded: {nifti}")
         except RuntimeError as err:
             print(f"❌ Conversion failed: {err}")
 
 def run_cli(input_path: str, output_path: str, **kwargs):
     vol_dir = Path(input_path)
-    out_dir = Path(output_path)
+    out_dir = Path(output_path) if output_path else vol_dir
 
     merge_2d = kwargs.get("merge_2d", False)
-    series_num = kwargs.get("series_number", -2)
     single_file = kwargs.get("single_file", False)
 
     print(f" Converting:\n → Input: {vol_dir}\n → Output: {out_dir}")
     try:
-        nifti, bval, bvec = dicom_to_niix(vol_dir, out_dir, merge_2d, series_num, single_file)
+        nifti, bval, bvec = dicom_to_niix(vol_dir, out_dir, merge_2d, single_file)
         print(f" Created NIfTI: {nifti}")
 
         if bval and bvec:
@@ -219,8 +305,7 @@ def run_cli(input_path: str, output_path: str, **kwargs):
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(description="DICOM to NIfTI converter with optional IVIM processing")
     parser.add_argument("input", nargs="?", help="Path to input DICOM directory")
-    parser.add_argument("output", nargs="?", help="Path to output directory for NIfTI files")
-    parser.add_argument("-n", "--series-number", type=int, default=-2, help="Only convert this series number (-n <num>)")
+    parser.add_argument("-o", "--output", nargs="?", help="Path to output directory for NIfTI files, defaults to the same folder as the original DICOM files.")
     parser.add_argument("-m", "--merge-2d", action="store_true", help="Merge 2D slices (-m y)")
     parser.add_argument("-s", "--single-file", action="store_true", help="Enable single file mode (-s y)")
     parser.add_argument("-pu", "--prompt-user", action="store_true", help="Run in interactive mode")
@@ -229,7 +314,7 @@ def run_cli(input_path: str, output_path: str, **kwargs):
 
     if args.prompt_user:
         run_interactive()
-    elif args.input and args.output:
+    elif args.input:
         run_cli(args.input, args.output, **vars(args))
     else:
         print("❗ You must provide input and output paths OR use --prompt-user for interactive mode.")