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

Fixed up readme and enabled the output to buffered line by line for our subprocess output

Author: jph6366

Docker/README.md

@@ -81,32 +81,66 @@ Before running the Docker container, here are the available options for the `Doc
 
 - You can run the dicom2niix_wrapper.py script either directly or from inside a Docker container (non-interactive only). Here are the available options:
 
-#### Required (CLI Mode Only)
+##### 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 /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
+    ```
+
+#### Required parameters
+
 input: Path to the input DICOM directory.
 
 output: Path to the output directory for the converted NIfTI files.
 
 #### Optional Flags
--n, --series-number:
+
+#### -n, --series-number
+
 Convert only the specified DICOM series number.
-Example: --series-number 5
+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. 
+Depending on your vendor, you may want to keep images segmented based on these attributes or merge/combine them.
 
--m, --merge-2d:
-Merge 2D slices into a 3D or 4D volume if supported.
-Example: --merge-2d
+#### -s, --single-file
 
--s, --single-file:
 Use single file mode (convert only one series per folder).
-Example: --single-file
 
--pu, --prompt-user:
+For example, if the input path "~/dir/001.dcm" will only convert the file 001.dcm.
+
+#### -pu, --prompt-user
+
 Run the tool in interactive mode. This launches a terminal-based wizard where you can select DICOM folders and configure conversion interactively.
 
 [Note that NIfTI and DICOM encode space differently](https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage#Spatial_Coordinates)
 
 ![image](https://github.com/user-attachments/assets/8ea21692-36ac-4773-aec7-6cb3a6838055)
 
-##### The goal of dcm2niix is to create FSL format bvec/bval files for processing. A crucial concern is ensuring that the gradient directions are reported in the frame of reference expected by the software you use to fit your tractography. [dicom2niix should generate a ".bvec" file that reports the tensors as expected](https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage#Diffusion_Tensor_Imaging) by FSL's dtifit, where vectors are reported relative to image frame of reference (rather than relative to the scanner bore). 
+##### The goal of dcm2niix is to create FSL format bvec/bval files for processing. A crucial concern is ensuring that the gradient directions are reported in the frame of reference expected by the software you use to fit your tractography. [dicom2niix should generate a ".bvec" file that reports the tensors as expected](https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage#Diffusion_Tensor_Imaging) by FSL's dtifit, where vectors are reported relative to image frame of reference (rather than relative to the scanner bore)
 
 #### 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)
+
 ---

WrapImage/dicom2niix_wrapper.py

@@ -1,6 +1,8 @@
 import argparse
+import io
 import os
 from pathlib import Path
+import selectors
 import subprocess
 import sys
 import inquirer
@@ -69,7 +71,10 @@ def dicom_to_niix(vol_dir: Path, out_dir: Path, merge_2d: bool = False, series_n
     cmd.append(str(vol_dir)) # input directory
 
     try:
-        res = subprocess.run(cmd, capture_output=True, text=True, check=True)
+        success, output = capture_subprocess_output(cmd)
+        print(output)
+        if not success:
+            raise RuntimeError(f"dcm2niix failed: {output}")
 
         nifti_files = list(Path(out_dir).glob("*.nii.gz"))
 
@@ -98,6 +103,48 @@ 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}")
+    
+
+def capture_subprocess_output(subprocess_args):
+    process = subprocess.Popen(
+        subprocess_args,
+        bufsize=1, # output is line buffered
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        universal_newlines=True # for line buffering
+    )
+
+    buf = io.StringIO() # callback for output
+    def handle_output(stream, mask):
+        line = stream.readline()
+        buf.write(line)
+        sys.stdout.write(line)
+
+    selector = selectors.DefaultSelector()               # register callback 
+    selector.register(process.stdout, selectors.EVENT_READ, handle_output) # for 'read' event from subprocess stdout stream
+
+    while process.poll() is None:
+        events = selector.select()
+        for key, mask in events:
+            callback = key.data
+            callback(key.fileobj, mask)
+
+    # ensure all remaining output is processed
+    while True:
+        line = process.stdout.readline()
+        if not line:
+            break
+        buf.write(line)
+        sys.stdout.write(line)
+
+    return_code = process.wait()
+    selector.close()
+
+    success = (return_code == 0)
+    output = buf.getvalue()
+    buf.close()
+
+    return success, output
 
 def run_interactive():
 
@@ -178,7 +225,6 @@ def run_cli(input_path: str, output_path: str, **kwargs):
     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")
 
-
     args = parser.parse_args()
 
     if args.prompt_user: